DillieDocs
dillie.work

찾기와 대량 정리

많은 티켓 중에서 필요한 것만 찾고, 여러 건을 한 번에 만들고·고치고·지우는 법을 다룬다. 목록을 통째로 받는 것은 마지막 수단이다.

검색 좁히기

아는 것이 많을수록 좁은 질의가 있다.

  • 이슈 키를 안다 — --issue-key 로 정확히 일치하는 한 건만 받는다. 없으면 오류가 아니라 빈 목록이 온다.
  • 단어를 안다 — --search 로 이슈 키·제목·본문에서 찾는다. 단어를 여럿 주면 모두 들어 있는 아이템만 나온다.
  • 담당자를 안다 — --assignee 에 프로젝트 멤버의 이름 전체나 사용자 id 를 준다. --search 는 담당자를 찾지 않는다. 같은 이름의 멤버가 여럿이면 오류가 나므로 사용자 id 로 준다.
  • 구조나 값을 안다 — --top-level-only 로 최상위만, --filter 로 필드 값 조건을 준다.
dillie --agent project tasks query ACME --issue-key ACME-123
dillie --agent project tasks query ACME --search "결제 실패"
dillie --agent project tasks query ACME --assignee "홍길동"
dillie --agent project tasks query ACME --top-level-only
dillie --agent project tasks query ACME --filter '{"and":[{"fieldId":"<fieldId>","op":"eq","value":"<optionId>"}]}' --sort <fieldId>:desc

--filter 의 op 는 eq·neq·in·contains·isEmpty·isNotEmpty·gte·lte 다. --assignee 와 함께 쓰면 두 조건을 모두 만족하는 것만 나온다. --issue-key 는 --search 와 함께 쓸 수 없다.

어떤 옵션이 있는지 추측하지 않는다. 옵션은 describe 의 globalOptions(모든 명령에 쓰는 것)와 commands[].options(그 명령에만 쓰는 것) 두 곳에 있다. 두 곳 어디에도 없는 옵션은 unknown option 으로 거부된다.

다른 워크스페이스에서 찾기

명령은 워크스페이스 하나에서 실행되고, 프로젝트 키와 이슈 키는 그 워크스페이스 안에서만 유일하다. 찾는 프로젝트가 다른 워크스페이스에 있으면 지금 워크스페이스에서는 없는 것처럼 보인다.

어느 워크스페이스에 있는지 알면 그 실행만 그 워크스페이스로 보낸다(CLI 0.21.0 이상).

dillie --agent --workspace <tenantId> project tasks query ACME --issue-key ACME-123

모르면 속한 모든 워크스페이스의 프로젝트를 모은다(CLI 0.21.0 이상).

dillie --agent project projects list --all-workspaces

항목마다 workspace: { tenantId, label } 가 붙는다. 읽지 못한 워크스페이스는 workspaces[] 에 status 와 함께 남는다 — authorization_required 면 dillie workspace use <tenantId> 로 한 번 승인하고, failed 면 error 를 읽는다. 하나라도 읽지 못했으면 complete 가 false 다. 자세한 규칙은 dillie CLI 로 일하기 — 워크스페이스 정하기에 있다.

다음 페이지 요청하기

목록 명령은 페이지 크기를 주지 않으면 첫 페이지 50건만 돌려준다. 응답의 page.hasMore 가 true 면 아직 다 본 것이 아니다.

  • page.nextCursor 가 있으면 그 값을 --cursor 로 넘긴다(tasks query 등).
  • 없으면 --page 를 하나 올린다(projects list 등).

전부 필요하면 --paginate 로 마지막 페이지까지 한 번에 읽는다(projects list·tasks query, CLI 0.21.0 이상). --limit 은 한 번에 받는 페이지 크기가 된다.

dillie --agent project tasks query ACME --top-level-only --paginate

--paginate 도 페이지마다 호출을 하나씩 쓴다. 이슈 키나 검색으로 좁힐 수 있으면 그쪽이 호출이 적다.

페이지 정보를 주지 않는 목록(프로젝트 멤버 등)도 있다. 그런 목록은 받은 건수가 --limit 보다 적어질 때까지 --page 를 올린다.

응답 필드 좁히기

목록 출력은 기본으로 감사 메타데이터(createdAt·updatedBy 등)를 뺀다. 필드 값(values)은 그대로 오므로 필요한 키만 남기려면 --fields 로 좁힌다.

dillie --agent project tasks query ACME --top-level-only --fields id,issueKey,title

감사 메타데이터까지 필요하면 --full 을 붙인다.

대량 생성하기

벌크 요청의 본문은 최상위가 배열이다. 객체로 감싸지 않는다. 항목이 많으면 --data-file 로 넘기고, 파일 확장자가 .jsonl·.ndjson 이면 한 줄에 항목 하나로 읽는다.

dillie --agent project tasks bulk-create ACME --issue-type story --data '[{"values":{…}},{"values":{…}}]'

--issue-type 은 모든 항목의 이슈 타입을 그 값으로 덮어쓴다. 타입이 섞인 목록을 한 번에 만들려면 옵션을 빼고 각 항목의 values 에 issueType 을 넣는다.

벌크 작업은 전부 반영되거나 하나도 반영되지 않는다. 한 항목이라도 거부되면 배치 전체가 취소된다.

대량 수정·삭제하기

bulk-update 는 아이템 id 와 바꿀 값을, bulk-delete 는 아이템 id 배열을 받는다. 단건 명령과 달리 이슈 키를 받지 않는다 — 먼저 조회해 id 를 모은다.

dillie --agent project tasks bulk-update ACME --data '[{"itemId":"<itemId>","values":{"status":"<optionId>"}}]'
dillie --agent project tasks bulk-delete ACME --data '["<itemId>","<itemId>"]'

응답은 bulk-update 가 { updated: Item[] }, bulk-delete 가 { deleted: string[] } 다.

보내기 전 대상 확인하기

수십 건을 만들거나 지우기 전에, 실제로 보내지 않고 대상 건수와 앞쪽 몇 건을 확인한다. bulk-create·bulk-update·bulk-delete 모두 --dry-run 을 받는다.

dillie --agent project tasks bulk-create ACME --dry-run --data-file ./items.json

이것은 검증이 아니라 샘플링이다. 총 개수와 앞 3건을 보여 주고, 확인하는 것은 본문이 배열인지·프로젝트를 찾을 수 있는지·--issue-type 라벨이 맞는지뿐이다. 각 항목의 값과 계층 규칙은 서버가 실제 요청에서 판정한다. 파일을 잘못 만들었거나 대상 범위가 통째로 어긋난 것은 여기서 잡히지만, 미리 보기가 깨끗하다고 배치가 성공하는 것은 아니다.

생성 결과 이어 쓰기

bulk-create 응답의 createdRefs 가 만들어진 아이템마다 { id, issueKey, clientId } 를 준다. 요청 항목에 clientId 를 붙여 두면 어느 항목이 어떤 이슈 키가 됐는지 대조해 곧바로 후속 전이·기록에 쓸 수 있다. clientId 를 붙이지 않은 항목은 clientId: null 로 온다.

문서 찾기

이 가이드를 포함한 공개 문서는 CLI 에서 로그인 없이 읽을 수 있다. 기본 언어는 한국어이고, 영어로 읽으려면 --locale en 을 붙인다.

dillie docs nav
dillie docs list --section cli
dillie docs read dillie cli-grooming
dillie docs search "벌크" --limit 5

문서 명령에는 분당 호출 제한이 있다(검색 30회, 읽기 60회). 트리를 먼저 받아 필요한 문서만 읽으면 여기 걸릴 일이 없다.

문제 해결

호출 제한에 걸렸다(429)

--agent 오류의 error.status 가 429 면 호출 제한이다. 아이템이 없다거나 값이 틀렸다는 뜻이 아니므로 입력을 고치려 들지 않는다.

  • 바로 다시 부르지 않는다. 얼마나 기다려야 하는지는 출력에 나오지 않는다. 간격을 짐작해 촘촘히 재시도하지 말고 점점 늘려 가며 기다린다.
  • 쓰기에서 걸렸으면 되읽고 판단한다. 재시도가 같은 작업을 두 번 만들지 않게, 먼저 조회해 이미 반영됐는지 본다.
  • 호출 수를 줄인다. 목록을 페이지마다 훑는 대신 이슈 키·검색으로 좁히면 애초에 여기 닿지 않는다.

벌크 요청이 거부됐다

아무것도 반영되지 않았다. 메시지가 말하는 항목을 고쳐 배치 전체를 다시 보낸다. 응답을 받지 못하고 끊겼다면, 다시 보내기 전에 조회해 반영됐는지 먼저 확인한다.

프로젝트를 찾을 수 없다

오류 메시지가 어느 워크스페이스에서 찾았는지 알려 준다. 다른 워크스페이스에 있을 수 있으면 다른 워크스페이스에서 찾기대로 찾는다.