> ## Documentation Index
> Fetch the complete documentation index at: https://docs.custral.com/llms.txt
> Use this file to discover all available pages before exploring further.

# CLI

> Sign in from your terminal and work with your workspace as yourself.

The **`@custral/cli`** package gives you a `custral` command that holds a real Custral session (not an API key), so it can act **as you**, across every organization you belong to.

<Info>
  The CLI is *you*. For unattended / CI use, prefer an [API key](/dev/auth/overview) with the [REST API](/dev/api-reference/overview) or [`@custral/sdk`](/dev/sdks/typescript) instead. Those are org-scoped, server-to-server credentials.
</Info>

## Install

```bash theme={null}
npm install -g @custral/cli
```

## Sign in

```bash theme={null}
custral login
```

This opens the [RFC 8628](https://datatracker.ietf.org/doc/html/rfc8628) **device flow**: the CLI prints a short code and a URL, you approve it in your browser (where you're already signed in), and the session is saved to `~/.custral/config.json` (`0600`).

<Steps>
  <Step title="Run `custral login`">
    The CLI requests a device code and prints a verification URL + short code.
  </Step>

  <Step title="Approve in the browser">
    Open the URL, enter the code, and confirm. No password is ever typed into the terminal.
  </Step>

  <Step title="Session saved">
    The minted session is written to `~/.custral/config.json`. Revoke it any time in **Settings → Sessions**.
  </Step>
</Steps>

## Commands

| Command                              | What it does                                                            |
| ------------------------------------ | ----------------------------------------------------------------------- |
| `custral login`                      | Sign in via your browser (device flow).                                 |
| `custral logout`                     | Sign out (clears the stored session).                                   |
| `custral whoami`                     | Show the signed-in account + current org.                               |
| `custral org list`                   | List your organizations.                                                |
| `custral org switch <slug>`          | Switch the current organization.                                        |
| `custral mcp`                        | Connect the Custral [MCP server](/dev/mcp/overview) to your MCP client. |
| `custral api <method> <path> [json]` | Make a raw authenticated request.                                       |

Switching orgs is instant and local. The session works for every org you belong to, so `org switch` just changes which one subsequent commands target.

```bash theme={null}
custral org switch pied
custral api GET organizations
custral api POST records/paginate '{"objectId":"obj_123","limit":10}'
```

## Connect to MCP

`custral mcp` wires Custral's [MCP server](/dev/mcp/overview) into your MCP client so an agent (Claude Code, Claude Desktop, Cursor, …) can search and manage your records and conversations. Because the MCP server is API-key authenticated, the command mints a scoped key on a "Custral CLI" application for you, then prints the endpoint and a paste-ready config for each client:

```bash theme={null}
custral mcp
```

For **Claude Code**, it prints a command you can run as-is; for **Claude Desktop / Cursor**, a JSON block to drop into your MCP config:

```bash theme={null}
claude mcp add --transport http custral https://api.custral.com/v1/mcp \
  --header "Authorization: Bearer sk_live_..."
```

The minted key carries read access plus the record + conversation **write** scopes (not `applications:manage` / `webhooks:manage`), so the agent can view and manage records and conversations, but can't provision more keys. The plaintext key is shown once. Manage or revoke it in **Settings → Applications**. Already have a key? Skip the minting:

```bash theme={null}
custral mcp --key sk_live_...
```

See [MCP → Use it](/dev/mcp/overview#use-it) for example prompts once you're connected.

## Configuration

|                           |                                                                |
| ------------------------- | -------------------------------------------------------------- |
| Config file               | `~/.custral/config.json` (mode `0600`)                         |
| `CUSTRAL_API_URL`         | Override the API base (default `https://api.custral.com`)      |
| `CUSTRAL_NO_UPDATE_CHECK` | Set to any value to silence the "new version available" notice |

## Staying up to date

When a newer `@custral/cli` is published, the CLI prints a one-line upgrade notice
to **stderr** (so it never interferes with piping `custral api …` output):

```
★ @custral/cli@1.1.0 is now available.
To upgrade, run:
npm install -g @custral/cli
Proceeding with outdated version.
```

The check is cached (`~/.custral/update-check.json`) and the registry is polled at
most once a day in the background, so it never adds latency to a command, the
notice you see reflects the last check. Set `CUSTRAL_NO_UPDATE_CHECK` to turn it
off entirely.

## Auth model

The CLI signs in **as you** with `custral login`, the same way the web app does, and acts against whichever workspace you select. It is deliberately **not** an API-key client. See [Authentication](/dev/auth/overview) for when to use a session and when to use a key.

## Troubleshooting

<AccordionGroup>
  <Accordion title="`Could not start login. Check your connection or CUSTRAL_API_URL.`">
    The CLI couldn't reach the API to begin the device flow. Confirm you're online and that `CUSTRAL_API_URL` (if set) points at a reachable Custral API. It defaults to `https://api.custral.com`.
  </Accordion>

  <Accordion title="The code expired before it was approved">
    Device codes are short-lived. Run `custral login` again and approve promptly. If you keep missing the window, the URL printed after "or go straight to…" opens the approval screen with the code pre-filled.
  </Accordion>

  <Accordion title="`custral whoami` shows the wrong organization">
    The session spans every org you belong to; only the *current* one changes. Run `custral org list` to see your orgs, then `custral org switch <slug>`.
  </Accordion>

  <Accordion title="Commands fail with an auth error after a while">
    Your session may have been revoked (in **Settings → Sessions**) or expired. Run `custral logout` then `custral login` to mint a fresh one.
  </Accordion>
</AccordionGroup>


## Related topics

- [Authentication](/dev/auth/overview.md)
- [email.clicked](/dev/webhooks/events/email-clicked.md)
- [Developer Overview](/dev/overview.md)
- [Managing subscriptions](/dev/webhooks/managing.md)
- [Requests & responses](/dev/api-reference/requests.md)