Colony CLI Reference
Colony CLI Reference
Section titled “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 inpackages/cli/src/program.ts(thebuildProgram()function) and the individual command files underpackages/cli/src/commands/, so this page matchescolony <command> --help.
Slash commands vs. CLI commands: The
colonyCLI 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
Section titled “Contents”- Setup & Init
- Pipeline Lifecycle
- Diagnostics & Recovery
- Strategy & Tracks
- Deployment & Process Control
- Advanced
Global Options
Section titled “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) |
JSON error envelope
Section titled “JSON error envelope”Commands that accept --json/--ndjson write a flat error envelope to stdout and exit 1 on
failure instead of a human-readable Error: … line:
{ "error": "issue #42 not found in pipeline database", "code": "ISSUE_NOT_FOUND", "status": 1 }Only the 3-key shape (error, code, status) matches the ApiError contract used by the
REST API (packages/sdk/src/api-types.ts). The status field does not carry HTTP status
semantics here — it is always the literal 1 (a process-exit-status sentinel), unlike
ApiError.status, which is the real HTTP status code (e.g. 404, 500) of the failed REST
call. A consumer sharing one parser across CLI and REST errors must branch on code, not
status, to distinguish CLI failures.
code is a free-form string (there is no enumerated type backing it, unlike the REST
ApiErrorCode and webhook-receiver WebhookErrorCode unions). The table below lists every
distinct code currently emitted by the CLI:
| Code | Emitted when | Commands |
|---|---|---|
| AMBIGUOUS_REPO | more than one repo is configured and the issue can’t be pinned to one (no database, or the issue number exists in several repos); pass --repo | issue transition, pause, resume, unblock |
| CONFIG_LOAD_ERROR | colony.config.yaml failed to load or validate | status, validate-config |
| CYCLE_RESET_FAILED | resetting an epic’s review budget failed, so the unblock was not performed (the budget is restored) | unblock |
| FETCH_ERROR | fetching status data (PID/DB/Cloud) failed | status |
| INTERNAL_ERROR | an unexpected error was thrown while a DB-backed command ran with --json | blocked, estimate, inspect, issues, metrics, why |
| INVALID_ARGUMENT | a CLI argument or flag combination is malformed or mutually exclusive | estimate, inspect, metrics, pause, resume, status, tasks, issue transition, unblock, why |
| INVALID_STATE | requested state is not valid for the target workflow, or the issue is not in a pauseable state | pause, issue transition |
| INVALID_TRANSITION | requested transition is not legal from the issue’s current state | issue transition |
| ISSUE_NOT_FOUND | the given issue number has no row in the pipeline database | issue transition, pause, resume, unblock |
| ISSUE_PAUSED | the issue is paused and must be resumed before the requested action | issue transition, unblock |
| NOT_BLOCKED | unblock targeted an issue that is not in a blocked state; use retry instead | unblock |
| REPO_NOT_FOUND | no matching repo found in config (or --repo doesn’t match any) | blocked, issue transition, pause, resume, tasks, unblock, why |
| STORE_UNAVAILABLE | the command requires a database connection that isn’t configured | blocked, inspect, issues, why |
Setup & Init
Section titled “Setup & Init”colony quickstart
Section titled “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
Section titled “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
Section titled “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 |
|---|---|
--cloud | Use Colony Cloud (not yet available) |
-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
Section titled “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
Section titled “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
Section titled “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
Section titled “Pipeline Lifecycle”colony start
Section titled “colony start”colony start [agent] [options]Start agent processes (all if no agent specified). Valid [agent] values: sprint-master, worker, monitor, webhook-receiver.
| 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
Section titled “colony stop”colony stop [agent] [options]Stop agent processes (all if no agent specified). Valid [agent] values: sprint-master, worker, monitor, webhook-receiver.
| Option | Description |
|---|---|
-c, --config <path> | Path to colony.config.yaml |
colony status
Section titled “colony status”colony status [options]Show pipeline status and agent health.
| Option | Description |
|---|---|
-c, --config <path> | Path to colony.config.yaml |
--check | Deprecated: runs colony check --stage credentials --stage labels before the status output |
--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
Section titled “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
Section titled “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
Section titled “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
Section titled “colony issue transition”colony issue transition <issue-number> --state <target> --reason <reason> [options]Transition an issue to a new pipeline state.
| Option | Description |
|---|---|
-s, --state <target> | Target state (required) |
--reason <reason> | Reason for the manual transition (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
Section titled “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
Section titled “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
Section titled “Diagnostics & Recovery”colony check
Section titled “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, colony preflight and colony validate-config are aliases for specific stages of colony check:
colony doctor— delegates tocolony checkrunning theconfig,credentials,database,repository, andlabelsstages.colony preflight— delegates tocolony check --stage database+--stage runtimeto validate end-to-end pipeline readiness (migrations, tables, intake mode, worker health).colony validate-config— without--json, prints a tip and delegates tocolony check --stage config; with--json, emits the effective config with thedatabase.urlpassword redacted.
All aliases support -c/--config; doctor also supports --docker and --fix, and validate-config also supports --json. colony check is the recommended entry point; the aliases remain for backward compatibility.
colony doctor
Section titled “colony doctor”colony doctor [options]Validate Colony setup: config, provider access, API keys, CLI tools, and ports.
Alias: Delegates to
colony checkstagesconfig,credentials,database,repository, andlabels. Prefercolony checkfor 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
Section titled “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. Prefercolony checkfor new scripts.
| Option | Description |
|---|---|
-c, --config <path> | Path to colony.config.yaml |
colony validate-config
Section titled “colony validate-config”colony validate-config [options]Show the effective resolved config.
Alias: Without
--json, delegates tocolony check --stage config. Prefercolony checkfor new scripts.
| 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
Section titled “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
Section titled “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 blocked
Section titled “colony blocked”colony blocked [options]List all blocked issues (across configured repos, or one with --repo) with their block reason,
classification (transient / permanent / quota / unknown), auto-unblock attempts used vs. the
configured cap, any remaining cooldown before the next auto-unblock attempt, and a recommended
operator action. Unlike colony why, which diagnoses one issue, this surfaces recovery progress
across every currently-blocked issue at once — useful for answering “which blocked issues are still
being auto-retried, and which have exhausted recovery and need a human?” without reading logs or the
dashboard.
| Option | Description |
|---|---|
-c, --config <path> | Path to colony.config.yaml |
-r, --repo <owner/repo> | Filter by repo |
--json | Machine-readable JSON output |
colony inspect
Section titled “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
Section titled “colony logs”colony logs [agent] [options]Tail agent log files interleaved (like docker compose logs -f). [agent] accepts sprint-master, worker, monitor, webhook-receiver, or any <name>.log present in the log directory.
| 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 <when> | Only include items since a duration ago (30m, 24h, 7d) or a date (YYYY-MM-DD) |
-j, --json | Machine-readable NDJSON output (one JSON object per line) |
colony events
Section titled “colony events”colony events [options]Query structured pipeline events. Without --since, only the last 24 hours are read. Events print newest first, capped at --limit.
| 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 <when> | Only include events since a duration ago (30m, 24h, 7d) or a date (YYYY-MM-DD). Default 24h |
--limit <n> | Maximum number of events to show, newest first (positive integer, default 200) |
--json | Machine-readable NDJSON output (one JSON object per line) |
colony tasks
Section titled “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, ci_repair, retrospect, converse, code-map-scan, strategize) |
-i, --issue <number> | Filter by issue number |
--since <when> | Only include items since a duration ago (30m, 24h, 7d) or a date (YYYY-MM-DD) |
--json | Machine-readable NDJSON output (one JSON object per line) |
colony workers
Section titled “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
Section titled “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
Section titled “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 <when> | Only include items since a duration ago (30m, 24h, 7d) or a date (YYYY-MM-DD) (default: 24h). A bare integer still means hours (--since 48 = 48h). |
--limit <n> | Show at most n issues (default: 100), in repo order. When more exist, Showing N of M issues (use --limit to see more). is printed after the table (to stderr with --json). With --blocked, last errors are looked up only for the shown issues. |
--json | Machine-readable NDJSON output (one JSON object per line) |
colony dead-letters
Section titled “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
Section titled “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
Section titled “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
Section titled “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
Section titled “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
Section titled “colony metrics”colony metrics [options]Show pipeline metrics: throughput, cycle times, success rates, and bottlenecks.
When a database is configured, each repo also gets a Flaky checks section listing its top 5 flakiest deterministic review checks as name flakes/evaluations rate%, with a (quarantined) suffix when flakes reach review.flaky_quarantine_threshold. It always uses the fixed 14-day quarantine window, independent of --days. If the flake stats can’t be read (e.g. migration not applied), a dim warning is printed and the rest of the output is unaffected.
| 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: { ... }, flakyChecks: [{ checkName, flakes, evaluations, flakeRate, quarantined }] }] } |
colony digest
Section titled “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
Section titled “Strategy & Tracks”colony strategy charter set
Section titled “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 non-empty goals string and nothing else that Colony reads. A file with an envelope key is rejected: size caps are part of the repository autonomy grant, set with colony autonomy set.
| 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
Section titled “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 autonomy show
Section titled “colony autonomy show”colony autonomy show --repo <owner/repo> [options]Print the repository autonomy grant: max_auto_size, max_auto_select_size, and whether the grant is configured or the default.
| Option | Description |
|---|---|
-r, --repo <owner/repo> | Target repo (owner/repo) (required) |
-c, --config <path> | Path to colony.config.yaml |
colony autonomy set
Section titled “colony autonomy set”colony autonomy set --repo <owner/repo> --max-auto-size <size> [options]Set the repository autonomy grant. Sizes are validated before anything is written.
| Option | Description |
|---|---|
-r, --repo <owner/repo> | Target repo (owner/repo) (required) |
--max-auto-size <size> | small, medium, large, or epic (required) |
--max-auto-select-size <size> | small, medium, large, epic, or none; omitted keeps the stored value |
--author <name> | Author recorded as updated_by (default: operator) |
-c, --config <path> | Path to colony.config.yaml |
colony strategize
Section titled “colony strategize”colony strategize --repo <owner/repo> [options]Request a strategize run (processed by a worker). The command only enqueues: it records a generate request, wakes the sprint-master scheduler and prints Strategize requested at <timestamp>. A worker runs the strategist; nothing runs in the CLI process. Exits 1 if the repo has no active charter (no request is recorded).
With --wait, the command polls every 5 seconds for the first generate run created at or after the request and prints its outcome: Strategize produced proposal v<N> (exit 0), the no-change reason or goal-assessment summary (exit 0), or the failure reason (exit 1). On timeout it exits 1; a run that was already in flight when the request was made may have absorbed the request, so check colony tasks -r <owner>/<repo> -t strategize or the dashboard Strategy tab.
| Option | Description |
|---|---|
-c, --config <path> | Path to colony.config.yaml |
-r, --repo <owner/repo> | Target repo (owner/repo) (required) |
--wait | Wait for the requested run to finish and print its outcome |
--timeout <seconds> | Max seconds to wait with --wait (default: 1800) |
colony tracks (deprecated)
Section titled “colony tracks (deprecated)”colony tracks <subcommand> [options]Manage self-improvement tracks and prompts.
Deprecated: The CLI
trackscommand manages file-backed tracks. Use the dashboard UI at/tracksfor Postgres-backed track management. CLI edits are written to file-backed tracks that are imported into Postgres only once, when Postgres has no tracks for the repo; after that they are ignored at runtime. Manage tracks from the dashboard Tracks tab or the monitor tracks API (POST /api/tracksand/api/tracks/:owner/:repo/:name/*, see API Reference); the MCPcolony_trackstool can list tracks but not edit them.
colony tracks list
Section titled “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
Section titled “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
Section titled “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
Section titled “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
Section titled “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
Section titled “colony tracks set”colony tracks set <name> [options]Update track metadata.
| Option | Description |
|---|---|
--cooldown <minutes> | Cooldown between seeds in minutes |
--label <label> | Track label, in your configured labels.prefix (e.g. si-code-quality) |
-c, --config <path> | Path to colony.config.yaml |
-r, --repo <owner/repo> | Target a specific repo |
colony tracks prompt
Section titled “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
Section titled “Deployment & Process Control”colony safestop
Section titled “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 |
-t, --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
Section titled “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
Section titled “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
Section titled “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
Section titled “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
Section titled “Advanced”colony code-map scan
Section titled “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
Section titled “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. It also removes a non-empty self_improvement.tracks array, which is deprecated and ignored at runtime (tracks live in Postgres).
| 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
Section titled “colony auth login”colony auth login [options]Log in with a Colony Cloud connection.
| Option | Description |
|---|---|
--token <token> | Connection (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
Section titled “colony auth status”colony auth statusShow the authenticated Cloud identity.
colony auth logout
Section titled “colony auth logout”colony auth logoutRemove cached Cloud credentials.
colony workflow validate
Section titled “colony workflow validate”colony workflow validate <file>Parse and validate a workflow YAML file.
Prints OK: <id> v<version> on success (followed by states, operator_actions and content_hash lines), or a parse error and exits with code 2 on failure.
colony workflow show
Section titled “colony workflow show”colony workflow show [options]Print a workflow definition as YAML.
| Option | Description |
|---|---|
--builtin <id> | Print a built-in workflow by ID (One of: colony-default, colony-content, colony-support, colony-dependabot) |
--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
Section titled “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
Section titled “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 |
|---|---|
-c, --config <path> | Path to colony.config.yaml |
--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
Section titled “colony version”colony versionShow Colony version, Node.js version, and dependency versions.