> ## Documentation Index
> Fetch the complete documentation index at: https://docs.kentron.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# Switching workspaces
> Move a CLI session between workspaces with receipt workspace, and understand why that changes everything else the CLI can see.
A workspace is the boundary that decides which connections and tools a session can reach. `receipt workspace` tells you which one you are in, lists the others you can reach, creates, renames and deletes them, and — with `use` — moves your session to a different one. What a workspace holds is described in [Workspaces in the MCP Gateway](/mcp-gateway/workspaces).
`use` is the lever. Your session carries a token bound to exactly one workspace, and every other command — listing connections, connecting a provider, listing tools, calling a tool — is scoped by the workspace id inside that token. `receipt setup` always signs you in to the organization's **Default** workspace, and nothing in the browser step lets you pick another, so `receipt workspace use` is the only way to move.
## Before you start
`receipt workspace` requires a saved session. Unlike `receipt tools`, it does **not** accept environment credentials. Signed out, every subcommand fails with:
```
receipt workspace: not signed in; run 'receipt setup' first
```
The command that signs you in is [`receipt setup`](/cli/setup). Run it once, then come back to `receipt workspace`.
All requests go to `/connect/workspaces` with your session token and a 35-second timeout.
## Subcommands
| Subcommand | Positionals | What it does |
| ------------------------------- | ------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `current` (default), `identity` | none | `GET /connect/workspaces` and prints the workspace the session is bound to |
| `list` | none | Lists every workspace you can reach, marking the current one |
| `create ` | name words, joined with spaces | Creates a workspace. Requires organization owner or admin |
| `rename [] ` | selector optional | Renames a workspace. The first positional is treated as a selector **only when two or more positionals are given**; with one positional it renames the current workspace |
| `use ` | selector required | Switches workspaces. The only subcommand that binds your session to a different workspace |
| `delete ` | selector required | Deletes a workspace |
An unrecognised subcommand answers:
```
receipt workspace supports list, current, create, rename, use, and delete
```
`receipt workspace --help` gets that same line: the word is taken literally as a subcommand name, so this command never prints help. Help comes only from `receipt --help`, `receipt help` or `receipt -h`.
A missing name or selector answers `receipt workspace create requires a name`, `receipt workspace rename requires a name`, `receipt workspace use requires a workspace id, slug, or name` or `receipt workspace delete requires a workspace id, slug, or name`.
### Text output
A single workspace prints as `Name (id)`, with a trailing `[Default]` when it is the default workspace. `list` prefixes each row with a space, except the current workspace, which gets `*`:
```
Default () [Default]
* Engineering ()
```
The server returns the default workspace first, then the rest by name.
`delete` prints `Deleted workspace `.
### Who may create, rename and delete
`receipt workspace create` calls `POST /connect/workspaces` and is organization owner or admin only. If your role is neither, the server answers 403 with:
```
organization owner or admin permission is required
```
`rename` and `delete` are checked per workspace: you must be a member of that workspace **and** hold the owner or admin role there. An organization owner or admin holds that role in every workspace they are a member of, but membership is still required — an organization admin who was never added to a workspace gets `workspace not found or unavailable` instead. `current`, `list` and `use` need nothing beyond membership of the workspace involved.
### `use` is the only command that re-scopes your session
`use` calls `POST /connect/workspaces//token`, receives a new JWT bound to that workspace, and rewrites the session file. Nothing else moves you: renaming the current workspace updates the name stored in the file, and `current` and `list` repair it (below) — they can even mint a replacement token — but only `use` changes which workspace the token is for.
With `--json`, `use` additionally reports `sessionFile` and `targetSessionFile` so you can see exactly which files were rewritten.
`--target` is not a sandbox. Every session write goes to **both** `session..json` and the active `~/.receipt/session.json`, so `receipt workspace use --target dev ` also repoints the plain, target-less `receipt tools` and `receipt mcp` at that dev session.
Clients that read the session at start-up do not notice the switch. Restart Codex, or any other MCP client using the `receipt mcp` bridge, after `receipt workspace use`, then rediscover tools.
### Three ways `delete` is refused
Deleting the workspace you are currently in is refused by the CLI before any request is sent:
```
cannot delete the current workspace; switch to another workspace first
```
Switch away with `receipt workspace use ` first. The server adds two refusals of its own, both 409. It never deletes the Default workspace:
```
the Default workspace cannot be deleted
```
And it will not delete a workspace that still holds provider connections:
```
workspace connections must be removed before deleting the workspace
```
Remove them first: `receipt connect disconnect --provider ` from a session bound to that workspace, or the workspace's **Open integrations** page.
## How selectors match
`use`, `rename` and `delete` take a selector, which is matched case-insensitively against a workspace's **id**, **slug** or **name**. Two failure modes:
```
workspace 'platform' is ambiguous; use its id
workspace 'platform' was not found
```
If more than one workspace matches your selector, pass the id instead.
## Self-healing on `current` and `list`
`current` and `list` reconcile your saved session against what the server reports, and can rewrite the session file as a side effect:
* If the saved workspace name or id has drifted from the server's current workspace, the session file is rewritten in place — no new token.
* If the saved workspace no longer exists server-side, a fresh token is minted for the server's current workspace and saved.
One thing it will not do: persist a workspace belonging to a different organization. That is refused with `refusing to persist a workspace from another organization`.
## The flag parser is not the usual one
`receipt workspace` uses its own minimal argument parser, separate from the rest of the CLI. It understands exactly two flags:
| Flag | Effect |
| ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `--json` | Print a JSON envelope instead of text |
| `--target ` | Act on the session saved for that target — `session.prod.json`, `session.dev.json`, `session.local.json` — falling back to the active session when it already belongs to that target |
Four consequences you will hit:
* Flags must be given in space-separated form. `--target dev` works; `--target=dev` does not.
* `--target` swallows the word after it, whatever that word is. `receipt workspace use --target engineering` looks for a *session* named `engineering`, never sees a selector, and fails with `receipt workspace use requires a workspace id, slug, or name`. Put the selector first.
* Any other flag is dropped silently — including `--server-url`, which this command does not accept. The gateway always comes from the saved session.
* The word after a dropped flag is **not** dropped: it becomes a positional. `receipt workspace create --server-url X My Team` creates a workspace named `X My Team`.
### JSON envelopes
| Subcommand | Envelope |
| ----------------------------------------- | ------------------------------------------------------------------- |
| `current`, `identity`, `create`, `rename` | `{ "ok": true, "workspace": { … } }` |
| `list` | `{ "ok": true, "currentWorkspaceId": "…", "workspaces": [ … ] }` |
| `use` | the `workspace` envelope plus `sessionFile` and `targetSessionFile` |
| `delete` | `{ "ok": true, "deleted": true, "workspaceId": "…" }` |
Each workspace object carries `id`, `organizationId`, `name`, `slug`, `isDefault`, `role`, `createdAt` and `updatedAt`.
## Errors from the server
Server errors surface verbatim, so you can search on the text you saw:
* `unauthorized` (401) — the gateway would not accept your session token, usually because it expired; the CLI session JWT lives 12 hours and is not refreshed
* `organization owner or admin permission is required` (403)
* `workspace not found or unavailable` (404) — the workspace id in the request is not one you are a member of. `use`, `rename` and `delete` resolve their selector against your own workspace list first, so you normally get the local `workspace '' was not found` instead; this one reaches you when the workspace is deleted, or your access to it is revoked, between the list call and the request
* `workspace not found` (404) — the workspace row disappeared mid-request, after the permission check and before the write
* `a workspace with this name already exists` (409)
* `the Default workspace cannot be deleted` (409)
* `workspace connections must be removed before deleting the workspace` (409)
* `workspace name is too long` (400) — names are capped at 120 characters
* `workspace name is invalid` (400) — nothing in the name survives to become a slug
* `workspace name uses a reserved system prefix` (400)
* `receipt_workspace_unavailable` (503)
When the server sends no error string at all, the CLI reports `Receipt workspace request returned HTTP ` instead.
If [`receipt tools list`](/cli/tools-and-mcp) shows fewer tools than you expected, check `receipt workspace current` first. `receipt tools list`, `receipt tools call`, `receipt mcp config` and `receipt connect status` all read the workspace bound into your saved session, and a provider you connect from the terminal lands in that same workspace — so a connection made before a switch will not appear after it.
The ones that call the gateway — `receipt tools list`, `receipt tools call` and `receipt connect status` — answer `workspace_membership_required` (403) when the workspace in your session is one you no longer belong to, or one that has been deleted. (`receipt mcp config` only reads the session file, so it keeps printing a config for a workspace that is already gone.) Signing in again with `receipt setup --fresh-login` mints a token for **Default**, which you are always a member of.
Next step: [connect a provider from the terminal](/cli/connect).