Skip to main content
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.
The CLI is you. For unattended / CI use, prefer an API key with the REST API or @custral/sdk instead. Those are org-scoped, server-to-server credentials.

Install

Sign in

This opens the RFC 8628 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).
1

Run custral login

The CLI requests a device code and prints a verification URL + short code.
2

Approve in the browser

Open the URL, enter the code, and confirm. No password is ever typed into the terminal.
3

Session saved

The minted session is written to ~/.custral/config.json. Revoke it any time in Settings → Sessions.

Commands

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.

What custral api can reach

Every path is sent under /v1, so applications and v1/applications both mean /v1/applications. Internal API routes are out of reach by design. The CLI holds your session, not an API key, and most of /v1 accepts only a key. So custral api works on the routes that also take a session: Anything else (records/…, objects, conversations, and so on) answers authorization_missing, because no key was sent. To call those, mint a key and use curl or the SDK:
custral api prints the data on success. On a failure it prints the error code and reqId, and exits with 1.

Connect to MCP

custral mcp wires Custral’s MCP server 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:
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:
The minted key carries seven scopes: mcp:read, mcp:write, objects:read, records:read, records:write, conversations:read and conversations:write. So the agent can read your schema and view and manage records and conversations. It can’t read documents, tasks, usage or billing, and it can’t provision keys or webhooks (no applications:manage / webhooks:manage). For a wider reach, create a key with the scopes you want and pass it with --key. The plaintext key is shown once. It’s minted under an application named Custral CLI, which later runs reuse, and you can revoke it in Settings → Developers → Applications. Already have a key? Skip the minting:
See MCP → Use it for example prompts once you’re connected.

Configuration

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):
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, which is why custral api reaches only the session-capable routes. See Authentication for when to use a session and when to use a key.

Troubleshooting

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.
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.
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>.
The path needs an API key, and the CLI sends your session. Only auth/…, organizations and applications/… take a session. For anything else, use a key with curl or the SDK, as shown under What custral api can reach.
There’s no session in ~/.custral/config.json. Run custral login.
The third argument isn’t JSON. Wrap it in single quotes so your shell leaves the double quotes alone.
Your session may have been revoked (in Settings → Sessions) or expired. Run custral logout then custral login to mint a fresh one.

Authentication

Sessions versus keys, and every scope.

MCP

The server custral mcp connects you to.

Applications & keys

The routes custral api can reach.

TypeScript SDK

Call the key-only routes from code.