DillieDocs
dillie.work

dillie CLI 로 일하기

AI 에이전트나 스크립트로 dillie CLI 를 쓸 때 세션을 시작하고, 워크스페이스를 정하고, 아이템을 정확히 지목하고, 거부를 읽는 법을 다룬다. 명령과 옵션의 목록은 dillie describe 가 실행 시점의 실제 계약으로 돌려준다.

CLI 를 아직 설치하지 않았으면 시작하기 부터 따라간다. 예시의 ACME 는 자기 프로젝트 키로 바꿔 쓴다.

세션 시작하기

dillie --agent whoami
dillie --agent describe ACME --fields fieldMap

--agent 는 출력을 JSON 으로 고정한다. 성공 응답은 stdout 에 JSON 하나로, 오류는 stderr 에 { "error": { … } } 로, 업데이트 안내 같은 알림은 stderr 에 { "advisory": { … } } 로 나온다. stdout 과 stderr 를 따로 읽는다.

describe 를 매 세션 다시 부른다. 필드 id·상태 옵션·계층 규칙은 프로젝트마다 다르고 운영 중에 바뀐다. 지난 세션에 본 값을 그대로 쓰면 지워진 필드나 옵션을 보내게 된다.

--fields fieldMap 으로 좁히면 그 프로젝트의 필드 id·옵션·기본 리스트·계층(hierarchy)만 받는다. 명령 옵션이나 출력 규약(conventions)까지 볼 때만 --fields 를 뺀다.

워크스페이스 정하기

모든 명령은 워크스페이스 하나에서 실행된다. 기본은 지금 선택된 워크스페이스(dillie workspace list 의 current: true)다.

여러 에이전트가 동시에 다른 워크스페이스를 다룰 때는 dillie workspace use 로 바꾸지 않는다. 그 명령은 이 기기의 현재 워크스페이스를 바꿔서, 다른 에이전트의 다음 명령까지 그 워크스페이스로 보낸다. 대신 실행마다 지정한다(CLI 0.21.0 이상).

dillie --agent --workspace <tenantId> project projects list
DILLIE_WORKSPACE=<tenantId> dillie --agent project tasks query ACME --issue-key ACME-123
  • --workspace 와 환경변수 DILLIE_WORKSPACE 는 그 실행에만 적용되고 현재 워크스페이스를 바꾸지 않는다. 둘 다 있으면 --workspace 가 이긴다.
  • 적용되는 명령은 project·bots·whoami, 그리고 프로젝트를 준 describe <project> 다. workspace·logout 같은 명령에 --workspace 를 주면 거부된다. 환경변수는 그런 명령에서 무시된다.
  • 워크스페이스는 tenantId 로 지정한다. 이름도 받지만 정확히 하나와 일치할 때만이다 — 같은 이름의 워크스페이스가 둘이면 거부된다.
  • dillie login 의 기본 방식(브라우저·--device)으로 로그인한 세션이어야 한다. --method 로 로그인한 세션에서는 쓸 수 없다.

아이템과 프로젝트 지목하기

아이템은 UUID 를 기억해 두지 말고 이슈 키로 지목한다. 아이템을 받는 명령(get·update·complete·set-description 등)은 이슈 키를 그대로 받는다.

dillie --agent project tasks get ACME ACME-123

기억해 둔 UUID 로 “찾을 수 없다” 는 응답을 받으면 원인을 가릴 수 없다 — 아이템이 지워졌을 수도, 다른 프로젝트나 다른 워크스페이스의 것일 수도, 잘못 옮겨 적었을 수도 있다. 매번 이슈 키로 지목하면 이 갈림이 생기지 않는다.

이슈 키로 지목했는데 아이템이 없으면 오류가 난다. 반대로 tasks query --issue-key 로 조회하면 오류가 아니라 빈 목록(items: [])이 온다. 있는지만 확인하려면 조회를 쓴다.

프로젝트는 키(ACME)로 지목한다. 대소문자는 가리지 않는다. 키는 워크스페이스 안에서만 유일해서, 다른 워크스페이스에 같은 키의 다른 프로젝트가 있을 수 있다. 여러 워크스페이스를 다루면 --workspace 로 워크스페이스를 고정한다.

프로젝트를 못 찾으면 오류 메시지가 어느 워크스페이스에서 찾았는지와 다른 소속 워크스페이스 수를 알려 준다. 어느 워크스페이스에 있는지 모르면 전부에서 찾는다(CLI 0.21.0 이상).

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

항목마다 workspace: { tenantId, label } 가 붙는다. 읽지 못한 워크스페이스는 결과에서 빠지지 않고 workspaces[] 에 status(authorization_required 또는 failed)로 남으며, 그때 complete 는 false 다. complete: false 인 결과를 「그 워크스페이스에는 프로젝트가 없다」로 읽지 않는다.

쓴 뒤 되읽기

성공 응답은 요청이 받아들여졌다는 뜻이지, 저장된 내용이 의도한 것이라는 뜻이 아니다. 본문·상태처럼 나중에 사람이 읽을 값을 쓴 뒤에는 되읽어 확인한다.

dillie --agent project tasks get-description ACME ACME-123

셸에 긴 마크다운을 인라인으로 넘기면 따옴표·개행이 셸 단계에서 잘린다. 본문이 몇 줄을 넘어가면 파일로 넘긴다.

dillie project tasks set-description ACME ACME-123 --content-file ./body.md

날짜 필드는 "YYYY-MM-DD" 로 써도 { "due": …, "start": … } 로 저장되고 그 모양으로 돌아온다. 되읽은 모양이 보낸 것과 달라도 실패가 아니다.

문제 해결

거부 사유 읽기

--agent 오류의 error.status 는 거부의 종류를, error.message 는 어느 규칙이 막았는지를 말한다. 같은 상태 코드라도 규칙은 여럿이므로 메시지를 읽는다. --agent 없이 실행하면 상태 코드는 나오지 않고 메시지만 나온다.

상태 뜻 다시 시도
400 입력이 규칙에 어긋난다 입력을 고치기 전에는 하지 않는다
401 세션이 없거나 만료됐다 dillie login 뒤에
403 이 작업을 할 권한이 없다 하지 않는다
404 대상이 없다 지목한 키·id 를 확인한 뒤에
409 지금 상태와 충돌한다 대상을 다시 읽은 뒤에
429 호출이 너무 많다 잠시 기다린 뒤에(대기 시간은 출력에 나오지 않는다)

워크스페이스 승인이 필요하다는 오류

--workspace 로 지정한 워크스페이스에서 dillie CLI 를 아직 승인하지 않았으면 code: "authorization_required" 와 그 tenantId 가 담긴 오류가 난다. 그 워크스페이스로 한 번 전환해 브라우저에서 승인한다.

dillie workspace use <tenantId>

이 명령은 현재 워크스페이스도 그쪽으로 바꾼다. 승인한 뒤에는 원래 워크스페이스로 돌아가도 그 워크스페이스를 --workspace 로 계속 쓸 수 있다.

저장된 세션이 거절됐다는 오류

--workspace 로 실행하는 도중 그 워크스페이스의 세션이 만료되거나 폐기되면, CLI 가 그 세션을 지우고 다시 실행하라고 안내한다. 같은 명령을 다시 실행하면 새 세션을 받는다.

다음 단계

에이전트는 이 문서들을 dillie docs read dillie <slug> 로 읽을 수 있다(예: dillie docs read dillie cli-writing-tickets).