Gas City

https://docs.gascityhall.com
Admin
Gas City is an open-source orchestration-builder SDK for multi-agent systems that enables teams to...
Tokens:92,458
Snippets:1,360
Trust Score:4.4
Update:5 months ago
Show doc for...
Tokens:
Raw
### Build and Install gascity from Source

Source: https://docs.gascityhall.com/getting-started/installation

Clone the repository, navigate to the directory, and use 'make install' to build and install the gascity binary. Ensure you have Go 1.25+ and 'make' installed.

```bash
git clone https://github.com/gastownhall/gascity.git
cd gascity
make install        # builds and installs to $(GOPATH)/bin/gc
gc version
```

--------------------------------

### Install supervisor as a platform service

Source: https://docs.gascityhall.com/reference/cli

Installs the machine-wide supervisor as a platform service that starts automatically on login.

```bash
gc supervisor install
```

--------------------------------

### Contributor Setup for gascity

Source: https://docs.gascityhall.com/getting-started/installation

After building from source, set up the development toolchain and install pre-commit hooks. This ensures code quality and consistency for contributors.

```bash
make setup
make check          # runs fmt, lint, vet, and unit tests
```

--------------------------------

### Install gc Binary to PATH

Source: https://docs.gascityhall.com/getting-started/troubleshooting

If `gc` is not found after installation, ensure the binary is in your system's PATH. This command installs the binary to `~/.local/bin/gc`.

```bash
install -m 755 gc ~/.local/bin/gc   # or /usr/local/bin/gc
```

--------------------------------

### Start the City and List Orders

Source: https://docs.gascityhall.com/tutorials/07-orders

Use `gc start` to initiate the city's services and `gc order list` to view all configured orders, their types, triggers, and targets.

```shell
~/my-city
$ gc start
City 'my-city' started

~/my-city
$ gc order list
NAME           TYPE     TRIGGER      INTERVAL/SCHED  TARGET
lint-check     exec     cooldown  30s             -
release-notes  formula  cron      0 9 * * 1       worker

```

--------------------------------

### Verify gc Installation

Source: https://docs.gascityhall.com/getting-started/troubleshooting

After installing `gc` to your PATH, verify its accessibility and check the version.

```bash
which gc
gc version
```

--------------------------------

### Pack Structure Example

Source: https://docs.gascityhall.com/guides/shareable-packs

Illustrates the conventional directory structure for a PackV2.

```text
code-review-pack/
├── pack.toml
├── agents/
│   └── reviewer/
│       ├── agent.toml
│       └── prompt.template.md
├── formulas/
│   └── review-change.toml
├── orders/
│   └── nightly-review.toml
├── commands/
│   └── status/
│       ├── help.md
│       └── run.sh
├── doctor/
│   └── check-review-tools/
│       └── run.sh
├── overlay/
├── skills/
├── mcp/
├── template-fragments/
└── assets/
    └── scripts/
        └── setup-reviewer.sh
```

--------------------------------

### Start Operation JSON Config

Source: https://docs.gascityhall.com/reference/exec-session-provider

The 'start' operation receives a JSON object on stdin containing configuration details for the session. All fields are optional.

```json
{
  "work_dir": "/path/to/working/directory",
  "command": "claude --dangerously-skip-permissions",
  "env": {"GC_AGENT": "mayor", "GC_CITY": "/home/user/bright-lights"},
  "process_names": ["claude", "node"],
  "nudge": "initial prompt text",
  "pre_start": ["mkdir -p /workspace", "git clone repo /workspace"]
}
```

--------------------------------

### gc import install

Source: https://docs.gascityhall.com/reference/cli

Install pack imports defined in pack.toml and pack.lock files.

```APIDOC
## gc import install

Install imports from pack.toml and packs.lock

```
gc import install
```
```

--------------------------------

### Start a city with gc

Source: https://docs.gascityhall.com/reference/cli

Starts a city under the machine-wide supervisor. Requires an existing city bootstrapped by 'gc init'. Fetches remote packs, registers the city, ensures the supervisor is running, and triggers reconciliation. Use 'gc supervisor run' for foreground operation.

```bash
gc start [path] [flags]
```

```bash
gc start
  gc start ~\/my-city
  gc start --dry-run
  gc supervisor run
```

--------------------------------

### Agent Configuration with agent.toml

Source: https://docs.gascityhall.com/guides/shareable-packs

Specifies agent-specific settings like scope, nudge message, and timeouts. `pre_start` can execute setup scripts.

```toml
# agents/reviewer/agent.toml
scope = "rig"
nudge = "Check your hook, review the assigned change, and leave findings."
idle_timeout = "30m"
min_active_sessions = 0
max_active_sessions = 3
pre_start = ["{{.ConfigDir}}/assets/scripts/setup-reviewer.sh {{.RigRoot}}"]
```

--------------------------------

### Migration example for commands

Source: https://docs.gascityhall.com/guides/migrating-to-pack-vnext

Illustrates the transition from an inline command definition in `city.toml` to the new directory-based structure.

```toml
# Old:
[[commands]]
name = "status"
description = "Show status"
script = "commands/status.sh"

```

```text
# New simple case:
commands/status/run.sh

```

```text
# New richer case:
commands/repo-sync/
├── command.toml
├── run.sh
└── help.md

```

--------------------------------

### Refactored script placement - entry local

Source: https://docs.gascityhall.com/guides/migrating-to-pack-vnext

Example showing an entrypoint script placed next to its command.

```text
commands/status/run.sh
```

--------------------------------

### Download and Install gascity (Direct)

Source: https://docs.gascityhall.com/getting-started/installation

Download the release tarball for your platform, extract it, and install the binary to a directory on your PATH. This method requires manual verification of release artifacts.

```bash
# Set the version you want (check https://github.com/gastownhall/gascity/releases)
VERSION=1.1.0

# Detect platform
OS=$(uname -s | tr '[:upper:]' '[:lower:]')
ARCH=$(uname -m)
case "$ARCH" in
  x86_64)         ARCH=amd64 ;;
  aarch64|arm64)  ARCH=arm64 ;;
esac

# Download and extract
curl -fsSLO "https://github.com/gastownhall/gascity/releases/download/v${VERSION}/gascity_${VERSION}_${OS}_${ARCH}.tar.gz"
tar -xzf "gascity_${VERSION}_${OS}_${ARCH}.tar.gz"

# Move to a directory on your PATH
sudo install -m 755 gc /usr/local/bin/gc

# Verify
gc version
```

--------------------------------

### Initialize a Gas City Hall City

Source: https://docs.gascityhall.com/getting-started/quickstart

Bootstrap a new city directory, register it with the supervisor, and start the controller. This command should be run in the desired parent directory for your city.

```bash
gc init ~/bright-lights
cd ~/bright-lights
```

--------------------------------

### Preview Docs Locally

Source: https://docs.gascityhall.com/getting-started/installation

Preview the documentation site locally by running the './mint.sh dev' script from the repository root. This command starts a local development server for the docs.

```bash
./mint.sh dev
```

--------------------------------

### Install Gas City CLI

Source: https://docs.gascityhall.com/tutorials/01-cities-and-rigs

Install the Gas City CLI using Homebrew. Ensure your system meets the prerequisites.

```shell
~
$ brew install gascity
...
```

--------------------------------

### Initialize a New City with gascity

Source: https://docs.gascityhall.com/getting-started/installation

Create your first city project using the 'gc init' command, followed by navigating into the new city's directory. This command registers the city with the supervisor and starts it.

```bash
gc init ~/my-city
cd ~/my-city
```

--------------------------------

### Install Gas City with Homebrew

Source: https://docs.gascityhall.com/getting-started/installation

Use this command to install Gas City and all its dependencies using Homebrew. This is the recommended method for most users.

```bash
brew install gastownhall/gascity/gascity
```

--------------------------------

### Initialize GC Mail

Source: https://docs.gascityhall.com/reference/cli

Run this command to start the mail service or check its status.

```bash
gc mail
```

--------------------------------

### Verify gascity Installation

Source: https://docs.gascityhall.com/getting-started/installation

Confirm that the gascity installation is successful by running the 'gc version' command. This should display the installed version and commit hash.

```bash
gc version          # should print the installed version and commit
```

--------------------------------

### Install pack imports

Source: https://docs.gascityhall.com/reference/cli

Use this command to install pack imports defined in your pack.toml and packs.lock files. This is typically done after adding or modifying import configurations.

```bash
gc import install
```

--------------------------------

### Install flock on macOS

Source: https://docs.gascityhall.com/getting-started/troubleshooting

Install the `flock` utility on macOS using Homebrew, as it is not included by default. This is required for the default beads provider.

```bash
brew install flock
```

--------------------------------

### Verify Gas City Installation

Source: https://docs.gascityhall.com/getting-started/installation

After installation, run this command to verify that Gas City is installed correctly and check its version.

```bash
gc version
```

--------------------------------

### Check Make and Go Versions

Source: https://docs.gascityhall.com/getting-started/troubleshooting

Verify that `make` and `go` are installed and meet the minimum version requirements for building Gas City from source.

```bash
make --version
go version
```

--------------------------------

### Refactored script placement - general helper

Source: https://docs.gascityhall.com/guides/migrating-to-pack-vnext

Example showing a general helper script moved to the assets directory.

```text
assets/scripts/setup.sh
```

--------------------------------

### Start supervisor in background

Source: https://docs.gascityhall.com/reference/cli

Starts the machine-wide supervisor in the background by forking the 'gc supervisor run' process and verifying its readiness.

```bash
gc supervisor start
```

--------------------------------

### Register a new rig

Source: https://docs.gascityhall.com/reference/cli

Register an external project directory as a rig. This initializes its database, installs agent hooks, generates routes, and adds it to the city configuration. The directory can be created if it doesn't exist. Use --include to apply agent configurations from packs and --start-suspended to add it in a dormant state.

```bash
gc rig add <path> [flags]
```

```bash
gc rig add /path/to/project
```

```bash
gc rig add /path/to/project --name myrig
```

```bash
gc rig add /path/to/project --prefix r1
```

```bash
gc rig add ./my-project --include packs/gastown
```

```bash
gc rig add ./my-project --include packs/planner --include packs/architect
```

```bash
gc rig add ./my-project --include packs/gastown --start-suspended
```

```bash
gc rig add /path/to/existing --adopt
```

--------------------------------

### Migrating scripts/ directory

Source: https://docs.gascityhall.com/guides/migrating-to-pack-vnext

Example of refactoring the old scripts/ directory structure. Entrypoint scripts should be placed next to their command or doctor, while general helpers move to assets/.

```text
scripts/
└── setup.sh
```

--------------------------------

### Serve GC dashboard with gc dashboard serve

Source: https://docs.gascityhall.com/reference/cli

Starts the static GC dashboard against the machine-wide supervisor API. Similar to `gc dashboard`, it provides supervisor or city-specific views based on the context.

```bash
gc dashboard serve [flags]
```

--------------------------------

### gc trace start

Source: https://docs.gascityhall.com/reference/cli

Starts or extends tracing for a specified template. Tracing can be marked as auto-triggered, set to a specific level (baseline or detail), and have a defined duration.

```APIDOC
## gc trace start

Start or extend tracing for a template

```
gc trace start [flags]
```

| Flag         | Type   | Default  | Description                        |
| ------------ | ------ | -------- | ---------------------------------- |
| `--auto`     | bool   |          | mark the arm as auto-triggered     |
| `--for`      | string | `15m`    | trace arm duration (e.g. 15m)      |
| `--level`    | string | `detail` | trace level: baseline or detail    |
| `--template` | string |          | exact normalized template selector |
```

--------------------------------

### Explain pack import presence

Source: https://docs.gascityhall.com/reference/cli

Use this command to understand why a specific pack import is present in your project. Provide the name or source of the import to get an explanation.

```bash
gc import why <name-or-source>
```

--------------------------------

### Start or extend tracing for a template

Source: https://docs.gascityhall.com/reference/cli

Initiates or extends tracing for a specified template. Allows setting trace level and duration, and marking the arm as auto-triggered.

```bash
gc trace start [flags]
```

--------------------------------

### GC shell integration

Source: https://docs.gascityhall.com/reference/cli

Manage the GC shell integration for tab-completion. Subcommands include install, remove, and status.

```bash
gc shell
```

--------------------------------

### Get help for GC commands

Source: https://docs.gascityhall.com/reference/cli

Use 'gc help' followed by a command path to retrieve detailed help information for any GC CLI command.

```bash
gc help [command]
```

--------------------------------

### Check bd Version

Source: https://docs.gascityhall.com/getting-started/troubleshooting

Verify the installed `bd` (beads provider) version to ensure it meets the minimum requirement of 1.0.0 for Gas City.

```bash
bd version
```

--------------------------------

### Path-valued fields examples

Source: https://docs.gascityhall.com/guides/migrating-to-pack-vnext

Illustrates how path-valued fields can point to files within the same pack, including assets and relative paths. Ensure normalized paths remain within the pack root.

```toml
run = "./run.sh"
help = "./help.md"
run = "../shared/run.sh"
source = "./assets/imports/maintenance"
```

--------------------------------

### Configure File-Based Beads Provider

Source: https://docs.gascityhall.com/getting-started/troubleshooting

Switch to the file-based beads provider by setting the `GC_BEADS` environment variable or configuring it in `city.toml` to avoid installing `dolt`, `bd`, and `flock`.

```bash
export GC_BEADS=file
```

```toml
[beads]
provider = "file"
```

--------------------------------

### Add a Rig to the City

Source: https://docs.gascityhall.com/getting-started/quickstart

Register an external project directory as a rig with the city. This provides the rig with its own beads database, hook installation, and routing context.

```bash
mkdir ~/hello-world && cd ~/hello-world && git init
gc rig add ~/hello-world
```

--------------------------------

### Agent-Specific Hook Configuration

Source: https://docs.gascityhall.com/tutorials/04-communication

Sets hooks for a specific agent, overriding workspace-level settings if necessary. This example installs hooks for 'claude' for the 'mayor' agent.

```toml
# agents/mayor/agent.toml
install_agent_hooks = ["claude"]
```

--------------------------------

### Workspace Agent Hook Configuration

Source: https://docs.gascityhall.com/tutorials/04-communication

Configures hooks at the workspace level, ensuring all agents automatically integrate with the provider's event system. This example specifically installs hooks for 'claude'.

```toml
[workspace]
install_agent_hooks = ["claude"]
```

--------------------------------

### List all enabled orders in the city

Source: https://docs.gascityhall.com/tutorials/07-orders

Use the 'gc order list' command to view all configured orders, their types, triggers, intervals, and target pools. This command helps in understanding the overall order setup.

```shell
ப்பில்~/my-city
$ gc order list
NAME            TYPE     TRIGGER      INTERVAL/SCHED  TARGET
review-check    formula  cooldown  5m              worker
dep-update      formula  cooldown  1h              worker
release-notes   formula  cooldown  24h             worker

```

--------------------------------

### Configure City and Agents

Source: https://docs.gascityhall.com/tutorials/03-sessions

Set up the city's pack.toml, city.toml, and agent configurations. Ensure the reviewer agent is defined with its provider and prompt template.

```shell
cat pack.toml
[pack]
name = "my-city"
schema = 2

[[agent]]
name = "mayor"
prompt_template = "agents/mayor/prompt.template.md"

[[named_session]]
template = "mayor"
mode = "always"

cat city.toml
[workspace]
provider = "claude"

[[rigs]]
name = "my-project"

cat agents/reviewer/agent.toml
dir = "my-project"
provider = "codex"

```

--------------------------------

### Verify Gas City CLI Version

Source: https://docs.gascityhall.com/tutorials/01-cities-and-rigs

Check the installed version of the Gas City CLI. This command confirms the installation was successful.

```shell
~ 
$ gc version
0.13.4
```

--------------------------------

### TOML usage for configuration

Source: https://docs.gascityhall.com/guides/migrating-to-pack-vnext

Demonstrates when to use TOML for configuration, such as defaults, overrides, metadata, and explicit placement, as opposed to convention-based files.

```toml
session_setup_script = "scripts/setup.sh"
```

--------------------------------

### Install GC shell integration

Source: https://docs.gascityhall.com/reference/cli

Install or update the GC shell completion hook. If no shell is specified, it's detected from the SHELL environment variable.

```bash
gc shell install [bash|zsh|fish]
```

--------------------------------

### gc shell install

Source: https://docs.gascityhall.com/reference/cli

Installs or updates the GC shell completion hook. It automatically detects the shell if not specified and configures the completion script and RC file.

```APIDOC
## gc shell install

Install or update the gc shell completion hook.

If no shell is specified, the shell is detected from $SHELL.
The completion script is written to ~/.gc/completions/ and a source line
is added to your shell RC file.

```
gc shell install [bash|zsh|fish]
```
```

--------------------------------

### Build Docker image for city

Source: https://docs.gascityhall.com/reference/cli

Assemble a Docker build context from city configurations and content, then build a container image. This pre-stages resources to reduce startup times.

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

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

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

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

--------------------------------

### Build gascity without Global Installation

Source: https://docs.gascityhall.com/getting-started/installation

Build the gascity binary without installing it globally. The executable will be available in the 'bin/' directory within the repository root.

```bash
make build          # outputs bin/gc in the repo root
./bin/gc version
```

--------------------------------

### Initialize ExecStore

Source: https://docs.gascityhall.com/reference/exec-beads-provider

Defines the ExecStore struct and its constructor. The store delegates operations to a user-supplied script using fork/exec, with a configurable timeout.

```go
import (
	"context"
	"os/exec"
	"time"
)

// ExecStore implements beads.Store by delegating each operation to a
// user-supplied script via fork/exec.
type ExecStore struct {
    script  string
    timeout time.Duration
}

func NewExecStore(script string) *ExecStore {
    return &ExecStore{script: script, timeout: 30 * time.Second}
}
```

--------------------------------

### Configure Exec Provider in Go

Source: https://docs.gascityhall.com/reference/exec-beads-provider

This Go code snippet shows how to register the 'exec:' provider. It parses the provider string, extracts the script path, and instantiates ExecStore.

```go
import (
	"io"
	"strings"

	"github.com/your_org/your_project/beads"
	"github.com/your_org/your_project/beadsexec"
)

func newBeadStore(cityPath, cmdName string, stderr io.Writer) (beads.Store, int) {
    provider := beadsProvider(cityPath)
    if strings.HasPrefix(provider, "exec:") {
        script := strings.TrimPrefix(provider, "exec:")
        return beadsexec.NewExecStore(script), 0
    }
    switch provider {
    case "file":
        // ... existing ...
    default:
        // ... existing bd ...
    }
}
```

--------------------------------

### Get Supervisor Events

Source: https://docs.gascityhall.com/reference/api

Retrieves a list of historical events for the supervisor.

```APIDOC
## GET /v0/events

### Description
Retrieves a list of historical events for the supervisor. This includes events related to city lifecycle management.

### Method
GET

### Endpoint
/v0/events

### Response
#### Success Response (200)
- **body** (SupervisorEventListOutputBody) - Contains a list of `WireTaggedEvent` items representing supervisor events.
```

--------------------------------

### gc import check

Source: https://docs.gascityhall.com/reference/cli

Validate the current state of installed pack imports.

```APIDOC
## gc import check

Validate installed pack import state

```
gc import check
```
```

--------------------------------

### View city.toml configuration

Source: https://docs.gascityhall.com/tutorials/01-cities-and-rigs

Inspect the `city.toml` file to understand the city-local deployment and runtime settings, such as the workspace provider.

```shell
~/my-city
$ cat city.toml
[workspace]
provider = "claude"

```

--------------------------------

### Define Agent Prompt

Source: https://docs.gascityhall.com/tutorials/02-agents

Create a `prompt.template.md` file to define the custom instructions and behavior for an agent. This includes its role, available tools, and how to work.

```shell
cat > agents/reviewer/prompt.template.md << 'EOF'
# Code Reviewer Agent
You are an agent in a Gas City workspace. Check for available work and execute it.

## Your tools
- `bd ready` — see available work items
- `bd show <id>` — see details of a work item
- `bd close <id>` — mark work as done

## How to work
1. Check for available work: `bd ready`
2. Pick a bead and execute the work described in its title
3. When done, close it: `bd close <id>`
4. Check for more work. Repeat until the queue is empty.

## Reviewing Code
Read the code and provide feedback on bugs, security issues, and style.
EOF
```

--------------------------------

### Get City Events

Source: https://docs.gascityhall.com/reference/api

Retrieves a list of historical events for a specific city.

```APIDOC
## GET /v0/city/{cityName}/events

### Description
Retrieves a list of historical events for a specified city. Requires the city to be marked as running.

### Method
GET

### Endpoint
/v0/city/{cityName}/events

### Parameters
#### Path Parameters
- **cityName** (string) - Required - The name of the city.

### Response
#### Success Response (200)
- **X-GC-Index** (string) - A cursor or index for the events.
- **body** (ListBodyWireEvent) - A list of wire events for the city.
```

--------------------------------

### View .gc/site.toml configuration

Source: https://docs.gascityhall.com/tutorials/01-cities-and-rigs

Check the .gc/site.toml file for machine-local workspace and rig path bindings. This file maps rig names to their physical locations on your machine.

```toml
workspace_name = "my-city"

[[rig]]
name = "my-project"
path = "/Users/csells/my-project"
```

--------------------------------

### Initialize a new Gas City workspace

Source: https://docs.gascityhall.com/reference/cli

Use this command to create a new Gas City workspace. It can initialize in the current directory or a specified path, interactively or non-interactively using flags like `--provider` or `--file`. Existing configuration files can be preserved using `--preserve-existing`.

```bash
gc init [path] [flags]
```

```bash
gc init
```

```bash
gc init ~/my-city
```

```bash
gc init --provider codex ~/my-city
```

```bash
gc init --provider codex --bootstrap-profile k8s-cell /city
```

```bash
gc init --name my-city
```

```bash
gc init --from ~/elan --name elan /city
```

```bash
gc init --file examples/gastown.toml ~/bright-lights
```

```bash
gc init --file city.toml --preserve-existing .
```

--------------------------------

### Configure Site and Rig

Source: https://docs.gascityhall.com/tutorials/03-sessions

Define the city's workspace name and rig path bindings in .gc/site.toml. This file holds machine-local identity and rig path information.

```toml
workspace_name = "my-city"

[[rig]]
name = "my-project"
path = "/Users/csells/my-project"

```

--------------------------------

### gc init

Source: https://docs.gascityhall.com/reference/cli

Create a new Gas City workspace. This command can be run interactively or non-interactively using flags to specify the path, provider, configuration file, or source directory.

```APIDOC
## gc init

Create a new Gas City workspace in the given directory (or cwd).

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, then
materializes builtin packs under .gc/system/packs. Use --provider to create the default minimal 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 --provider codex ~/my-city
  gc init --provider codex --bootstrap-profile k8s-cell /city
  gc init --name my-city
  gc init --from ~/elan --name elan /city
  gc init --file examples/gastown.toml ~/bright-lights
  gc init --file city.toml --preserve-existing .
```

### Flags

*   **--bootstrap-profile** (string) - bootstrap profile to apply for hosted/container defaults
*   **--file** (string) - path to a TOML file to use as city.toml
*   **--from** (string) - path to an example city directory to copy
*   **--name** (string) - workspace name (default: target directory basename)
*   **--preserve-existing** (bool) - keep any pre-authored pack.toml, city.toml, or agent prompt files instead of overwriting them
*   **--provider** (string) - built-in workspace provider to use for the default mayor config
*   **--skip-provider-readiness** (bool) - skip provider login/readiness checks during init and continue startup
```

--------------------------------

### Check Dolt Version

Source: https://docs.gascityhall.com/getting-started/troubleshooting

Verify the installed Dolt version to ensure it meets the minimum requirement of 1.86.2 for Gas City.

```bash
dolt version
```

--------------------------------

### List Workspace Services

Source: https://docs.gascityhall.com/reference/cli

List all available workspace services.

```bash
gc service list
```

--------------------------------

### Explain Resolved Configuration

Source: https://docs.gascityhall.com/reference/cli

Shows the resolved configuration with provenance. Use flags to filter by agent, rig, or provider. Use --json for machine-readable output when explaining providers.

```bash
gc config explain [flags]
```

```bash
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 shell

Source: https://docs.gascityhall.com/reference/cli

Provides shell integration for the GC CLI, including tab-completion for commands and flags. It manages the installation, removal, and status of this integration.

```APIDOC
## gc shell

The shell integration adds a completion hook to your shell RC file that
provides tab-completion for gc commands and flags.

Subcommands: install, remove, status.

```
gc shell
```

| Subcommand                            | Description                         |
| ------------------------------------- | ----------------------------------- |
| [gc shell install](#gc-shell-install) | Install or update shell integration |
| [gc shell remove](#gc-shell-remove)   | Remove shell integration            |
| [gc shell status](#gc-shell-status)   | Show shell integration status       |
```

--------------------------------

### Exec Store Package Structure

Source: https://docs.gascityhall.com/reference/exec-beads-provider

Outlines the directory structure for the ExecStore implementation within the beads package.

```go
internal/beads/exec/
├── exec.go          # ExecStore implementing Store interface
├── exec_test.go     # unit tests with fake script
└── json.go          # wire format types (like session/exec/json.go)
```

--------------------------------

### Register a Rig with Gastown Pack

Source: https://docs.gascityhall.com/getting-started/coming-from-gastown

Import the Gastown pack and bind rigs in `city.toml` and with `gc rig add`. This sets up your project to use Gastown's infrastructure.

```toml
# pack.toml
[pack]
name = "my-city"
schema = 2

[imports.gastown]
source = "./assets/gastown"
```

```toml
# city.toml
[[rigs]]
name = "myproject"

[rigs.imports.gastown]
source = "./assets/gastown"
```

--------------------------------

### Restart the city controller

Source: https://docs.gascityhall.com/reference/cli

Use 'gc restart' to stop and then start the city again. Under supervisor mode, this unregisters and then re-registers the city, triggering an immediate reconcile.

```bash
gc restart [path]
```

--------------------------------

### Show GC Formula Recipe

Source: https://docs.gascityhall.com/reference/cli

Compile and display a formula recipe. Use --var to substitute variables and preview the resolved output.

```bash
gc formula show <formula-name> [flags]
```

```bash
gc formula show mol-feature --var title="Auth system" --var branch=main
```

--------------------------------

### Check pack import state

Source: https://docs.gascityhall.com/reference/cli

Use this command to validate the current state of your installed pack imports. This helps ensure consistency and identify potential issues.

```bash
gc import check
```

--------------------------------

### Wake a GC session

Source: https://docs.gascityhall.com/reference/cli

Request wake for a session and release user hold or crash-loop quarantine metadata. The session starts on the next tick if it has wake reasons.

```bash
gc session wake <session-id-or-alias>
```

```bash
gc session wake gc-42
```

```bash
gc session wake mayor
```

--------------------------------

### gc build-image

Source: https://docs.gascityhall.com/reference/cli

Assembles a Docker build context from city configuration, prompts, formulas, and rig content, then builds a container image.

```APIDOC
## 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]
```

### Parameters
#### Path Parameters
- `city-path` (string) - Path to the city configuration.

#### Flags
- `--base-image` (string) - base Docker image (default: `gc-agent:latest`)
- `--context-only` (bool) - write build context without running docker build
- `--push` (bool) - push image after building
- `--rig-path` (stringSlice) - rig name:path pairs (repeatable)
- `--tag` (string) - image tag (required unless --context-only)

### Examples
```
# 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
```
```

--------------------------------

### Resume a Suspended Agent

Source: https://docs.gascityhall.com/reference/cli

Use 'gc agent resume <name>' to clear the suspended flag in an agent's durable config, allowing the reconciler to start it.

```bash
gc agent resume <name>
```

--------------------------------

### List city contents

Source: https://docs.gascityhall.com/tutorials/01-cities-and-rigs

After initialization, navigate to the city directory and use `ls` to view its standard file and directory structure.

```shell
~ 
$ cd ~/my-city

~/my-city
$ ls
agents  assets  city.toml  commands  doctor  formulas  orders  overlay  pack.toml  template-fragments

```

--------------------------------

### City Pack and Import Configuration

Source: https://docs.gascityhall.com/guides/shareable-packs

Configures the root pack to import other packs and defines deployment details in `city.toml`. Local imports use relative paths.

```toml
# pack.toml
[pack]
name = "bright-lights"
schema = 2

[imports.gastown]
source = "./assets/gastown"

[imports.review]
source = "./assets/code-review"
```

```toml
# city.toml
[beads]
provider = "bd"

[[rigs]]
name = "backend"
max_active_sessions = 4
default_sling_target = "backend/gastown.polecat"
```

--------------------------------

### Disabling Orders

Source: https://docs.gascityhall.com/tutorials/07-orders

Temporarily disable an order by setting `enabled = false` in its definition. Disabled orders are excluded from scanning and do not appear in order lists or get evaluated.

```toml
[order]
description = "Temporarily disabled"
formula = "nightly-bench"
trigger = "cooldown"
interval = "1m"
pool = "worker"
enabled = false
```

--------------------------------

### Run gc dolt-cleanup

Source: https://docs.gascityhall.com/reference/cli

Execute the Dolt cleanup tool. Pass --force to perform destructive operations. Use --max-orphan-dbs with --force to set a threshold for live stale databases.

```bash
gc dolt-cleanup [flags]
```

--------------------------------

### Set managed city endpoint

Source: https://docs.gascityhall.com/reference/cli

Configure the city endpoint to use the GC-managed service. This command simplifies the setup for using GC's managed infrastructure.

```bash
gc beads city use-managed [flags]
```

--------------------------------

### View city.toml configuration

Source: https://docs.gascityhall.com/tutorials/01-cities-and-rigs

Inspect the city.toml file to see the registered rigs. The '[[rigs]]' section lists all projects added as rigs to the city.

```toml
[workspace]
provider = "claude"

... # content elided

[[rigs]]
name = "my-project"
```

--------------------------------

### Resume a suspended rig

Source: https://docs.gascityhall.com/reference/cli

Resume a rig that was previously suspended. This clears the suspended state in city.toml, allowing the reconciler to start the rig's agents on its next tick.

```bash
gc rig resume [name]
```

--------------------------------

### Build Gas City from Source

Source: https://docs.gascityhall.com/getting-started/troubleshooting

Compile the Gas City binary from its source code after ensuring prerequisites are met. This command generates the executable in the `bin/` directory.

```bash
make build
./bin/gc version
```

--------------------------------

### List Pack Sources

Source: https://docs.gascityhall.com/reference/cli

Show configured pack sources with their cache status, including name, URL, git ref, and locked commit hash.

```bash
gc pack list
```

--------------------------------

### Add a Blocking Dependency

Source: https://docs.gascityhall.com/tutorials/06-beads

Use `bd dep --blocks` to establish a dependency where one bead must be closed before another can start. This affects work visibility for agents.

```shell
~/my-city
$ bd dep mc-a4l --blocks mc-xp7
✓ Added dependency: mc-a4l (Refactor auth module) blocks mc-xp7 (Update API docs)
```

--------------------------------

### Run Link Check for Docs

Source: https://docs.gascityhall.com/getting-started/installation

Perform a link check on the documentation without starting the development server. This command helps identify broken internal or external links in the docs.

```bash
make check-docs
```

--------------------------------

### View pack.toml configuration

Source: https://docs.gascityhall.com/tutorials/01-cities-and-rigs

Examine the `pack.toml` file, which defines the portable pack layer, including agents and named sessions.

```shell
~/my-city
$ cat pack.toml
[pack]
name = "my-city"
schema = 2

[[agent]]
name = "mayor"
prompt_template = "agents/mayor/prompt.template.md"

[[named_session]]
template = "mayor"
mode = "always"

```

--------------------------------

### Configure Exec Provider via Environment Variable

Source: https://docs.gascityhall.com/reference/exec-beads-provider

Example bash command to set the GC_BEADS environment variable, configuring the system to use an external script as the beads provider.

```bash
export GC_BEADS=exec:gc-beads-br
```

--------------------------------

### Create a convoy with metadata

Source: https://docs.gascityhall.com/tutorials/06-beads

Set convoy metadata like owner, notification preferences, merge strategy, and target branch during creation using flags.

```shell
gc convoy create "Deploy v2" --owner mayor --merge mr --target main
```
Tokens:
Raw