Package Exports

@ritualai/cli
@ritualai/cli/dist/index.js

This package does not declare an exports field, so the exports above have been automatically detected and optimized by JSPM instead. If any package subpath is missing, it is recommended to post an issue to the original package (@ritualai/cli) to support the "exports" field. If that is not possible, create a JSPM override to customize the exports field for this package.

Readme

`@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.

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:

Signs you in if you aren't already (browser OAuth, npm-style "press Enter to open browser" prompt). Skipped if already signed in.
Detects which AI coding agents you have installed (Claude Code, Cursor, Windsurf, Kiro, Gemini CLI, VS Code / Copilot, Codex).
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.
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.
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.

Restart your agent after init so it picks up the new MCP server, then try /ritual build <feature> from inside the agent.

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 (v0.2)

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.

CLI binds a one-shot HTTP server on a random localhost port.
CLI opens your browser to the Ritual identity provider (Keycloak).
You authenticate (or use SSO if your org has it configured).
Keycloak redirects back to http://127.0.0.1:<port>/callback with an authorization code.
CLI exchanges the code at the token endpoint using PKCE proof.
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

Defaults point at production. For dev, either:

ritual login --issuer https://auth.dev.ritualapp.cloud/realms/ritual

or set env vars:

export RITUAL_KEYCLOAK_URL=https://auth.dev.ritualapp.cloud/realms/ritual
ritual login

What's next

Per-agent skill format transforms (currently every agent gets the same SKILL.md; future versions emit Cursor .mdc, Kiro YAML, Gemini's specific frontmatter).
Workflow commands (ritual explore, ritual run, ritual brief) that wrap the MCP tools so you can drive Ritual from the terminal outside an agent session.

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.

@ritualai/cli