STD-GC-001: Gas City Command Taxonomy & Interface Reference
Status: APPROVED & BINDING
Authority: BluCity-Docs/Engineering-Standard/standards/gas-city/STD-GC-001-gas-city-command-taxonomy-and-interface-reference.md
Scope: Estate-wide Gas City runtime, agent workflows, shell environment convergence, and interface contracts.
1. Overview & Architectural Intent
Gas City (gc) is the primary orchestration runtime for the Bluefly Agent Factory. Every agent interaction, session lifecycle event, inter-agent message, work routing operation, and external conversation binding MUST use gc native commands.
This document establishes the canonical command taxonomy for all 58 gc CLI commands, detailing their functional categories, exact parameters, operational trust boundaries, and shell convergence rules.
2. Command Taxonomy Matrix (58 Native Commands)
2.1 External Messaging & Inter-Agent Operations
| Command |
Purpose |
Subcommands & Key Parameters |
Trust & Transport |
extmsg |
External Conversation Bindings: Binds external messaging platforms (Telegram, Discord, webhooks, ContextControl) to Gas City agents/sessions. Bound conversations survive session restarts and cold-wake agents on inbound messages. Supports front-desk routing via extmsg handoff. |
gc extmsg bind <conv-id> <agent>
gc extmsg handoff <conv-id> <new-agent>
gc extmsg unbind <conv-id> |
Requires City API Server. No local fallback. |
mail |
Inter-Agent & Human Messaging: Durable asynchronous communication implemented as type="message" Beads in Dolt. Stores sender, recipient, subject, and body. |
gc mail send <recipient> -s "Subject" -m "Body"
gc mail check --inject
gc mail read <id> |
Synchronized across Dolt :3308/hq. |
sling |
Targeted Work Routing: Directly routes a Bead or materialized Formula to an agent or session config using work queries (sling_query). |
gc sling <agent> <bead-id>
gc sling <agent> <formula-name> --formula |
Controller-governed dispatch. |
handoff |
Session Handoff & Self-Restart: Sends context handoff mail and requests a clean session restart by the Gas City controller. |
gc handoff
gc handoff <target-agent> |
Process-intrinsic runtime signal. |
nudge |
Interactive Boundary Nudges: Delivers deferred reminders queued while an agent was sleeping or busy at a non-interactive boundary. |
gc nudge list
gc nudge deliver <id> |
Local/Server event queue. |
2.2 Work Graph & Durable Beads Integration
| Command |
Purpose |
Subcommands & Key Parameters |
Trust & Transport |
convoy |
Work Graph Management: Groups related Beads into trackable Convoys. Propagates target branches and triggers on_close hooks upon completion. |
gc convoy create "<title>" --target release/v0.1.x
gc convoy list
gc convoy check
gc convoy land <id> |
Native Dolt graph object. |
graph |
Dependency Visualization: Resolves and displays dependency trees for Beads or Convoys, highlighting blockers and ready work. |
gc graph <bead-id\|convoy-id> |
Read-only graph query. |
bd |
Rig-Scoped Beads CLI: Proxies bd execution directly inside the correct rig directory and Dolt server port. |
gc bd list
gc bd show <bead> |
Executable wrapper over bd. |
beads |
Beads Provider Config: Manages the underlying Beads database provider bindings for the city workspace. |
gc beads status
gc beads health |
System health check. |
dolt-cleanup |
Dolt DB Maintenance: Identifies and removes orphaned Dolt database directories across rig ports. |
gc dolt-cleanup --dry-run |
Admin maintenance. |
maintenance |
Store GC & Snapshots: Triggers or inspects periodic Dolt garbage collection and store compaction runs. |
gc maintenance status
gc maintenance dolt-gc |
Supervisor scheduled loop. |
| Command |
Purpose |
Subcommands & Key Parameters |
Trust & Transport |
formula |
Reusable Methods (HOW): Manages and validates TOML workflow specifications (Formula V2 engine: DETECT → AUTHORIZE → ACT → VERIFY → PROVE). |
gc formula list
gc formula show <name>
gc formula run <name> |
Immutable TOML specification. |
order |
Automated Dispatch (WHEN): Configures scheduled or event-driven triggers (cron, cooldown, event, condition, manual) that execute Formulas. |
gc order list
gc order trigger <name> |
Supervisor event subscriber. |
event / events |
Append-Only Event Stream: Observes and emits immutable Gas City runtime events (e.g., Bead state transitions, session lifecycle). |
gc events --follow
gc event emit --type <category> |
Event stream API. |
converge |
Iterative Refinement: Manages bounded convergence loops for automated verification and repair cycles. |
gc converge status
gc converge run |
Loop reconciler engine. |
agent-script |
Deterministic Execution: Runs non-LLM, deterministic YAML agent scripts for high-frequency mechanical operations. |
gc agent-script run <script.yaml> |
Deterministic runner. |
2.4 Agent Lifecycle, Sessions & Prompts
| Command |
Purpose |
Subcommands & Key Parameters |
Trust & Transport |
agent |
Agent Roster: Lists and inspects configured agent definitions, roles, providers, and capabilities within the city. |
gc agent list
gc agent show <name> |
Config reader. |
session |
Interactive Session Lifecycle: Manages persistent LLM conversations. Supports suspension to free RAM and resumption with context preserved. |
gc session list
gc session suspend <id>
gc session resume <id> |
Controller multiplexer. |
prime |
Agent Prompt Priming: Outputs the complete rendered system prompt for initializing any LLM CLI tool (e.g. Claude Code). |
claude "$(gc prime mayor)" |
Local prompt renderer. |
prompt |
Prompt Template Authoring: Synthesizes and tests prompt templates for specific agent roles. |
gc prompt synth --role <role> |
One-shot provider invocation. |
runtime |
Internal Session Primitives: Low-level session lifecycle hooks invoked by running agent code (drain, restart). |
gc runtime drain |
In-session process call. |
build-image |
Prebaked Container Images: Builds container images containing prebaked dependencies for isolated agent execution. |
gc build-image --agent <name> |
Container engine build. |
2.5 Workspace Infrastructure, Rigs & Governance
| Command |
Purpose |
Subcommands & Key Parameters |
Trust & Transport |
init |
City Bootstrap: Interactive wizard to create a new Gas City workspace (city.toml, .gc/, pack.toml). |
gc init <city-name> |
File generator. |
start / stop / restart |
Supervisor Service Control: Starts, stops, or restarts all agent sessions and controllers under the supervisor daemon. |
gc start
gc stop
gc restart |
Supervisor IPC. |
suspend / resume |
Workspace Suspension: Temporarily pauses or resumes all active agent sessions across the entire city. |
gc suspend
gc resume |
Suspension state flag. |
status |
City Overview: Shows controller health, running/suspended agents, registered rigs, and active sessions. |
gc status |
Read-only city query. |
doctor |
Diagnostic Health Check: Verifies workspace structure, city.toml validity, binary dependencies (tmux, git, dolt, bd), and orphan processes. |
gc doctor |
Diagnostic audit script. |
rig |
Project Registration: Registers, lists, and manages external source repositories (Rigs) orchestrated by the City. |
gc rig list
gc rig add <path> |
City config binding. |
pack / import / lint |
Pack Configuration: Imports and validates remote/local configuration Packs (pack.toml) supplying agents and formulas. |
gc pack list
gc import add <url>
gc lint <pack-path> |
Pack loader & linter. |
config / reload |
Configuration Governance: Validates and hot-reloads city.toml rules without restarting session processes. |
gc config validate
gc reload |
Controller config reloader. |
2.6 Multi-City, Hosted Cloud, Cost & Observability
| Command |
Purpose |
Subcommands & Key Parameters |
Trust & Transport |
supervisor / register |
Machine Supervisor Daemon: Manages the machine-wide supervisor process that hosts multiple cities on one API server. |
gc supervisor status
gc register --name <alias> |
Supervisor daemon API. |
cities / context |
Multi-City Context Navigation: Navigates between local and remote Gas City environments configured in ~/.gc/contexts.toml. |
gc cities list
gc context use <remote-city> |
Remote context switcher. |
login / logout / whoami |
Hosted Service Auth: Authenticates against hosted Gas City API backends (gascity.com or private clusters). |
gc login --at <url>
gc whoami |
OAuth/Token session credentials. |
costs |
Token & Compute Usage: Aggregates token spend and compute wall-seconds from .gc/usage.jsonl. |
gc costs --by-agent |
Local usage log aggregator. |
dashboard |
Web UI Dashboard: Launches the embedded single-page web dashboard served directly by the supervisor. |
gc dashboard |
Supervisor web server. |
mcp |
Targeted MCP Inspection: Displays projected Model Context Protocol (MCP) server configurations per agent. |
gc mcp list --agent <name> |
MCP catalog compiler. |
skill |
Skill Library Discovery: Discovers all versioned Skills available across imported packs and city folders. |
gc skill list |
Skill registry scanner. |
metrics / trace |
Telemetry & Tracing: Inspects CLI command invocation frequency and reconciler tracing output. |
gc metrics
gc trace |
System telemetry. |
shell |
CLI Shell Autocompletion: Manages zsh/bash shell autocompletion hooks. |
gc shell install |
Shell RC installer. |
analyze / wait |
Analytics & Delays: Runs read-only analytical queries over events/beads or manages durable session waits. |
gc analyze --events
gc wait list |
Analytical engine. |
3. Shell Environment Convergence Rules
gc Protection Law: The gc executable MUST NEVER be aliased to git commit or any other git command. gc is strictly reserved for Gas City.- Zero Plaintext Secrets in Shell Configuration: No API tokens, private SSH keys, or Tailscale auth keys may be committed or stored in shell startup scripts (
.zshrc, .zshenv, .zprofile). Secrets must be delivered via 1Password Credential Broker references or environment variable passes.
- No Personal Absolute Paths: Shell configurations must use standard PATH resolution or
$HOME relative anchors instead of hardcoded workstation paths.
- Single Startup Responsibility:
.zshenv: Non-interactive environment variables only..zprofile: Login shell PATH initialization..zshrc: Interactive alias shorthand and shell autocompletion hooks.
4. Verification & Governance
- Documentation Standard:
STD-GATE-001
- Execution Gate:
STD-WORK-001
- Economic Scorecard:
STD-ECON-001