Skip to main content
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. 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:
The command that signs you in is receipt setup. Run it once, then come back to receipt workspace.
All requests go to <gatewayUrl>/connect/workspaces with your session token and a 35-second timeout.

​
Subcommands

An unrecognised subcommand answers:
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 *:
The server returns the default workspace first, then the rest by name. delete prints Deleted workspace <id>.

​
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:
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/<id>/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.<target>.json and the active ~/.receipt/session.json, so receipt workspace use --target dev <name> 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:
Switch away with receipt workspace use <other> first. The server adds two refusals of its own, both 409. It never deletes the Default workspace:
And it will not delete a workspace that still holds provider connections:
Remove them first: receipt connect disconnect --provider <id> 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:
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: 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

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 '<x>' 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 <n> instead.
If receipt tools list 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.