PackagesCity CLI

Operations and Debugging

The boundary between fed, city, Admin City, and direct database inspection, and when the CLI is the better tool.

The CLI and Admin City can both help you debug Downcity, but they fit different work: fed/downfed manages Federation, city/downcity manages local Agents and local Federation connections, and Admin City is for trusted programmatic management.

The simplest rule first

If your thought is:

  • "I need to see the facts right now"

start with the CLI.

If your thought is:

  • "this action should live in the system long term"

move toward Admin City or a trusted script.

CLI, Admin City, and direct DB inspection each fit different work

Better fits for the CLI

  • fast local inspection
  • checking whether a service actually wrote the expected tables
  • inspecting models, schema, and rows
  • one-off debugging without writing code first

Better fits for Admin City

  • backend-owned actions
  • automated token issuance
  • formal management workflows
  • internal admin surfaces

Better fits for direct database inspection

  • when the issue has clearly reached the lower database layer
  • when the CLI already narrowed the problem but you need deeper SQL-level facts

Common CLI debugging actions

city
city federation status
city agent list

A common debugging chain

  1. confirm Federation is connected to the database you think it is
  2. confirm the expected models and tables exist
  3. confirm the service actually wrote data
  4. only then suspect deeper business logic

Example: usage seems missing

A good first reaction is not "change code" but "confirm facts":

  • is the usage service enabled?
  • was the usage table created?
  • is this really the database instance you expect?
  • were any events written at all?

Example: payment completed but access is still denied

Check these facts first:

  • did the webhook reach Federation?
  • was the webhook event persisted?
  • did the entitlement become active?

Common misunderstandings

The CLI is not just a one-time development tool

If you operate many products, services, or model configurations, it remains a frequent operations entry.

Admin City is not just a more advanced CLI

They are different modes:

  • Admin City: trusted programmatic management
  • CLI: human terminal inspection

Direct SQL should not always be your first instinct

In many cases the CLI is already enough to narrow the problem sharply.

Models and Tables

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

AI Model Service

AIService's two independent pathways: SDK pathway (User City) and OpenAI-compatible pathway (downcity agent / curl / OpenAI SDK).

Table of Contents

The simplest rule firstCLI, Admin City, and direct DB inspection each fit different workBetter fits for the CLIBetter fits for Admin CityBetter fits for direct database inspectionCommon CLI debugging actionsA common debugging chainExample: usage seems missingExample: payment completed but access is still deniedCommon misunderstandingsThe CLI is not just a one-time development toolAdmin City is not just a more advanced CLIDirect SQL should not always be your first instinctRead next