Command reference
Every duun CLI command with its synopsis, flags, examples and output, plus exit codes and the YAML format for workflow files.
On this page
This page lists every duun command. All commands accept the global flags --workspace, --profile, --json, --help and --version. Ids can be given in full (run_7f3aK2pQ) and runs can also be named by their issue key (PLT-482).
Account
duun login
duun login [--token <key>] [--profile <name>]Signs in and saves an API key to your config file. Without --token, opens the browser and uses a device code. With --token, stores the key you pass and checks it against the API.
| Flag | Description |
|---|---|
--token <key> | Use an existing API key (duun_sk_…) instead of the browser flow. |
--profile <name> | Save to this profile. Defaults to default. |
duun login --token "$DUUN_API_KEY" --profile ci✓ Key works for acme (ws_acme). Saved to profile "ci".duun logout
duun logout [--profile <name>]Removes the profile’s key from the config file and revokes it, if it was created by duun login. Keys you passed with --token are only removed locally.
duun whoami
duun whoamiPrints the signed-in member, workspace, profile and the key’s scopes.
[email protected] on acme (ws_acme)
Profile: default · Key: duun_sk_…f81c · Scopes: runs:read runs:write factories:read workflows:read workflows:write skills:writeRuns
duun run
duun run "<prompt>" --factory <factory> [--workflow <workflow>] [--issue <url|KEY>] [--input key=value]… [--watch]Starts a run in a factory and prints its id. The run uses the factory’s default workflow unless you pass --workflow. Same as POST /runs in the Runs API.
| Flag | Description |
|---|---|
--factory <factory> | Required. Factory id, for example fac_platform. |
--workflow <workflow> | Workflow id. Defaults to the factory default. |
--issue <url|KEY> | Link a Linear, GitHub or Jira issue by URL or key. Available to steps as {{trigger.issue.*}}. |
--input key=value | Set a run input. Repeat for several. Values are strings; use [email protected] to read a file. |
--title <text> | Run title. Defaults to the issue title or the first line of the prompt. |
--watch | Stay attached: stream logs, show asks as they appear and exit when the run finishes. |
duun run "Add idempotency keys to refund webhooks" --factory fac_platform --issue PLT-482 --watch✓ Started run_7f3aK2pQ · Idempotency keys for refund webhooks
Workflow Base Loop v5 · agent builder · budget $8.00
https://app.duun.ai/acme/runs/run_7f3aK2pQ
10:38:12 plan builder Reading the refund webhook path and ledger schema…
10:42:07 plan waiting Approve the plan → open in Inbox or press a to approve hereWith --watch, you can answer some asks in the terminal: a approves a plan or allows a command once, o opens the ask in the browser, q detaches without stopping the run. --watch exits 0 when the run succeeds and 1 when it fails or is cancelled.
duun runs list
duun runs list [--status <status>] [--factory <factory>] [--limit <n>]Lists recent runs, newest first.
| Flag | Description |
|---|---|
--status <status> | queued, running, waiting, succeeded, failed or cancelled. |
--factory <factory> | Only runs in this factory. |
--limit <n> | How many to show (1–100). Default 20. The CLI pages through results for you. |
duun runs list --status waitingID STATUS STEP AGENT COST TITLE
run_7f3aK2pQ waiting plan builder $1.84 Idempotency keys for refund webhooks
run_2Bq7mXn4 waiting deploy operator $0.22 Run db:migrate against stagingduun runs get
duun runs get <run>Prints one run: status, workflow version, current step, ask, branch, pull request and cost.
duun runs get PLT-482 --json{
"id": "run_7f3aK2pQ",
"object": "run",
"status": "waiting",
"workflow_id": "wf_base9c1d",
"workflow_revision": 5,
"current_step": "plan",
"ask": { "id": "ask_3h2Wn8", "kind": "approve_plan", "title": "Approve the plan", "created_at": "2026-11-15T10:42:07Z" },
"cost": { "spent_usd": 1.84, "limit_usd": 8.0, "billed_to": "duun" }
}duun runs cancel
duun runs cancel <run> [--yes]Cancels a run. The agent stops after its current tool call; the worktree and thread are kept, so you can restart it later from the app. Asks for confirmation unless you pass --yes.
duun logs
duun logs <run> [--follow] [--step <step>] [--since <duration>]Prints a run’s log: step starts and finishes, agent messages, commands and their output.
| Flag | Description |
|---|---|
--follow, -f | Keep streaming new lines until the run finishes. |
--step <step> | Only lines from one step, by step id (for example implement). |
--since <duration> | Only lines newer than this, for example 10m or 2h. |
duun logs run_7f3aK2pQ --step implement --follow11:02:19 implement builder Implementing step 1 of 4: writing migration 0142_refund_events…
11:04:51 implement $ pnpm test ledger
11:05:37 implement ✓ reader drains (412ms)Factories
duun factories list
duun factories listID STATUS DEFAULT WORKFLOW REPOS NAME
fac_platform active wf_base9c1d (v5) 2 Platform
fac_growth active wf_small71ab (v3) 1 Growth
fac_mobile paused wf_large4e02 (v2) 1 Mobileduun factories get
duun factories get <factory>Prints a factory with its workflows, repos and sandbox status, guardrails and budgets.
Workflows
duun workflows list
duun workflows list [--factory <factory>]ID FACTORY STATUS LIVE NAME
wf_base9c1d fac_platform on v5 Base Loop (factory default)
wf_hotfix3b8e fac_platform paused v2 Hotfixduun workflows pull
duun workflows pull <workflow> [-o <file>]Writes the workflow’s live version as a workflow file. Prints to stdout unless you pass -o. The file records the revision it came from, which apply uses to detect conflicting changes.
duun workflows pull wf_base9c1d -o duun/workflows/base-loop.yaml✓ Wrote Base Loop v5 to duun/workflows/base-loop.yamlduun workflows diff
duun workflows diff <file>Compares a workflow file with the live version and checks it for problems, without applying anything. Same as POST /workflows/{workflow_id}/diff.
duun workflows diff duun/workflows/base-loop.yamlBase Loop · file vs live v5
+ security-review Added (agent · reviewer) runs after implement
~ implement Edited: gate.on_fail.return_to plan → test
~ limits Edited: budget_usd 8 → 10
✗ 1 problem
security-review: "{{steps.spec.output.doc}}" isn't available here: Spec doesn't run before Security review.Exits 0 when there are no errors (warnings are printed but don’t fail), 3 when there are problems.
duun workflows apply
duun workflows apply <file> [--message <text>] [--yes]Applies the file as a new version of the workflow. New runs use it immediately; runs in progress keep the version they started on. Shows the diff and asks for confirmation unless you pass --yes.
| Flag | Description |
|---|---|
--message <text> | Label for the new version, shown in the version picker. |
--yes | Skip the confirmation prompt (for CI). |
✓ Applied Base Loop v6 · new runs use it. Runs in progress keep v5.
Updated revision in duun/workflows/base-loop.yamlIf someone applied a version after your file’s revision, apply stops with exit code 1 and conflict: live is v6, file is based on v5. Pull the latest version, merge your change and apply again.
duun workflows test
duun workflows test <file|workflow> [--live] [--input key=value]… [--force <step>=<outcome>]Runs a test of a workflow file or a live workflow and streams the result. By default it’s a dry run: notify, Send to URL and deliver steps are mocked, nothing leaves Duun and it costs $0. Testing a file tests the file’s contents without applying them.
| Flag | Description |
|---|---|
--live | Run a live test. This triggers real events and uses credits. |
--input key=value | Set run inputs, as with duun run. |
--force <step>=<outcome> | Force a Decide step’s outcome, for example --force size=Small. |
Dry run of Base Loop (file) on manual input
✓ plan 1m 32s $0.00
✓ size Small $0.00
– spec not this route
✓ implement 4m 10s $0.00
✓ deliver Would open a PR and merge it on green
Test passed · Small · 6m 02s · $0.00See Test runs.
Skills
duun skills list
duun skills listNAME AGENTS VISIBILITY VERSION DESCRIPTION
payments every agent workspace — Stripe, ledger invariants, reconciliation
postgres-migrations builder,op… public 1.2.0 Safe migrations, EXPLAIN reading, locksduun skills push
duun skills push <dir>Creates or updates a workspace skill from a directory containing a SKILL.md and any scripts or references it uses. The skill name comes from the SKILL.md frontmatter. See Skills.
duun skills push ./skills/stripe-webhooks✓ Updated #stripe-webhooks (SKILL.md + 3 files, 14 KB) · available to every agentduun skills publish
duun skills publish <dir|name> [--visibility <visibility>] [--bump patch|minor|major] [--notes <text>]Publishes a skill so other people can install it. Pushes the directory first if you pass one. The first publish is version 1.0.0; later publishes need --bump and --notes. See Publishing to Explore.
| Flag | Description |
|---|---|
--visibility <visibility> | private, team, workspace, link or public. Default workspace. |
--bump <part> | patch, minor or major. Required after the first version. |
--notes <text> | Release notes, shown in Explore’s changelog. Required with --bump. |
duun skills publish ./skills/stripe-webhooks --visibility public --bump minor --notes "Covers refund.updated events"Preflight
✓ SKILL.md and 3 files travel with it
✓ No secrets, repo names or webhook URLs found
✓ Published #stripe-webhooks 1.3.0 · Public on Explore
https://app.duun.ai/explore/skills/stripe-webhooksWebhooks
duun webhooks listen
duun webhooks listen --forward-to <url> [--events <list>]Receives your workspace’s webhook events and forwards them to a local URL, signed with a temporary secret that the command prints. Use it to develop a handler without a public endpoint. See Webhooks.
| Flag | Description |
|---|---|
--forward-to <url> | Required. Local URL to POST events to. |
--events <list> | Comma-separated event types. Default: all events. |
Shell completion
duun completion
duun completion zsh|bash|fishPrints a completion script. See Install and sign in.
Exit codes
| Code | Meaning |
|---|---|
0 | Success. |
1 | The command failed: an API error, a conflict, or a watched run that failed. |
2 | Usage error: unknown command, missing argument or invalid flag. |
3 | Validation problems in a workflow file (workflows diff and workflows apply). |
4 | Authentication failed: no key, an invalid or revoked key, or a missing scope. |
With --json, errors are printed to stderr in the API’s error format, including request_id. Include it when you contact support.
Workflow files
duun workflows pull, diff, apply and test use YAML files. The first line must be # duun.workflow/v1. The keys match the workflow config in the Workflows API, in snake_case.
| Key | Description |
|---|---|
id | Workflow id. Required for apply. |
revision | The live version this file was pulled from. Written by pull and apply; don’t edit it. |
name, description | Shown wherever the workflow is listed. |
factory | Factory id. |
triggers | What starts a run. See Triggers. |
limits | budget_usd, pause_at_pct, timeout_min, max_concurrent_runs. See Limits and budgets. |
inputs | Run inputs, available as {{input.<key>}}. |
rules | Natural-language rules with scope and enforce (instruct, check or block). |
steps | Up to 24 steps. See Step kinds. |
# duun.workflow/v1
id: wf_base9c1d
revision: 5
name: Base Loop
description: Plan, approve, build, test, review and merge one issue.
factory: fac_platform
triggers:
- kind: issue
provider: linear
team: Platform
label: ready
- kind: manual
limits:
budget_usd: 8
pause_at_pct: 80
timeout_min: 180
max_concurrent_runs: 4
inputs:
- key: issue
type: markdown
description: The issue to work on
rules:
- text: Never touch infra/prod without the operator agent.
scope: all
enforce: check
steps:
- id: plan
kind: agent
name: Plan with repo context
owner: { kind: agent, agent: builder, model: opus-5.5 }
instructions: |
Read {{trigger.issue.url}} and the code it touches.
Write a plan with the problem, approach, migration and tests.
done_criteria: The plan lists every file it will change.
skills: [payments, ledger]
outputs:
- { key: summary, type: markdown, description: The plan }
- { key: prs, type: number, description: Estimated PR count }
gate: { type: user_approval }
- id: size
kind: decide
name: Size and route
owner: { kind: orchestrator }
control:
mode: first_match
cases:
- id: small
label: Small
when: { name: expression, expr: "{{steps.plan.output.prs}} <= 1" }
activate: [implement]
otherwise: { activate: [spec] }
- id: spec
kind: agent
name: Write a spec
owner: { kind: agent, agent: builder, model: opus-5.5 }
instructions: Turn {{steps.plan.output.summary}} into a spec with acceptance criteria.
outputs:
- { key: doc, type: markdown }
gate: { type: user_approval }
- id: implement
kind: agent
name: Implement in isolated worktree
owner: { kind: agent, agent: builder, model: opus-5.5 }
depends_on: [size, spec]
instructions: Implement {{steps.plan.output.summary}}. Keep commits small.
limits: { timeout_min: 90, retries: 1 }
outputs:
- { key: summary, type: markdown }
- id: ci
kind: check
name: CI and contract tests
owner: { kind: orchestrator }
instructions: Run the checks and report each failure with its log.
gate:
type: ci_green
command: pnpm ci
on_fail: { return_to: implement, policy: retry_with_feedback, max_attempts: 3 }
- id: notify
kind: notify
name: Post the result in Slack
owner: { kind: orchestrator }
channel: { type: slack, channel: "#platform-ships" }
message: "Ready to merge: {{steps.implement.output.summary}}"
- id: deliver
kind: deliver
name: Open PR & merge on green
owner: { kind: orchestrator }
instructions: Open a PR from the run branch; merge when checks and reviews pass.
mode: merge_on_green