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.

FlagDescription
--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 whoami

Prints the signed-in member, workspace, profile and the key’s scopes.

alex@acme.dev on acme (ws_acme)
Profile: default · Key: duun_sk_…f81c · Scopes: runs:read runs:write factories:read workflows:read workflows:write skills:write

Runs

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.

FlagDescription
--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=valueSet a run input. Repeat for several. Values are strings; use key=@file.md to read a file.
--title <text>Run title. Defaults to the issue title or the first line of the prompt.
--watchStay 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 here

With --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.

FlagDescription
--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 waiting
ID             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 staging

duun 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.

FlagDescription
--follow, -fKeep 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 --follow
11: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 list
ID              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       Mobile

duun 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     Hotfix

duun 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.yaml

duun 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.yaml
Base 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.

FlagDescription
--message <text>Label for the new version, shown in the version picker.
--yesSkip 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.yaml

If 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.

FlagDescription
--liveRun a live test. This triggers real events and uses credits.
--input key=valueSet 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.00

See Test runs.

Skills

duun skills list

duun skills list
NAME                  AGENTS          VISIBILITY   VERSION   DESCRIPTION
payments              every agent     workspace    —         Stripe, ledger invariants, reconciliation
postgres-migrations   builder,op…     public       1.2.0     Safe migrations, EXPLAIN reading, locks

duun 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 agent

duun 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.

FlagDescription
--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-webhooks

Webhooks

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.

FlagDescription
--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|fish

Prints a completion script. See Install and sign in.

Exit codes

CodeMeaning
0Success.
1The command failed: an API error, a conflict, or a watched run that failed.
2Usage error: unknown command, missing argument or invalid flag.
3Validation problems in a workflow file (workflows diff and workflows apply).
4Authentication 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.

KeyDescription
idWorkflow id. Required for apply.
revisionThe live version this file was pulled from. Written by pull and apply; don’t edit it.
name, descriptionShown wherever the workflow is listed.
factoryFactory id.
triggersWhat starts a run. See Triggers.
limitsbudget_usd, pause_at_pct, timeout_min, max_concurrent_runs. See Limits and budgets.
inputsRun inputs, available as {{input.<key>}}.
rulesNatural-language rules with scope and enforce (instruct, check or block).
stepsUp to 24 steps. See Step kinds.
duun/workflows/base-loop.yaml
# 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

    Type to search the docs, help center and blog.