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.

​
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 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:
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. 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>.
Your session may have been revoked (in Settings → Sessions) or expired. Run custral logout then custral login to mint a fresh one.