Operations and Debugging

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

The CLI and Embassy Admin 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 Embassy Admin 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 Embassy Admin or a trusted script.

CLI, Embassy Admin, 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 `Embassy Admin`

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
fed
city federation status
city agent list

CLI and Desktop City ownership

The CLI and Desktop share the same ~/.downcity data while owning independent City processes. Each City registers its host at startup. If the other host is already running, the new host asks whether it should close the existing City and take over. Cancelling leaves the existing host untouched. Stopping City does not remove Agent, Plugin, or Session data.

User system dashboard

Open fed, choose a saved Federation, then select User system dashboard in the Admin menu.

The CLI reads admin data from the installed official services and computes the dashboard locally in the terminal.

The dashboard covers:

accounts: registered users, new users, active sessions
usage: active users and service-call events
payment: paying users, first-paid users, paid orders, real revenue by currency
balance: credited credits and current balance credits

If a service is not installed, the dashboard marks that module as unavailable and still shows data from the other installed services.

Revenue uses successful payment records and their real amount_minor values. Credits are shown separately as balance and recharge units.

A common debugging chain

confirm Federation is connected to the database you think it is
confirm the expected models and tables exist
confirm the service actually wrote data
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?

Embassy Admin: 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.