Operations and Debugging

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

CLI, FederationAdmin, 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 FederationAdmin

• 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

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

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.

FederationAdmin is not just a more advanced CLI

They are different modes:

• FederationAdmin: 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.

Read next

• For the basic fed / city entries, read CLI Quickstart
• For model and table inspection, read Models and Tables
• For the data layer behind those facts, read Store and Table