CLI Reference

Auto-generated — do not edit. Run go run ./cmd/genschema to regenerate.

Global Flags

gc

Gas City CLI — orchestration-builder for multi-agent workflows

gc [flags]

gc agent

Manage agent configuration in city.toml.

Runtime operations (attach, list, peek, nudge, kill, start, stop, destroy) have moved to "gc session" and "gc runtime".

gc agent

gc agent add

Add a new agent scaffold under agents/<name>/.

Creates agents/<name>/prompt.template.md and, when needed, agents/<name>/agent.toml. These files live in the city directory and do not append [[agent]] blocks to city.toml.

Use --prompt-template to copy prompt content from an existing file into the canonical prompt.template.md location. Schema-2 convention agents are city-scoped; define rig-scoped agents in pack config or [[patches.agent]]. Use --suspended to scaffold the agent in a suspended state.

gc agent add --name <name> [flags]

Example:

gc agent add --name mayor
gc agent add --name polecat
gc agent add --name worker --prompt-template ./worker.md --suspended

gc agent list

List configured agents from the resolved city configuration.

Use --json to inspect agent routing fields, including effective work_query and sling_query values.

gc agent list [flags]

gc agent resume

Resume a suspended agent by clearing suspended in its durable config.

The reconciler will start the agent on its next tick. Supports bare names (resolved via rig context) and qualified names (e.g. "myrig/worker").

gc agent resume <name> [flags]

gc agent suspend

Suspend an agent by setting suspended=true in its durable config.

Suspended agents are skipped by the reconciler — their sessions are not started or restarted. Existing sessions continue running but won't be replaced if they exit. Use "gc agent resume" to restore.

gc agent suspend <name> [flags]

gc agent-script

Run a deterministic YAML agent script for examples and demos.

The runner probes gc hook once, selects the matching turn, and executes the configured actions. It is intentionally small and generic: role behavior stays in the YAML script.

Status: experimental. Gas City owns this runner so repository examples can be tested without external helper binaries; the YAML action surface may change until a stable SDK boundary exists.

For k8s-backed agent-script agents, set lifecycle = "one_shot" in the agent config so the runtime treats a clean script exit as expected work completion instead of startup death.

gc agent-script --script <path> [flags]

gc analyze

Analyze produces correlated reports over the events log and bead state. All subcommands are read-only and safe to run alongside a live controller.

gc analyze

gc analyze reliability

Reliability reports per-(model, prompt_version, rig) counts of the tracked session-lifecycle events:

session.crashed session.quarantined (reserved; current production paths do not emit it) session.idle_killed session.draining

Worker.operation events from #1252 supply the (model, prompt_version, agent_name) tuple per session. Lifecycle events get attributed via the session id or producer aliases from worker.operation payloads. Sessions with worker.operation events but no lifecycle events count toward the per-group total — they're the denominator side of crash-rate calculations. Model and prompt_version are best-effort dimensions; the report warns when the source event stream is missing them.

Read-only: this command never writes events or beads.

gc analyze reliability [flags]

gc bd

Run a bd command routed to the correct rig directory.

When beads belong to a rig (not the city root), bd must run from the rig directory to find the correct .beads database. This command resolves the rig automatically from the --rig flag or by detecting the bead prefix in the arguments.

Use --rig <name> to pin a specific rig store, or --city <path> to pin the city (HQ) store. An explicit --city is a true scope override: it forces the city store and disables rig auto-detection (GC_RIG, cwd, bead prefix), so a deliberate city-scoped query is never silently downgraded to a rig store.

On a city that serves a coordination class from its own [storage] binding, a by-id read or write of a bead that binding owns is answered in process from the binding, not by bd against a work store that does not hold it. --rig is refused for those beads rather than ignored or honored: it names a work scope, and a relocated class is not partitioned by rig, so there is nothing to narrow within. Drop --rig for a class-owned id. Auto-detected scope (GC_RIG, -C, cwd) is unaffected, and --city still selects which city's binding answers.

"gc bd ready" is refused outright on such a city, whatever arguments it is given, and so is "gc bd list --ready", which bd documents as the same semantics: both compute a frontier over one ledger and take no selector that could reach another, so the answer is the work-class subset of the city's ready set with no way to tell. Use "gc ready", which federates every store the city spreads work across. It is flag-compatible with the "bd ready" invocation the generated work query builds, not with all of "bd ready" — "gc ready --help" lists what it takes. A city that relocates no class is unaffected.

All arguments after "gc bd" are forwarded to bd unchanged. "heartbeat <issue-id>" forwards to bd's native heartbeat, which refreshes the claim's lease and fails loudly when the caller no longer owns it. gc adds one subcommand of its own: "release-if-current <issue-id> <assignee>", which conditionally resets an in-progress assignment only when the bead still has that assignee.

gc bd forces BD_EXPORT_AUTO=false to prevent bd's git auto-export hook from wedging the wrapper after printing command output. If you need auto-export behavior, invoke bd directly.

gc bd [bd-args...]

Example:

gc bd --rig my-project list
gc bd --rig my-project create "New task"
gc bd show my-project-abc          # auto-detects rig from bead prefix
gc bd list --rig my-project -s open
gc bd --city /path/to/city list    # pins the city (HQ) store, no rig auto-detect
gc bd heartbeat my-project-abc     # refresh the claim lease you hold
gc bd release-if-current my-project-abc worker-1

gc beads

Manage the beads provider (backing store for issue tracking).

Subcommands for topology operations, health checking, diagnostics, exact-store metadata compare-and-set, and read-only list/show routed through the supervisor API with transparent fallback to direct bd reads.

gc beads

gc beads city

Manage the canonical city endpoint topology for bd-backed beads stores.

Use use-managed to make the city GC-managed again. Use use-external to pin the city to an external Dolt endpoint and rewrite inherited rig mirrors.

gc beads city

gc beads city use-external

Set the city endpoint to an external Dolt server

gc beads city use-external [flags]

gc beads city use-managed

Set the city endpoint to GC-managed

gc beads city use-managed [flags]

gc beads health

Check beads provider health and attempt recovery on failure.

Delegates to the provider's lifecycle health operation. For exec providers (including bd/dolt), the script handles multi-tier checking and recovery internally. For the file provider, always succeeds (no-op).

Also used by the beads-health system order for periodic monitoring.

gc beads health [flags]

Example:

gc beads health
gc beads health --quiet
gc beads health --json

gc beads list

List beads across all rigs, routed through the supervisor API when the controller is alive and falling back to a direct multi-store read otherwise.

Supports --label, --status, --all, and --format. --format=json emits JSON (API-path JSON includes _cache_age_s; fallback-path JSON omits it). The bare --json flag is reserved by the CLI's JSON-contract layer and is not wired for this command; use --format=json.

gc beads list [flags]

Example:

gc beads list
gc beads list --label ready-to-build
gc beads list --status open --format=json

gc beads metadata-cas

Atomically compare and set one metadata key in one exact local bead store.

The store must be selected explicitly with --store-ref=city:<name> or --store-ref=rig:<name>. This command never scans other stores, follows a cross-store fallback, or operates on a remote city. A conflict is an ordinary zero-exit outcome; capability, transport, readback, and validation failures are non-zero.

Legacy file-provider cities created before scope-local file stores may map city and rig references to the same shared city file. That provider-layout alias is preserved for compatibility; it is not a search or cross-store fallback.

Use --json for the canonical machine-output contract. --format=json remains accepted for compatibility. Combining --json with an explicit --format=text is a usage error.

gc beads metadata-cas <bead-id> [flags]

Example:

gc beads metadata-cas tr-123 \
  --store-ref=rig:tributary \
  --key=semantic_review_sha \
  --expected=old-sha \
  --next=new-sha \
  --json

gc beads show

Show one bead by ID, routed through the supervisor API when the controller is alive and falling back to a direct multi-store lookup otherwise.

Supports --format. --format=json emits JSON (API-path JSON includes _cache_age_s; fallback-path JSON omits it). The bare --json flag is reserved by the CLI's JSON-contract layer and is not wired for this command; use --format=json.

gc beads show <bead-id> [flags]

Example:

gc beads show ga-abc
gc beads show ga-abc --format=json

gc build-image

Assemble a Docker build context from city config, prompts, formulas, and rig content, then build a container image with everything pre-staged.

Pods using the prebaked image skip init containers and file staging, reducing startup from 30-60s to seconds. Configure with prebaked = true in [session.k8s].

Secrets (Claude credentials) are never baked — they stay as K8s Secret volume mounts at runtime.

gc build-image [city-path] [flags]

Example:

# Build context only (no docker build)
gc build-image ~/bright-lights --context-only

# Build and tag image
gc build-image ~/bright-lights --tag my-city:latest

# Build with rig content baked in
gc build-image ~/bright-lights --tag my-city:latest --rig-path demo:/path/to/demo

# Build and push to registry
gc build-image ~/bright-lights --tag registry.io/my-city:latest --push

gc cities

List all cities registered with the machine-wide supervisor.

gc cities [flags]

gc cities list

List registered cities

gc cities list [flags]

gc completion

Generate the autocompletion script for gc for the specified shell. See each sub-command's help for details on how to use the generated script.

gc completion

gc completion bash

Generate the autocompletion script for the bash shell.

This script depends on the 'bash-completion' package. If it is not installed already, you can install it via your OS's package manager.

To load completions in your current shell session:

source <(gc completion bash)

To load completions for every new session, execute once:

Linux:

gc completion bash > /etc/bash_completion.d/gc

macOS:

gc completion bash > $(brew --prefix)/etc/bash_completion.d/gc

You will need to start a new shell for this setup to take effect.

gc completion bash

gc completion fish

Generate the autocompletion script for the fish shell.

To load completions in your current shell session:

gc completion fish | source

To load completions for every new session, execute once:

gc completion fish > ~/.config/fish/completions/gc.fish

You will need to start a new shell for this setup to take effect.

gc completion fish [flags]

gc completion powershell

Generate the autocompletion script for powershell.

To load completions in your current shell session:

gc completion powershell | Out-String | Invoke-Expression

To load completions for every new session, add the output of the above command to your powershell profile.

gc completion powershell [flags]

gc completion zsh

Generate the autocompletion script for the zsh shell.

If shell completion is not already enabled in your environment you will need to enable it. You can execute the following once:

echo "autoload -U compinit; compinit" >> ~/.zshrc

To load completions in your current shell session:

source <(gc completion zsh)

To load completions for every new session, execute once:

Linux:

gc completion zsh > "${fpath[1]}/_gc"

macOS:

gc completion zsh > $(brew --prefix)/share/zsh/site-functions/_gc

You will need to start a new shell for this setup to take effect.

gc completion zsh [flags]

gc config

Inspect, validate, and debug the resolved city configuration.

The config system supports multi-file composition with includes, packs, patches, and overrides. Use "show" to dump the resolved config and "explain" to see where each value originated.

gc config

gc config explain

Show the resolved configuration with provenance.

For agents (default): displays every resolved field with an annotation showing which config file provided the value. Use --rig and --agent to filter.

For providers (--provider): displays the resolved ProviderSpec along with per-field and per-map-key attribution — which chain layer (builtin:X or providers.Y) contributed each value. Useful for debugging base-chain inheritance.

Use --json to emit machine-readable output (providers only).

gc config explain [flags]

Example:

gc config explain
gc config explain --agent mayor
gc config explain --rig my-project
gc config explain --provider codex-max
gc config explain --provider codex-max --json
gc config explain -f overlay.toml --agent polecat

gc config show

Dump the fully resolved city configuration as TOML.

Loads city.toml with all includes, packs, patches, and overrides, then outputs the merged result. Use --validate to check for errors without printing. Use --provenance to see which file contributed each config element. Use -f to layer additional config files.

gc config show [flags]

Example:

gc config show
gc config show --validate
gc config show --provenance
gc config show --json
gc config show -f overlay.toml

gc context

Manage the client-side registry of named remote cities.

A context names a remote city the gc CLI can operate over the HTTP+SSE control plane: its URL, the remote city name, and an optional credential command. Select a context per-invocation with --context <name>, or set a sticky default with 'gc context use <name>' (a discoverable local city always wins over the default).

gc context

gc context add

Add a named remote city to ~/.gc/contexts.toml.

--url is required and must be https for a non-loopback host. --city sets the remote city name (defaults to <name>). At most one credential technique applies: --grant-command mints an X-GC-City-Write grant for a direct hardened self-host; --credential-command mints a transport bearer consumed by an edge/proxy.

gc context add <name> [flags]

gc context current

Dry-run the target resolver and report the winning tier.

Applies the same precedence as every command — explicit flag > explicit env > local city discovery > sticky default — and prints the target it would use, noting what was shadowed. Makes no network call.

gc context current

gc context list

List named remote cities

gc context list [flags]

gc context remove

Remove a named remote city

gc context remove <name>

gc context show

Show a named remote city

gc context show <name> [flags]

gc context use

Set the sticky default remote city.

The default is used only when no local city is discoverable from the current directory — a local city always wins (git-like). Clear it with 'gc context use' with no arguments is not supported; remove the default by removing the context.

gc context use <name>

gc converge

Convergence loops are bounded multi-step refinement cycles.

A root bead + formula + gate = repeat until the gate passes or max iterations are reached. The controller processes wisp_closed events and drives the loop automatically.

gc converge

gc converge approve

Approve and close a convergence loop (manual gate)

gc converge approve <bead-id> [flags]

gc converge create

Create a convergence loop

gc converge create [flags]

gc converge iterate

Force next iteration (manual gate)

gc converge iterate <bead-id> [flags]

gc converge list

List convergence loops

gc converge list [flags]

gc converge retry

Retry a terminated convergence loop

gc converge retry <bead-id> [flags]

gc converge status

Show convergence loop status

gc converge status <bead-id> [flags]

gc converge stop

Stop a convergence loop

gc converge stop <bead-id> [flags]

gc converge test-gate

Dry-run the gate condition (no state changes)

gc converge test-gate <bead-id> [flags]

gc converge test-trigger

Dry-run the trigger condition (no state changes)

gc converge test-trigger <bead-id> [flags]

gc convoy

Manage convoys — graphs of related work beads.

A convoy is a named graph of beads with dependencies. Convoys group related issues via tracks dependencies.

Convoys are distinct from workflows — the DAGs compiled from v2 formulas and managed by the dispatch subsystem. The convoy lifecycle subcommands (create, list, status, target, add, close, check, stranded, land) do not operate on workflow roots; the dispatch subcommands (control, delete, delete-source, reopen-source) manage workflow trees and their control beads.

gc convoy

gc convoy add

Link an existing issue bead to a convoy.

Adds a tracks dependency from the convoy to the issue, making it appear in the convoy's progress tracking without changing the issue parent.

gc convoy add <convoy-id> <issue-id> [flags]

gc convoy check

Scan open convoys and auto-close any where all child issues are resolved.

Evaluates each open convoy's children. If all children have status "closed", the convoy is automatically closed and an event is recorded.

gc convoy check [flags]

gc convoy close

Close a convoy bead manually.

Marks the convoy as closed regardless of child issue status. Use "gc convoy check" to auto-close convoys where all issues are resolved.

gc convoy close <id> [flags]

gc convoy control

Process a single control bead, or run the control-dispatcher loop with --serve to continuously process ready control beads. Use --follow <agent> to filter the serve loop to a specific agent template.

gc convoy control [bead-id] [flags]

gc convoy create

Create a convoy and optionally link existing issues to it.

Creates a convoy bead and tracks any provided issue IDs. Issues can also be added later with "gc convoy add".

gc convoy create <name> [issue-ids...] [flags]

Example:

gc convoy create sprint-42
gc convoy create sprint-42 issue-1 issue-2 issue-3
gc convoy create deploy --owner mayor --notify mayor --merge mr
gc convoy create auth-rewrite --owned --target integration/auth-rewrite

gc convoy delete

Close all open beads in a convoy, or delete them.

Searches all stores (city + rigs) for the convoy root and all beads with matching gc.root_bead_id. Without --force, shows a preview.

By default, beads are closed with gc.outcome=skipped. Use --delete to remove them from the store via bd delete --cascade --force.

gc convoy delete <convoy-id> [flags]

gc convoy delete-source

Find every live workflow root sourced from the given bead and close its subtree. By default this is a preview. Use --apply to mutate. Use --delete with --apply to also delete closed beads.

gc convoy delete-source <source-bead-id> [flags]

gc convoy land

Land an owned convoy, verifying all children are closed.

Landing is the natural lifecycle termination for owned convoys created via "gc sling --owned". It verifies all children are closed (or uses --force), closes the convoy bead, and records a ConvoyClosed event.

gc convoy land <convoy-id> [flags]

Example:

gc convoy land gc-42
gc convoy land gc-42 --force
gc convoy land gc-42 --dry-run

gc convoy list

List all open convoys with completion progress.

Shows each convoy's ID, title, and the number of closed vs total child issues.

gc convoy list [flags]

gc convoy reopen-source

Reopen a source bead after workflow cleanup

gc convoy reopen-source <source-bead-id> [flags]

gc convoy status

Show detailed status of a convoy and all its child issues.

Displays the convoy's ID, title, status, completion progress, and a table of all child issues with their status and assignee.

gc convoy status <id> [flags]

gc convoy stranded

Find open issues in convoys that have no assignee.

Lists issues that are ready for work but not claimed by any agent. Useful for identifying bottlenecks in convoy processing.

gc convoy stranded [flags]

gc convoy target

Set the target branch metadata on a convoy.

Child work beads can inherit this target branch when slung with feature-branch formulas such as mol-polecat-work.

gc convoy target <convoy-id> <branch> [flags]

gc costs

Aggregate recorded usage facts (model tokens and compute wall-seconds) by run for local cost insight.

Reads .gc/usage.jsonl (the local usage sink) and groups facts by run id. This reflects facts only under the default "local" usage provider; with an "exec:" or "discard" provider the facts are forwarded out of process or dropped, so gc costs shows nothing local.

Cost is a list-price estimate for decision support, not an authoritative charge; invocations with no pricing are flagged "unpriced" and excluded from the cost total.

gc costs

Example:

gc costs

gc dashboard

Open the GC dashboard in your browser.

The dashboard SPA is embedded in the gc binary and served same-origin by the supervisor; it is no longer a separate static server. This command resolves the supervisor URL, opens it in your default browser, and prints it too (or tells you how to start the supervisor). Use --no-open to print the URL without launching a browser.

gc dashboard [flags]

gc dashboard serve

Report the URL where the GC dashboard is served.

The dashboard SPA is embedded in the gc binary and served same-origin by the supervisor; "gc dashboard serve" no longer starts a static server. It resolves and prints the supervisor URL (or tells you how to start the supervisor).

gc dashboard serve [flags]

gc doctor

Run diagnostic health checks on the city workspace.

Checks city structure, config validity, binary dependencies (tmux, git, bd, dolt), controller status, agent sessions, zombie/orphan sessions, bead stores, Dolt server health, event log integrity, formula compiler requirements (deprecated contract = "graph.v2" opt-ins, missing [requires] formula_compiler = ">=2.0.0" declarations, and requirements the host's [daemon] formula_v2 setting cannot satisfy), v2 config deprecations such as legacy [formulas].dir, and per-rig health. Use --fix for the canonical remediation path, including any safe mechanical legacy-to-current pack rewrites that are available on this branch.

gc doctor [flags]

Example:

gc doctor
gc doctor --fix
gc doctor --verbose
gc doctor --json

gc dolt-cleanup

gc dolt-cleanup is the Go-side implementation of the operational Dolt cleanup tool. It resolves the Dolt server port via the AD-04 chain (--port > city dolt.port > <rigRoot>/.beads/dolt-server.port > 3307), drops stale test/agent databases, calls DOLT_PURGE_DROPPED_DATABASES to reclaim disk, and reaps orphaned dolt sql-server processes left over from leaked test harnesses. Invalid explicit ports and unreadable or invalid city/rig port settings fail closed before cleanup stages run; only absent rig port files can reach the legacy default. The legacy default is a connection fallback only; it does not protect port 3307 from orphan-process reaping.

Dry-run by default. Pass --force to actually drop, purge, and kill. Pass --max-orphan-dbs with --force to refuse all destructive cleanup stages if the live apply-time stale database count exceeds the scan-time threshold. The default 0 disables this guard; negative values are rejected before any city lookup or cleanup stage runs. Protection is conservative and checked first: active rig dolt servers (matched by listening port), registered rig databases, and active test temp roots are always protected, and any process whose state cannot be determined degrades to protected. A dolt sql-server is reaped only when its scope is provably gone — its working directory is an unlinked inode (the kernel "(deleted)" cwd marker), or its --config path is on the test-config-path allowlist (/tmp/Test*, os.TempDir()/Test*, known Gas City test prefixes, ~/.gotmp/Test*). A server whose --config has merely vanished while its working directory is still live is protected, not reaped, until an operator confirms; a lone missing-config observation is not proof of scope deletion. See the PROTECTED section of the report. Destructive drops are limited to known stale test database name shapes and conservative SQL identifier characters; skipped stale matches are reported in dropped.skipped. Rig dolt_database names used for purge must use the same identifier shape: ASCII letters, digits, underscores, and non-leading hyphens. Missing or silent rig metadata disables forced drop/purge because the live database name cannot be proven safe.

JSON envelope schema is stable: gc.dolt.cleanup.v1. Automation that uses --json must inspect summary.errors_total and errors, and must also refuse to invoke --force when dry-run force_blockers is non-empty. force_blockers reports conditions that would block forced cleanup without incrementing errors_total. The rig-protection blocker is intentionally global: missing or silent rig metadata prevents forced drop/purge because the command cannot prove all registered rig databases are protected. Cleanup stage errors are reported in the envelope even when the command can still return successfully after emitting the report.

gc dolt-cleanup [flags]

gc event

Event operations

gc event

gc event emit

Record a custom event to the city event log.

Best-effort: always exits 0 so bead hooks never fail. Supports attaching arbitrary JSON payloads. JSON summaries report whether submission to the configured provider was attempted; the event bus does not acknowledge durable persistence.

gc event emit <type> [flags]

gc events

Show events from the GC API with optional filtering.

The API is the source of truth for both city-scoped and supervisor-scoped events. In a city directory (or with --city), this command reflects the city's /v0/city/{cityName}/events and /stream endpoints. Without a city in scope, it reflects the supervisor's /v0/events and /stream endpoints.

List, watch, and follow output are always JSON Lines. Each line is one API DTO or SSE envelope.

gc events [flags]

Example:

gc events
gc events --type bead.created --since 1h
gc events --watch --type convoy.closed --timeout 5m
gc events --follow
gc events --seq
gc events --follow --after-cursor city-a:12,city-b:9

gc events reemit-execution

Project exactly one stopped local graph.v2 execution run into execution facts.

The default is a dry run. Pass --apply to append the projected snapshot to the default city event log.

gc events reemit-execution --city <city> --run <run> [--apply] [flags]

gc events rotate

Force rotate the city event log through the running supervisor.

Output is one JSON line. Empty active logs are successful no-ops.

gc events rotate [flags]

Example:

gc events rotate
gc events rotate --wait
gc --city /path/to/city events rotate --api http://127.0.0.1:8080

gc extmsg

Manage bindings between external conversations (telegram, discord, ...) and gc sessions or configured agents.

A conversation bound to an agent name survives session restarts: inbound messages resolve a live session for the agent at delivery time, cold-waking one when none is live. "handoff" rebinds a conversation to another agent — the front-desk pattern: a default-routed agent inspects the conversation and hands it to the right specialist.

These commands require the city API server; they have no local fallback.

gc extmsg

gc extmsg bind

Bind an external conversation to a concrete session (--session) or to a configured agent (--agent). Agent bindings survive session restarts: delivery resolves a live session for the agent each time, cold-waking one when none is live. Binding an actively-bound conversation conflicts; use "gc extmsg handoff" to rebind.

gc extmsg bind [flags]

gc extmsg handoff

Rebind an external conversation to another configured agent, replacing the active binding. Run from inside an agent session to hand a conversation to the right specialist — the routing judgment lives in the agent's prompt, this verb is pure transport.

gc extmsg handoff [flags]

gc extmsg unbind

Remove active external-conversation bindings. Filter by conversation (--provider/--conversation-id), by --agent, by --session, or a combination. At least one filter is required.

gc extmsg unbind [flags]

gc formula

Manage and inspect formulas.

A formula is a reusable TOML method for how multi-step work should be done (a bead is the work itself). See docs/reference/specs/formula-spec-v2.md for the file format, the formulas v2 contract, and the [requires] formula_compiler opt-in.

gc formula

gc formula cook

Compile and instantiate a formula as real beads in the current store.

This is a low-level workflow construction tool. It creates the formula root and all compiled step beads without routing any work.

With --attach=<bead-id>, the given bead gains a blocking dependency on the sub-DAG root, so it won't close until the sub-DAG completes. This is a "blocks" dependency only, not a parent-child relationship — the sub-DAG root does not become a child of the attached bead (gc bd list --parent will not find it), and convoy auto-close, which watches parent-child children and "tracks" members rather than blocks dependents, is not triggered by the sub-DAG completing. This is the core primitive for late-bound DAG expansion — any agent, script, or workflow step can call it to expand a bead into a sub-workflow at runtime.

With --attach on a v2 formula — one declaring [requires] formula_compiler = ">=2.0.0" — the invocation runs under a per-source workflow lock and is idempotent: a repeat cook for the same source bead reuses the live workflow instead of duplicating it, and a conflicting live workflow from the same source is an error.

On a city that serves the graph class from its own [storage] binding, most of --attach in CITY scope is NOT SUPPORTED YET and refuses rather than serving. A graft is graph class whatever the formula's version — every bead it creates carries gc.root_bead_id — so the sub-DAG belongs in the binding while the blocking dependency belongs beside the attach bead, and a split city cannot have both:

• attach bead in the city's WORK ledger — refused. Writing the sub-DAG beside it strands graph-class beads in the work store, which gc storage status reports and exits non-zero on; writing it into the binding leaves the work store holding a blocks row naming an id it cannot resolve, which never clears. Representing that block across the store boundary needs a cross-class membership edge: ga-2orlf.
• attach bead in the BINDING, v2 (graph.v2) formula — refused. It normalizes its target into a synthetic input convoy, which is a work bead that can live in neither store; its membership edge to the target would be cross-class. Same remedy: ga-2orlf.
• attach bead in the BINDING, v1 formula — served. The sub-DAG and its blocking dependency are both written to the binding.
• RIG scope (--rig, GC_RIG, or a cwd inside a rig) — served, unchanged. A relocation moves city-level stores only, so a rig's ledger holds both ends of the graft and nothing it writes can be stranded.

Single-store cities are unaffected: --attach behaves exactly as it always has. If an earlier cook already stranded beads in a split city's work store, copy them into the binding with gc storage recover-stranded --from-work --fleet-stopped.

gc formula cook <formula-name> [flags]

gc formula list

List all formulas available in the city's formula search paths.

Formulas are discovered from the well-known formulas/ directories of city and rig pack layers, the city's own formulas/ directory, and the rig-local formulas_dir directory. Later layers win for same-named formulas.

gc formula list [flags]

gc formula show

Compile and display a formula recipe.

By default, shows the recipe with {{variable}} placeholders intact. Use --var to substitute variables and preview the resolved output.

When --rig is set (or cwd is inside a rig), rig-scoped formula_vars from city.toml are shown as "(rig default=...)" alongside each applicable var. An explicit --city pins city scope, which has no rig-scoped formula_vars.

Examples: gc formula show mol-feature gc formula show mol-feature --var title="Auth system" --var branch=main gc formula show mol-polecat-work --rig mo

gc formula show <formula-name> [flags]

gc formula version-check

Compare the formula content hash stored on a molecule/workflow bead against the current on-disk formula file. Exits 0 if they match, 1 if they diverge.

The bead must have gc.formula_hash metadata (set during instantiation). The formula is located via the bead's Ref field and the current formula search paths.

Use this to detect whether a running session's formula has been updated since it was spawned.

gc formula version-check <bead-id> [flags]

gc github

GitHub integration commands

gc github

gc github pr

GitHub pull-request monitor commands

gc github pr

gc github pr backfill

Query configured GitHub PR readiness monitors.

The command reads [[github.pr_monitor]] entries from the resolved city configuration, queries open pull requests from GitHub, and reports PRs that need repair: failed checks, merge conflicts, blocked mergeability, or branches behind their base. By default clean and pending-only PRs are omitted; pass --all to include every observed PR.

gc github pr backfill [monitor-name] [flags]

gc graph

Show the dependency graph for a set of beads or a convoy.

Resolves dependencies via the bead store and prints each bead with its status and what blocks it. Convoys are expanded to their children automatically. Readiness is computed within the displayed set.

By default prints a table. Use --tree for a Unicode tree view or --mermaid for a Mermaid.js flowchart you can paste into Markdown.

gc graph <bead-ids|convoy-id...> [flags]

Example:

gc graph gc-42               # expand convoy children
gc graph gc-1 gc-2 gc-3     # arbitrary beads
gc graph gc-42 --tree        # dependency tree
gc graph gc-42 --mermaid     # Mermaid.js diagram

gc handoff

Convenience command for context handoff.

Self-handoff (default): sends mail to self. If the current session is controller-restartable, requests a restart and blocks until the controller stops the session. For on-demand configured named sessions, sends mail and returns without requesting restart: handoff intentionally leaves the user-attended session running instead of restarting it out from under the user. The controller can restart such a session via gc runtime request-restart; handoff deliberately does not.

For controller-restartable sessions, equivalent to:

gc mail send $GC_ALIAS <subject> [message] gc runtime request-restart

Under normal operation the controller stops controller-restartable self-handoff sessions before this command returns. If the controller does not act within a bounded timeout, gc handoff exits 1 with a diagnostic instead of blocking indefinitely. If interrupted, the restart request remains set for the controller to process on its next reconcile tick.

Auto handoff (--auto): sends mail to self and returns without requesting a restart. This is for PreCompact hooks, where the provider is already managing the context compaction lifecycle.

Remote handoff (--target): sends mail to a target session. If the target is controller-restartable, kills it so the reconciler restarts it with the handoff mail waiting. For on-demand configured named targets, sends mail and returns without killing the session.

For controller-restartable targets, equivalent to:

gc mail send <target> <subject> [message] gc session kill <target>

Self-handoff requires session context (GC_ALIAS or GC_SESSION_ID, plus GC_SESSION_NAME and city context env). Remote handoff accepts a session alias or ID. Subject is required unless --auto is set.

gc handoff [subject] [message] [flags]

gc help

Help provides help for any command in the application. Simply type gc help [path to command] for full details.

gc help [command]

gc hook

Finds routed work using the agent's work_query config.

Without --inject: prints normalized ready-only output, exits 0 if work exists, 1 if empty. With --inject: silent legacy Stop-hook compatibility; skips the work query and always exits 0. With --claim: runs the standard startup claim protocol for one work item.

The agent is determined from $GC_AGENT or a positional argument.

gc hook [agent] [flags]

gc hook current

Prints the work bead this session most recently claimed with gc hook --claim.

The claim protocol stamps the claimed bead id onto the calling session's own bead, because the environment alone cannot reliably name it: $GC_BEAD_ID exists only in the controller's dispatch condition environment, never in a session shell, and $GC_TRIGGER_BEAD_ID — exported to demand-spawned pool seats as a pool-level spawn marker — is absent on other seats (e.g. a warm seat bound after start) and never decides what a session claims; the pool is pull. It appears in the chain below only as a name fallback for work already claimed: for a vapor wisp the trigger IS the work bead. A formula step that must close the bead it is running reads the stamp back here:

BEAD_ID="${GC_BEAD_ID:-${GC_TRIGGER_BEAD_ID:-$(gc hook current --id-only)}}"

The calling session is taken from $GC_SESSION_ID. Exits 1 when there is no session identity and when the session has claimed nothing, so a caller that cannot name its bead fails loudly instead of skipping its own work.

gc hook current [flags]

gc hook run

Runs a managed gc hook command in a child process with a hard timeout.

This protects provider hook callbacks from wedged data-plane commands. The child process is the current gc executable, and <gc args...> are passed to it verbatim.

gc hook run -- <gc args...> [flags]

gc import

Manage pack imports

gc import

gc import add

Add a pack import.

The source argument is resolved once and written as a durable [imports.<name>] entry using source plus optional version. Supported sources are:

• local paths outside git worktrees: stored as plain paths, with no lock entry
• local paths inside git worktrees at HEAD: promoted to a file:// repo source with the pack subpath and locked to the current commit
• remote git repositories: cloned and locked; --version accepts a semver constraint or sha:<commit>
• remote GitHub repository subpaths: use dereferenceable tree URLs such as https://github.com/org/repo/tree/main/packs/foo

Registry catalog handles are lookup shortcuts in this wave, not durable [imports.*] field values. After lookup, authored TOML stores the resolved source and optional version.

The [imports.<name>] table key is the local binding name. Imported package names are display/advisory metadata and never become registry identity.

gc import add <source> [flags]

Example:

gc import add ./packs/review
gc import add https://github.com/org/repo/tree/main/packs/review --version '^1.2.0'

# For uncommitted packs inside a git worktree, edit TOML directly:
# [imports.review]
# source = "/Users/you/shared-packs/packs/review"

gc import check

Validate installed pack import state

gc import check

gc import credential

Manage pack-source git credentials

gc import credential

gc import credential add

Register a pack-source credential

gc import credential add <match> (--helper CMD | --token-file PATH | --token-env NAME | --ssh-key-file PATH) [--username NAME] [--global] [flags]

gc import credential list

List registered pack-source credentials

gc import credential list

gc import credential remove

Remove a registered pack-source credential

gc import credential remove <match> [flags]

gc import install

Install imports from pack.toml and packs.lock

gc import install

gc import list

List imported packs

gc import list [flags]

gc import prune

Remove unreferenced clones from the machine-wide pack cache.

The pack cache (~/.gc/cache/repos) is shared by every city on the machine and is keyed by (source, commit), so commit churn accumulates stale clones over time. A clone is "referenced" when some city's packs.lock still pins it; prune keeps every referenced clone and removes only the rest.

By default prune considers every city in the supervisor registry plus the city resolved from the current directory; pass --all-cities to reference the full registry set and ignore the current directory. Prune is a dry run unless --apply is given. The --keep-days guard never removes an unreferenced clone whose directory was modified more recently than N days ago, protecting in-flight installs from a race.

gc import prune [flags]

gc import remove

Remove a pack import

gc import remove <name>

gc import status

Report declared imports and packs.lock pins.

Covers every import scope (root pack [imports.], [defaults.rig.imports.], and rig-scoped [rigs.imports.*]) plus the full packs.lock closure and the lockfile content hash. With --json the output is a stable machine-readable document for drift checkers.

gc import status [flags]

gc import upgrade

Upgrade imported packs within their constraints

gc import upgrade [name]

gc import why

Explain why an import is present

gc import why <name-or-source>

gc init

Create a new Gas City workspace in the given directory. With no path, the current directory is used only when stdin is an interactive terminal; otherwise pass an explicit path ("." for the current directory).

Runs an interactive wizard to choose a config template and coding agent provider. Creates the .gc/ runtime directory plus pack.toml, city.toml, the standard top-level directories, and .template.md prompt templates, and pins the builtin pack imports (resolved from the user-global pack cache). Use --template with --default-provider and an explicit path to create a city non-interactively, or --file to initialize from an existing TOML config file.

Pass --preserve-existing to keep any pre-authored pack.toml, city.toml, or agent prompt files in the target directory (useful when bootstrapping a committed workspace — e.g. from a bootstrap.sh shipped in the repo).

gc init [path] [flags]

Example:

gc init
gc init ~/my-city
gc init --default-provider codex ~/my-city
gc init --template gastown --default-provider codex ~/my-city
gc init --providers claude,codex --default-provider codex ~/my-city
gc init --default-provider codex --bootstrap-profile k8s-cell /city
gc init --name my-city
gc init --from ~/elan --name elan /city
gc init --file ./my-city.toml ~/bright-lights
gc init --file city.toml --preserve-existing .
gc init --template gascity --default-provider claude \
  --dolt-host db.example.com --dolt-port 4406 \
  --dolt-database bd_prj_x --dolt-project-id prj_x --no-start /city

gc lint

Validate a pack before merge.

gc lint <pack> validates the pack.toml file, reports non-fatal loader warnings, and parses prompt templates with the same missing-key behavior used by runtime prompt rendering. Use gc lint . to recursively find every pack.toml below the current directory.

gc lint <pack> [flags]

gc login

Log in to a hosted Gas City service and store a local API token.

By default this targets https://gascity.com; pass --at <url> to log in to any server that implements the Gas City Service Protocol v0. It opens a browser to sign in; use --device for headless shells, or --token to store an existing token. The token is stored per service under ~/.gc/credentials.json.

gc login [flags]

gc logout

Log out of a hosted Gas City service: revoke the session server-side, then remove the stored token. Because the session is the only long-lived credential, this is the kill switch for a leaked ~/.gc/credentials.json — the local token is always removed even if the server-side revoke fails or is not yet supported.

gc logout [flags]

gc mail

Send and receive messages between agents and humans.

Mail is implemented as beads with type="message". Messages have a sender, recipient, subject, and body. Use "gc mail check --inject" in agent hooks to deliver mail notifications into agent prompts.

gc mail

gc mail archive

Remove one or more message beads without displaying their contents.

Use this to dismiss messages without reading them. Each message is removed and will no longer appear in mail check or inbox results. When multiple IDs are passed, they are archived in input order.

For large advisory backlogs, use --to or --all-recipients with --subject-prefix, --subject-contains, or --from to archive a bounded matching slice without enumerating IDs by hand.

gc mail archive <id>... [flags]

gc mail check

Check for unread mail addressed to a session alias or mailbox.

Without --inject: prints the count and exits 0 if mail exists, 1 if empty. With --inject: outputs a <system-reminder> block suitable for hook injection (always exits 0). The recipient defaults to $GC_SESSION_ID, $GC_ALIAS, $GC_AGENT, or "human".

gc mail check [session] [flags]

Example:

gc mail check
gc mail check --inject
gc mail check mayor

gc mail count

Show total and unread message counts for a session alias or human. The recipient defaults to $GC_SESSION_ID, $GC_ALIAS, $GC_AGENT, or "human".

gc mail count [session] [flags]

gc mail delete

Delete one or more messages by closing the beads. Same effect as archive but with different user intent. When multiple IDs are passed, they are deleted in a single batch round-trip.

gc mail delete <id>... [flags]

gc mail inbox

List all unread messages for a session alias or human.

Shows message ID, sender, subject, and body in a table. The recipient defaults to $GC_SESSION_ID, $GC_ALIAS, $GC_AGENT, or "human". Pass a session alias to view another inbox.

gc mail inbox [session] [flags]

gc mail mark-read

Mark a message as read without displaying it. The message will no longer appear in inbox results.

gc mail mark-read <id> [flags]

gc mail mark-unread

Mark a message as unread. The message will appear again in inbox results.

gc mail mark-unread <id> [flags]

gc mail peek

Display a message without marking it as read.

Same output as "gc mail read" but does not change the message's read status. The message will continue to appear in inbox results.

gc mail peek <id> [flags]

gc mail read

Display a message and mark it as read.

Shows the full message details (ID, sender, recipient, subject, date, body). The message stays in the store — use "gc mail archive" to remove it.

gc mail read <id> [flags]

gc mail reply

Reply to a message. The reply is addressed to the original sender.

Inherits the thread ID from the original message for conversation tracking. Use --notify to request a recipient turn after replying. In a managed city, it can request a wake for a non-running recipient. Unread mail alone does not request a wake. Use -s/--subject for the reply subject and -m/--message for the reply body.

gc mail reply <id> [-s subject] [-m body] [flags]

gc mail send

Send a message to a session alias or human.

Creates a message bead addressed to the recipient. The sender defaults to $GC_SESSION_ID, $GC_ALIAS, $GC_AGENT, or "human". Use --notify to request a recipient turn after sending. In a managed city, it can request a wake for a non-running recipient. Unread mail alone does not request a wake. Use --from to override the sender identity. Use --to as an alternative to the positional <to> argument. Use -s/--subject for the summary line and -m/--message for the body text. Use --all to broadcast to all live sessions (excluding sender and "human").

gc mail send [<to>] [<body>] [flags]

Example:

gc mail send mayor "Build is green"
gc mail send mayor -s "Build is green"
gc mail send myrig/witness -s "Need investigation" -m "Attach logs from the last failed run"
gc mail send --to mayor "Build is green"
gc mail send human "Review needed for PR #42"
gc mail send polecat "Priority task" --notify
gc mail send --all "Status update: tests passing"

gc mail thread

Show all messages sharing a thread ID or message ID, ordered by time.

gc mail thread <id> [flags]

gc maintenance

Manage periodic Dolt store maintenance (see docs/adr/0002-dolt-store-maintenance-runbook.md).

The weekly loop runs inside the supervisor process when [maintenance.dolt] enabled=true in city.toml. 'status' shows loop state and recent runs; 'dolt-gc' triggers a manual run.

gc maintenance

gc maintenance dolt-gc

Trigger a Dolt store maintenance run

gc maintenance dolt-gc [flags]

gc maintenance status

Show Dolt store maintenance status

gc maintenance status [flags]

gc mcp

Inspect the projected MCP catalog for a concrete target.

Projected MCP is target-specific. Use "gc mcp list --agent <name>" when the agent has a single deterministic projection target from config, or "gc mcp list --session <id>" for a live session target.

gc mcp

gc mcp list

Show the precedence-resolved MCP servers that Gas City would project into the provider-native config for one agent or session target.

gc mcp list [flags]

gc metrics

Inspect or control Gas City command usage metrics

gc metrics

gc metrics example

Print the fixed state-independent command-usage request example

gc metrics example [flags]

gc metrics off

Disable command usage metrics and delete local queued data

gc metrics off

gc metrics on

Read and accept the command-usage disclosure on a verified TTY

gc metrics on

gc metrics status

Show redacted local command-usage metrics status

gc metrics status [flags]

gc nudge

Inspect and deliver deferred nudges.

Deferred nudges are reminders that were queued because the target agent was asleep or was not at a safe interactive boundary yet.

gc nudge

gc nudge status

Show queued and dead-letter nudges for a session.

Defaults to $GC_ALIAS or $GC_SESSION_ID when run inside a session.

gc nudge status [session] [flags]

gc order

Manage orders — scheduled or event-driven dispatch of formulas and scripts.

Orders live in flat orders/<name>.toml files. Each order pairs a trigger condition (cooldown, cron, condition, event, or manual) with an action (a formula or an exec script). The controller evaluates triggers on each tick and dispatches work when a trigger opens.

gc order

gc order check

Evaluate trigger conditions for all orders and show which are due.

Prints a table with each order's trigger, due status, and reason. Returns exit code 0 if any order is due, 1 if none are due.

gc order check [flags]

gc order history

Show execution history for orders.

Queries bead history for past order runs. Optionally filter by order name. Use --rig to filter by rig.

The read is bounded by default: only the most recent runs are fetched. Widen it with --limit (0 fetches every retained run) or bound it by time with --since. On a city with a long order-run history an unbounded read costs tens of seconds, so prefer keeping a bound when triaging.

gc order history [name] [flags]

gc order list

List all available orders with their trigger type, schedule, and target.

Scans orders/ directories for flat .toml files defining trigger conditions, scheduling parameters, and target pools.

gc order list [flags]

gc order run

Execute an order manually, bypassing its trigger conditions.

Formula orders instantiate a wisp from the order's formula and route it to the configured target (if any). Exec orders run their script directly — no wisp is created, and --json is rejected because the exec body may write arbitrary stdout. Useful for testing orders or triggering them outside their normal schedule. Use --rig to disambiguate same-name orders in different rigs. Use --var key=value (repeatable) to pass args to the order: formula orders receive them as formula vars, exec orders as environment variables. A param declared required in [order.params] must be supplied or the run fails.

gc order run <name> [flags]

gc order show

Display detailed information about a named order.

Shows the order name, description, formula reference, trigger type, scheduling parameters, check command, target, and source file. Use --rig to disambiguate same-name orders in different rigs.

gc order show <name> [flags]

gc order sweep-nudge-mail

Close stale delivered nudge beads and read mail beads.

Nudge beads that are past --nudge-ttl and not in the live nudge queue are closed. Read mail beads past --mail-ttl are closed. A budget cap of 50 closes per invocation prevents runaway sweeps under load.

Use --dry-run to log what would be closed without making any changes. The controller watchdog also runs this sweep automatically every 5 minutes.

gc order sweep-nudge-mail [flags]

gc order sweep-tracking

Close stale open order-tracking beads and prune expired closed history.

This is intended for maintenance exec orders. It only closes tracking beads older than --stale-after so a fresh in-flight order is not interrupted. Closed order-tracking history is deleted after [beads.policies.order_tracking].delete_after_close, defaulting to 7d, while always retaining at least the latest 10 closed tracking beads per order. The manual command runs to completion; controller startup and watchdog sweeps use bounded cleanup to avoid spending an unbounded tick on stale work.

Use --include-wisps for operator recovery of abandoned order-run wisp subtrees whose open descendants are also older than --stale-after. Pass one or more scoped order names when --include-wisps is set; wisp recovery is order-scoped to avoid scanning unrelated beads.

When the number of eligible closed-bead deletions exceeds GC_BULK_DELETE_CONFIRM_THRESHOLD (default 20), --confirm is required to proceed. This guard prevents accidental mass-deletes without an explicit operator acknowledgement.

gc order sweep-tracking [order ...] [flags]

gc pack

Manage remote pack sources that provide agent configurations.

Packs are git repositories containing pack.toml files that define agent configurations for rigs. They are cached locally and can be pinned to specific git refs.

gc pack

gc pack fetch

Clone missing and update existing remote pack caches.

Fetches all configured pack sources from their git repositories, updates the local cache, and writes a lockfile with commit hashes for reproducibility. Automatically called during "gc start".

gc pack fetch

gc pack list

Show configured pack sources with their cache status.

Displays each pack's name, source URL, git ref, cache status, and locked commit hash (if available).

gc pack list

gc pack registry

Manage configured Gas City pack registries, inspect cached catalog entries, authenticate to the hosted Registry, and publish packs.

Native Registry login stores a per-registry API token. When no explicit, environment, stored native, development, or GitHub Actions credential applies, the canonical hosted Registry uses the existing Gasworks login through "gasworks credential-provider". Set GC_CREDENTIAL_PROVIDER to a JSON argv array to configure that command without invoking a shell. Gasworks credentials are never persisted by gc and are never sent to custom Registry origins.

gc pack registry

gc pack registry add

Add a pack registry

gc pack registry add <registry-name> <source> [flags]

gc pack registry list

List configured pack registries

gc pack registry list [flags]

gc pack registry login

Log in to Gas City Registry and store a local API token.

By default this opens a browser for GitHub or Google Workspace sign-in. Use --device for headless shells, or --token to store an existing registry token.

gc pack registry login [flags]

gc pack registry publish

Submit a pack publish request to Gas City Registry.

The command requires a clean Git checkout whose current HEAD matches its configured upstream branch, then submits the GitHub repository, commit, pack path, pack name, and version to the registry API.

Registry pack names are scoped as <github-owner>/<pack>, where <github-owner> is the lowercased GitHub owner of the source repository. [pack].name must already carry that scoped name: the registry compares it byte-for-byte with the requested name, and reserves unscoped names for packs it already holds a claim for. --allow-unscoped-name submits such a legacy unscoped name anyway.

--dev-auth (localhost only) replaces all other credentials. Otherwise, authentication precedence is --token, GC_REGISTRY_TOKEN, a complete session cookie and CSRF-token pair from flags or the environment, a stored native Registry token, GitHub Actions OIDC, then the existing Gasworks login for the canonical hosted Registry. Run "gasworks login" once before using the provider, or use "gc pack registry login" to create a separate native Registry token.

gc pack registry publish <path-to-pack-root> [flags]

gc pack registry refresh

Refresh cached pack registry catalogs

gc pack registry refresh [registry-name] [flags]

gc pack registry remove

Remove a pack registry

gc pack registry remove <registry-name> [flags]

gc pack registry requests

Show recent publish requests you submitted to Registry, or one request with its feedback comments.

This command is read-only. Use a personal Registry token; run "gc pack registry login" if you have not logged in yet.

gc pack registry requests [request-id] [flags]

gc pack registry search

Search cached pack registry catalogs

gc pack registry search [query] [flags]

gc pack registry show

Show one pack registry entry

gc pack registry show <pack-name> [flags]

gc pack registry whoami

Show the Registry account for the active credential.

Explicit, environment, and stored native Registry tokens take precedence. For the canonical hosted Registry, gc otherwise uses the existing Gasworks login through the configured credential provider without storing its credential.

gc pack registry whoami [flags]

gc pack release

Author pack registry release metadata, including canonical pack content hashes.

gc pack release

gc pack release hash

Compute a pack release content hash

gc pack release hash <source> [flags]

gc pack release stamp

Stamp a registry release entry with a computed content hash

gc pack release stamp <registry.toml> <pack-name> [flags]

gc pack release validate

Validate registry release content hashes

gc pack release validate <registry.toml> [flags]

gc pack release verify

Verify a pack release content hash

gc pack release verify <source> [flags]

gc prime

Outputs the behavioral prompt for an agent.

Use it to prime any CLI coding agent with city-aware instructions: claude "$(gc prime mayor)" codex --prompt "$(gc prime worker)"

Runtime hook profiles may call gc prime --hook. When agent-name is omitted, GC_ALIAS is used (falling back to GC_AGENT).

If agent-name matches a configured agent with a prompt_template, that template is output. Otherwise outputs a default worker prompt.

Pass --strict to fail on debugging mistakes instead of silently falling back to the default prompt. Strict errors on:

• no city config found
• city config fails to load
• no agent name given (from args, GC_ALIAS, or GC_AGENT)
• agent name not in city config (typo detection — the main use case)
• agent's prompt_template points at a file that cannot be read

Strict does NOT error on agents whose config intentionally lacks a prompt_template (a supported minimal config), on templates that render to empty output from valid conditional logic, or on suspended states (city or agent) — those are legitimate quiet states, not mistakes.

gc prime [agent-name] [flags]

gc prompt

Subcommands for authoring agent prompt templates.

Currently the only subcommand is 'synth', which invokes the configured provider in one-shot mode to generate a prompt template for a given role.

gc prompt

gc prompt synth

Renders a meta-prompt with the given parameters, invokes the configured provider in one-shot mode, and emits the generated prompt template.

The default behavior prints the generated prompt to stdout. Pass --write to save it directly to <city>/agents/<role>/prompt.template.md (use --force to overwrite an existing file).

Context type is determined by --rig:

(no --rig) City context. The agent is HQ-only and operates at the city level (e.g. mayor, deacon). The meta-prompt emphasizes coordination, dispatch, monitoring. --rig <name> Rig context. The agent is attached to the named rig (looked up in city.toml). The meta-prompt includes the rig path, default branch, and project-aware guidance (git operations, branch management, etc.).

Auto-detection: --provider defaults to workspace.provider in city.toml

Baseline: The synth pulls in an existing prompt template as a refinement baseline so the LLM iterates on a known-good shape rather than designing from scratch. Resolution priority:

1. <city>/agents/<role>/prompt.template.md (user customization)
2. <composed pack dirs>/agents/<role>/ (pack default)
3. embedded prompts/<role>.md (built-in fallback)
4. embedded prompts/mayor.md (structural reference, used only when no role-specific source exists)

Two execution modes:

--writer-agent "" Direct mode (default). Spawns a one-shot subprocess of the configured provider; no Gas City agent is involved. Useful for bootstrap and offline-friendly invocations.

--writer-agent <name> Slingued mode. Creates a bead and slings the synth as work to the named agent via the mol-prompt-synth formula; the agent's session reads the meta-prompt, generates the prompt, and writes it to the destination.

Async by default — the CLI prints the bead ID + destination and returns immediately; use 'gc bd show <id>' to track progress. Pass --wait to block until the agent closes the bead (or --wait-timeout fires).

The output is LLM-generated. Review it carefully before relying on it. When --write is used, a comment header records the inputs and generation date for traceability.

gc prompt synth [flags]

gc ready

List ready, claimable work as a JSON array, federating the city store, the rig stores, and — on a split city — the relocated graph store where molecule roots, step beads and control beads live.

It is the in-process, city-wide drop-in for the single-store "bd ready" work query, so workers and the control plane see graph-class work instead of an authoritative-looking short answer. On a city that relocates no coordination class it reads the one store, unchanged.

The flags mirror the "bd ready" contract the default work_query builds: gc ready --metadata-field "gc.routed_to=$target" --unassigned
--exclude-type=epic --exclude-label "hold:mayor"
--sort oldest --limit 20 --json

Rows are emitted in canonical ready order (priority, created_at, id) unless --sort selects a created_at order, and --limit is applied last, so a bounded read is the true top-N of the merged set rather than the top-N of whichever store answered first.

Every leg is read across both storage tiers, so the wisp/ephemeral rows an orchestration step runs as are claimable work here whether or not --include-ephemeral is passed.

gc ready [flags]

gc register

Register a city directory with the machine-wide supervisor.

If no path is given, registers the current city (discovered from cwd). Use --name to set the machine-local registration alias. The alias is stored in the machine-local supervisor registry and never written back to city.toml. When --name is omitted, the current effective city identity is used (site-bound workspace name if present, otherwise legacy workspace.name, otherwise the directory basename) — in every case city.toml is not modified. Registration is idempotent — registering the same city twice is a no-op. The supervisor is started if needed and immediately reconciles the city.

gc register [path] [flags]

gc reload

Force the current city controller to re-read effective config and process one reload tick without restarting the city/controller.

Reload may fetch configured remote packs before recomputing effective config. By default, per-session restarts may still happen if normal config drift rules require them.

With --soft, the controller accepts any detected per-session config drift instead of draining the drifted sessions: each open session's recorded config hash is updated to the hash the freshly reloaded config produces for it, the matching hash breakdown is refreshed, and any already queued config-drift drain for that session is canceled. The immediately-following reconcile tick sees no drift and no config-drift drains fire. Useful when editing a running city's .gc/settings.json without disrupting in-flight work. Sessions whose template no longer maps to a configured agent are NOT updated; normal orphan/suspended drain handles them on the next tick.

gc reload [path|name] [flags]

gc restart

Restart the city by stopping it then starting it again.

Equivalent to running "gc stop" followed by "gc start". Under supervisor mode this unregisters the city, then re-registers it and triggers an immediate reconcile.

gc restart [path|name] [flags]

gc resume

Resume a suspended city by recording an explicit "resumed" preference in .gc/runtime/suspension-state.json. The override sticks across city restarts even when [workspace] declares suspended_on_start = true.

Restores normal operation: the reconciler will spawn agents again and gc hook/prime will return work. Use "gc agent resume" to resume individual agents, or "gc rig resume" for rigs.

gc resume [path|name] [flags]

gc rig

Manage rigs (external project directories) registered with the city.

Rigs are project directories that the city orchestrates. Each rig gets its own beads database, agent hooks, and cross-rig routing. Agents are scoped to rigs via their "dir" field.

gc rig

gc rig add

Register an external project directory as a rig.

Initializes beads database, installs agent hooks if configured, generates cross-rig routes, and appends the rig to city.toml. If the target directory doesn't exist, it is created. Use --include to apply a pack source that defines the rig's agent configuration; repeat the flag to compose multiple packs for one rig. The flag is compatibility sugar: gc rig add writes canonical rig imports.

--include takes a pack source (local path or remote URL) or a pack name: a bundled pack ("gastown"), or a registry pack resolved from the cached registry catalogs, including a scoped community name ("owner/pack"). A "./" prefix or a "packs/<name>" token is never read as a registry name (a bundled pack still canonicalizes, so "./gastown" resolves to the bundled source), and an existing directory always wins over a registry pack of the same name.

Use --name to set the rig name explicitly (default: directory basename). Use --prefix to set the bead ID prefix explicitly (default: derived from name). Use --default-branch to set the rig's mainline branch explicitly. By default, gc rig add probes the repo's remote HEADs — origin first, then any other configured remote — and falls back to the currently checked-out branch, then stores the result in city.toml so polecats and the refinery target the right branch without manual metadata patching. The banner reports which remote answered, or says the branch was inferred when no remote HEAD is set. Use --start-suspended to add the rig in a suspended state (dormant-by-default). The rig's agents won't spawn until explicitly resumed with "gc rig resume".

Use --adopt to register a directory that already has a fully initialized .beads/ directory (must include both metadata.json and config.yaml). For managed-Dolt rigs, runs an idempotent config sync (registers types.custom and other config into the DB, never destructively reinitializes). The git repo check remains informational.

gc rig add <path> [flags]

Example:

gc rig add /path/to/project
gc rig add /path/to/project --name myrig
gc rig add /path/to/project --prefix r1
gc rig add /path/to/master-repo --default-branch master
gc rig add ./my-project --include gastown
gc rig add ./my-project --include packs/planner --include packs/architect
gc rig add ./my-project --include acme/planner
gc rig add ./my-project --include gastown --start-suspended
gc rig add /path/to/existing --adopt

gc rig list

List all registered rigs with their paths, prefixes, default branches, and beads status.

Shows the HQ rig (the city itself) and all configured rigs. Each rig displays its bead ID prefix, recorded default branch when set, and whether its beads database is initialized.

gc rig list [flags]

gc rig remove

Remove a rig from the current city's configuration.

Removes the rig entry from city.toml and removes its machine-local path binding from .gc/site.toml.

gc rig remove <name> [flags]

Example:

gc rig remove myrig

gc rig restart

Kill all agent sessions belonging to a rig.

The reconciler will restart the agents on its next tick. This is a quick way to force-refresh all agents working on a particular project.

gc rig restart [name]

gc rig resume

Resume a suspended rig by recording an explicit "resumed" preference in .gc/runtime/suspension-state.json. The override sticks across city restarts even when the rig declares suspended_on_start = true.

The reconciler will start the rig's agents on its next tick.

gc rig resume [name] [flags]

gc rig set-endpoint

Set the canonical endpoint ownership for a rig.

Use --inherit to make a rig derive its endpoint from the current city topology. Use --external to pin the rig to its own external Dolt endpoint. Use --self to mark the rig as running its own local Dolt server on 127.0.0.1 at the given --port; while the city is in managed_city mode the command requires --force because the rig's .beads/dolt-server.port mirror will no longer track the managed city Dolt.

This command owns the rig's canonical .beads/config.yaml topology state.

gc rig set-endpoint <rig> [flags]

Example:

gc rig set-endpoint frontend --inherit
gc rig set-endpoint frontend --external --host db.example.com --port 3307
gc rig set-endpoint frontend --external --host db.example.com --port 3307 --user agent --adopt-unverified
gc rig set-endpoint frontend --self --port 28232 --force
gc rig set-endpoint frontend --inherit --dry-run

gc rig status

Show rig status and agent running state

gc rig status [name] [flags]

gc rig suspend

Suspend a rig by recording the suspension in the runtime state file (.gc/runtime/suspension-state.json).

All agents scoped to the suspended rig are effectively suspended — the reconciler skips them and gc hook returns empty. The rig's beads database remains accessible. Use "gc rig resume" to restore.

Suspension state is stored in the runtime directory, not city.toml, so it is local to this machine and does not need to be committed.

gc rig suspend [name] [flags]

gc runtime

Process-intrinsic runtime operations called by agent code from within sessions.

These commands read and write session metadata to coordinate lifecycle events (drain, restart) between agents and the controller. They are designed to be called from within running agent sessions, not by humans.

The exception is "gc runtime check", which validates a Runtime Provider Protocol executable — run by humans and runtime-pack CIs.

gc runtime

gc runtime check

Validate a runtime executable against the Runtime Provider Protocol (RPP v0).

Runs the protocol handshake, the required lifecycle round-trip (start, is-running, stop, idempotent stop), exercises every capability the handshake declares, and probes optional operations. Optional operations that are absent (exit 2) are reported but never fail the run; everything else that misbehaves does. Exits non-zero if any check fails, so a runtime pack's CI can gate on it directly.

One exception: when the argument resolves to a pack-declared runtime whose [runtimes.<name>] entry declares prompt_delivery = "nudge-fallback", the nudge probe is reported as "required: nudge" and an absent or broken nudge op fails the run — the declaration is smoke-tested, not trusted.

The argument is an executable (path or PATH name) or a pack-declared runtime name: when it names a [runtimes.<name>] entry from the current city's packs, the check runs against that pack's declared command. Arguments containing a path separator, or matching an existing file, are always treated as the executable itself.

The protocol contract is docs/reference/exec-session-provider.md.

gc runtime check <name|executable> [flags]

gc runtime conformance

Run the golden Runtime Provider Protocol conformance suite against an executable. Every requirement is requirement-coded (RPP-<GROUP>-NNN) and mirrors the in-tree provider contract (RunProviderTests); a run that passes every required requirement is guaranteed to behave like a gascity runtime.

Unlike "gc runtime check" (a lighter smoke test), each requirement is proven to gate: the suite is kept honest by negative tests in which a broken reference fails exactly its requirement's check.

The argument is an executable (path or PATH name) or a pack-declared runtime name from the current city's packs. Path-like or existing-file arguments are always the executable itself.

Use --json for a machine-readable report (CI artifacts). Exits non-zero if any required requirement fails.

gc runtime conformance <name|executable> [flags]

gc runtime drain

Signal a session to drain — wind down its current work gracefully.

Sets a GC_DRAIN metadata flag on the session. The agent should check for drain status periodically (via "gc runtime drain-check") and finish its current task before exiting. Pass a session alias or ID. Use "gc runtime undrain" to cancel.

gc runtime drain <name> [flags]

gc runtime drain-ack

Acknowledge a drain signal — tell the controller to stop this session.

Sets GC_DRAIN_ACK metadata on the session, then pokes the controller socket so the reconciler stops the session immediately rather than on its next patrol tick. Call this after the session has finished its current work in response to a drain signal.

gc runtime drain-ack [name] [flags]

gc runtime drain-check

Check if a session is currently draining.

Returns exit code 0 if draining, 1 if not. Designed for use in conditionals: "if gc runtime drain-check; then finish-up; fi". Without arguments, uses the current session context.

gc runtime drain-check [name] [flags]

gc runtime heartbeat

Extend the idle-timeout and max-session-age windows during a long operation.

Sets held_until on the current session's bead, suppressing the idle-timeout and max-session-age timers until the hold expires. Call this at the start of slow operations that produce no terminal output and would otherwise trigger a false-alarm watchdog kill.

The hold is automatically cleared by the reconciler once held_until passes. This is the agent-facing API for the held_until bead-metadata mechanism; it does not put the session into a suspended state or change its sleep_intent.

The default duration (45m0s) covers long-running operations. Pass --duration to override.

gc runtime heartbeat [flags]

gc runtime request-restart

Signal the controller to stop and restart this session.

Sets GC_RESTART_REQUESTED metadata on the session, then waits while the controller stops the session on its next reconcile tick and restarts it fresh. The wait keeps the agent idle so it does not consume more context in the interim.

Under normal operation the controller SIGKILLs the process tree before this command returns. If the controller accepts the stop handoff, the runtime is already gone, or a SIGINT/SIGTERM is received, the command exits 0 cleanly. If the controller has not acted within a bounded timeout (max(5*PatrolInterval, 5min), capped at 30min) the command exits 1 with a diagnostic pointing at controller health.

This command is designed to be called from within a session context. It emits a session.draining event before waiting.

gc runtime request-restart

gc runtime undrain

Cancel a pending drain signal on a session.

Clears the GC_DRAIN and GC_DRAIN_ACK metadata flags, allowing the session to continue normal operation. Pass a session alias or ID.

gc runtime undrain <name> [flags]

gc service

Inspect workspace services

gc service

gc service doctor

Show detailed workspace service status

gc service doctor <name> [flags]

gc service list

List workspace services

gc service list [flags]

gc service restart

Stop and restart a workspace service by name.

The controller closes the current service process and starts a fresh one. Useful after updating pack scripts without a full city restart.

gc service restart <name> [flags]

gc session

Create, resume, suspend, and close persistent conversations with agents.

Sessions are conversations backed by agent templates. They can be suspended to free resources and resumed later with full conversation continuity.

gc session

gc session attach

Attach to a running session or resume a suspended one.

If the session is active with a live tmux session, reattaches. If the session is suspended or the tmux session died, resumes using the provider's resume mechanism (if supported) or restarts.

Accepts a session ID (e.g., gc-42) or session alias (e.g., mayor).

gc session attach <session-id-or-alias>

gc session close

End a conversation. Stops the runtime if active and closes the bead.

Accepts a session ID (e.g., gc-42) or session alias (e.g., mayor).

gc session close <session-id-or-alias> [flags]

gc session kill

Force-kill the runtime process for a session without changing its bead state.

The session remains marked as active, so the reconciler will detect the dead process and restart it according to the session's lifecycle rules. This is useful for unsticking a session without losing its conversation history.

Accepts a session ID (e.g., gc-42) or session alias (e.g., mayor).

gc session kill <session-id-or-alias> [flags]

gc session list

List all chat sessions. By default shows active and suspended sessions.

gc session list [flags]

gc session logs

Show structured session log messages from a session's JSONL file.

Reads the session log, resolves the conversation DAG, and prints messages in chronological order. Searches default paths (~/.claude/projects/) and any extra paths from [daemon] observe_paths in city.toml.

Use --tail to print only the last N transcript entries (0 = all). Semantics match Unix 'tail -n': '--tail 5' prints the final 5 entries, not the first 5. A single assistant turn with multiple tool-use blocks still counts as one entry. Compact-boundary dividers count as entries when they fall inside the final window.

Compatibility note: before 1.0, --tail mapped to compaction segments. As of 1.0, --tail trims the displayed transcript entry window instead. The HTTP API's tail query parameter still uses compaction-segment semantics. Use -f to follow new messages as they arrive.

gc session logs <session> [flags]