Working with the dillie CLI

How to start a session, choose a workspace, point at items precisely, and read rejections when you use the dillie CLI from an AI agent or a script. For the list of commands and options, dillie describe returns the actual contract at run time.

If you have not installed the CLI yet, start with Getting started. Replace ACME in the examples with your own project key.

Start a session

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

--agent fixes the output to JSON. A successful response is a single JSON document on stdout, errors are { "error": { … } } on stderr, and notices such as update notices are { "advisory": { … } } on stderr. Read stdout and stderr separately.

Call describe again every session. Field ids, status options, and hierarchy rules differ by project and change while it runs. Reusing values from a previous session sends fields or options that have since been removed.

Narrowing with --fields fieldMap returns only the project’s field ids, options, default list, and hierarchy (hierarchy). Drop --fields only when you also need command options or the output conventions (conventions).

Choose a workspace

Every command runs in one workspace. By default it is the one selected now (current: true in dillie workspace list).

When several agents work in different workspaces at the same time, do not switch with dillie workspace use. That command changes the current workspace on this machine, so the other agents’ next commands go to that workspace too. Choose the workspace per run instead (CLI 0.21.0 or later).

dillie --agent --workspace <tenantId> project projects list
DILLIE_WORKSPACE=<tenantId> dillie --agent project tasks query ACME --issue-key ACME-123

• --workspace and the DILLIE_WORKSPACE environment variable apply to that run only and do not change the current workspace. If both are set, --workspace wins.
• They apply to project, bots, whoami, and describe <project> when a project is given. Passing --workspace to commands such as workspace or logout is rejected; the environment variable is ignored there.
• Name the workspace by tenantId. A name is accepted only when it matches exactly one workspace — if two share the name, it is rejected.
• The session must come from the default dillie login (browser or --device). Sessions signed in with --method cannot use it.

Point at items and projects

Point at items by issue key instead of remembering UUIDs. Commands that take an item (get, update, complete, set-description, and so on) accept the issue key as is.

dillie --agent project tasks get ACME ACME-123

When a remembered UUID returns “not found”, you cannot tell why — the item may have been deleted, it may belong to another project or another workspace, or it may have been copied wrong. Pointing by issue key every time avoids that ambiguity.

Pointing at a missing item by issue key is an error. A tasks query --issue-key lookup instead returns an empty list (items: []), not an error. To check only whether an item exists, use the lookup.

Point at projects by key (ACME); case does not matter. A key is unique only within a workspace, so another workspace can have a different project with the same key. When you work across workspaces, pin the workspace with --workspace.

When a project is not found, the error message says which workspace was searched and how many other workspaces you belong to. If you do not know which workspace it is in, search all of them (CLI 0.21.0 or later).

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

Each item carries workspace: { tenantId, label }. A workspace that could not be read is not dropped: it stays in workspaces[] with a status (authorization_required or failed), and complete is false. Do not read a complete: false result as “that workspace has no projects”.

Read back after writing

A successful response means the request was accepted, not that what was stored is what you intended. After writing values people will read later, such as the description or status, read them back.

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

Passing long Markdown inline through the shell cuts quotes and newlines at the shell stage. Once the body runs past a few lines, pass it as a file.

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

A date field written as "YYYY-MM-DD" is stored and returned as { "due": …, "start": … }. A read-back shape that differs from what you sent is not a failure.

Troubleshooting

Read the reason for a rejection

In --agent errors, error.status says the kind of rejection and error.message says which rule blocked it. One status code covers several rules, so read the message. Without --agent, only the message is printed, not the status code.

Workspace approval required

If the dillie CLI has not been approved yet in the workspace given by --workspace, the error carries code: "authorization_required" and that tenantId. Switch to that workspace once and approve it in the browser.

dillie workspace use <tenantId>

This also makes it your current workspace. After approving, you can switch back and keep using that workspace with --workspace.

Saved session rejected

If the session for a workspace expires or is revoked while a --workspace run is in progress, the CLI removes that session and tells you to run again. Running the same command again gets a new session.

Next steps

• Writing tickets — what goes into a ticket and what stays out
• Creating projects and hierarchy — what it means that the hierarchy differs by project
• Recording progress and moving status — when to leave a comment and how to move status
• Finding items and bulk cleanup — the order for finding items, and doing bulk work safely

Agents can read these documents with dillie docs read dillie <slug> (for example dillie docs read dillie cli-writing-tickets).