CLI
City manages local Agents; Fed manages Federation Servers
CLI
The Downcity package installs two independent tools:
city(aliasdowncity) is the local City container for Agents, plugins, environment variables, and Federation connections.fed(aliasdownfed) is the Federation Server Manager. Its TUI manages registered servers,fed webstarts the local Web control plane, and project commands readfederation.jsonfrom the current project.
City data model
Agents and Workspaces are independent global entities. An Agent is identified by agent_id, keeps its structured definition in ~/.downcity/agents/<agent_id>/agent.json, and keeps its stable identity instructions in SOUL.md. A Workspace is identified by workspace_id and points to a project directory. An Agent can enter multiple Workspaces; neither entity stores a persistent binding to the other. CLI and Desktop own separate City instances but share the same user-level files and Workspace index.
Federation Admin configuration and Embassy User Sessions also live in ~/.downcity/downcity.db. On upgrade, administration configuration in the legacy ~/.downcity/federation.db is migrated once. The old file remains available for manual recovery but is no longer read at runtime.
Each Plugin uses its stable ID as ~/.downcity/plugins/<plugin_id>/. Its plaintext profiles live in config.toml; a third-party Plugin installation contains only its single plugin.json, the package.json that establishes the ESM boundary, and its self-contained entry, not source or build configuration. An Agent registers a Plugin and selects an optional profile in its own agent.json. downcity.db stores Workspace indexes, tokens, and platform state, not Agent or Plugin configuration.
City commands
| Command | Purpose |
|---|---|
city agent | Manage global Agents |
city plugin | Manage Plugin artifacts, profiles, Agent references, and actions |
city env | Manage environment variables injected by City |
city federation | Manage Federation connections |
Automation can override the current Embassy user identity with DOWNCITY_FEDERATION_URL and DOWNCITY_USER_TOKEN. The legacy DOWNCITY_CITY_URL, DOWNCITY_CITY_USER_TOKEN, CITY_URL, and CITY_USER_TOKEN variables are no longer parsed.
city init, city update, and city config are no longer provided. Upgrade globally with npm i -g downcity@latest.
Every command that operates on one Agent targets an agent_id. If omitted in a TTY, City opens the global Agent selector. Non-interactive calls fail with Agent ID is required; the current directory is never used for inference.
Platform support
The CLI architecture is cross-platform. macOS and Linux are stable targets; Windows adapters are currently preview quality.
Continue with CLI commands.