Story: Add tenant discovery to CLI and compass
Table of Contents
This page documents a story in the product backlog. It captures the goal, current status, acceptance criteria, and the tasks that compose it.
Goal
After compass db provision (or any provisioning flow), developers
need to identify the tenant they want to target and export its UUID
as ORES_TENANT. Today there is no command to do this — the UUID
must be obtained by running raw SQL or by inspecting provisioning
output.
Two layers of discovery need to be added:
- CLI:
ores.cli iam tenants list— a new entity under the IAM domain that queries the database and returns all active tenants with theircode,name, andtenant_id(UUID). - Compass:
compass db tenants— wrapsores.cli iam tenants list(reading credentials from.env) and formats the output with a copy-pasteableexport ORES_TENANT=<uuid>hint per row.
Once in place, the standard post-provision developer workflow becomes:
compass db recreate compass db provision compass db tenants # → see codes + UUIDs export ORES_TENANT=<uuid> # copy from output
Status
| Field | Value |
|---|---|
| State | BACKLOG |
| Parent sprint | None (product backlog) |
| Now | Nothing. |
| Waiting on | Nothing. |
| Next | Pick up CLI task first; compass task depends on it. |
| Last touched | 2026-06-25 |
Acceptance
ores.cli iam tenants listlists all active tenants (code,name,tenant_id) from the database.ores.cli iam tenants list --format jsonand--format tableboth work.compass db tenants(reading.envfor DB credentials) calls the CLI and prints a table of code / name / tenant_id with anexport ORES_TENANT=<uuid>hint alongside each row.- The
ores.cli iam --helpcrash (boost::bad_any_cast) is fixed or filed as a separate bug during the CLI task. - A recipe is added:
How do I list tenants?(CLI and compass variants).
Tasks
| Task | State | Start | End | Description |
|---|---|---|---|---|
| Add ores.cli iam tenants list command | BACKLOG | Add a tenants entity to the ores.cli IAM domain: list active tenants (code, name, tenant_id). Fix or file the iam –help crash found during verification. | ||
| Add compass db tenants command | BACKLOG | Wrap ores.cli iam tenants list in a compass db tenants subcommand that reads .env for DB credentials and shows code, name, tenant_id with a copy-pasteable export ORES_TENANT=<uuid> hint. Blocked on CLI task. |
Notes
Surfaced during the Commission: country story (sprint 21) while
verifying country CLI commands. The --tenant flag requires a UUID;
there was no way to discover that UUID without running raw SQL. The
Barclays tenant UUID (36d4c3c9-195c-46b5-a4d8-b36cb48c8f46) was
discovered via:
SELECT code, name, tenant_id FROM ores_iam_tenants_tbl WHERE valid_to = ores_utility_infinity_timestamp_fn() ORDER BY code;
ORES_TENANT is not written to .env by provisioning — it is
tenant-specific by design (a developer chooses which tenant to target).
The compass command makes this self-service without requiring knowledge
of the schema or raw SQL access.
The ores.cli iam --help crash (boost::bad_any_cast) was noticed
during the CLI task 1D7A5AA2 but not investigated; the CLI task
here should resolve it so that iam --help works correctly once the
tenants entity is registered.