PackagesCity CLI

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 plugins, chat/gateway, and the local user's selected Federation login.

Install

npm i -g downcity

Check versions:

fed -v
city -v

Manage Federations With fed

Use fed when you are creating, deploying, or operating the shared backend.

fed
fed create .
fed deploy
fed deploy --dry-run
fed deploy --verify

fed create scaffolds a Federation project. The config file is federation.json. fed deploy reads a local Federation project and deploys it to the selected target; for Cloudflare Workers, it prepares D1, Queue, and R2 storage automatically.

Manage deployed Federations:

fed server add
fed server manage
fed query GET /health
fed query GET /v1/ai/models
fed query POST /v1/ai/image/result --data '{"job_id":"..."}'

fed query uses the active Federation and the saved admin_secret_key.

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 .
city agent list
city agent start
city agent chat

city federation ... only manages local Federation membership and user login state. It does not deploy Federations.

Default Storage In federation.json

Cloudflare Workers Federation projects can declare default storage in federation.json. R2 is currently supported:

{
  "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 to create a local Agent project.

fed and city have different roles

  • fed: manages shared backend and admin-side capabilities.
  • city: manages local Agents and user-side connection state.

CLI

Separate fed/downfed from city/downcity: one manages Federation infrastructure, the other manages local Agent state and Federation login.

Models and Tables

Use downcity to inspect models, schema, and table data, and understand how that connects to the City data layer.

Table of Contents

InstallManage Federations With fedManage Local Agents And Login State With cityDefault Storage In federation.jsonCommon Misunderstandingscity deploy is not the deploy entrycity create is not the Federation project entryfed and city have different rolesRead Next