@ritualai/cli

The Ritual CLI. Connects your AI coding agent (Claude Code, Cursor, Codex, Kiro, Gemini CLI, Windsurf, etc.) to Ritual Cloud via the Model Context Protocol.

Docs: ritual.work/ritual-mcp/docs/

AI coding agents: start here

If you are an AI coding agent and a user asked you to "set up Ritual MCP," "install 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.

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. If they are a brand-new user, they will 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 — the agent caches 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 automatically.
• Do not edit ~/.claude.json, .mcp.json, .cursor/mcp.json, or any other agent config file by hand.
• Do not paste docs URLs into a fetch tool and ask the user to read the rendered marketing site — the bootstrap script above is the authoritative source.

Only escape hatch: if the user explicitly declines Ritual setup, or if ritual init fails twice in a row with the same error, ask the user how they'd like to proceed. Don't surface the escape hatch unsolicited.

Install

npm install -g @ritualai/cli

Quick start

ritual init           # scaffold skills + register MCP for every detected agent
                      # (prompts to open browser for sign-in on first run)
ritual doctor         # sanity-check the environment

That's it — one command. On first run, init detects you're not signed in and prompts:

  You are not signed in.

  We'll open your browser for sign-in. A few notes before you continue:
    • If this is a brand-new account, you'll be asked to verify your
      email. KEEP THIS TERMINAL OPEN while you check your inbox — closing it
      drops the loopback listener and you'll have to re-run `ritual init`.
    • If you already have an account, sign in as usual — you'll bounce back
      here automatically.
    • The sign-in window is 5 minutes. If you exceed it, just re-run
      `ritual init` and we'll pick up from this prompt.

  Press Enter to open the browser, or Ctrl-C to abort:

Hit Enter, complete the browser OAuth flow, and init resumes automatically. Subsequent init runs skip the prompt (credentials are cached and refreshed automatically).

init does five things:

1. Signs you in if you aren't already (browser OAuth, npm-style "press Enter to open browser" prompt). Skipped if already signed in.
2. Detects which AI coding agents are actually installed and configurable on this machine. "Detected" means real local evidence (a populated config dir, the claude binary on PATH, etc.) — not just "Ritual supports this agent in theory." Output cleanly separates what was detected from what's supported-but-absent. If multiple agents are detected, init prints the full list of config files it's about to touch and pauses for a single Enter — abort and re-run with --agent <id> to scope to one.
3. Mints a long-lived Personal Access Token via the Ritual API named Ritual CLI — <hostname>, so the agent has a credential that doesn't expire every 5 minutes the way OAuth tokens do.
4. Binds a project workspace. If .ritual/config.json doesn't exist, suggests creating one named after your repo (git remote get-url origin → fall back to cwd basename). Y/n/custom-name prompt. Writes the binding to .ritual/config.json so future tool calls default to this workspace. Commit that file — your team uses the same workspace. Pass --no-workspace to skip.
5. For each detected agent: copies the Ritual skill files into your project (.claude/skills/, .cursor/rules/, etc.) AND writes the MCP server config (claude mcp add-json for Claude Code, or mcp.json merge for the others) with the PAT as the Bearer.

After ritual init — close and reopen your agent

The CLI registers the MCP server, but every agent caches its MCP config at startup. You must fully close and reopen the agent for the ritual server to come online. Reloading the window or running /clear is usually NOT enough — kill the process and start a fresh one.

After restarting, verify the registration landed:

| Agent | How to verify | |---|---| | Claude Code | claude mcp list from any terminal — ritual should appear, status ● (green). Or /mcp inside Claude Code. | | Cursor | Settings → MCP → look for ritual server with a green toggle. Or cat ~/.cursor/mcp.json and confirm mcpServers.ritual is present. | | Windsurf | Settings → Plugins / MCP → look for ritual. Or cat ~/.codeium/windsurf/mcp_config.json. | | Kiro | Settings → MCP Servers → confirm ritual is listed. Or cat ~/.kiro/mcp.json. | | Gemini CLI | cat ~/.gemini/mcp.json — mcpServers.ritual should be present. (Gemini's mcp list subcommand isn't available in every build yet.) | | VS Code (Copilot) | Open the Copilot Chat panel → click the MCP icon → confirm ritual is listed and enabled. Or cat ~/.vscode/mcp.json — note the top-level key is servers, not mcpServers. | | Codex | cat ~/.codex/mcp.json and confirm mcpServers.ritual is present. |

If ritual is missing from your agent, run ritual doctor to see which agents were detected and which got the MCP registration. Common causes: agent installed in a non-standard location, or the agent was running during init and cached the old config (close + reopen).

Once you see ritual registered, try /ritual build <feature> inside the agent. The CLI is now out of the way — everything happens via the agent's MCP client talking to Ritual Cloud.

Commands

ritual init [--agent <id>] [--list]   # scaffold + register (signs in if needed)
ritual init --switch-account          # force a fresh sign-in as a different account
ritual login                          # explicit browser sign-in
ritual login --switch-account         # same switch behavior, without the full init flow
ritual logout                         # clear local creds
ritual logout --all                   # also end the Keycloak browser SSO session
ritual whoami                         # session info, auto-refresh
ritual refresh                        # force token refresh
ritual doctor                         # env + detection report

The agent ids are: claude-code, cursor, windsurf, kiro, gemini, vscode, codex. Use --agent <id> if you want to scaffold for a specific one without auto-detecting (handy when you've got the agent installed somewhere non-standard).

Switching accounts

Most users have one Ritual account and never think about this. If you need to switch (work vs personal, testing a different tenant, etc.):

ritual init --switch-account

This is atomic — your existing local credentials are backed up, the browser is opened with OIDC prompt=login (so Keycloak shows its sign-in form even if its SSO cookie says you're already signed in as someone else), and on any failure your previous session is restored. No incognito window needed.

In CI / non-interactive use, pass --yes to bypass the confirmation:

ritual init --switch-account --yes

To also end your Keycloak browser SSO session (so the next sign-in from anywhere on this machine shows the sign-in form):

ritual logout --all

This does NOT revoke minted Personal Access Tokens, agent MCP registrations, or refresh tokens cached server-side — manage those separately at the URL logout --all prints.

How refresh works

Keycloak issues a short-lived access token (~5 min by default) and a longer-lived refresh token (~30 min). The CLI handles this transparently:

• ritual whoami and any future Bearer-using command call getValidAccessToken() internally. If the cached access token is still fresh (>30s of life left), they use it as-is. If it's expired but the refresh token is still good, they exchange it for a new access token and persist the result before continuing.
• If the refresh token is also expired/revoked (Keycloak returns 400 invalid_grant), you'll see a clear "session expired, run ritual login" message — not a confusing 401 from the API.
• ritual refresh exposes the refresh path explicitly for scripts and debugging. Most users never need to run it directly.

Refresh-token rotation (Keycloak's default) means the stored refresh token changes on every successful refresh — the CLI persists the new one automatically.

How sign-in works

1. CLI binds a one-shot HTTP server on a random localhost port.
2. CLI opens your browser to the Ritual identity provider (Keycloak).
3. You authenticate (or use SSO if your org has it configured).
4. Keycloak redirects back to http://127.0.0.1:<port>/callback with an authorization code.
5. CLI exchanges the code at the token endpoint using PKCE proof.
6. Tokens are stored at ~/.config/ritual/credentials.json (chmod 0600).

This is the standard RFC 8252 loopback pattern — no shared secret, no manual API key copy-paste.

Override defaults

The CLI points at Ritual Cloud by default. To point it at a different Ritual deployment (a self-hosted instance, an enterprise tenant, or a staging environment), set environment variables:

export RITUAL_KEYCLOAK_URL=https://<your-keycloak-host>/realms/<realm>
export RITUAL_API_URL=https://<your-api-host>
ritual login

Or pass --issuer to ritual login for a one-off override:

ritual login --issuer https://<your-keycloak-host>/realms/<realm>

ritual doctor prints the effective endpoints so you can confirm the override took.

Security notes

• The credentials file is chmod 0600 (owner-only). On shared machines this is your only protection — don't chmod 644 ~/.config/ritual.
• The CLI never sends your credentials anywhere except to Keycloak's token endpoint over TLS.
• The ritual-cli Keycloak client is a public OAuth client (no client secret). PKCE is what makes this safe — only the CLI process that generated the verifier can exchange the code.

License

Apache-2.0. See LICENSE for the full text.