@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/

Install

npm install -g @ritualai/cli

Quick start

ritual init           # scaffold skills + register MCP with 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.
  Press Enter to sign in (opens 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 you have installed (Claude Code, Cursor, Windsurf, Kiro, Gemini CLI, VS Code / Copilot, Codex).
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:

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 login                          # explicit browser sign-in
ritual logout                         # clear creds
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).

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.