DillieDocs
dillie.work

Finding items and bulk cleanup

How to find only the tickets you need among many, and how to create, update, and delete many at once. Pulling the whole list is the last resort.

The more you know, the narrower the query you can use.

  • You know the issue key — --issue-key returns only the one exact match. If there is none, you get an empty list, not an error.
  • You know words — --search looks in the issue key, title, and description. With several words, only items containing all of them match.
  • You know the assignee — pass a project member’s full name or user id to --assignee. --search does not search assignees. If several members share the name, it errors, so pass the user id.
  • You know the structure or values — --top-level-only for top-level items only, --filter for conditions on field values.
dillie --agent project tasks query ACME --issue-key ACME-123
dillie --agent project tasks query ACME --search "payment failure"
dillie --agent project tasks query ACME --assignee "Jane Doe"
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

The op in --filter is one of eq, neq, in, contains, isEmpty, isNotEmpty, gte, lte. Combined with --assignee, only items matching both conditions come back. --issue-key cannot be combined with --search.

Do not guess which options exist. Options live in two places in describe: globalOptions (for every command) and commands[].options (for that command only). An option in neither is rejected as unknown option.

Search other workspaces

A command runs in one workspace, and project keys and issue keys are unique only within that workspace. A project in another workspace looks as if it does not exist from the current one.

If you know which workspace it is in, send just that run there (CLI 0.21.0 or later).

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

If you do not, collect the projects of every workspace you belong to (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 stays in workspaces[] with a status — for authorization_required, approve once with dillie workspace use <tenantId>; for failed, read error. If any workspace could not be read, complete is false. The full rules are in Working with the dillie CLI — Choose a workspace.

Request the next page

Without a page size, list commands return only the first page of 50. If page.hasMore in the response is true, you have not seen everything yet.

  • If page.nextCursor is present, pass it as --cursor (tasks query and others).
  • If not, increase --page by one (projects list and others).

To get everything, read through the last page in one go with --paginate (projects list, tasks query; CLI 0.21.0 or later). --limit becomes the page size for each request.

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

--paginate still uses one call per page. If you can narrow by issue key or search, that takes fewer calls.

Some lists return no page information (project members and others). For those, increase --page until you receive fewer items than --limit.

Narrow the response fields

List output leaves out audit metadata (createdAt, updatedBy, and so on) by default. Field values (values) still come through, so narrow with --fields to keep only the keys you need.

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

Add --full when you also need the audit metadata.

Create in bulk

The body of a bulk request is an array at the top level. Do not wrap it in an object. For many items, pass --data-file; if the file extension is .jsonl or .ndjson, each line is read as one item.

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

--issue-type overwrites the issue type of every item with that value. To create a list of mixed types in one call, leave the option out and put issueType in each item’s values.

Bulk operations apply all or nothing. If any item is rejected, the whole batch is cancelled.

Update and delete in bulk

bulk-update takes item ids with the values to change; bulk-delete takes an array of item ids. Unlike single-item commands, they do not accept issue keys — query first and collect the ids.

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 responds with { updated: Item[] } and bulk-delete with { deleted: string[] }.

Check the targets before sending

Before creating or deleting dozens of items, check the target count and the first few without actually sending. bulk-create, bulk-update, and bulk-delete all accept --dry-run.

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

This is sampling, not validation. It shows the total count and the first 3, and it checks only that the body is an array, that the project can be found, and that the --issue-type label is valid. Each item’s values and the hierarchy rules are judged by the server on the real request. A malformed file or a target range that is off entirely is caught here, but a clean preview does not mean the batch will succeed.

Use the creation results

createdRefs in the bulk-create response gives { id, issueKey, clientId } for each created item. If you attach a clientId to each request item, you can match which item became which issue key and use it right away for follow-up transitions and notes. Items sent without a clientId come back with clientId: null.

Find documents

Public documents, including this guide, can be read from the CLI without signing in. The default language is Korean; add --locale en to read in English.

dillie docs nav --locale en
dillie docs list --section cli --locale en
dillie docs read dillie cli-grooming --locale en
dillie docs search "bulk" --locale en --limit 5

Document commands have a per-minute call limit (30 searches, 60 reads). Fetch the tree first and read only the documents you need, and you will not hit it.

Troubleshooting

Hit the call limit (429)

If error.status in an --agent error is 429, you hit the call limit. It does not mean an item is missing or a value is wrong, so do not try to fix the input.

  • Do not call again right away. How long to wait is not in the output. Instead of guessing a short interval and retrying densely, wait longer each time.
  • If a write hit the limit, read back before deciding. So the retry does not do the same work twice, query first to see whether it was already applied.
  • Make fewer calls. Narrowing by issue key or search instead of paging through lists keeps you from getting here at all.

A bulk request was rejected

Nothing was applied. Fix the items the message names and resend the whole batch. If the connection dropped before you got a response, query to check whether it was applied before resending.

The project cannot be found

The error message says which workspace was searched. If it may be in another workspace, look for it as in Search other workspaces.