Workspaces

Every authenticated command needs a workspace context — the server uses it for tenant isolation, billing, and rate limits. The CLI resolves the active workspace from this chain (first match wins):

1. --workspace <slug-or-id> explicit flag (always wins)
2. ATHENA_WORKSPACE_ID env var
3. active_workspace pinned in your profile’s config.toml
4. Autodetect — if you belong to exactly one workspace, the CLI uses it and writes a stderr note so the implicit choice is visible
5. Ambiguous error (exit 2) when you belong to 2+ workspaces and none is pinned
6. No-memberships error (exit 2) when you belong to zero workspaces

Steps 4–6 cost one /auth/me round-trip. The first three short-circuit without network.

Commands

List your memberships

athena workspace list

{
  "workspaces": [
    {
      "workspace_id": "019f58c6-0400-7fa2-a41f-a32abf613c76",
      "workspace_name": "Athena Dev",
      "role": "admin"
    },
    {
      "workspace_id": "019f58c6-0401-7fa2-a41f-a32abf613c76",
      "workspace_name": "Demo Tenant",
      "role": "member"
    }
  ]
}

Pin one as the active workspace (sticky)

athena workspace use athena            # by slug
athena workspace use 019f58c6-0400-7fa2-a41f-a32abf613c76 # by full ID

Both work. The CLI resolves slugs to the raw workspace UUIDv7 required by the API, validates membership against /auth/me, then writes it to [profile.<name>].active_workspace in config.toml.

Show the current selection

athena workspace current

{
  "active_workspace": "019f58c6-0400-7fa2-a41f-a32abf613c76",
  "profile": "default",
  "source": "config"
}

source is one of config, env, or flag — tells you where the current selection came from, useful for debugging “why did this command hit the wrong workspace?”.

Clear the pinned selection

athena workspace clear

Removes active_workspace from the profile. Next command falls back to env var → autodetect → error.

Override for a single command

Pass --workspace to override without changing the pin:

athena --workspace demo agent list

Or set the env var:

ATHENA_WORKSPACE_ID=019f58c6-0401-7fa2-a41f-a32abf613c76 athena agent list

Caution

ATHENA_WORKSPACE_ID is validated before it hits the wire. Crafted CRLF or non-ASCII bytes return invalid_header_value (exit 2) instead of panicking inside the HTTP layer.

Working with multiple workspaces

If you frequently switch, use profiles instead of flags. See Authentication → Profiles.