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. city agent list prints every Agent as name · agent_id. 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 and enters that Session's Workspace. When the Agent has no history yet, Chat opens in the current Workspace and creates a new Session. 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. city agent chat --session-id <id> must reference an existing Session and enters that Session's Workspace; --workspace <id> keeps Chat in that Workspace by limiting session lookup to it, requiring it to match the Workspace of a selected --session-id Session, and creating new Sessions there. 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 whether it provides Config.

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 config <plugin_id>
city plugin config <plugin_id> --set '{"key":"value"}'
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, a version, a required relative readme path to a .md file, and optional main and renderer entries. main is a self-contained unified City Plugin ESM. The renderer object declares a single-file ESM entry and static sidebar, mainview, and config capabilities; Sidebar and Mainview must be paired. At least one of the two runtime entries is required. package.json must declare "type": "module". The installed directory keeps only declared artifacts, documentation, an optional icon, and local config.toml. Installation never runs dependencies, build scripts, or any third-party entry.

A Plugin that declares Config stores one configuration in plugins/<plugin_id>/config.toml. The Plugin owns its structure, validation, Secret projection, and Config UI. CLI config --set only replaces a complete JSON object explicitly; it does not generate a generic form or print credential values. Without --set, it reports only whether Config exists and its field names.

City automatically provides every registered Plugin to every Agent; agent.json stores neither Plugin references nor configuration. A Plugin models its own account collection and selection rules when it needs multiple accounts. After Config is saved, the Plugin refreshes affected long-lived resources.

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.