Run one-shot with the CLI | Docs

One-shot mode runs the packet loop from your terminal. It prepares the repository, moves each selected board ticket through implementation, syncs packet updates back to SwarmCraft, and moves completed customer one-shot work to done by default.

Use this flow when a project board should be set up and advanced before the customer continues in VS Code or the browser.

If you prefer to start from VS Code, run SwarmCraft: Run One-Shot with CLI after the CLI is installed and signed in. VS Code launches the same swarmcraft one-shot command and records the manifest path in the SwarmCraft output channel.

During a run, the CLI prints ticket and stage progress. Agent output is written under:

.swarmcraft/runs/<run-id>/logs/

Start from a clean repository

Commit or stash unrelated changes first:

git status --short

The CLI refuses a dirty workspace by default because one-shot work may edit many files. Use --allow-dirty only when you intentionally want the run to start from existing local changes.

Run the board

Start with a limited run when you are proving a new customer setup:

swarmcraft one-shot \
  --project <project-id> \
  --workspace . \
  --agent-provider codex \
  --ticket-limit 1 \
  --max-agent-requests 6 \
  --commit-policy done

Run the full board after the first ticket proves the setup:

swarmcraft one-shot \
  --project <project-id> \
  --workspace . \
  --agent-provider codex \
  --max-agent-requests 40 \
  --commit-policy done

Use --agent-provider copilot for the Copilot CLI, or use --agent-provider custom --agent-command '<command with {command}>' for a different local agent wrapper.

Lane policies

The customer CLI one-shot policy is:

implementation runs in doing
checking is off
reviewing is off
completed tickets move to done
no local commit is created unless --commit-policy done is supplied

Enable extra lanes only when an internal or customer run explicitly needs them:

swarmcraft one-shot \
  --project <project-id> \
  --workspace . \
  --agent-provider codex \
  --checking on \
  --reviewing on

--checking on runs the checking lane. --reviewing on stops accepted work in reviewing instead of moving it to done. --commit-policy done creates a local git commit for completed ticket changes.

Budgets and credentials

Limit the number of agent stages:

swarmcraft one-shot \
  --project <project-id> \
  --workspace . \
  --agent-provider codex \
  --max-agent-requests 40

If the selected agent writes cost telemetry, require and cap it:

swarmcraft one-shot \
  --project <project-id> \
  --workspace . \
  --agent-provider custom \
  --agent-command '<command with {command}>' \
  --agent-api-key-env-name MY_AGENT_KEY \
  --agent-env-file .env/agent.env \
  --require-cost-telemetry \
  --max-agent-spend-usd 25

The CLI passes only a restricted environment to the agent process by default. Use --agent-api-key-env-name when one explicit credential should be made available.

Resume and status

Each run writes a manifest under:

.swarmcraft/runs/<run-id>/manifest.json

Check progress:

swarmcraft status --run <run-id> --workspace .

Resume after a failed command, terminal cancellation, or machine restart:

swarmcraft resume --run <run-id> --workspace .

Resume keeps completed tickets and restarts from the last safe incomplete ticket.

Recovery

If SwarmCraft reports a stale revision, refresh the project board, inspect the packet, and rerun resume. A stale revision means the board changed after the packet was written.

If an agent stage fails, read the terminal output and the run manifest, fix local setup or agent credentials, then run resume.

If the repository has partial local changes, review git status --short before resuming. Commit, stash, or discard only changes you understand.

If a packet identity or lane mismatch appears, stop and inspect the packet frontmatter before editing the board. The CLI blocks these cases to avoid syncing the wrong ticket.

Support bundle

Collect a redacted support bundle when you need help diagnosing a run:

swarmcraft support-bundle --run <run-id> --workspace .

The bundle is written under:

.swarmcraft/runs/<run-id>/support-bundle/

It includes a redacted manifest, run id, selected policy, failed stage details, and artifact paths. Review the files before sharing them with support.