Skip to content

cli-reference.md

Latest commit

 

History

History
386 lines (278 loc) · 12.8 KB

cli-reference.md

File metadata and controls

386 lines (278 loc) · 12.8 KB
Raw

warren CLI reference

This page enumerates every warren command with its arguments, flags, and the stable exit-code table. It's derived directly from the commander program definition built by src/cli/main.ts — the same walk warren prime prints at agent session start — so it can't drift from the running CLI.

To refresh: bun run gen:cli-ref. To check (CI mode): bun run gen:cli-ref:check.

Total commands: 22.

Global options

Flag Description
-V, --version output the version number
--output <mode> global output mode: ndjson|json|pretty (default ndjson; agents script against ndjson/json, pretty is the human opt-in)
-h, --help print command help (commander built-in)

Every remote-capable command also accepts --url <url> / --token <token>, listed per command below. Resolution precedence everywhere: flags > env > client config file > built-in default.

Environment

Variable Summary
WARREN_BASE_URL warren server base URL (default http://localhost:8080)
WARREN_API_TOKEN bearer token for the server (required unless WARREN_AUTH=public); note the Bun CLI auto-loads .env from your cwd — a stale token there overrides the client config file on every command (warren login still prefers a piped stdin token over it)
WARREN_CLIENT_CONFIG override the client config path (default ~/.warren/client.json, written by warren login)

Commands

warren add-project

register a project on the warren server (POST /projects)

warren add-project [options] <git-url>
Argument Required Description
<git-url> yes GitHub URL (https or git@)
Flag Required Default Description
--default-branch <name> override the auto-detected default branch
--url <url> warren server base URL (env WARREN_BASE_URL)
--token <token> bearer token (env WARREN_API_TOKEN)

warren run

dispatch a one-shot run against the warren server, tail events as NDJSON, and exit

warren run [options] <agent> <project>
Argument Required Description
<agent> yes registered agent name
<project> yes project id (prj_xxx)
Flag Required Default Description
-p, --prompt <text> yes prompt text the agent receives
--trigger <label> "cli" run trigger label
--provider <name> per-run override of agent frontmatter.provider
--model <name> per-run override of agent frontmatter.model
--max-cost-usd <usd> per-run USD spend cap; wins over the agent's own and the project default
--seed <id> link the run to a seeds issue (POST /runs seedId)
--base-commit <sha> pin the workspace cut to a 40-hex commit SHA
--url <url> warren server base URL (env WARREN_BASE_URL)
--token <token> bearer token (env WARREN_API_TOKEN)

warren init

scaffold a .warren/ directory (triggers.yaml + config.yaml) in a project repo

warren init [options]
Flag Required Default Description
--project <id> target a registered project by id (writes into its warren clone)
--cwd <path> target a directory on disk (defaults to process.cwd())
--default-role <name> pin defaults.defaultRole to this registered agent
--url <url> warren server base URL (env WARREN_BASE_URL)
--token <token> bearer token (env WARREN_API_TOKEN)

warren config

Command group — see the subcommands below.

.warren/ admin tools

warren config [options] [command]

warren config migrate

convert legacy .warren/defaults.json into the warren-5840 YAML layout (config.yaml + preview.yaml)

warren config migrate [options]
Flag Required Default Description
--project <id> target a registered project by id (writes into its warren clone)
--cwd <path> target a directory on disk (defaults to process.cwd())
--url <url> warren server base URL (env WARREN_BASE_URL)
--token <token> bearer token (env WARREN_API_TOKEN)

warren doctor

check the client's view of a warren server (reachable? auth valid? version match?)

warren doctor [options]
Flag Required Default Description
--local run the deployment-side checks instead (env vars, sandbox runtime, bwrap, DB)
--no-auth skip the auth check (loopback dev mode)
--verbose print raw probe/driver output (withheld from check messages) to stderr
--url <url> warren server base URL (env WARREN_BASE_URL)
--token <token> bearer token (env WARREN_API_TOKEN)

warren db

Command group — see the subcommands below.

database admin tools

warren db [options] [command]

warren db migrate-to-postgres

one-shot copy of a SQLite warren.db into a Postgres database

warren db migrate-to-postgres [options]
Flag Required Default Description
--from <sqlite> yes source SQLite path or URL (bare path, sqlite://, file://, :memory:)
--to <pg-url> yes target Postgres URL (postgres:// or postgresql://)

warren plan

Command group — see the subcommands below.

dispatch and steer cloud plan-runs

warren plan [options] [command]

warren plan run

dispatch a serial plan-run against a remote warren and tail events as NDJSON

warren plan run [options] [plan-id]
Argument Required Description
[plan-id] seeds plan id (pl_xxx); mutually exclusive with --issues
Flag Required Default Description
--project <id> yes project id (prj_xxx)
--agent <name> yes registered agent name
--issues <ids> comma-separated ordered issue-id list (plan-run without a plan-capable tracker)
--prompt-template <text> per-child prompt template override
--ref <git-ref> git ref to clone child workspaces from
--provider <name> per-run override of agent frontmatter.provider
--model <name> per-run override of agent frontmatter.model
--max-cost-usd <usd> per-child USD spend cap applied to every child dispatch
--no-follow dispatch and exit without tailing events
--output <mode> "ndjson" output mode: ndjson (default) or pretty
--url <url> warren server base URL (env WARREN_BASE_URL)
--token <token> bearer token (env WARREN_API_TOKEN)

warren plan cancel

cancel a remote plan-run and its in-flight child run

warren plan cancel [options] <plan-run-id>
Argument Required Description
<plan-run-id> yes plan-run id
Flag Required Default Description
--output <mode> "ndjson" output mode: ndjson (default) or pretty
--url <url> warren server base URL (env WARREN_BASE_URL)
--token <token> bearer token (env WARREN_API_TOKEN)

warren plan status

render a plan-run's child-state table with per-child cost + duration

warren plan status [options] <plan-run-id>
Argument Required Description
<plan-run-id> yes plan-run id
Flag Required Default Description
--output <mode> "ndjson" output mode: ndjson (default) or pretty
--url <url> warren server base URL (env WARREN_BASE_URL)
--token <token> bearer token (env WARREN_API_TOKEN)

warren plan list

list plan-runs, optionally filtered by project / state

warren plan list [options]
Flag Required Default Description
--project <id> only plan-runs for this project (prj_xxx)
--state <state> only plan-runs in this state (queued|running|succeeded|failed|cancelled)
--output <mode> "ndjson" output mode: ndjson (default) or pretty
--url <url> warren server base URL (env WARREN_BASE_URL)
--token <token> bearer token (env WARREN_API_TOKEN)

warren projects

list the projects registered on the warren server (GET /projects)

warren projects [options]
Flag Required Default Description
--url <url> warren server base URL (env WARREN_BASE_URL)
--token <token> bearer token (env WARREN_API_TOKEN)

warren show

render a run's detail (GET /runs/:id; json mode is the raw run document)

warren show [options] <run-id>
Argument Required Description
<run-id> yes run id
Flag Required Default Description
--summary emit a compact projection (id, state, failureReason, prUrl, costUsd, endedAt)
--url <url> warren server base URL (env WARREN_BASE_URL)
--token <token> bearer token (env WARREN_API_TOKEN)

warren wait

poll a run to its terminal state (SDK waitForRun; exit 0 on succeeded)

warren wait [options] <run-id>
Argument Required Description
<run-id> yes run id
Flag Required Default Description
--timeout <seconds> overall wait budget in seconds (default 1800)
--summary emit a compact projection (id, state, failureReason, prUrl, costUsd, endedAt)
--url <url> warren server base URL (env WARREN_BASE_URL)
--token <token> bearer token (env WARREN_API_TOKEN)

warren tail

stream a run's events (GET /runs/:id/events; SIGINT detaches, exit 130)

warren tail [options] <run-id>
Argument Required Description
<run-id> yes run id
Flag Required Default Description
--no-follow drain the current backlog and exit instead of following
--from-seq <n> replay only events after this seq
--url <url> warren server base URL (env WARREN_BASE_URL)
--token <token> bearer token (env WARREN_API_TOKEN)

warren cancel

cancel a non-terminal run (POST /runs/:id/cancel; idempotent)

warren cancel [options] <run-id>
Argument Required Description
<run-id> yes run id
Flag Required Default Description
--reason <text> operator note recorded on the cancel
--url <url> warren server base URL (env WARREN_BASE_URL)
--token <token> bearer token (env WARREN_API_TOKEN)

warren login

verify a base URL + token against the server and persist them to the client config

warren login [options]
Flag Required Default Description
--url <url> warren server base URL (env WARREN_BASE_URL)
--token <token> bearer token (env WARREN_API_TOKEN)

warren prime

emit agent session context: command reference, env contract, exit codes, workflows

warren prime [options]

warren serve

start the HTTP server (default in docker entrypoint)

warren serve [options]
Flag Required Default Description
--no-auth boot without bearer-token auth (loopback only)

warren up

boot warren for a fresh machine: detect the runtime, default the data dir, serve, and log the operator in

warren up [options]
Flag Required Default Description
--no-open do not open the UI in a browser (the setup URL is still printed)
--no-wizard skip the first-boot credential wizard (also automatic when stdin is not a TTY)

Exit codes

Code Name Summary
0 success the command completed successfully
1 run-failed the dispatched run/plan-run reached a non-success terminal state, or the command failed for any other reason
2 usage-error bad flags or arguments (missing required option, invalid --output value, validation error)
3 server-unreachable the warren server did not answer the pre-flight probe
4 auth-rejected the server rejected the bearer token (HTTP 401/403)
130 sigint-detach operator detached a live event tail with SIGINT; the remote run keeps going