CLI Commands

Agent

city agent                         # Open the Agent panel
city agent create [path]           # No path: current directory or native folder picker
city agent list
city agent start [agent_id]
city agent stop [agent_id]
city agent restart [agent_id]
city agent status [agent_id]
city agent doctor [agent_id]
city agent model [agent_id]
city agent chat [agent_id]
city web                         # start the local City Web control plane
city web --no-open --port 43128  # do not open a browser and choose a port

Agents assembled by city agent start enable the ask_question tool by default. In city agent chat, 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.

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.

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 name, purpose description, source, and version.

city plugin list
city plugin install <local-directory|git-url|github:owner/repo#ref>
city plugin update <plugin_name>
city plugin uninstall <plugin_name>
city plugin inspect <plugin_name>
city plugin enable <plugin_name> [agent_id] --config '{"key":"value"}'
city plugin disable <plugin_name> [agent_id]
city plugin config <plugin_name> [agent_id]
city plugin config <plugin_name> [agent_id] --set '{"key":"value"}'
city plugin config <plugin_name> [agent_id] --interactive
city plugin config <plugin_name> [agent_id] --resources '["resource-id"]'
city plugin resource list <plugin_name>
city plugin resource create <plugin_name> --set '{"type":"api","api_key":"secret"}'
city plugin resource create <plugin_name> --interactive
city plugin resource update <plugin_name> <resource_id> --set '{"type":"api","api_key":"new-secret"}'
city plugin resource refresh <plugin_name> <resource_id>
city plugin resource remove <plugin_name> <resource_id>
city plugin action <plugin_name> <action_name> [agent_id] --input '{"key":"value"}' --token <token>

A third-party entry provides a named plugins constructor array export. Each Plugin declares its name, configuration, and Resource Schema through static manifest, and may resolve dynamic Resource fields through static resolve_resource. The artifact must contain a v2 downcity.plugin.json and a self-contained ESM entry. Installation never runs npm install, build scripts, lifecycle scripts, or the Plugin entry.

Plugin configuration belongs to the Agent Binding. Plugin Resources belong to the global Resource Store, while a Binding stores only resource_ids. The CLI collects user fields from the Schema, invokes the Plugin constructor static Resolver for dynamic readOnly fields, and resolves IDs into complete Items before instantiation. The CLI then executes new PluginType({ config, resources }). writeOnly fields are stored encrypted and never echoed by CLI output.

resource update --set replaces all user-writable fields. resource refresh preserves user fields and only recomputes Resolver fields. A bound Resource cannot be removed, and a third-party Plugin that still owns Resources cannot be uninstalled.

After changing enable, disable, config, or Resource Binding state, restart a running Agent to apply the new Runtime assembly.

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; Agent Env is stored in .env at the root of its Workspace. You can also use “Configure Env” in city agent. After a change, City asks affected running Agents to reload Env and Workspace broadcasts the new snapshot to existing Sessions. Stopped Agents load it on their next start.

Agents bound to 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.

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.