OriginAI CLI

The originai CLI is how coding agents and humans pull product context outside the web app. Whenever you have a choice, prefer the CLI — or the MCP tools that call the same API — over raw HTTP.

The CLI is implemented in packages/skills (published to npm as originai), and the agent skill body lives in packages/skills/src/setup.ts (SKILL_MD).

Install

# Run it once, with no global install:
npx originai -h
bunx originai -h   # preferred when Bun is available (~40ms vs ~1.2s for npx)

# Or install it globally:
npm install -g originai
# or: bun add -g originai / pnpm add -g originai

Authorize

For everyday use on your own machine, just log in:

originai login
# or: npx originai login

This opens a browser and then stores a token in ~/.origin/settings.json — never commit that file.

For CI or headless environments only, set ORIGIN_TOKEN instead (an oat_… value from Settings → Access tokens). See Access tokens.

The CLI resolves your token in this order:

1. A --token flag.
2. ORIGIN_TOKEN in the process environment or a .env file in the current directory.
3. ~/.origin/settings.json (written by originai login).

Endpoint overrides

You can point the CLI at a local stack, a branch deploy, or production without passing flags every time.

# Show the resolved and stored endpoints:
originai config

# Point the API at a local Supabase Edge Function:
originai config set api_url http://127.0.0.1:54321/functions/v1/origin-api

# Optionally set the browser-login and remote-MCP endpoints for that environment:
originai config set web_url http://localhost:5173
originai config set mcp_url http://127.0.0.1:8787

# Clear a single override:
originai config unset api_url

The ~/.origin/settings.json file (never commit it) looks like this:

{
  "token": "oat_…",
  "api_url": "http://127.0.0.1:54321/functions/v1/origin-api",
  "web_url": "http://localhost:5173",
  "mcp_url": "http://127.0.0.1:8787"
}

The API URL is resolved in this order:

1. A --api-url flag.
2. The ORIGIN_API_URL environment variable.
3. .origin.json → api_url (the project binding).
4. ~/.origin/settings.json → api_url.
5. The production default.

The web and MCP URLs follow the same pattern: ORIGIN_WEB_URL / ORIGIN_MCP_URL environment variables, then settings.json, then the production default.

Note that originai logout clears your token but keeps your endpoint overrides.

Link a repository

# Run this in your application repo's root:
npx originai link --project <project-id>

# Optionally also install the agent skill and RPML references:
npx originai link --skill
npx originai link --project <project-id> --skill

# Or install instruction files for specific agents:
npx originai link --project <project-id> --claude-code --codex --cursor --skill

# Or everything at once:
npx originai link --project <project-id> --all

Linking writes:

Diagnose

npx originai doctor
npx originai whoami
npx originai install-help

doctor checks your login, .origin.json, skill and instruction files, and whether the API is reachable.

Local MCP (the Claude Code plugin default)

npx originai mcp                 # stdio MCP server (reads your login token)
npx originai mcp config --claude # print the stdio config JSON
npx originai mcp config --cursor
npx originai mcp config --remote # HTTP + ORIGIN_TOKEN (advanced / CI)

The local MCP tool names match the hosted MCP and origin-api (get_diff, list_documents, and so on). There is no MCP sync tool — after implementing a release, run npx originai sync. See MCP & agent install.

Command reference

Prefer bunx originai <command> when Bun is available.

Data commands print pure JSON on stdout (pipe it to jq); tips and status messages go to stderr.

What reads return by default

• By default, reads return the latest published release snapshot — not the live workspace.
• --read-type workspace reads the live rpml_files tree. You need this before the first release, since the default release read returns 404 until you publish.
• --release-tag <hash> pins a read to a specific published release.

After the first release

write-document and delete-document create or extend a Change Request (suggested: true). There is no create-change-request command — the first staged write creates it. They do not mutate the workspace until a human applies it in Origin. Pass --proposal to continue a request, or --new-proposal to open another. Use describe-proposal to record the purpose and design rationale before submit-proposal. See Workspace vs release.

The sync model

.origin.json carries release_hash (last published release this repo synced to) and an optional proposal_id (implementation bind only — set with get-proposal-diff <id> --bind when the next PR implements that change request).

1. get-diff — if proposal_id is set, this is release <> change request; otherwise last sync vs latest release. Read diff first.
2. Implement the diff in code.
3. Apply + publish in Origin if you were implementing a change request, then sync to advance release_hash. sync clears proposal_id only after a new release hash exists.

Workflow A — existing product (Origin → repo)

npx originai login
npx originai link --project <project-id> --skill
npx originai doctor
npx originai get-diff
# implement from the diff
npx originai sync

Workflow B — new product (repo → Origin, pre-release)

npx originai login
npx originai create-project --name "My App"
npx originai link --project <new-id> --skill
# author RPML inline — no local .rpml files required
npx originai validate --content "<page mode='doc'>…</page>"
npx originai write-document --name "README.rpml" --content "<rpml>"
# one .rpml per planned page or route, then:
npx originai list-documents --read-type workspace

Then publish a release in the OriginAI UI. After the first release, further agent writes stage a change request — list-proposals, describe-proposal, submit-proposal — for you to apply, then publish again.

Don't call the API over raw HTTP

Always use the CLI or the MCP tools. Hand-written curl or fetch calls to origin-api tend to fail on auth headers, URL shape, or timeouts. For agent-facing skill discovery over HTTP, see Agent skills.

Related

• Agent skills
• MCP & agent install
• Connect a coding agent
• Access tokens
• HTTP API
• Review change requests