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; one-shot — it never changes your pin)
2. ATHENA_WORKSPACE_ID env var (also one-shot)
3. active_workspace pinned in your profile’s config.toml
4. Autodetect — if you belong to exactly one workspace, the CLI uses it, pins it, and writes a stderr note so the implicit choice is visible. Because it is pinned, this happens once, not once per command. (Skipped when --api-url / ATHENA_API_URL points at a different deployment than the profile’s own api_url — a workspace found there is used for that command only, never pinned)
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.

Nothing is ever sent without a workspace

Workspace-scoped endpoints are gated server-side: a missing X-Workspace-Id is a 400, and so is a value that isn’t a UUIDv7. The CLI enforces the same contract locally, so those requests never leave your machine:

• Every request is classified against the API’s route groups. Anything not known to be public or account-level is treated as workspace-scoped, so a new endpoint is covered the day it ships.
• A workspace id is validated as a UUIDv7 no matter where it came from — the flag, the env var, or a stale pin in config.toml. A workspace name left in ATHENA_WORKSPACE_ID fails locally instead of 400-ing once per request.
• With no workspace resolvable, the command stops with exit 2 and lists what you can pick — including in an interactive terminal. The CLI does not prompt; scripts, agents, and humans get the same answer.

athena agent list   # nothing pinned, two memberships

{
  "code": "ambiguous_workspace",
  "message": "no workspace is set and you belong to 2 workspaces",
  "hint": "Run `athena workspace use <name-or-uuid>` to pin one — every later command reuses it. Available: Athena Dev  (019f58c6-0400-7fa2-a41f-a32abf613c76), Demo Tenant  (019f58c6-0401-7fa2-a41f-a32abf613c76).",
  "details": {
    "available_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"
      }
    ]
  }
}

details.available_workspaces carries the same ids and names as athena workspace list, so a caller can recover without a second command.

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.

Tip

Clearing the pin when you belong to exactly one workspace is a no-op in practice: the next command auto-detects it and pins it again.

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

Neither changes the pinned workspace — they apply to that invocation only, so a CI job exporting ATHENA_WORKSPACE_ID can’t quietly repin a developer’s default.

Caution

ATHENA_WORKSPACE_ID is validated before it hits the wire. A value that isn’t a UUIDv7 (a workspace name, say) returns invalid_workspace (exit 2), and 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.