Skip to content

CLI

The ritual CLI is the one-time setup tool for using Ritual from inside a coding agent. It signs you in via browser OAuth, mints a long-lived Personal Access Token, binds your project to a Ritual workspace, and scaffolds the /ritual skill into every coding agent it detects.

Supported agents: Claude Code, Cursor, Windsurf, Kiro, Gemini CLI, VS Code (Copilot), Codex.

AI coding agents — read this first

If you are an AI coding agent and a user asked you to “set up Ritual MCP,” “install Ritual,” “connect this project to Ritual,” or anything similar, follow this script verbatim. Do not ask the user about their project, their stack, or where to register the MCP server — ritual init handles all of that automatically.

1. Do not scaffold the user's app yet.

2. Install or upgrade the CLI:
     npm install -g @ritualai/cli

3. From the project root, run:
     ritual init

4. If `init` opens a browser for sign-in, tell the user to complete it.
   Brand-new users get a verification email — they must click the link.
   Keep the terminal open while they do. If the loopback times out,
   re-run `ritual init` once.

5. After `init` reports success, run:
     ritual doctor

6. Tell the user to fully close and reopen their coding agent so the
   newly-registered MCP server comes online. Reload / `/clear` is not
   enough — agents cache MCP config at startup.

7. Once the user is back in the agent, verify the `ritual` MCP server
   is connected (in Claude Code: `/mcp`). Only then offer to start
   product work — typically by running `/ritual build <feature>`.

Hard rules until ritual init succeeds:

  • Do not ask the user what kind of project they’re building.
  • Do not ask which stack to scaffold against.
  • Do not ask whether to register MCP project-local vs user-global — ritual init picks the right scope per agent.
  • Do not edit ~/.claude.json, .mcp.json, .cursor/mcp.json, or any other agent config file by hand.
  • Do not paste the URL of this page into a fetch tool and ask the user to read it for you — the script above is the canonical procedure.

The plain-text version of this script is also served at /llms.txt for agents that prefer a no-styling fetch target.

The detailed human-facing flow continues below.

Prerequisites

  • Node.js 20+ — node --version
  • A coding agent installed locally (one of the seven above)
  • A git repo — ritual init runs inside a project directory

Install

npm install -g @ritualai/cli

Puts the ritual binary on your PATH. Verify with:

ritual --version
# 0.7.5 (or newer)

If the version reports 0.5.0 you have a stale install — npm uninstall -g @ritualai/cli && npm install -g @ritualai/cli@latest.

Quickstart

cd ~/your-project
ritual init

ritual init walks you through:

  1. Browser sign-in. Opens your default browser to the Ritual Keycloak login. The CLI listens on a loopback port for the OAuth callback.
  2. PAT mint. A long-lived Personal Access Token is created in your account and saved to ~/.config/ritual/credentials.json (0o600 permissions, owner-only).
  3. Workspace bind. Auto-suggests a workspace name from your git remote get-url origin (or the cwd basename). Y/n/custom-name prompt. Writes .ritual/config.json to the project — safe to commit.
  4. Skill scaffolding. Detects every supported coding agent on this machine, copies the /ritual skill into each one’s expected location, and registers the MCP server config (Bearer-authed against your fresh PAT).

Then restart your coding agent so it picks up the new skill, and run /ritual build <feature> from inside.

Welcome banner

On a fresh install you’ll see a Claude Code-style welcome box (0.7.5+):

╭─── Ritual CLI v0.7.5 ────────────────────────────────────────────────────────╮
│                                          │ What this will do                 │
│           Welcome to Ritual!             │   1. Sign you in (browser OAuth)  │
│                                          │   2. Bind a workspace for repo    │
│                  ╭─────╮                 │   3. Mint a long-lived MCP key    │
│                 │  ╭──┼──╮               │   4. Wire your AI coding agent    │
│                 │  │  │  │               │                                   │
│                 ╰──┼──╯  │               │ Quick commands                    │
│                    ╰─────╯               │   /ritual build <feature>         │
│                                          │   ritual graph status             │
│        Plan and ship without             │   ritual doctor                   │
│        surprise context                  │   ritual init --switch-account    │
│                                          │                                   │
│        ~/Development/your-project        │                                   │
╰──────────────────────────────────────────┴───────────────────────────────────╯

Returning users see the same box but greet-by-identity (Welcome back, you@example.com) and a recent-activity panel on the right.

Commands

CommandWhat it does
ritual initFirst-time setup. Sign in, mint PAT, bind workspace, scaffold skills, register MCP. Idempotent — safe to re-run anytime to refresh.
ritual init --switch-accountForce a fresh sign-in even if local creds are still valid. Uses OIDC prompt=login so Keycloak’s SSO cookie is ignored. Atomic — your previous session is restored on failure.
ritual init --agent <id>Restrict to one agent. IDs: claude-code, cursor, windsurf, kiro, gemini, vscode, codex.
ritual loginBrowser sign-in only. Useful if you cleared creds but the workspace binding and skills are still in place.
ritual logoutClear local credentials. Browser SSO session is untouched.
ritual logout --allAlso end the Keycloak browser session via OIDC RP-initiated logout. Cleanest sign-out.
ritual whoamiShow the current signed-in identity + token expiry.
ritual refreshRe-scaffold the bundled skill version after upgrading the CLI. Restart your agent after.
ritual doctorDiagnose credentials, MCP endpoint reachability, agent detection. First-line tool when something’s wrong.
ritual graph statusShow the workspace KG — implementations, decisions, deferrals, recent syncs.

Switching accounts

If you have multiple Ritual accounts (work vs personal, testing a different tenant):

ritual init --switch-account

The CLI backs up your existing ~/.config/ritual/credentials.json to a timestamped file, opens Keycloak with prompt=login (forces the sign-in form even if SSO says you’re already logged in), and on success replaces the backup. On any failure the backup is restored — you can’t end up credential-less from a failed switch.

Restart your coding agent

Every agent caches its skill list at startup. After ritual init finishes:

AgentRestart how
Claude CodeQuit & reopen — type / and ritual appears
CursorCmd+Q & reopen — ⌘L → / → select ritual
WindsurfQuit & reopen — open chat, type /
KiroRestart Kiro — /ritual shows in the skills palette
Gemini CLIOpen a new gemini session — /ritual autocompletes
VS Code (Copilot)Reload window — ⌘⇧P → Developer: Reload Window
CodexRestart codex — /ritual is registered

What gets written to disk

PathContents
~/.config/ritual/credentials.jsonYour PAT and signed-in account. Per-machine. Never commit. 0o600 perms.
.ritual/config.json (in repo)Workspace binding for this project. Safe to commit — no secrets.
<agent>/skills/ritual/SKILL.md (per agent, in repo)The /ritual skill copied into each detected agent’s expected location. Safe to commit.
Agent MCP config (e.g. ~/.claude.json)One ritual server entry registering mcp.ritualapp.cloud/mcp with your PAT as Bearer. Per-machine.