Safe scope switching in multi-tenant developer tools

Persisted context is what makes developer tools feel fast, but nested context can quietly go invalid the moment a parent selection changes. A project belongs to a tenant. An environment belongs to a project. Keep either one around after switching to a different tenant, and you've got a state that never actually existed on the server.

Authdog CLI treats scope as a hierarchy, not a loose bag of IDs that happen to sit next to each other.

Model the descendants explicitly

The persisted session can include:

organization
  tenant
    project
      environment

Each level constrains everything below it, and the CLI enforces that relationship the moment a selection changes.

Pick a different organization, and tenant, project, and environment all clear. Pick a different tenant, and project and environment clear. Pick a different project, and any previously selected environment clears with it.

Why cascading clears matter

Without that cascade, a session could end up claiming:

• an organization from account A
• a tenant from organization B
• a project from an older tenant
• an environment from an unrelated project

Even when the API would reject that combination outright, just displaying it in local status is confusing enough on its own. Worse, client code might use one stale identifier before a later request has a chance to correct the state, and that's the kind of bug that's genuinely painful to track down after the fact.

Clearing descendants the instant a parent changes gives the local session exactly one valid interpretation at any given time.

Tenant choices get filtered by organization too

Choosing an organization also changes what shows up in the tenant picker. Authdog CLI filters merged tenant data against the active organization, so unrelated tenants never leak into that scoped view.

And if an account has no organizations at all, /browse just proceeds straight to the full tenant list. The rule adapts to whatever shape the account actually has, without weakening organization boundaries wherever they do exist.

Make clearing visible, not silent

You can always inspect the resulting path with /status. /tenant shows the current tenant, and /tenant clear removes tenant scope (and everything under it) deliberately, as an explicit action rather than something that just happens.

That visibility matters more than it might seem. Hidden context is hard to debug by definition; visible context at least gives someone a chance to catch a mistake before it turns into an action.

The general lesson here

Any developer tool that persists hierarchical cloud resources should encode parent-child invalidation in one central place. Don't rely on every screen or command remembering, on its own, which IDs have quietly gone stale.

Scope safety comes down to one small invariant: when a parent changes, no descendant survives without being chosen again.