DillieDocs
dillie.work

Recording progress and moving status

How to record your work on a ticket as a comment, move its status, and close it as completed or cancelled with the CLI. A ticket closed without a record tells you nothing about what was done.

Replace ACME in the examples with your own project key.

Record what you did

Moving status alone leaves no record of what was done. Weeks later, whoever asks “how did we fix this” opens the ticket before the commit log. Put the outcome and the reasoning in the comment.

  • What changed — named so a reader can navigate to it
  • Why that way — including the reason another approach was dropped, if there was one
  • What you verified — the checks that passed, and what you could not check

Do not leave out the last item. Writing “I could not verify this” keeps it standing as something to review; smoothing it into “verified” means nobody looks again.

To leave a progress record without closing the item, use messages create.

dillie --agent project messages create ACME <itemId> --data '{"content":"Deployed to staging. Card payment retry not verified yet."}'

messages create accepts the item only as a UUID. If you only know the issue key, look the item up first and use the id from the response.

dillie --agent project tasks get ACME ACME-123

Choose who posts the comment

Comments the CLI posts (notes on tasks complete and tasks cancel, and messages create) are posted under the user’s automation bot by default. The bot’s name is the user’s name followed by “automation” (for example, “Jane’s automation”). This keeps what a tool recorded distinguishable later from what a person wrote.

Add --as-me only when posting words a person actually wrote.

dillie --agent project tasks complete ACME ACME-123 --note "Summary of the work …"             # posted by the automation bot
dillie --agent project tasks complete ACME ACME-123 --note "Checked this myself" --as-me       # posted under my name
  • --agent only sets the output format and has nothing to do with the author. Only --as-me decides the author.
  • Do not put an author key in the request body (--data). If you include asBot, the CLI stops, and any other unknown key is rejected by the server with 400.
  • If the server cannot post as the automation bot, the command fails. The comment is not posted under the person’s name instead.

Attach files

Upload and attach a local file in one step with attachments upload.

dillie --agent project attachments upload ACME <itemId> ./error.log

To attach a file that is already uploaded (fileId), use attachments attach. Both commands take the item as a UUID.

Posting a comment that carries a file requires --as-me. The automation bot cannot attach files, so if you put fileId in --data without --as-me, the CLI stops. The CLI does not switch the author for you so that you never discover, after the fact, a comment posted under your own name.

dillie --agent project messages create ACME <itemId> \
  --data '{"content":"Attaching the log","fileId":"<fileId>"}' --as-me

Add a note when completing or cancelling

Adding a note to the complete or cancel command closes the item and records the work in one step. You can point at the item by issue key.

dillie --agent project tasks complete ACME ACME-123 --note "Summary of the work …"
dillie --agent project tasks complete ACME ACME-123 --note-file ./done.md
  • If the note spans several lines or contains quotes, pass it with --note-file. A \n inside --note does not become a line break.
  • --note and --note-file cannot be used together. A note that is empty after trimming surrounding whitespace, or longer than 10,000 characters, is rejected.

The note is posted first, and the status changes only if that succeeds. If the note cannot be posted, the item is not closed. Conversely, if the note is posted but the transition fails, only the note remains. Running the same command again would post the note a second time, so fix the cause and run it again without the note option.

Running complete on an item that is already completed, or cancel on one already cancelled, leaves the status unchanged. If you added a note, the note is still posted.

Close work you decided not to do

Close duplicate, deferred, or invalid work by cancelling it, not completing it. Cancelling is a separate way to close, parallel to completing; closing such work as completed inflates what looks done.

dillie --agent project tasks cancel ACME ACME-123 --note "Cancelled as a duplicate of ACME-98"

A cancelled item drops out of both the numerator and the denominator of progress, and disappears from “My Tasks”.

To undo a cancellation use uncancel; to undo a completion use uncomplete. Both return the item to the first not-started (unstarted) STATUS option, not to the status it had before it was closed.

Look up status values

Workflows differ per project. A status name you saw in another project is not guaranteed to exist here, so look it up every time.

dillie --agent describe ACME --fields fieldMap

The options of the field whose role is STATUS are the option ids you can use. However, the options in describe carry neither a category (not started, completed, cancelled, and so on) nor the transition rules. Read those from the list details.

dillie --agent project lists get ACME
  • Each entry in config.options of the field in fields whose role is STATUS has a category. complete moves to the first completed option and cancel to the first cancelled option.
  • In workProfile.config, transitions maps the current status → statuses it can move to, and initial lists the statuses an item can take when it starts with no status.

Whether these rules apply is decided by workProfile. The three cases are explained in Creating projects and hierarchy — Look up the hierarchy rules directly. In addition, even with agileMode: true, if transitions is missing or empty there are no status rules and initial is not applied either. If initial is empty, there is no restriction on the starting status.

Move status

To move to a status other than completed or cancelled, change the STATUS value with update.

dillie --agent project tasks update ACME ACME-123 --data '{"values":{"status":"<STATUS option id>"}}'

update moves one step at a time. If the target status is not directly reachable in transitions, it is rejected, so move through the intermediate statuses one by one.

Complete and cancel with complete and cancel, not update. For these two commands the server finds the shortest path in the transition rules and passes through intermediate statuses automatically. In a project that is not agile, the item moves directly.

Set status on creation

If you create an item without a status in an agile project that has transitions, the server sets the first option in initial (by STATUS option order).

dillie --agent project tasks create ACME --data '{"values":{"title":"…","_description":"…"}}'

If you set a status on creation, it must be in initial (no restriction if initial is empty). If the item needs to start in another status, create it and then move it as in Move status. After creating, read the item back to confirm its actual status.

dillie --agent project tasks get ACME ACME-123

Send option ids

For fields with a fixed set of choices (status, issue type, priority), send the option id, not the label shown on screen. A label is converted to an option id only when you use an alias key such as status, issueType, or priority, and labels are not guaranteed to be unique within a list. When you use a field id as the key, always send the option id.

Send messages as a custom bot

You can send messages under a custom bot created in your workspace, to channels that bot has joined. This is separate from the automation bot that posts task comments.

dillie --agent bots list

hasWebhookSecret tells whether the server holds a signing key, while localApiKey and localWebhookSecret tell whether this device holds the plaintext. Sending a message needs both. The server never returns these values again, so if you lose them, reissue or rotate.

dillie --agent bots keys issue <botId>
dillie --agent bots secret rotate <botId>

A bot can send messages only to channels it has already joined. Sending a message does not make it join, so add it first. Otherwise a single bot key would open every channel in the workspace.

dillie --agent bots channels add <botId> <channelId>

Give the bot-and-channel pair a name so you do not copy both ids every time.

dillie --agent bots targets set notice --bot <botId> --channel <channelId>
dillie --agent bots send notice --text "Deployment finished"
  • Bot keys and names are stored on this device per signed-in user. Signing in with another account hides the previous account’s entries. dillie logout removes this device’s bot credentials along with the session — a bot key authenticates on its own without a session, so leaving it behind would keep the access you meant to cut off.
  • Issuing and revoking keys, rotating secrets, and adding or removing channels cannot be done with an OAuth sign-in session. You need a session signed in with credentials, such as dillie login --method email, under a role that has bot management permissions. For the same reason, these commands cannot be used with --workspace — --workspace works only with an OAuth sign-in session. Listing and sending messages are not affected by this restriction.

The project tasks, project messages, and bots commands can run against another workspace for one run with --workspace or DILLIE_WORKSPACE (CLI 0.21.0 or later). The rules are in Working with the dillie CLI — Choose a workspace.

Troubleshooting

How to read status codes in general is covered in Working with the dillie CLI — Troubleshooting. The errors below are all 400; tell them apart by error.code. The same input will not pass if sent again.

{
  "error": {
    "message": "…",
    "status": 400,
    "code": "INVALID_STATUS_TRANSITION"
  }
}

A status transition is rejected

INVALID_STATUS_TRANSITION — the target status cannot be reached directly from the current one, or the value is not a STATUS option. (initial) in the message means “from no status” (you set a status on creation that is not in initial). Read transitions and initial as in Look up status values, then pick a reachable status or pass through intermediate ones.

Completing or cancelling is rejected

  • STATUS_TRANSITION_PATH_NOT_FOUND — the transition rules have no path from the current status to completed (or cancelled).
  • STATUS_COMPLETED_OPTION_MISSING / STATUS_CANCELLED_OPTION_MISSING — STATUS has no option in the completed or cancelled category.
  • STATUS_FIELD_MISSING — the list has no STATUS field.

If you ran the command with a note, the note has already been posted. Fix the cause and run it again without the note option.

The project cannot be found

The error message tells you which workspace was searched. If the project is in another workspace, find it with projects list --all-workspaces and specify that workspace with --workspace.