CLI

City manages local Agents; Fed manages Federation Servers

The Downcity package installs two independent tools:

  • city (alias downcity) is the local City container for Agents, powers, environment variables, and Federation connections.
  • fed (alias downfed) is the Federation Server Manager. Its TUI manages registered servers, fed web starts the local Web control plane, and project commands read federation.toml from the current project. Federation project configuration uses TOML only; JSON configuration is not supported.

For local deployments, omitting deployment.port uses the fixed default port 12314. Set port in [deployment] to override it. If the selected port is occupied, deployment fails; the CLI does not scan for another port or infer one from deployment history.

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 share user-level files and the Workspace index. One host owns a data root at a time; resource commands connect to its verified local management channel. Offline access supports configuration management and historical browsing, while Session execution requires an explicit host start.

Federation Admin configuration and Federation 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 Power uses its stable ID as ~/.downcity/powers/<power_id>/, with one plaintext configuration in config.toml. A third-party installation contains one power.json, the package.json that establishes its ESM boundary, and optional self-contained main and renderer entries declared by the manifest—not source or build configuration. City provides every registered Power and the same configuration to every Agent; agent.json stores no Power reference. downcity.db stores Workspace indexes, tokens, and platform state, not Agent or Power configuration.

City commands

CommandPurpose
city agentCreate, inspect, update and permanently delete Agent identities
city workspaceRegister, rename and remove project registrations
city sessionBrowse history and manage online Session execution
city powerManage Power artifacts, unique configuration, and actions
city envManage environment variables injected by City
city federationManage Federation connections

Automation can override the current Federation 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.

Explicit resource commands require complete stable IDs. The TUI selects complete IDs from resource lists. Agent identity is never inferred from the current directory. See Resource Management for ownership, offline rules and automation.

Platform support

The CLI architecture is cross-platform. macOS and Linux are stable targets; Windows adapters are currently preview quality.

Continue with CLI commands.