CLI reference

Every contractor command and subcommand registered in the CLI entry point.

contractor is driven from the contractor CLI. This page lists every top-level command, its subcommands, and the flags they accept. Slash commands installed into AI providers live on the slash commands reference.

Global flags

Every command accepts these flags up front, before the subcommand:

Flag	Description
`--target <path>`	Filter to a specific repo. By default contractor uses the current working directory.
`--all`	Force the global view from inside a repo (used by `status`, `dashboard`, `blueprint list`, `blueprint graph`).
`--help`, `-h`	Print help for the most specific command in the args.

Global state lives under ~/.contractor/ (the global config file at ~/.contractor/config.yaml, the SQLite database at ~/.contractor/contractor.db, and per-run logs under ~/.contractor/projects/<encoded-repo>/logs/). Older repos may still carry a contractor/.state/ directory; it is no longer read at runtime — contractor doctor --fix will help migrate it.

Setup

Per-repo installation and AI provider integration.

`contractor repo`

Subcommand	Description
`repo install [--yes]`	Initialize the `contractor/` directory structure in the current repo.
`repo uninstall [--yes]`	Remove the `contractor/` directory.

`contractor ai`

Subcommand	Description
`ai install [provider...] [--global [path]] [--schema <name>] [--json]`	Install AI provider slash commands (e.g. Claude Code) into `.claude/commands/`. `--global` writes to `~/.claude/` (or a custom path); `--schema` selects which schema to render slash commands from.
`ai uninstall [provider...] [--global [path]] [--json]`	Remove AI provider slash commands.
`ai list [--json]`	List available providers and whether each is installed.

Blueprints

Create, inspect, validate, and archive blueprints.

`contractor blueprint`

Subcommand	Description
`blueprint new <name> [--scope <name>] [--schema <name>] [--description <text>] [--base <branch>] [--worktree\|--no-worktree]`	Create a new blueprint. `--base` selects the worktree's base branch; `--worktree`/`--no-worktree` opt in to or out of contractor-managed worktrees.
`blueprint ready <name>`	Mark a blueprint ready for implementation (sets `lifecycle: implement` in its `.contractor.yaml`).
`blueprint sync [--blueprint <name>]`	Merge requirement deltas into `contractor/requirements/` without archiving the blueprint.
`blueprint status [--blueprint <name>] [--json]`	Show artifact completion status for a blueprint. Auto-resolves the active blueprint when omitted.
`blueprint list [--all] [--scope <name>] [--json]`	List blueprints in the current repo (or across known repos in global scope). `--all` includes drafts.
`blueprint graph [--json]`	Show capability overlap between active blueprints and a suggested execution order.
`blueprint current [--json]`	Alias of `show` — print the active blueprint's metadata and artifact state.
`blueprint show [<name>] [--json]`	Show a blueprint's metadata and artifact state.
`blueprint instructions <artifact> [--blueprint <name>] [--json]`	Print the creation prompt for an artifact, with full context.
`blueprint phase <id> [--blueprint <name>] [--json]`	Print a phase definition (strategy, instruction, agents, tracks) from the blueprint's schema.
`blueprint validate [<name>] [--json]`	Validate artifact structure and format. With no name, validates every active blueprint.
`blueprint base <name>`	Print the blueprint's resolved base branch (used by the close phase).
`blueprint close <name> [--yes]`	Archive a completed blueprint and merge its requirements into `contractor/requirements/`.
`blueprint reject <name> [--yes]`	Reject a blueprint without applying its specs; cleans up the worktree and branch.

Worktrees

`contractor worktree`

Subcommand	Description
`worktree prepare [<blueprint>] [--force]`	Run the synthetic prepare step against a worktree. With no argument, infers the blueprint from the current worktree. `--force` re-runs even if the prepare marker is valid for the current HEAD.

Profiles

Manage the per-profile Claude usage cache.

`contractor profile`

Subcommand	Description
`profile list [--json]`	Show configured profiles with their cached `5h`, `7d`, and `7d-opus` usage.
`profile refresh [--id <id>] [--json]`	Probe every profile (or one by id) and update the cached usage rows.

Execution

Run pipelines, watch the dashboard, and keep the global state DB healthy.

`contractor run`

contractor run [--blueprint <name>] [--resume <id|last-failed>]
               [--backend <name>] [--model <name>] [--effort <level>]
               [--pipeline <name>] [--scope <name>]
               [--gate-after <step-id>]...

Spawns a detached pipeline-shim and tails its events. The active blueprint is auto-resolved when there is exactly one in the worktree.

Flag	Description
`--blueprint <name>`	Pin the run to a specific blueprint (useful when more than one is active).
`--resume <id\|last-failed>`	Re-spawn a previously failed pipeline run, preserving terminal step state. `last-failed` resolves to the most recent failed run for the current repo.
`--backend <name>`	Override the default agent backend (e.g. `claude`, `codex`).
`--model <name>`	Override the model passed to the backend (e.g. `opus[1m]`).
`--effort <level>`	Reasoning effort for backends that honor it. One of `low`, `medium`, `high`, `max`.
`--pipeline <name>`	Select a named pipeline from `contractor/config.yaml` or `~/.contractor/config.yaml`.
`--scope <name>`	Run as a scoped invocation; substituted into `{{scope}}` shell steps and gated by `when: scope` guards.
`--gate-after <step-id>`	Inject a gate after the named step. Repeatable.

Exit codes: 0 on completed, 1 on failed, 130 on cancelled (SIGINT).

Dashboards and daemons

Command	Description
`contractor dashboard [--target <path>] [--all]`	Launch the interactive TUI dashboard.
`contractor serve [--relay <url>] [--machine <name>] [--backend <name>] [--model <name>] [--effort <level>] [--token <token>]`	Run the local agent daemon for the web dashboard.

Health and maintenance

Command	Description
`contractor status [--json]`	Show pending cleanup work for the current repo (or globally with `--all`).
`contractor doctor [--fix]`	Report (or with `--fix`, repair) global DB health, schema-graph problems, partials wiring, and legacy `contractor/.state/` layouts.
`contractor logs <subcommand>`	List, tail, or print paths for runtime log files.
`contractor replay-model-usage [--dry-run]`	Rewrite `run_model_usage` from stored stream-json logs.
`contractor context log-event`	Log a hook event (reads JSON from stdin).

Other

Command	Description
`contractor completions <bash\|zsh>`	Generate shell completions.
`contractor version [--json]`	Print version and build info.
`contractor help [<command>]`	Print top-level or per-command help.

Shell completions

# bash
eval "$(contractor completions bash)"
 
# zsh
eval "$(contractor completions zsh)"