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 register-agent
Section titled “warren register-agent”refresh canopy and register one agent into warren’s cache
warren register-agent <name>Arguments
Section titled “Arguments”| Argument | Description |
|---|---|
<name> |
canopy prompt name (must be tagged ‘agent’) |
warren add-project
Section titled “warren add-project”clone a GitHub repo into the projects root and persist it
warren add-project <git-url> [options]Arguments
Section titled “Arguments”| Argument | Description |
|---|---|
<git-url> |
GitHub URL (https or git@) |
Options
Section titled “Options”| Option | Description | Default |
|---|---|---|
--default-branch <name> |
override the auto-detected default branch | — |
warren run
Section titled “warren run”spawn a one-shot run, tail events as NDJSON, and exit
warren run <agent> <project> [options]Arguments
Section titled “Arguments”| Argument | Description |
|---|---|
<agent> |
registered agent name |
<project> |
project id (prj_xxx) |
Options
Section titled “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 | — |
warren init
Section titled “warren init”scaffold a .warren/ directory (triggers.yaml + config.yaml) in a project repo
warren init [options]Options
Section titled “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
Section titled “warren config”.warren/ admin tools
warren config <subcommand>Subcommands:
warren config migrate
Section titled “warren config migrate”convert legacy .warren/defaults.json into the warren-5840 YAML layout (config.yaml + preview.yaml)
warren config migrate [options]Options
Section titled “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
Section titled “warren doctor”check warren’s environment: env vars, burrow socket, canopy clone
warren doctor [options]Options
Section titled “Options”| Option | Description | Default |
|---|---|---|
--no-auth |
skip the WARREN_API_TOKEN check (loopback dev mode) | — |
warren db
Section titled “warren db”database admin tools
warren db <subcommand>Subcommands:
warren db migrate-to-postgres
Section titled “warren db migrate-to-postgres”one-shot copy of a SQLite warren.db into a Postgres database
warren db migrate-to-postgres [options]Options
Section titled “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
Section titled “warren plan”dispatch and steer cloud plan-runs
warren plan <subcommand>Subcommands:
warren plan run
Section titled “warren plan run”dispatch a serial plan-run against a remote warren and tail events as NDJSON
warren plan run <plan-id> [options]Arguments
Section titled “Arguments”| Argument | Description |
|---|---|
<plan-id> |
seeds plan id (pl_xxx) |
Options
Section titled “Options”| Option | Description | Default |
|---|---|---|
--project <id> |
project id (prj_xxx) | required |
--agent <name> |
registered agent name | required |
--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 | — |
--no-follow |
dispatch and exit without tailing events | — |
--output <mode> |
output mode: ndjson (default) or pretty | ndjson |
warren plan cancel
Section titled “warren plan cancel”cancel a remote plan-run and its in-flight child run
warren plan cancel <plan-run-id> [options]Arguments
Section titled “Arguments”| Argument | Description |
|---|---|
<plan-run-id> |
plan-run id |
Options
Section titled “Options”| Option | Description | Default |
|---|---|---|
--output <mode> |
output mode: ndjson (default) or pretty | ndjson |
warren plan status
Section titled “warren plan status”render a plan-run’s child-state table with per-child cost + duration
warren plan status <plan-run-id> [options]Arguments
Section titled “Arguments”| Argument | Description |
|---|---|
<plan-run-id> |
plan-run id |
Options
Section titled “Options”| Option | Description | Default |
|---|---|---|
--output <mode> |
output mode: ndjson (default) or pretty | ndjson |
warren plan list
Section titled “warren plan list”list plan-runs, optionally filtered by project / state
warren plan list [options]Options
Section titled “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 serve
Section titled “warren serve”start the HTTP server (default in docker entrypoint)
warren serve [options]Options
Section titled “Options”| Option | Description | Default |
|---|---|---|
--no-auth |
boot without bearer-token auth (loopback only) | — |