Colony CLI Reference

Colony CLI Reference

Complete command reference for the colony CLI, organized by category.

Note: Every synopsis and option description is sourced verbatim from the .command()/.description()/.option() registrations in packages/cli/src/index.ts and the individual command files, so this page matches colony <command> --help.

Slash commands vs. CLI commands: The colony CLI runs on your machine to manage pipeline infrastructure (init, start, stop, check, why, etc.). Slash commands (/colony:retry, /colony:state, /colony:cancel, etc.) are a separate control surface — they are posted as GitHub issue comments and processed by the Sprint Master to control individual in-flight issues. See the Slash Command Reference for the full slash command reference.

---

Contents

• Setup & Init
• Pipeline Lifecycle
• Diagnostics & Recovery
• Strategy & Tracks
• Deployment & Process Control
• Advanced

---

Global Options

These options are accepted by most commands:

Option	Description
-c, --config <path>	Path to colony.config.yaml (default: auto-detected from ./colony.config.yaml or ~/.colony/config.yaml)

---

Setup & Init

colony quickstart

colony quickstart [options]

Set up Colony from scratch: validate prerequisites, generate config, initialize repos, and start agents.

Option	Description
--dry-run	Preview what quickstart would do without executing

The interactive wizard guides you through six phases: environment validation, repository configuration, database setup, cost preview, launch, and first issue creation. If interrupted, re-running resumes from the last successful phase.

---

colony init

colony init [options]

Initialize Colony: validate credentials and create pipeline labels.

Option	Description
-c, --config <path>	Path to colony.config.yaml
-r, --repo <owner/repo>	Initialize only a specific repo
--conventions <language>	Write a conventions template (ruby, rails, python, go, rust, java, node, typescript)
--force	Overwrite existing .colony/conventions.md
--generate	Interactively generate a colony.config.yaml

---

colony bootstrap

colony bootstrap [stack] [name] [options]

Scaffold a new Colony-managed repo from a stack template.

Valid stacks: nextjs, rails, cloudflare-workers, django, go-cli

Option	Description
-c, --config <path>	Path to colony.config.yaml
--with-d1	Add D1 database binding with Drizzle (cloudflare-workers)
--with-kv	Add KV namespace binding (cloudflare-workers)
--with-cron	Add cron trigger and scheduled handler (cloudflare-workers)
--with-resend	Add Resend email integration (nextjs, cloudflare-workers)
--with-stripe	Add Stripe payment integration (nextjs)
--with-postmark	Add Postmark transactional email integration (rails, django)
--with-r2	Add Cloudflare R2 object storage integration (nextjs, django)
--with-scheduled-tasks	Add Celery + django-celery-beat for scheduled tasks (django)
--with-sidekiq	Add Sidekiq background job processing (rails)
--with-pundit	Add Pundit authorization policies (rails)
--with-hotwire-cable	Add Hotwire (Turbo + Stimulus) with Action Cable (rails)
--with-sqlite	Add SQLite storage via modernc.org/sqlite (go-cli)
--with-goreleaser	Add GoReleaser release configuration (go-cli)

See Bootstrap Guide for a full walkthrough.

---

colony bootstrap configure

colony bootstrap configure [options]

Apply conventions and tool ignore configs to the current repo.

Option	Description
-c, --config <path>	Path to colony.config.yaml
--dry-run	Print what would be done without writing

---

colony colonize

colony colonize [options]

Generate .colony/conventions.md by analyzing the target repository.

Option	Description
-c, --config <path>	Path to colony.config.yaml
-r, --repo <owner/repo>	Target a specific repo

---

colony scan-conventions

colony scan-conventions [options]

Auto-detect stack and generate .colony/conventions.md.

Option	Description
-c, --config <path>	Path to colony.config.yaml
-r, --repo <owner/repo>	Target a specific repo
--stack <templates>	Force specific template keys (comma-separated)
--output <path>	Output file path
--dry-run	Print detected stack without writing
--force	Overwrite existing conventions.md
--with-analysis	Use LLM to refine conventions (costs API credits)

---

Pipeline Lifecycle

colony start

colony start [agent] [options]

Start agent processes (all if no agent specified).

Option	Description
-c, --config <path>	Path to colony.config.yaml
--native	Bypass deployment-mode guard and run native host processes even when deployment.mode is docker-compose or apple-container

---

colony stop

colony stop [agent] [options]

Stop agent processes (all if no agent specified).

Option	Description
-c, --config <path>	Path to colony.config.yaml

---

colony status

colony status [options]

Show pipeline status and agent health.

Option	Description
-c, --config <path>	Path to colony.config.yaml
--check	Validate setup: check config, provider connectivity, and labels
--db	Query Postgres directly for pipeline state (skips PID files and health endpoints)
--database-url <url>	Database URL for --db mode; overrides DATABASE_URL and config
--pid	Use local PID files and GitHub for status instead of the database (legacy local-dev path)
-w, --watch	Re-poll and re-render DB status on an interval until Ctrl-C
--interval <seconds>	Refresh interval in seconds for --watch (default: 10, minimum: 5)
--json	Machine-readable JSON output — emits {repos, globalCost, configReloads} for DB mode; {mode:'pid', agents} for legacy PID mode; raw overview object for Cloud mode. Incompatible with --watch.

---

colony pause

colony pause <issue-number> [options]

Pause processing of an issue without permanently blocking it.

Option	Description
-c, --config <path>	Path to colony.config.yaml
-r, --repo <owner/repo>	Target a specific repo
--json	Machine-readable JSON output

---

colony resume

colony resume <issue-number> [options]

Resume a paused issue (sprint master restores original state on next poll).

Option	Description
-c, --config <path>	Path to colony.config.yaml
-r, --repo <owner/repo>	Target a specific repo
--json	Machine-readable JSON output

---

colony unblock

colony unblock <issue-number> [options]

Clear a stuck is_blocked flag and re-queue the issue.

Option	Description
-c, --config <path>	Path to colony.config.yaml
-r, --repo <owner/repo>	Target a specific repo
--json	Machine-readable JSON output

---

colony issue transition

colony issue transition <issue-number> --state <target> [options]

Transition an issue to a new pipeline state.

Option	Description
-s, --state <target>	Target state (required)
-c, --config <path>	Path to colony.config.yaml
-r, --repo <owner/repo>	Target a specific repo
--json	Machine-readable JSON output

---

colony issue history

colony issue history <issue-number> [options]

Show structured lifecycle timeline for an issue (transitions, costs, telemetry, dead letters).

Option	Description
-c, --config <path>	Path to colony.config.yaml
-r, --repo <owner/repo>	Target a specific repo
--json	Machine-readable JSON output (one object)

---

colony plan import

colony plan import <path> [options]

File issues from a superpowers plan.

Option	Description
--dry-run	Show what would be created without filing
-r, --repo <owner/repo>	Target repo (overrides config default)
-c, --config <path>	Path to colony.config.yaml

See Plan Import Guide for the plan file format.

---

Diagnostics & Recovery

colony check

colony check [options]

Progressive validation: config, credentials, database, repository, labels, runtime.

Option	Description
-c, --config <path>	Path to colony.config.yaml
--stage <name>	Run only the named stage (config, credentials, database, repository, labels, runtime)
--fix	Auto-remediate common setup failures (exclusions, env vars, config placeholders)
--docker	Force container-aware checks (auto-detected from deployment.mode — only needed to override)

Aliases: colony doctor and colony preflight are aliases for specific stages of colony check:

• colony doctor — delegates to colony check running the config, credentials, database, repository, and labels stages.
• colony preflight — delegates to colony check --stage database + --stage runtime to validate end-to-end pipeline readiness (migrations, tables, intake mode, worker health).

Both aliases support the same -c/--config and --docker options. colony check is the recommended entry point; the aliases remain for backward compatibility.

---

colony doctor

colony doctor [options]

Validate Colony setup: config, provider access, API keys, CLI tools, and ports.

Alias: Delegates to colony check stages config, credentials, database, repository, and labels. Prefer colony check for new scripts.

Option	Description
-c, --config <path>	Path to colony.config.yaml
--docker	Force container-aware checks
--fix	Auto-remediate common setup failures

---

colony preflight

colony preflight [options]

Validate end-to-end pipeline readiness: migrations, tables, intake mode, and worker health.

Alias: Delegates to colony check --stage database + --stage runtime. Prefer colony check for new scripts.

Option	Description
-c, --config <path>	Path to colony.config.yaml

---

colony validate-config

colony validate-config [options]

Show effective resolved config and verify env vars and workspace directories are present.

Option	Description
-c, --config <path>	Path to colony.config.yaml
--json	Machine-readable JSON output — emits the effective loaded config (with database.url password redacted) and skips the interactive check output. Use colony check --stage config if you want pass/fail validation results.

---

colony validate-issue

colony validate-issue [issue] [options]

Pre-flight check: validate issue structure and estimate cost.

Option	Description
-c, --config <path>	Path to colony.config.yaml
-r, --repo <owner/repo>	Target a specific repo
-f, --file <path>	Validate a local markdown file as a draft issue

---

colony why

colony why <issue-number> [options]

Diagnose why an issue is stuck, blocked, or in an unexpected state.

Option	Description
-c, --config <path>	Path to colony.config.yaml
-r, --repo <owner/repo>	Target a specific repo
--json	Machine-readable JSON output (one object)

---

colony inspect

colony inspect <issue-number> [options]

Show per-issue cost and timeline.

Option	Description
-c, --config <path>	Path to colony.config.yaml
-r, --repo <owner/repo>	Target a specific repo
-t, --tasks	Show work_task history from Postgres
-f, --findings	Show polish/integration findings from Postgres
--json	Machine-readable JSON output

---

colony logs

colony logs [agent] [options]

Tail agent log files interleaved (like docker-compose logs -f).

Option	Description
-c, --config <path>	Path to colony.config.yaml
-n, --tail <lines>	Number of lines to show from end of each log (default: 50)
-f, --follow	Follow log output (stream new lines as they are written)
-l, --level <level>	Minimum log level to show (debug, info, warn, error, fatal)
-i, --issue <number>	Filter log lines where the JSON issue field matches N
-g, --grep <pattern>	Regex match against the msg field (plain text match for non-JSON lines)
-a, --agent <name>	Filter by Pino name field (agent/process name in JSON)
-s, --since <duration>	Show only lines within this window from now (e.g. 1h, 30m, 2d)
-j, --json	Machine-readable NDJSON output (one JSON object per line)

---

colony events

colony events [options]

Query structured pipeline events.

Option	Description
-c, --config <path>	Path to colony.config.yaml
-r, --repo <owner/repo>	Filter by repo
-i, --issue <number>	Filter by issue number
-t, --type <event_type>	Filter by event type
-s, --since <date>	Filter events after date (YYYY-MM-DD)
--json	Machine-readable NDJSON output (one JSON object per line)

---

colony tasks

colony tasks [options]

List work tasks from Postgres with optional filters.

Option	Description
-c, --config <path>	Path to colony.config.yaml
-r, --repo <owner/repo>	Filter by repo
-s, --status <status>	Filter by status (pending, claimed, complete, failed, cancelled)
-t, --type <type>	Filter by task type (analyze, develop, review, merge, plan, sweep, review-external)
-i, --issue <number>	Filter by issue number
--since <duration>	Show tasks created after this duration ago (e.g. 24h, 7d, 30m)
--json	Machine-readable NDJSON output (one JSON object per line)

---

colony workers

colony workers [options]

List worker pool liveness: heartbeat freshness, current task, uptime.

Option	Description
-c, --config <path>	Path to colony.config.yaml
--json	Machine-readable JSON output (one object)

colony workers reclaim

colony workers reclaim <workerId> [options]

Force-reclaim the currently-claimed task for a worker.

Option	Description
-c, --config <path>	Path to colony.config.yaml
--json	Machine-readable JSON output (one object)

---

colony issues

colony issues [options]

List pipeline issues from Postgres grouped by state.

Option	Description
-c, --config <path>	Path to colony.config.yaml
-s, --state <state>	Filter to a specific pipeline state
--blocked	Show only blocked issues with last error
--paused	Show only paused issues
--label-drift	Show issues where Postgres state and stored labels have diverged
-r, --repo <owner/repo>	Filter by repo
--errors	Show recent agent run failures across all issues
--since <hours>	Hours to look back for --errors (default: 24)
--json	Machine-readable NDJSON output (one JSON object per line)

---

colony dead-letters

colony dead-letters [options]

List and manage dead letter transitions (failed state transitions that could not be retried automatically).

Option	Description
-c, --config <path>	Path to colony.config.yaml
-r, --repo <owner/repo>	Filter by repo
--json	Machine-readable NDJSON output (one JSON object per line)

colony dead-letters list

colony dead-letters list [options]

List unresolved dead letter transitions.

Option	Description
-c, --config <path>	Path to colony.config.yaml
-r, --repo <owner/repo>	Filter by repo
--json	Machine-readable NDJSON output (one JSON object per line)

colony dead-letters retry

colony dead-letters retry <id> [options]

Retry a specific dead letter transition (re-enqueue the task).

Option	Description
-c, --config <path>	Path to colony.config.yaml

colony dead-letters resolve

colony dead-letters resolve <id> [options]

Resolve (acknowledge) a single dead letter transition without retrying it.

Option	Description
-c, --config <path>	Path to colony.config.yaml

colony dead-letters resolve-all

colony dead-letters resolve-all [options]

Resolve all dead letter transitions (mark as acknowledged).

Option	Description
-c, --config <path>	Path to colony.config.yaml
-r, --repo <owner/repo>	Filter by repo

---

colony metrics

colony metrics [options]

Show pipeline metrics: throughput, cycle times, success rates, and bottlenecks.

Option	Description
-c, --config <path>	Path to colony.config.yaml
-d, --days <number>	Lookback window in days (default: 30)
--json	Machine-readable JSON output — emits { repos: [{ repo: "owner/repo", metrics: { ... } }] }

---

colony digest

colony digest [options]

Generate pipeline daily digest on-demand.

Option	Description
-c, --config <path>	Path to colony.config.yaml
--json	Machine-readable JSON output (one object)

---

Strategy & Tracks

colony strategy charter set

colony strategy charter set --repo <owner/repo> --from <file> [options]

Create a new charter version from a YAML or JSON file.

The charter file must be a YAML or JSON object with a goals string and an envelope object containing max_auto_size (small|medium|large|epic), prefer (string array), avoid (string array), and escalate_when (string array).

Option	Description
-r, --repo <owner/repo>	Target repo (owner/repo) (required)
-f, --from <file>	Path to charter YAML/JSON file (required)
--author <name>	Author recorded on the charter (default: operator)
-c, --config <path>	Path to colony.config.yaml

---

colony strategy charter show

colony strategy charter show --repo <owner/repo> [options]

Print the active charter for a repo.

Option	Description
-r, --repo <owner/repo>	Target repo (owner/repo) (required)
-c, --config <path>	Path to colony.config.yaml

---

colony strategize

colony strategize --repo <owner/repo> [options]

Run one strategize cycle on demand and print the proposed snapshot version.

Option	Description
-c, --config <path>	Path to colony.config.yaml
-r, --repo <owner/repo>	Target repo (owner/repo) (required)

---

colony tracks (deprecated)

colony tracks <subcommand> [options]

Manage self-improvement tracks and prompts.

Deprecated: The CLI tracks command manages file-backed tracks. Use the dashboard UI at /tracks for Postgres-backed track management.

colony tracks list

colony tracks list [options]

List all tracks.

Option	Description
-c, --config <path>	Path to colony.config.yaml
-r, --repo <owner/repo>	Target a specific repo
-a, --all	Show tracks for all repos

colony tracks add

colony tracks add <name> --label <label> --cooldown <minutes> [options]

Create a new track.

Option	Description
-l, --label <label>	GitHub label to apply to seeded issues (required)
--cooldown <minutes>	Cooldown between seeds in minutes (required)
--prompt-file <path>	Path to initial prompt file (v1)
-c, --config <path>	Path to colony.config.yaml
-r, --repo <owner/repo>	Target a specific repo

colony tracks remove

colony tracks remove <name> [options]

Remove a track.

Option	Description
-c, --config <path>	Path to colony.config.yaml
-r, --repo <owner/repo>	Target a specific repo

colony tracks enable

colony tracks enable <name> [options]

Enable a track.

Option	Description
-c, --config <path>	Path to colony.config.yaml
-r, --repo <owner/repo>	Target a specific repo

colony tracks disable

colony tracks disable <name> [options]

Disable a track.

Option	Description
-c, --config <path>	Path to colony.config.yaml
-r, --repo <owner/repo>	Target a specific repo

colony tracks set

colony tracks set <name> [options]

Update track metadata.

Option	Description
--cooldown <minutes>	Cooldown between seeds in minutes
--label <label>	Track label (e.g. colony:si-code-quality)
-c, --config <path>	Path to colony.config.yaml
-r, --repo <owner/repo>	Target a specific repo

colony tracks prompt

colony tracks prompt <name> [options]

View or manage prompt versions.

Option	Description
--history	List all prompt versions
--new	Create a new prompt version from stdin or --file
--notes <text>	Notes for the new version
--file <path>	Read prompt content from file (with --new)
--activate <version>	Set active prompt version
-c, --config <path>	Path to colony.config.yaml
-r, --repo <owner/repo>	Target a specific repo

---

Deployment & Process Control

colony safestop

colony safestop [options]

Gracefully drain and stop all agents (waits for active polls to finish).

Option	Description
-c, --config <path>	Path to colony.config.yaml
--timeout <minutes>	Maximum minutes to wait before giving up (default: 15)
--force	Send SIGKILL to agents that survive SIGTERM (default: leave sentinel and exit)

---

colony migrate apply

colony migrate apply [options]

Apply pending pipeline-store migrations against the configured database.

Option	Description
-c, --config <path>	Path to colony.config.yaml
--dry-run	List pending migrations without applying them

---

colony repos enable

colony repos enable <owner/repo> [options]

Activate a repo in the pipeline (creates if not present).

Option	Description
-c, --config <path>	Path to colony.config.yaml

---

colony repos disable

colony repos disable <owner/repo> [options]

Deactivate a repo in the pipeline.

Option	Description
-c, --config <path>	Path to colony.config.yaml

---

colony mcp

colony mcp [options]

Start the Colony MCP server for editor integration (Claude Code, Cursor, etc.).

Reads DATABASE_URL and GITHUB_TOKEN from the environment (or Colony config) and launches the MCP stdio server. Configure your editor to run this command as the MCP server process.

Option	Description
-c, --config <path>	Path to colony.config.yaml

See MCP Server for editor configuration examples, environment variables, and the full tool reference.

---

Advanced

colony code-map scan

colony code-map scan [options]

Scan configured repo(s) and populate the code map (repo_code_entities/relationships).

Option	Description
-c, --config <path>	Path to colony.config.yaml
-r, --repo <owner/repo>	Scan only this repo (defaults to all configured repos)

---

colony config migrate

colony config migrate [options]

Migrate old-format config (agents.* executor settings) to new format (executors.* + workers).

Moves executor-specific keys (effort, model, etc.) from agents.* to executors.*, and adds a workers block to repos that don’t have one.

Option	Description
-c, --config <path>	Path to colony.config.yaml
-o, --output <path>	Write migrated config to file instead of stdout
--dry-run	Show what would change without writing
--memory <size>	Default memory per worker container (default: 4g)

---

colony auth login

colony auth login [options]

Log in with a Colony Cloud API token.

Option	Description
--token <token>	API token (else COLONY_CLOUD_TOKEN or interactive prompt)
--cloud-url <url>	Colony Cloud base URL
--repo <owner/name>	Default repo when the org has more than one

---

colony auth status

colony auth status

Show the authenticated Cloud identity.

---

colony auth logout

colony auth logout

Remove cached Cloud credentials.

---

colony workflow validate

colony workflow validate <file>

Parse and validate a workflow YAML file.

Prints OK: <id> v<version> on success, or a parse error and exits with code 2 on failure.

---

colony workflow show

colony workflow show [options]

Print a workflow definition as YAML.

Option	Description
--builtin <id>	Print a built-in workflow by ID (e.g. colony-default, colony-content)
--workflow-id <id>	Workflow id to read from the registry
--version <n>	Version to read
--tenant-id <n>	Tenant id (for registry reads)
--database-url <url>	Postgres URL (default: $DATABASE_URL)

Either --builtin or all of --workflow-id, --version, --tenant-id are required.

See Workflows Guide for the workflow YAML schema.

---

colony estimate

colony estimate [options]

Estimate monthly Anthropic API cost based on config.

Option	Description
-c, --config <path>	Path to colony.config.yaml
-t, --throughput <issues-per-day>	Expected issues per day (default: 5)
-m, --mix <small/medium/large>	Complexity mix percentages (default: 60/30/10)
--no-calibrated	Use static default assumptions instead of calibrated data from repo history
--json	Machine-readable JSON output

---

colony canary run

colony canary run <id> [options]

Run a canary evaluation end-to-end through the Colony pipeline. Provisions an ephemeral target repo, stands up an isolated cluster (postgres + sprint-master + worker) via docker-compose.canary.yml, monitors the issue until it reaches a terminal state or a guardrail fires, captures a JSON run record, and tears the cluster down.

Prints a preflight summary (repo name, cluster, cost ceiling, timeout, retention) and prompts for confirmation before proceeding. Use --yes to skip the prompt for scripting.

Option	Description
--org <org>	GitHub org to provision canary repos in (default: colony-canary)
--cost-ceiling <usd>	Override the per-tier cost ceiling in USD
--timeout <minutes>	Override the per-tier wall-clock timeout in minutes
-y, --yes	Skip confirmation prompt (for scripting)

---

colony version

colony version

Show Colony version, Node.js version, and dependency versions.