CLI Commands

City lifecycle

city on                         # Start the single CLI City daemon
city on --port 5314 --rpc-port 15314
city status
city restart
city off
city reset                       # Confirm and reset the local configuration database
city reset --yes                 # Skip confirmation

The CLI City uses one HTTP port and one native TCP RPC port. Both protocols route all Agents by agent_id.

city reset first stops the CLI City daemon, then removes downcity.db, downcity.db-wal, and downcity.db-shm. It preserves .env, Agent/Plugin configuration, and Session files inside Workspaces.

Agent

city                               # Open the Agent list directly
city agent                         # Open the same Agent list
city agent create [path]           # No path: current directory or native folder picker
city agent list
city agent model [agent_id]
city agent chat [agent_id]

The bare city command opens the Agent list directly. It does not show Agent runtime status. Federation, global Plugins, language, and command help appear in a Settings group at the end of the same list.

Agents assembled by City enable the ask_question tool by default. Selecting an Agent in the city agent panel opens its most recent conversation directly, or the default Session when no history exists. The model can present text, single-select, or multi-select questions when key information is missing. The CLI submits the complete answer set to the current Session and continues the same Turn. Press Esc to stop that Turn.

Agents and Workspaces are registered independently. An Agent enters a selected Workspace for each execution and stores no persistent Workspace binding. Agents have no independent started state. In Chat, use /new to create a Session, /session to select an existing Session or create one, and /config to open Agent configuration. Configuration returns to the same conversation. Chat uses RPC while City is running; scriptable one-shot calls can use the local assembly path while City is off.

Use the slash command to open the system file picker and attach local files to the next message:

/attach

/file is an alias. On Unix, Ctrl-V (or Alt-V on Windows) also tries to paste clipboard images or files first, and falls back to normal text paste when no supported attachment is available.

Approval requests are handled by the dedicated interaction panel; /approve and /deny are no longer slash commands.

Per-Agent tokens

A token belongs to exactly one Agent and can access all of that Agent's protected HTTP API. There are no User, Role, or Permission layers.

city agent token list [agent_id]
city agent token create [agent_id] --name automation
city agent token create [agent_id] --name temporary --expires-at 2026-08-01T00:00:00Z
city agent token delete <token_id> [agent_id]

Plugins

city plugin list shows each Plugin title, stable ID, purpose, source, and saved profiles.

city plugin list
city plugin install <local-directory|git-url|github:owner/repo#ref>
city plugin update <plugin_id>
city plugin uninstall <plugin_id>
city plugin inspect <plugin_id>
city plugin profiles <plugin_id>
city plugin config <plugin_id> [profile] --set '{"key":"value"}'
city plugin config <plugin_id> [profile] --interactive
city plugin config <plugin_id> [profile] --remove
city plugin enable <plugin_id> [agent_id] --profile <profile>
city plugin disable <plugin_id> [agent_id]
city plugin enabled [agent_id]
city plugin action <plugin_id> <action_name> [agent_id] --input '{"key":"value"}' --token <token>

A third-party source directory defines exactly one Plugin. Its plugin.json declares schema_version: 1, a globally unique id, version, one self-contained ESM entry, and optional config.schema/defaults. The entry exports a Plugin constructor as the named plugin export, and package.json must declare "type": "module". The final ~/.downcity/plugins/<plugin_id>/ directory contains only the installed plugin.json, package.json, entry, and local config.toml; source and build configuration are not copied. Installation never runs npm install, build scripts, Plugin lifecycle hooks, or the entry module.

Plugin configuration belongs to named profiles in plugins/<plugin_id>/config.toml. Accounts, channels, endpoints, and other structures are defined by the setup module's JSON Schema, while the Plugin code maintains its TypeScript type separately. Configuration is plaintext with file mode 0600; CLI validates profiles, builds forms, and redacts writeOnly fields from that same Schema. An Agent without --profile receives {} and never implicitly reads a persisted default profile; named profiles are used only when explicitly selected.

The Agent's agent.json stores only the Plugin ID and optional profile reference. Removing that entry disables the Plugin. A profile or third-party Plugin cannot be removed while an Agent still references it.

After changing enable, disable, or profile configuration, run city restart to apply the new assembly to a running CLI City.

The CLI, Agent plugin_call, HTTP, and scheduled jobs all invoke Plugin Actions. There is no plugin command, and Chat is not a top-level CLI special case.

Env and Federation

city env                                      # open the Env TUI
city env list --global
city env list --agent <agent_id>
city env set <key> <value> --global
city env set <key> <value> --agent <agent_id>
city env delete <key> --global
city env delete <key> --agent <agent_id>
city federation

Global Env is stored in ~/.downcity/.env; Workspace Env is stored in .env at the project root. You can also use “Configure Env” in city agent to select an Agent's Workspace. After a change, the CLI City updates affected runtime Agents and Workspace broadcasts the new snapshot to existing Sessions. Agents not held by that City receive the configuration the next time a City assembles them.

Agents running in the same Workspace share one project .env. Runtime precedence is Global .env, then Workspace .env, then explicit process environment variables. list never prints plaintext values; copy requires an explicit local CLI invocation.

Federation user requests go through Embassy. Interactive sessions are stored in ~/.downcity/downcity.db; automation can explicitly override the current session with DOWNCITY_FEDERATION_URL and DOWNCITY_USER_TOKEN. These identity variables are never injected from Global .env into Workspace processes.

Fed

fed                              # Federation Server manager TUI
fed web                         # start the local Web admin UI for the active Federation
fed web --no-open --port 43128  # start without opening the browser
fed server add
fed server manage
fed bureau token                          # open the Bureau Token manager TUI
fed bureau token issue <bureau_id>        # enter a purpose and ask Federation to issue a token
fed bureau token list
fed bureau token revoke <token_id>
fed query GET /health
fed create [dir]
fed deploy [source]

fed web starts the local control plane at http://127.0.0.1:43128 by default. It uses the active Federation, or one selected with --federation <name-or-url>. The local CLI process keeps the administrator session token; it is never sent to the browser. To keep the administrator control plane off the network, the command only listens on 127.0.0.1, localhost, or ::1. The UI includes the Dashboard, users, Bureaus, models, Env, Credits, Usage, payments, the Service catalog, and a debugger. Analytics are organized into overview, activity, consumption, retention, quality, and per-user detail views.

The Usage Dashboard uses the browser's IANA timezone. DAU counts unique users with at least one AI Usage record today; WAU and MAU use rolling 7-day and 30-day windows. The user-usage view lists all registered users, including users with zero usage. It defaults to descending Total Tokens—the same metric as the overview's token-consumption ranking—and also supports sorting by calls, Credits, P95 duration, and last activity. Each row includes input, output, and total tokens, success rate, top model, duration, and applied Credits consumption. Charts cover DAU/WAU/MAU, local-hour activity, stacked token composition, model/action distribution, outcomes, latency, and D1/D3/D7/D14/D30 cohort retention.