Reference

CLI reference

The cran binary logs you in once (that login is the MCP connection and works in every repo on your default project) and, optionally, mints a connection key to route an app's live traffic. Use this to manage projects or understand what each file on disk means.

Install

bash

npm i -g cran-cli
cran --version

Two kinds of credentials

Credential	Created by	Stored in	Used for
User CLI session token	cran login	~/.cran/session.json	the MCP connection - scan, audit, manage, projects (default project, any repo)
Connection key (optional)	cran link	.env → OPENAI_API_KEY	routing your app's live traffic, cran dev, production proxy

One login per machine- the session file is shared across all repos, and that login is the MCP connection. “Use cran” then works in any repo against your default project, with no per-repo link or token.
Linking is optional, one key per repo - run cran linkonly to route an app’s live traffic; each tree then gets its own project binding and connection key.
Never commit .env; committing .cran/config.toml is fine (no secrets).

Which project am I on?

By default - including over MCP - you’re on your account’s default project; switch with the cran_use_project tool or cran link. If a repo has been linked for live-traffic routing, .cran/config.toml in the repo root (or nearest parent) pins that repo to a project - the CLI walks up from your cwd, like git.

toml

# .cran/config.toml - written by cran link, safe to commit
project_id = "proj_abc123"
project_slug = "my-saas-app"
api_base = "https://trycran.in"

bash

cran whoami        # session + linked project (if any)
cran status        # project, token tail, Connected check
cran open          # dashboard for this project, or your account

Connect, then optionally link for routing

bash

# connect once (the MCP connection) - works in every repo
cran login
cran mcp install cursor      # then "use cran" anywhere

# OPTIONAL: route this app's live traffic through the proxy
cran link --project "My App"
cran init && cran dev

# link an existing project by id (routing)
cran projects list
cran link --project-id proj_abc123

Files on disk

Path	Commit?	Role
~/.cran/session.json	No	User CLI session token (login) - the MCP connection
.cran/config.toml	Yes	project_id, slug, api_base (only if linked for routing)
.env	Never	OPENAI_API_KEY, OPENAI_BASE_URL, CRAN_PROJECT_ID (only if linked for routing)
.env.example	Yes	Template from cran init

Command reference

cran login

Browser device code → writes ~/.cran/session.json. This is the MCP connection. Sign in on the dashboard first if you're new.

cran logout

Remove the local session.

cran whoami

API base, token suffix, and the linked project (if this repo has one) from the cwd.

cran projects list

Project id and name for your account.

cran link [--project NAME] [--project-id ID]

OPTIONAL (live-traffic routing): mint a connection key; write .cran/config.toml and .env. Not needed for MCP, scan, or audit.

cran init

.gitignore .env, write .env.example and a config template.

cran status

Linked project (if any) + connection + a GET /api/connect Connected probe.

cran dev

Smoke-test POST /api/v1/chat/completions with model: auto (needs a connection key).

cran open

Open the dashboard for the linked project, or your account.

cran mcp install <cursor|claude|windsurf|codex>

Write IDE MCP config (requires login). Restart the IDE after. This is all you need to use Cran from your IDE.

cran mcp run

stdio MCP server using your account session (CRAN_API_KEY); targets your default project.

Troubleshooting

Not logged in / MCP not connecting - run cran login, then restart the IDE. That login is the MCP connection; no link required.
Wrong project over MCP - switch with the cran_use_projecttool (defaults to your account’s default project).
No .cran/config.toml or missing OPENAI_API_KEY - only needed for live-traffic routing; run cran link from the repo root to create them.
Wrong npm package - use cran-cli.