CLI Commands

Common City and Fed 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/Power configuration, and Session files inside Workspaces.

Agent

city                               # Open the Agent list directly
city agent                         # Open the same Agent list
city agent create --name Reviewer --id reviewer --model MODEL_ID
city agent list
city agent get reviewer
city agent update reviewer --model MODEL_ID
city agent delete reviewer --yes
city workspace register ./project
city workspace list
city session list --agent reviewer
city agent chat reviewer --new-session --workspace WORKSPACE_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 Powers, language, and command help appear in a Settings group at the end of the same list.

Agents assembled by City enable the ask_user 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.

For passwords, API keys, and tokens, ask_user uses type: "secret" with a snake_case name. Local Sessions collect masked input, then ask you to confirm the private value count, names, and replacement of existing same-name values. The model receives only a Session private reference. Values are held in Session memory and are lost after release or restart. CLI transports without the dedicated private submission method refuse private forms before collecting input; use Desktop or a local Session. Do not paste credentials into ordinary chat or text questions.

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 <agent_id> --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 and Session execution require an explicitly started current City host. Offline access supports configuration management and side-effect-free historical browsing. See Resource Management for the complete Agent/Workspace/Session command surface, JSON envelope, exit codes, revision checks and deletion boundaries.

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.

City Tokens

City owns connection credentials. Grant access to selected Agent IDs, or explicitly allow all existing and future Agents. city is the executable; downcity is an alias, without an additional city subcommand.

city token
city token create
city token list
city token create --name chrome --agents researcher,programmer --never-expires
city token create --name automation --all-agents --expires-at 2027-01-01T00:00:00Z
city token update <token_id> --agents researcher
city token delete <token_id>

The interactive menu supports creation, summary viewing, editing and revocation. Creation requires a name, scope and expiry policy. Missing options are prompted in a terminal and rejected in noninteractive execution. Interactive creation includes Agent multiselect, 30/90 days, no expiry or a custom date, followed by confirmation. Omit the ID on update/delete to select a record. Complete options run directly; use --json for scripts.

Plaintext is shown once at creation and never appears in summary queries. Enter it directly in Chrome settings. Lost credentials must be replaced. Revocation or scope reduction rejects new requests and closes affected HTTP streams within the approximately one-second authorization check interval. Cancellation cannot undo completed external effects.

The old city agent token command and Agent Tokens are no longer accepted. Issue a new credential with city token create; old records are not automatically migrated or granted broader access. Token management remains local and is not granted to remote connection credentials.

Powers

city power list shows each Power title, stable ID, purpose, source, and whether it provides Config.

city power list
city power install <local-directory|git-url|github:owner/repo#ref>
city power update <power_id>
city power uninstall <power_id>
city power inspect <power_id>
city power config <power_id>
city power config <power_id> --set '{"key":"value"}'
city power action <power_id> <action_name> [agent_id] --input '{"key":"value"}' --token <token>

Env, Token and Power configuration writes use the current host's shared resource coordinator; offline writes acquire the root lease. Token Agent references are rechecked inside the write transaction. Power install/update/uninstall replaces artifacts only while the root is offline and holds the exclusive lease; a running host refuses package replacement.

A third-party source directory defines exactly one Power. Its power.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 Power 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 Power that declares Config stores one configuration in powers/<power_id>/config.toml. The Power 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 Power to every Agent; agent.json stores neither Power references nor configuration. A Power models its own account collection and selection rules when it needs multiple accounts. After Config is saved, the Power refreshes affected long-lived resources.

The CLI, Agent Power tools, HTTP, and scheduled jobs all invoke Power Actions. There is no power 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 Federation. 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 create and fed deploy accept an explicit --path <path>, defaulting to .; positional path arguments are not accepted.

Fed has no global active/default Federation and does not store active_server_url. stop, restart, clean, backup, restore, status, logs, query, web, server, manage, and server manage accept mutually exclusive --id <id> or --name <name> selectors. Both match exactly. Without a selector, a TTY opens a list for this operation only; non-interactive execution fails with a missing-selector error. Duplicate names require a further selection in a TTY and fail outside a TTY. Lists have no global-current star marker. fed manage --id fed_x opens the target's management workspace directly, with no action positional argument; fed server manage supports the same selectors.

Federation validates signature, issuer, audience, expiry, and session revocation for protected requests. Device logout revokes its entire session. SDK logout preserves credentials on transport failure; Desktop and CLI end local use before attempting remote revocation. Running streams are not forcibly interrupted.

fed status works with any saved connection and shows the registry record and a live /health probe. Local instances also report launchd/systemd manager status separately. The record, system service state, and health probe are independent facts. A local release is healthy only when ok: true and its fed_id, release_id, and instance_id all match the managed instance. fed logs, fed stop, and fed restart work only with CLI-managed local instances. Logs come from the existing service.log. stop disables automatic startup and stops the service. The stopped state survives system restarts until an explicit fed deploy or fed restart; those operations restore the automatic startup policy from persisted configuration. Restart uses only the installed release and persisted runtime configuration, without reading or building source, and works after the original project is deleted. An explicitly selected database keeps its absolute path; preserve that file when deleting the project. Remove connection in the management UI only removes the saved connection; it does not stop the service.

fed clean only cleans local releases of registered Feds. Without either mutually exclusive --id / --name selector, a TTY opens a list for this operation only; non-TTY execution fails. It previews release IDs, sizes, and deletion or retention reasons before confirmation. --dry-run only previews. Non-interactive deletion requires explicit --yes and still applies all protection checks. The default policy always retains the 3 most recent successful releases; there is no --keep option.

Releases referenced by current.json, the registry, service launch.json (including pending recovery startup), or in-progress attempts are protected, as are candidates whose cleanup could not be confirmed. Unknown or damaged releases and those without trustworthy deployment records are retained with an explanation. Protection-information errors, including an unverifiable runner, refuse cleaning outright. After target selection, the same Fed lock covers preview, confirmation, and deletion to prevent concurrent cutovers. Failed artifacts are deleted only through manual fed clean; the CLI does not automatically clean releases. clean never deletes data, config, logs, staging, or deployment history. Deployment attempts are stored at ~/.downcity/federation/deployments/<fed_id>/attempts/<operation_id>.json to identify successful and failed history, which remains after release deletion. See Clean Local Releases.

fed backup creates a consistent online SQLite snapshot for a registered local release. fed restore --path <backup> requires explicit persistent stop facts, verifies ownership, SHA-256 and SQLite integrity, saves the current database before confirmation, and atomically replaces it without starting the service. --dry-run performs read-only preflight; non-interactive replacement requires --yes. Backup files use 0600 and can contain accounts, sessions and credentials; keep them out of Git and release artifacts. Restore does not switch application versions or guarantee schema compatibility. See SQLite Backup and Restore.

See Independent Local Node Releases for installation paths, runtime configuration, Node requirements, and dry-run boundaries. Local targets retain deployment.scripts.build and reject deployment.scripts.deploy.

Local services use macOS user-level launchd or Linux user-level systemd. The [deployment.process] table in federation.toml supports auto_start = false (default) and restart_on_failure = true (default). Only booleans are accepted; unknown fields are rejected, and Workers projects cannot declare this table. Recovery uses 10-second intervals with at most 5 attempts within 60 seconds. Only explicit auto_start = true persists a definition in macOS ~/Library/LaunchAgents or enables the Linux user service in default.target.wants. macOS starts after user login; Linux requires an available user manager. The CLI does not enable linger or guarantee Linux startup at boot. System service definitions contain no secrets; runtime configuration is stored separately. See CLI Quickstart for configuration examples.

User sessions own identity, permissions, and Credits. City automatically carries optional city_id for logs, usage, and job source only. Business calls use federation.user.service(name) on the current Federation; administrators use a separate Session.

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.

Saved account renewal

CLI and Desktop share saved device sessions. Access credentials renew before requests and expire after 15 minutes; a session requires sign-in again after revocation or 90 idle days. Running Cities read the renewed credentials without restarting. city federation logout ends local use of that shared session and attempts remote revocation. Explicit DOWNCITY_USER_TOKEN credentials do not renew automatically. See Desktop sign-in renewal.