CLI Reference

The Defiant CLI (defiant) is the primary interface for managing the Conductor, projects, sprints, and configuration. It communicates with the Conductor via the Unix socket at ~/.defiant/ipc/conductor.sock.

Installation

npm install -g @defiant/cli
# or
pnpm add -g @defiant/cli

Global flags

These flags apply to all commands:

Flag	Description
`--json`	Output as JSON (useful for scripting)
`--quiet`	Suppress all output except errors
`--verbose`	Show detailed debug output
`--no-color`	Disable ANSI colors
`--config <path>`	Use a custom config file path

`defiant init`

Interactive setup wizard. Prompts for API keys and writes ~/.defiant/credentials.json and ~/.defiant/config.json.

defiant init
defiant init --non-interactive  # use environment variables instead of prompts

Environment variables (used by --non-interactive):

ANTHROPIC_API_KEY=sk-ant-...
GITHUB_TOKEN=ghp_...
SUPABASE_URL=https://xxx.supabase.co
SUPABASE_ANON_KEY=eyJ...
ASANA_PAT=1/...           # optional
SENTRY_DSN=https://...    # optional
POSTHOG_KEY=phc_...       # optional
STRIPE_SECRET_KEY=sk_...  # optional

`defiant watch`

Manage the Conductor daemon.

`defiant watch start`

Start the Conductor. Exits immediately; Conductor runs in the background.

defiant watch start
defiant watch start --log-level debug  # verbose logging
defiant watch start --port 0           # use a random port for the HTTP debug API

`defiant watch stop`

Stop the Conductor gracefully. Active sprints are checkpointed.

defiant watch stop
defiant watch stop --force  # kill immediately without checkpointing

`defiant watch status`

Show Conductor status, active sprints, and token usage.

defiant watch status

# Output:
# Conductor: running (PID 12345)
# Uptime: 4h 32m
# Active sprints: 2
#   spr_01hw...: BUILD (builder x2)
#   spr_01hw...: SHIP (reviewer, guardian)
# Token usage today: 847,302 / 2,000,000 (yellow)
# IPC socket: ~/.defiant/ipc/conductor.sock

`defiant watch install-service`

Install the Conductor as a system service (launchd on macOS, systemd on Linux).

defiant watch install-service
defiant watch uninstall-service

`defiant watch logs`

Tail the Conductor log.

defiant watch logs
defiant watch logs --lines 100  # last 100 lines
defiant watch logs --follow     # tail -f behavior

`defiant config`

Manage configuration.

`defiant config check`

Validate all configured credentials against their APIs.

defiant config check

`defiant config set`

Set a single credential or config value.

defiant config set ANTHROPIC_API_KEY sk-ant-...
defiant config set model claude-opus-4-7  # override default model
defiant config set token_budget_daily 1000000

`defiant config get`

Get a config value.

defiant config get ANTHROPIC_API_KEY
defiant config get model

`defiant config list`

List all config values (credentials redacted).

defiant config list

`defiant projects`

Manage projects.

`defiant projects list`

defiant projects list
defiant projects list --json

`defiant projects create`

defiant projects create \
  --name "my-app" \
  --repo "github.com/yourorg/my-app" \
  --vertical b2b-saas

Options:

Flag	Required	Description
`--name`	yes	Human-readable project name
`--repo`	yes	GitHub repo in `owner/name` format
`--vertical`	yes	One of: `solo-founder`, `b2b-saas`, `marketplace`, `fintech`, `healthcare`, `pe-portfolio`
`--branch`	no	Default branch (default: `main`)
`--deploy-url`	no	Production URL for smoke tests

`defiant projects show`

defiant projects show proj_01hw...

`defiant projects update`

defiant projects update proj_01hw... --vertical fintech
defiant projects update proj_01hw... --deploy-url https://myapp.com

`defiant projects delete`

defiant projects delete proj_01hw...
# Prompts for confirmation. Preserves event log.

`defiant sprint`

Manage sprints.

`defiant sprint create`

defiant sprint create \
  --project proj_01hw... \
  --goal "Add user profile page with avatar and activity feed"

# From a file
defiant sprint create \
  --project proj_01hw... \
  --goal-file sprint-goal.txt

Options:

Flag	Required	Description
`--project`	yes	Project ID
`--goal`	yes*	Sprint goal text
`--goal-file`	yes*	Path to a file containing the goal
`--priority`	no	`low`, `normal` (default), `high`
`--token-budget`	no	Override per-sprint token budget (default: 200k)
`--dry-run`	no	Run Captain’s validation only; do not start BUILD

`defiant sprint status`

defiant sprint status spr_01hw...
defiant sprint status spr_01hw... --follow   # stream events
defiant sprint status spr_01hw... --json

`defiant sprint list`

defiant sprint list --project proj_01hw...
defiant sprint list --state active
defiant sprint list --state complete --limit 20

`defiant sprint cancel`

defiant sprint cancel spr_01hw...
# Cancels a running sprint. Cleans up worktree. Does not revert committed code.

`defiant sprint retry`

Re-run a FAILED or BLOCKED sprint from the last successful checkpoint:

defiant sprint retry spr_01hw...
defiant sprint retry spr_01hw... --from-state PLAN  # restart from a specific state

`defiant sprint events`

defiant sprint events spr_01hw...
defiant sprint events spr_01hw... --type state_transition
defiant sprint events spr_01hw... --agent builder
defiant sprint events spr_01hw... --since "2026-05-05T14:00:00Z"

`defiant inbox`

Manage inbox items (issues requiring human attention).

`defiant inbox list`

defiant inbox list
defiant inbox list --priority critical
defiant inbox list --resolved  # show resolved items

`defiant inbox show`

defiant inbox show inbox_01hw...

`defiant inbox resolve`

defiant inbox resolve inbox_01hw... --response "Use the existing users table"

`defiant mandates`

Manage and check mandates.

`defiant mandates list`

defiant mandates list
defiant mandates list --project proj_01hw...  # includes vertical pack mandates
defiant mandates list --category security

`defiant mandates check`

defiant mandates check                          # check current working tree
defiant mandates check --project proj_01hw...   # check with project mandates
defiant mandates check --mandate mandate_7       # check a single mandate
defiant mandates check --path src/payments/      # check a subdirectory

`defiant mandates show`

defiant mandates show mandate_7
# Prints the full YAML for the mandate

`defiant medic`

Run the Medic agent on demand.

defiant medic diagnose --sprint spr_01hw...   # diagnose a failed sprint
defiant medic triage --sentry                 # triage recent Sentry errors
defiant medic triage --sentry --limit 10      # triage last 10 errors

`defiant learning`

Interact with the Learning Engine.

defiant learning stats
defiant learning patterns
defiant learning calibration
defiant learning reset --project proj_01hw...

`defiant --version`

defiant --version
# Defiant CLI 2.0.0

Exit codes

Code	Meaning
`0`	Success
`1`	General error
`2`	Configuration error (missing credentials, bad config)
`3`	Conductor not running
`4`	Sprint error (blocked, failed)
`5`	Mandate violation