CLI reference

Control plane and UI for cloud-based custom agents

Every command below is extracted from src/cli/main.ts at the pinned upstream ref. Run warren --help for the same list from the binary you have installed.

`warren add-project`

warren add-project <git-url> [options]

Arguments

Argument	Description
`<git-url>`	GitHub URL (https or git@)

Options

Option	Description	Default
`--default-branch <name>`	override the auto-detected default branch	—

`warren run`

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

warren run <agent> <project> [options]

Arguments

Argument	Description
`<agent>`	registered agent name
`<project>`	project id (prj_xxx)

Options

Option	Description	Default
`-p, --prompt <text>`	prompt text the agent receives	required
`--trigger <label>`	run trigger label	`cli`
`--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	—

`warren init`

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

warren init [options]

Options

Option	Description	Default
`--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	—

`warren config`

.warren/ admin tools

warren config <subcommand>

Subcommands:

warren config migrate

`warren config migrate`

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

warren config migrate [options]

Options

Option	Description	Default
`--project <id>`	target a registered project by id (writes into its warren clone)	—
`--cwd <path>`	target a directory on disk (defaults to process.cwd())	—

`warren doctor`

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

warren doctor [options]

Options

Option	Description	Default
`--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	—

`warren db`

database admin tools

warren db <subcommand>

Subcommands:

warren db migrate-to-postgres

`warren db migrate-to-postgres`

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

warren db migrate-to-postgres [options]

Options

Option	Description	Default
`--from <sqlite>`	source SQLite path or URL (bare path, sqlite://, file://, :memory:)	required
`--to <pg-url>`	target Postgres URL (postgres:// or postgresql://)	required

`warren plan`

dispatch and steer cloud plan-runs

warren plan <subcommand>

Subcommands:

warren plan run
warren plan cancel
warren plan status
warren plan list

`warren plan run`

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

warren plan run [plan-id] [options]

Arguments

Argument	Description
`[plan-id]`	seeds plan id (pl_xxx); mutually exclusive with –issues

Options

Option	Description	Default
`--project <id>`	project id (prj_xxx)	required
`--agent <name>`	registered agent name	required
`--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>`	output mode: ndjson (default) or pretty	`ndjson`

`warren plan cancel`

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

warren plan cancel <plan-run-id> [options]

Arguments

Argument	Description
`<plan-run-id>`	plan-run id

Options

Option	Description	Default
`--output <mode>`	output mode: ndjson (default) or pretty	`ndjson`

`warren plan status`

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

warren plan status <plan-run-id> [options]

Arguments

Argument	Description
`<plan-run-id>`	plan-run id

Options

Option	Description	Default
`--output <mode>`	output mode: ndjson (default) or pretty	`ndjson`

`warren plan list`

list plan-runs, optionally filtered by project / state

warren plan list [options]

Options

Option	Description	Default
`--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>`	output mode: ndjson (default) or pretty	`ndjson`

`warren projects`

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

warren projects

`warren serve`

start the HTTP server (default in docker entrypoint)

warren serve [options]

Options

Option	Description	Default
`--no-auth`	boot without bearer-token auth (loopback only)	—