Skip to content

CLI

The ritual CLI connects your coding agent to Ritual in one command. It signs you in, binds your repo to a workspace, and wires the /ritual skill plus the Ritual MCP server into every agent it detects.

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

Install

npm install -g @ritualai/cli

Requires Node.js 20+. Verify, and upgrade anytime:

ritual --version                      # 0.25.0 or newer
npm install -g @ritualai/cli@latest   # upgrade

Set up

From your project root:

cd ~/your-project
ritual init

That one command:

  1. Signs you in (browser OAuth)
  2. Mints a long-lived access token
  3. Binds this repo to a workspace (.ritual/config.json — safe to commit)
  4. Copies the /ritual skill and registers the MCP server into every agent it detects

Restart your coding agent

Agents cache their config at startup, so fully close and reopen yours — a window reload or /clear usually isn’t enough.

AgentVerify it landed
Claude Code/mcp, or claude mcp list → ritual ●
CursorSettings → MCP → ritual
WindsurfCascade → MCP icon → ritual
KiroMCP Servers panel → ritual
Gemini CLIcat ~/.gemini/mcp.json
VS Code (Copilot)Reload window, then Copilot Chat → MCP icon
Codex/mcp in the Codex TUI

If ritual is missing, run ritual doctor — it reports which agents were detected and configured.

Start building

You’re set up. Use it from inside your agent:

/ritual build <feature description>
  • Slash commands — build, resume, lineage, context-pulse
  • MCP server — the tools /ritual calls, and how to wire up your own client
  • Build stages — what each phase of /ritual build does

Commands

CommandWhat it does
ritual initSet up or refresh everything. Idempotent — safe to re-run.
ritual init --skills-onlyJust refresh the /ritual skill after a CLI upgrade.
ritual init --switch-accountSign in as a different account (atomic — old session restored on failure).
ritual doctorDiagnose credentials, MCP reachability, and agent detection.
ritual status [--watch]Show the current agentic run; --watch polls live.
ritual graph statusInspect the workspace knowledge graph.
ritual logout [--all]Clear local creds; --all also ends the browser SSO session.
ritual uninstall [--project]Reverse setup; --project also removes this repo’s Ritual files.

Run ritual <command> --help for the full flag list.

For AI coding agents

You don’t need to read this section — it’s the script your AI coding agent follows when you ask it to set up Ritual.

🤖 Agent instructions — machine-facing, not setup steps for humans

If a user asks you to “set up Ritual MCP,” “install Ritual,” or anything similar, follow this verbatim — ritual init handles project detection, auth, and MCP registration on its own. Don’t ask about their stack or hand-edit agent config files.

1. Don't scaffold the user's app yet.
2. Install or upgrade: npm install -g @ritualai/cli
3. From the project root: ritual init
4. If a browser opens, have the user complete sign-in. New users get a
   verification email — they must click it; keep the terminal open. If
   the loopback times out, re-run `ritual init` once.
5. After success: ritual doctor
6. Have the user fully close and reopen their agent (config is cached at
   startup; reload / `/clear` is not enough).
7. Verify the `ritual` MCP server is connected (Claude Code: `/mcp`),
   then offer `/ritual build <feature>`.

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