> ## 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.

# The receipt CLI

> What the released receipt binary can do, how it differs from the in-repo developer CLI, and the parsing behaviour that trips people up.

Sign in once, pick a [workspace](/mcp-gateway/workspaces) — the boundary that holds your organization's connected apps — and use those connections from the terminal, from Codex, or from any other MCP client. MCP is the Model Context Protocol, the standard an agent uses to discover and call tools, and a *tool* here is one operation a connected app publishes, such as listing issues in a repository.

The released `receipt` binary is one compiled file: it holds a session, switches workspaces, lists and calls gateway tools, authorizes providers, and writes MCP client configuration, without ever holding a provider credential itself. It already knows the hosted endpoint, so a plain `receipt setup` signs a fresh machine in with nothing to configure; you name a host only for a dev or self-hosted origin.

The server it talks to is [Receipt Connect](/mcp-gateway/receipt-connect), the part of the MCP Gateway that holds your organization's connections. That name appears in the CLI's own output and in most of its error strings, so it is worth recognising before you meet it.

<CardGroup cols={2}>
  <Card title="Install the CLI" icon="download" href="/cli/install">
    One command, macOS and Linux.
  </Card>

  <Card title="Five-minute quickstart" icon="rocket" href="/cli/quickstart">
    Sign in, choose a workspace, call a tool.
  </Card>

  <Card title="Sign in and out" icon="key" href="/cli/setup">
    What setup, login and logout do, and the session file they leave behind.
  </Card>

  <Card title="Diagnose your setup" icon="stethoscope" href="/cli/doctor">
    The read-only check on your endpoint, the gateway and your saved session.
  </Card>

  <Card title="Command reference" icon="terminal" href="/cli/command-reference">
    Flags, defaults and exit codes.
  </Card>

  <Card title="Environment and exit codes" icon="sliders" href="/cli/environment-and-exit-codes">
    Every variable the binary reads, and where it keeps your session.
  </Card>

  <Card title="Troubleshooting" icon="life-ring" href="/cli/troubleshooting">
    Error strings, cause and fix.
  </Card>

  <Card title="Developer CLI from source" icon="code-branch" href="/cli/from-source/overview">
    The larger in-repo CLI: receipts, jobs, Factory and simulation.
  </Card>
</CardGroup>

## Two programs are named `receipt`

One is the released binary you install on your own machine. The other is the in-repo developer CLI, which only runs inside a Receipt git checkout. **This tab documents the released binary**, and keeps the developer CLI to its own section. A third build exists that you never invoke: Factory's sandbox workers carry a cut-down `receipt` in their container image, with no sign-in verbs — its identity comes from an environment token.

They are not one program with two option sets. Command for command, the released binary is a subset: `whoami`, `run`, `jobs`, `memory`, `debug`, `factory` and the rest of the developer surface exist only in the other one. Sign-in and sign-out are not among the gaps — `receipt setup`, `receipt login` and `receipt logout` all live here.

## Everything the released binary can do

The command surface is:

* `setup` — [sign in](/cli/setup), and install the Claude observer when the companion binary is present
* `login [prod|dev|local|<url>]` — [sign in](/cli/setup) only, without the connector summary or observer install; the target is an optional positional
* `logout` — delete the saved session and sign out
* `doctor` — [check the endpoint, gateway and session](/cli/doctor) without signing in (read-only)
* `workspace` — [read and switch the workspace](/cli/workspaces) your session is bound to
* `tools` — [list, describe, and call](/cli/tools-and-mcp) gateway tools
* `mcp` — [print, install, and serve](/cli/tools-and-mcp) MCP client configuration
* `connect` — [authorize providers](/cli/connect), inspect connections, and disconnect them
* `import` and `observe` — [capture Claude Code activity](/cli/observe-claude-code)
* `--version`, or `-V` — prints the build version; it works only as the entire command line

<Warning>
  Signed out, `receipt tools` and `receipt mcp` both fail with `receipt mcp: not signed in; run 'receipt setup' first` — the `receipt mcp:` prefix appears even when you ran `receipt tools`. `receipt workspace` uses its own prefix: `receipt workspace: not signed in; run 'receipt setup' first`.
</Warning>

`receipt logout` deletes the active session and its matching per-target file. Run it with no session and it prints `receipt logout: not signed in`.

## Parsing behaviour worth knowing before you hit it

The binary matches commands in a fixed order and the first match wins. Three consequences bite early.

### `--help` does not work on every command

`tools`, `mcp` and `workspace` are matched *before* the help check, so `receipt tools --help`, `receipt mcp --help` and `receipt workspace --help` never print help. They try to run instead; signed out, they hit the errors above. With a saved session they run their default subcommand: `receipt mcp --help` runs `mcp status codex`, `receipt tools --help` runs `tools list`, and `receipt workspace --help` fails with `receipt workspace supports list, current, create, rename, use, and delete`.

`receipt connect list`, `receipt connect tools` and `receipt connect call` are claimed before the help check too. Signed out, `receipt connect list` fails with `Receipt Connect gateway is unavailable; run 'receipt setup' or set RECEIPT_CONNECT_TOKEN`. The other two check their arguments first, so a bare `receipt connect tools` fails with `receipt connect tools requires a connection id or provider:name` before it looks for a session at all.

Help works everywhere else. `receipt help`, `receipt -h`, `receipt --help` and `receipt connect help` all print the same usage screen, and so does a trailing `--help` on any command the parser has not already claimed — `receipt doctor --help` and `receipt setup --help` print usage rather than running. Only `--help` is position-sensitive: a word after it becomes its value.

### The word `connect` is optional

A leading `connect` is dropped before dispatch, so `receipt status` is `receipt connect status` and `receipt aws` is `receipt connect aws`.

Bare `receipt` is therefore `receipt connect`: it starts the interactive onboarding flow, which signs you in through the browser first unless a live session for that gateway is already saved. A browser opening where you expected a help screen is intended, not a bug.

### A boolean flag can swallow the next word

`--flag value` consumes the following token as that flag's value unless the token starts with two dashes. Boolean flags are not exempt, so:

```bash theme={null}
receipt connect --no-open status
```

sets `no-open` to the string `"status"` rather than `true`. The check is for the literal `true`, so the browser still opens. Put boolean flags last, or use the `--flag=value` form — for the browser flag, `--open=false`:

```bash theme={null}
receipt connect status --no-open
receipt connect --open=false status
```

`receipt --help extra` fails the same way: `help` takes the value `extra`, so you get onboarding — a browser sign-in — instead of usage.

Setting `RECEIPT_CONNECT_OPEN_BROWSER=0` also keeps the browser closed. A bare `--` ends flag parsing, and a repeated flag accumulates with the last value winning.

<Note>
  `tools`, `mcp` and `connect list|tools|call` use a simpler parser of their own: `--key value`, `--key=value` and a bare `--key` as a boolean, with no `--` terminator, and a repeated flag overwriting rather than accumulating.

  `receipt workspace` is stricter again. It recognises only a bare `--json` and `--target <value>` — `--target=dev` is ignored — and it drops any other flag silently while keeping the word after it as a positional. So `receipt workspace create --server-url X My Team` creates a workspace named `X My Team`.
</Note>

## The two binaries side by side

|                 | Released `receipt` binary                                                                                                                                                               | In-repo `receipt`                                                                                                                                                                                                                                        |
| --------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| How you get it  | [Installer script](/cli/install) drops one compiled binary on your machine                                                                                                              | Comes with a Receipt git checkout, run through the `.receipt/bin/receipt` shell wrapper                                                                                                                                                                  |
| What it needs   | Nothing but the binary                                                                                                                                                                  | The checkout and Bun, plus Postgres for most commands                                                                                                                                                                                                    |
| Command surface | The commands listed above                                                                                                                                                               | `setup`, `workspace`, `tools`, `mcp`, `connect`, `import`, `observe`, plus `login`, `logout`, `whoami`, `doctor`, `new`, `dev`, `run`, `trace`, `replay`, `inspect`, `fork`, `dst`, `eval`, `jobs`, `abort`, `memory`, `sessions`, `debug` and `factory` |
| Sign-in command | `receipt setup` or `receipt login`                                                                                                                                                      | `receipt login` or `receipt setup`                                                                                                                                                                                                                       |
| `--version`     | Prints `receipt` and the build version — `receipt v0.1.0-preview.7` on the current release, or `development` when the run is neither a compiled build nor given a `RECEIPT_CLI_VERSION` | Not a command — it exits 1 with `error: Unknown command '--version'`                                                                                                                                                                                     |
| Documented in   | This tab                                                                                                                                                                                | [The developer CLI from source](/cli/from-source/overview)                                                                                                                                                                                               |

Both use the same session store, `~/.receipt/session.json` by default. Results go to standard output; errors go to standard error and set exit code 1. [Environment and exit codes](/cli/environment-and-exit-codes) has the variables, the session files and the exit codes in full.

Next step: [install the released binary](/cli/install).