Every top-level command, in one place you can search.

This reference covers all 22 top-level commands published in npm 0.5.5 and is checked against main bdc9f86. Search by command, concept, or behaviour.

Search commands22 commands

Global options

--help shows the installed surface and --version prints the exact version. If a later release differs from this page, the CLI wins.

TERMINAL

$agents-city --help$agents-city --version

Start and configure

Create cities, define agents, mount their work, and select the goal and runtimes.

agents-city [hall]#

Open the local Town Hall for the selected city.

The Hall binds to 127.0.0.1, opens on the map, and shows configuration plus a read-only live view of visible agent and committee activity.

TERMINAL

$agents-city$agents-city hall --city product$agents-city hall --no-browser

agents-city setup#

Create or select a city and open the Hall.

The default flow uses the browser Hall. --tui hands onboarding to seat; --demo opens the default disposable Aurora Games walkthrough.

TERMINAL

$agents-city setup$agents-city setup --city product$agents-city setup --city product --tui$agents-city setup --demo

agents-city seat#

Configure and open the city chair plus its repository-agent windows.

seat persists domain, chair role, repositories, per-repo roles, goal, and engine choices. --only, --model, --effort, --no-yolo, and --no-sync apply to one launch only.

TERMINAL

$agents-city seat$agents-city seat --city product$agents-city seat --repos --agent-roles$agents-city seat --engines$agents-city seat --only api,web$agents-city seat --model sonnet --effort high

agents-city cities#

List, create, or select local cities without starting them.

A user may own several isolated cities. create writes a managed city folder; use only changes the selected city.

TERMINAL

$agents-city cities list$agents-city cities current$agents-city cities create client-a$agents-city cities use product

agents-city agents#

List agents and manage the work mounted into their private workspaces.

The agent is the member unit. Its workspace may mount a repository, worktree, document folder, several sources, or none. Legacy repo-only cards are normalised to the same model.

TERMINAL

$agents-city agents list --data ~/.agents-city/alice/product --card ~/.agents-city/alice/product/alice.md$agents-city agents mount --data ~/.agents-city/alice/product --agent writer --src ~/Documents/handbook$agents-city agents mounts --data ~/.agents-city/alice/product --agent writer$agents-city agents unmount --data ~/.agents-city/alice/product --agent writer --name handbook

Coordinate

Open explicit roads, exchange information, and chair bounded decisions.

agents-city road#

Open or close the explicit allowlist between two city seats.

Local connect writes both ends symmetrically. Remote cities exchange public invitation files and each side accepts independently.

TERMINAL

$agents-city road list product$agents-city road connect product client-a$agents-city road invite product > product.invitation.json$agents-city road connect product research.invitation.json$agents-city road disconnect product client-a

agents-city connect#

Pair this computer with a managed Road service.

Both people approve the connection. One local hub keeps a single outbound encrypted session alive; no public port opens on the owner computer. Incoming person messages wait in the private human Reception until the owner routes or rejects them, unless they explicitly enable the conservative Auto router.

TERMINAL

$agents-city connect --service https://connect.example.com --trust-file roots.json$agents-city connect --city product$agents-city connect --all$agents-city connect status$agents-city connect roads

agents-city bus#

Send information from one seat across a declared road.

roster shows allowed destinations and presence. inbox consumes pending delivery while append-only history remains. Only the seat may send road messages.

TERMINAL

$agents-city bus roster$agents-city bus inbox$agents-city bus send alice/research "Confirm the event contract"$agents-city bus send '*' "Notice for every connected city"

agents-city committee#

Run an authenticated, chair-mediated deliberation inside one city.

The state machine covers open, respond, synthesise, floor requests, one scoped reply, decide, verify, replan, close, and cancel. Mutations accept flags or JSON through --input.

TERMINAL

$agents-city committee list$agents-city committee history$agents-city committee schema open$agents-city committee open --input proposal.json$agents-city committee show <deliberation-id>

Observe and measure

Inspect capabilities, draw the map, run the demo, and read evidence.

agents-city skills#

Recognise skills that already live in each repository.

This command is read-only. It recognises common SKILL.md layouts and reports capabilities; it never installs, copies, enables, or removes a skill.

TERMINAL

$agents-city skills$agents-city skills product

agents-city city#

Open one city map without starting an agent session.

The map binds to loopback and reads city units, parcels, owner card, and bus state. Ctrl-c stops the local server.

TERMINAL

$agents-city city$agents-city city ~/.agents-city/alice/product

agents-city shortcut#

Put a named city and its own icon on the desktop.

The published package writes a real macOS app, Linux .desktop entry, or Windows .lnk through WSL. Every shortcut runs the same CLI entry point; --hall opens the browser map instead of the tmux seat.

TERMINAL

$agents-city shortcut$agents-city shortcut product$agents-city shortcut product --hall$agents-city shortcut --remove$agents-city shortcut --to ~/bin

agents-city demo#

Run one of three disposable, human-readable Hall and committee walkthroughs.

Choose Aurora Games, Clínica Alba, or Costa & Ley. The demo starts no models and needs no provider account. Every story crosses the real authenticated bus, committee state machine, durable ledger, spectator feed, verification failure, and replan path.

TERMINAL

$agents-city demo$agents-city demo --domain medicina$agents-city demo --domain legal$agents-city demo --no-browser

agents-city report#

Compute map growth from configured folders and optionally push it.

Without --push it only computes and displays the report. --url and --token may override an optional city service.

TERMINAL

$agents-city report$agents-city report --data ~/.agents-city/alice/product$agents-city report --push --quiet

agents-city tokens#

Aggregate local Claude transcript usage without sending prompts or paths.

The command reports totals only. It does not automatically estimate Codex, OpenCode, or Kimi usage.

TERMINAL

$agents-city tokens$agents-city tokens --days 7$agents-city tokens --all$agents-city tokens --push --quiet

agents-city logs#

Read visible semantic activity or secret-scrubbed diagnostics.

Activity includes visible prompts, answers, work, and committee events. Diagnostics covers hub, socket, gateway, hook, and launcher operations. Provider reasoning is excluded.

TERMINAL

$agents-city logs$agents-city logs --activity --lines 50$agents-city logs --diagnostics --lines 200$agents-city logs --json --follow

Operate and maintain

Benchmark, reset, close, and validate the installation.

agents-city benchmark#

Measure local stress, real-runtime latency, or committee protocol behaviour.

Stress runs offline without model quota. Live runtime measurement is opt-in and consumes the configured provider quota. Committee benchmarks compare the structured protocol with an unbounded chat.

TERMINAL

$agents-city benchmark stress$agents-city benchmark live --runtime codex$agents-city benchmark committee

agents-city reset#

Return one explicit city to onboarding with a recovery copy.

reset clears that city’s seat/onboarding state and local road endpoints, preserves its stable identity, and never touches referenced repositories.

TERMINAL

$agents-city reset product --dry-run$agents-city reset product

agents-city exit#

Close one city session or every Agents City session safely.

Use this instead of killing generic processes. Save active work first: closing a city ends each tmux window in that session.

TERMINAL

$agents-city exit product --dry-run$agents-city exit product$agents-city exit --dry-run$agents-city exit

agents-city doctor#

Check the machine, runtimes, cage, selected city, Hall bundle, and available updates.

Without a file it reports the complete local installation and exits non-zero when something is broken. With an older config it can explain and migrate the shape while leaving a backup.

TERMINAL

$agents-city doctor$agents-city doctor path/to/old-city.yml$agents-city doctor path/to/old-city.yml --fix

agents-city update#

Check or install the newest npm release without touching source checkouts.

The update check makes one cached request to the public npm registry. CITY_UPDATE_CHECK=0 disables automatic checks, and source installations are never overwritten.

TERMINAL

$agents-city update --check$agents-city update$agents-city update --tag beta

agents-city test#

Run every repository check through the installed command surface.

The complete suite covers Python contracts, TypeScript bundles, runtime adapters, security invariants, demo flow, packaging, and benchmarks that do not require live models.

TERMINAL

$agents-city test