CLI Quickstart
First-time Downcity CLI usage starts by separating fed/downfed from city/downcity.
The downcity package installs two command families:
fed/downfed: manages and deploys Federations.city/downcity: manages local Agents, local powers, chat/gateway, and the local user's selected Federation login.
Install
npm i -g downcityCheck versions:
fed -v
city -vManage Federations With fed
Use fed when you are creating, deploying, or operating the shared backend.
fed
fed create
fed create --path ./edge-fed --template cloudflare-workers
fed create --path ./custom-fed --template git://example.com/custom-fed.git
fed deploy
fed deploy --dry-run
fed deploy --verifyfed create and fed deploy default to --path .. Use --path <path> for another directory, such as fed deploy --path ./edge-fed; positional path arguments are not accepted.
fed create generates a Local Node.js + SQLite project by default. --template can select cloudflare-workers or a Git template. Project identity and deployment intent live in federation.toml. Federation project configuration uses TOML only; JSON configuration is not supported.
fed deploy deploys the current project whether the destination is local or remote. Local deploys use the fixed default port 12314 when deployment.port is omitted and start a managed process. An explicit deployment.port overrides the default. If the selected port is occupied, an interactive terminal shows the listener PID, start time, command, working directory, and whether it belongs to the current project, then asks whether to stop it and continue (default: No). After confirmation, the CLI rechecks process identity, sends SIGTERM, and waits up to 5 seconds for the port to become available, without escalating to a forced kill. Deployment fails in non-interactive terminals, when process identity cannot be verified, or when the port remains unavailable. --yes does not bypass this confirmation. Process inspection requires lsof and ps. The CLI does not scan for another port or infer one from deployment history. On local deployments, the first deploy interactively sets an administrator ID and password, while ordinary redeploys preserve the existing administrator. Redeploying the same fed_id replaces the old process without changing administrator credentials. Cloudflare Workers deploys prepare D1, Queue, and R2, publish the Worker, then create a time-limited administrator Session Token for the local registry.
Manage deployed Federations:
fed server add
fed server --id fed_x
fed manage --id fed_x
fed server manage --name my-fed
fed web --id fed_x
fed status --id fed_x
fed logs --id fed_x
fed stop --id fed_x
fed restart --id fed_x
fed clean --id fed_x --dry-run
fed clean --name my-fed --yes
fed query GET /health --id fed_x
fed query GET /v1/ai/models --id fed_x
fed query POST /v1/ai/image/result --id fed_x --data '{"job_id":"..."}'Federation URLs, administrator IDs, administrator Session Tokens, local PIDs, ports, logs, and deployment status are stored in the system-level Federation registry and do not depend on the current directory. Fed has no global active/default Federation and does not store active_server_url; deployment only registers or updates an instance. Lists have no global-current star marker.
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.
fed status displays the registry record, live system manager facts, and a /health probe separately for any saved connection. Local instances also show deployment history. Registered state, saved policy, and deployment outcomes do not establish that a service stopped or that a particular release is running. A local release is reported ready only when the manager verifies its instance identity and the health response has ok: true with matching fed_id, release_id, and instance_id. HTTP 200 alone does not establish identity. A manager inspection error is shown as unknown and requires manual inspection of the system service and health endpoint.
logs, stop, and restart only support CLI-managed local instances. logs displays up to the last 200 lines of the current service.log only, without filling from archives; read archives manually. stop disables automatic startup and stops the service. The stopped state survives system restarts until an explicit fed deploy or a fed restart permitted by the recovery guard; those operations restore the automatic startup policy from persisted configuration. Restart runs only the installed artifact with its persisted runtime configuration, without reading or rebuilding source. It works after the original project is deleted. Before restarting, current.json must also match the registry release. Build/package/preflight failures allow restarting the last successful release when there is no pending cutover recovery. Entering cutover sets recovery_required = true; a failed or interrupted cutover blocks restart until an explicit fed deploy succeeds. This guard persists through later build/preflight failures and clears only after a successful deployment. Historical last_failure alone does not block restart. Remove connection in the management UI only removes the connection; it does not stop the service.
Independent Local Node Releases
The compiled entry, complete production dependencies, and project resources are installed at ~/.downcity/federation/deployments/<fed_id>/releases/<release_id>. The adjacent current.json points to the successfully activated release; it does not establish that the release is currently running. Runtime configuration is stored at ~/.downcity/federation/config/<fed_id>/runtime.env.json with file permissions 0600; the default SQLite path is ~/.downcity/federation/data/<fed_id>/data.sqlite. The registry also stores release_id, release_dir, runtime_config_path, and data_dir.
The deployment summary is stored at ~/.downcity/federation/deployments/<fed_id>/deployment.json. status shows the last successful release, the last failed release and failure phase, plus the latest release, outcome, phase, cutover, candidate, cleanup, and recovery required. A build that has not produced a candidate release shows not produced; missing history is displayed separately as not recorded. Failures never overwrite last_success. last_failure and latest are displayed separately, and a historical failure does not establish a current recovery guard. Cleanup describes that attempt's result, not live service state. Missing or unreadable history does not replace manager and health inspection.
Local Node deployments handle failures by phase, without automatic code or database rollback. There is no rollback command. These rules apply only to local Node, not Cloudflare Workers:
| Phase | Failure handling |
|---|---|
| build / package / validate / install / preflight | Preserve the existing instance and persisted runtime configuration without entering cutover. |
| stop | Do not start a candidate or competing instance; inspect the manager and health endpoint to establish actual state. |
| prepare | Commit configuration, initialize the database, and run migrations only after the old service has stopped. On failure, do not start the candidate or automatically roll back code or data. |
| start / ready | Stop the candidate and remove its automatic startup association. Confirmed cleanup is recorded as stopped; cleanup errors are recorded as unknown. Report both the original deployment error and any cleanup error. unknown requires manual inspection of the service, startup association, and health endpoint; it does not mean the service stopped. |
Declare project runtime resources explicitly in package.json.files, for example "files": ["assets", "templates"]. Production dependencies and their runtime resources are included in full; .env is excluded from the artifact. The system Node is used by default. Its version, platform, and architecture must match the build environment, particularly for native modules.
An explicitly selected SQLite database keeps its absolute path. Before deleting the project, check whether the selected database lives inside it; instances using that database still require the file. If the registered database file is missing, deployment fails rather than creating an empty replacement. If no explicit path is set but the source directory contains data.sqlite or data/local.db, the CLI rejects deployment and requires an explicit path in the project's .env, for example DOWNCITY_FEDERATION_DATABASE_URL=file:/absolute/path/data.sqlite. It does not guess or migrate the database.
Local fed deploy --dry-run builds and validates an artifact in a temporary directory, then deletes it. It does not install a release, modify persisted runtime configuration, or start or stop instances. Build scripts can still write build output into the project.
If an operation lock has a stale owner or no owner, the CLI reports its path and requires manual inspection. It does not automatically reclaim the lock.
Local deployments run under macOS user-level launchd or Linux user-level systemd. restart_on_failure = true is the default: unexpected exits trigger recovery at 10-second intervals, limited to 5 attempts within 60 seconds. An explicit stop does not trigger recovery.
auto_start = false is the default. Only an explicit true installs a persistent definition in macOS ~/Library/LaunchAgents or enables the Linux user service in default.target.wants. macOS starts the service after the user logs in. Linux requires that user's systemd user manager to exist and be available, so this does not guarantee startup at boot. The CLI does not automatically enable linger.
System service definitions reference the launch entry and runtime configuration path without containing secrets. Runtime configuration stays in the separate runtime.env.json file with permissions 0600. Deployment targets are local and cloudflare-workers; to deploy on another host, run local deployment commands on that machine.
Local Logs
Application stdout/stderr pass through runner pipes with backpressure and serialized writes to service.log: 20 MiB per file with 5 archives, about 120 MiB per Fed including the current file. .1 is newest and .5 oldest. Runner diagnostics go to supervisor.log in the service directory: 2 MiB per file with 3 archives, about 8 MiB including the current file. These are fixed defaults with no additional configuration.
Oversized chunks are split by actual bytes so each file stays within its limit. Rotation does not restart the service or guarantee complete UTF-8 characters or lines. Logging failures stop the application and mark the runtime receipt failed; status reports APPLICATION_LOG_FAILED, SUPERVISOR_LOG_FAILED, or RUNNER_FAILED under runner failure. Logs and archives must be regular files; symlinks, directories, and other invalid targets are rejected. Existing oversized files cause an error without truncation; the user must explicitly archive or clean them up first.
Application output is not guaranteed to be automatically redacted. Developers must not log tokens, API keys, or complete request/response bodies. macOS launchd stdout/stderr point to /dev/null; the Linux journal retains runtime startup information under operating-system quotas. A running instance must load the CLI and runner containing this feature; documentation updates do not apply it. See Local Fed Logs and Startup Diagnostics for startup failures and full logging boundaries.
Clean Local Releases
fed clean only cleans releases of locally registered Feds with a local deployment. It does not clean remote connections or unregistered directories. Select the target with mutually exclusive, exact-match --id <id> or --name <name>. Without a selector, a TTY opens a list to select one Fed for this operation only; non-TTY execution fails with a missing-target error. Duplicate names prompt for a further choice in a TTY and fail outside a TTY.
fed clean # TTY selection, preview, then confirmation
fed clean --id fed_x --dry-run # preview only
fed clean --name my-fed # preview, then interactive confirmation
fed clean --id fed_x --yes # explicit confirmation for non-interactive useThe preview lists each release ID, size, and reason for deletion or retention before asking for confirmation. --dry-run only previews and never deletes. Non-interactive deletion requires explicit --yes, which does not bypass protection checks. The default policy always retains the 3 most recent successful releases. There is no --keep option.
The following releases are also protected, with retention reasons shown in the preview:
- Releases referenced by the successful activation pointer
current.jsonor the registry. - Releases referenced by the service's
launch.json, including references awaiting recovery startup. - Releases referenced by in-progress deployment attempts, and candidates whose cleanup could not be confirmed.
- Unknown or damaged releases, and releases without trustworthy deployment records.
If the runner cannot be verified or any other protection-information check fails, cleaning is refused outright. After target selection, the same Fed operation lock covers preview, confirmation, and deletion to prevent concurrent cutovers from changing references.
Each deployment attempt is stored at ~/.downcity/federation/deployments/<fed_id>/attempts/<operation_id>.json to identify successful and failed deployment history. Failed artifacts are deleted only through a manual fed clean and remain subject to these protection checks. The CLI does not automatically clean releases. clean never deletes data, config, logs, staging, or deployment history; attempt records and the deployment.json summary remain after a release is deleted.
federation.toml
schema = 1
type = "federation"
id = "fed_example"
name = "example"
entry = "src/index.ts"
[deployment]
target = "local"
# Optional: override the fixed default port 12314.
port = 12315
[deployment.process]
auto_start = false
restart_on_failure = true
[deployment.scripts]
build = "pnpm typecheck"deployment.process applies only to local. Omitting the table or either field supplies the defaults above. Both fields require booleans; unknown fields are rejected. Declaring this table for cloudflare-workers is an error. Run fed deploy to apply project configuration changes; fed restart uses the persisted runtime configuration.
The optional deployment.scripts.build overrides the build stage; the release builder still compiles the entry. Local targets reject deployment.scripts.deploy and run the installed artifact's compiled entry directly with Node. See the deployment guide for Cloudflare Workers script overrides.
Manage Local Agents And Login State With city
Use city when the local machine needs to join a Federation, sign in as a user, run Agents, or open chat.
city
city federation status
city federation join https://your-federation.example.com
city federation login
city agent create --name Reviewer --id reviewer --model MODEL_ID
city workspace register .
city workspace list
city agent list
city on
city agent chat reviewer --new-session --workspace WORKSPACE_IDcity agent chat keeps one live subscription to the active Session and merges Message, Part, text, reasoning, Tool, Interaction, and configuration updates as they arrive. Opening an Agent enters its most recent Session and follows that Session's Workspace; when the Agent has no history yet, Chat opens in the current Workspace and creates a new Session. The header shows the active Session model. Use /model to choose from the current user's available model catalog, or /model <model-id> to switch directly. A model change affects only the active Session and reaches the UI through a Session Mutation; it does not change the Agent default model. When /session switches conversations, the TUI subscribes to the new Session before loading its full snapshot and then merges any buffered events. Visible reasoning text is rendered in Assistant Part order with subdued styling; reasoning metadata alone does not produce invented reasoning content.
Agent/Workspace configuration can be managed offline. Session execution requires the explicitly started current CLI or Desktop host; commands never start a temporary executor. Details/history are side-effect-free and retain orphaned Workspace references. See Resource Management for JSON, exit codes, revisions and the complete command tree.
city federation ... only manages local Federation membership and user login state. It does not deploy Federations.
When connecting to the official private/services/local-node, local login issues an ordinary user token without a password on a trusted machine. CLI requests need no Origin header. This node accepts only loopback listen addresses and a loopback PUBLIC_URL with the same port. Browser pages must use the target's own origin, PUBLIC_URL, or an exact trusted origin in DOWNCITY_LOCAL_ALLOWED_ORIGINS. The allowlist does not elevate identity; administrator operations still require a real administrator Session. See Official local-node configuration for origin syntax and port constraints.
Each CLI City start has a unique instance ID. city off verifies the PID and instance ID together. If pid/meta files are stale or the PID has been reused by another process, the CLI does not signal that unrelated process.
After selecting an OAuth provider such as GitHub or Google, the CLI always prints the authorization_url. In a local graphical session it also attempts to open the default browser. When connected to a VPS over SSH or running headlessly, open that URL in your own browser while the CLI waits for the login result.
Default Storage In federation.toml
Cloudflare Workers Federation projects can declare default storage in federation.toml. R2 is currently supported:
[deployment]
target = "cloudflare-workers"
[deployment.resources.storage]
type = "r2"
binding = "DOWNCITY_STORAGE"
name = "downcity-storage"
public_url_prefix = "https://images.example.com"During deploy, fed deploy first checks whether a same-name R2 bucket exists. If it is missing and the deploy is not a dry run, the CLI creates it automatically. The CLI then writes the binding to the temporary wrangler.toml as [[r2_buckets]] and emits public_url_prefix as a Worker var.
Common Misunderstandings
city deploy is not the deploy entry
Use fed deploy to deploy Federations.
city create is not the Federation project entry
Use fed create to scaffold a Federation project. Use city agent create --name NAME for a local identity and city workspace register PATH for an existing project.
fed and city have different roles
fed: manages shared backend and admin-side capabilities.city: manages local Agents and user-side connection state.
Read Next
- To deploy a Federation, read Deploy to Cloudflare Workers
- To debug local state, read Operations and Debugging
- To understand the Federation runtime, read Federation