CLI

Choose the right authentication

Run rayrun login before interactive execution, deployment, or management. It opens one browser approval and stores one rotating login. Members receive a Direct Mode token; workspace administrators also receive a separate control-plane token. rayrun auth status remains a compatibility alias.

npx --yes rayrun@latest login
npx --yes rayrun@latest status
npx --yes rayrun@latest doctor
npx --yes rayrun@latest status --json

• rayrun status verifies Direct Mode and control-plane credentials and reports identity, workspace, scopes, endpoints, and the project target.
• rayrun doctor presents the same facts as health checks. A narrowly scoped CI key can inspect its own identity.
• Set RAYRUN_API_KEY for CI management commands. Configured MCP clients keep their own OAuth credentials.

setup --login is not an alias for rayrun login: it runs supported MCP client login commands. For Codex, that is codex mcp login rayrun --scopes mcp:tools. A successful client login does not populate Rayrun CLI credentials.

Discover and automate commands

Use command help for syntax, completion for shell scripts, and schema for the complete machine-readable command contract.

rayrun --help
rayrun deployments --help
rayrun help deployments rollback
rayrun completion zsh
rayrun schema > rayrun-command-schema.json
rayrun connections list --json --paginate --fields displayName,uid

• Use --no-input to block prompts and browser launches, --quiet to hide progress, and --debug for failure diagnostics.
• Use --paginate to follow every list page. Combine --fields with --json to select fields from every returned item.
• With --json, success stays on stdout and structured failures go only to stderr. Exit codes distinguish command failure (1), usage (2), authentication (3), authorization (4), conflicts (5), and retryable service failures (6).

Deploy a source project

rayrun init creates a TypeScript and ViteMCP project; pass --template fastmcp for Python. It writes a stable source-project UUID to rayrun.json; you must commit that file. .rayrun/project.json caches only the current workspace and connection.

npx --yes rayrun@latest init my-mcp
cd my-mcp
npm test
npx --yes rayrun@latest login
npx --yes rayrun@latest deploy --wait
npx --yes rayrun@latest project status
npx --yes rayrun@latest deployments get <build-uid>
npx --yes rayrun@latest deployments logs <build-uid>
npx --yes rayrun@latest deployments rollback <connection-id> <release-uid> --wait

• Use browser OAuth interactively. For CI, export a Deploy services preset key as RAYRUN_API_KEY; never pass or commit the key.
• --wait streams progress to stderr and leaves the final human or JSON result on stdout. It prints the build UID and exact deployments get resume command before polling.
• Use deployments list, get, logs, and releases for inspection. Rollback creates a new release from an older verified build.
• Use project status to restore ignored workspace state on a new checkout. Use project adopt <connection-id> only to associate an unclaimed committed project ID with a known deployment.
• Bind declared secrets with --secret NAME=<workspace-secret-uid>. Build logs additionally require deployments:logs:read.

A clean checkout or retry after a lost response uses the committed project ID to recover the same service and identical queued or active build. Rayrun never silently replaces a known project association.

Deploy on push from GitHub

The first command opens the Rayrun GitHub App to grant repository access, deploys the configured branch, and records the repository UID. Every later push to that branch enters the normal source build and verified-release pipeline.

rayrun login
rayrun deploy github rayrun/hacker-news-mcp --wait

# Inspect installation and the latest signed delivery:
rayrun deployments github <repository-uid>

Same-repository pull requests receive isolated preview services by default. Pass --no-previews to disable them. Fork pull requests are ignored because preview builds may use workspace secrets.

Use --root for a monorepo directory, --branch to override the default branch, --no-open to print rather than launch the installation URL, and --wait to follow the first build through activation.

Execute and resume tools

Run rayrun login, then call service-qualified tool names through the default https://ray.run/mcp/direct endpoint. Override it with RAYRUN_MCP_URL or --endpoint for local or self-hosted gateways.

npx --yes rayrun@latest login
npx --yes rayrun@latest tools describe linear.create_issue
npx --yes rayrun@latest call linear.create_issue '{"title":"Fix the release"}'

# After approving a paused exact call in the browser:
npx --yes rayrun@latest resume --execution-id <execution-id>

• Pass arguments as inline JSON, --input <file>, or stdin with --input -. Add --json for machine-readable output.
• Approval or authorization pauses store the exact call and continuation, open the authenticated page, and print a resume command. Only that page can authorize the call.
• Resume within 10 minutes. The next execution command removes expired continuation files.
• ~/.rayrun/execution stores pending arguments and OAuth refresh tokens. POSIX enforces 0700 directories and 0600 files; Windows inherits current-profile ACLs. rayrun logout removes them and attempts revocation.

Authenticate management commands

Browser OAuth is the default for interactive management. Create a scoped key in Dashboard → Settings → API keys only for CI or unattended automation. RAYRUN_API_URL is optional and defaults to https://ray.run.

npx --yes rayrun@latest login
npx --yes rayrun@latest connections list

Management commands call the hosted public API and SDK. They do not start a local gateway or implement a second policy engine.

Connect services

Connect remote MCP servers by HTTPS URL, or import an OpenAPI specification. Update static credentials through JSON stdin, complete OAuth in the browser, re-index, enable or disable, and explicitly confirm deletion.

npx --yes rayrun@latest connect mcp https://mcp.example.com \
  --name 'Internal tools'

npx --yes rayrun@latest connect openapi https://api.example.com/openapi.json \
  --name 'Example API'

printf %s "$CONNECTION_CREDENTIAL_JSON" | \
  npx --yes rayrun@latest connections credential <connection-id> --stdin
npx --yes rayrun@latest connections authorize <connection-id>
npx --yes rayrun@latest connections index <connection-id>
npx --yes rayrun@latest connections disable <connection-id>
npx --yes rayrun@latest connections delete <connection-id> --confirm <connection-id>

Use --transport sse for an MCP server that requires legacy SSE; streamable-http is the default.

Manage Workspace Skills

Validate a local directory before upload, push it as a draft, and add --publish only when the automation is intended to make that revision live. Choose the first audience with --profiles and comma-separated access-profile UIDs, or --all-clients. Later changes preserve the audience unless either flag is supplied.

rayrun skills validate ./skills/incident-response
rayrun skills push ./skills/incident-response --publish \
  --mode both --all-clients --reason 'Reviewed for production use'
rayrun skills list
rayrun skills history <skill-uid>
rayrun skills diff <skill-uid> <version-uid>
rayrun skills pull <skill-uid> --output ./recovered-skill

Pull refuses to overwrite an existing path and never follows package symlinks. Restore copies an immutable historical revision into a new draft; publish it separately after review.

Compare and restore connection configuration

Every material change to a connection name, slug, description, timeout, enablement, or payload-capture preference creates one immutable, attributed configuration version. Credentials, headers, OAuth state, identity and tool policy, health, and index state never enter the snapshot.

npx --yes rayrun@latest connections history <connection-id>
npx --yes rayrun@latest connections diff <connection-id> <version-uid>
npx --yes rayrun@latest connections restore <connection-id> <version-uid>   --reason 'Restore reviewed settings'

History is cursor-paginated. Diff compares a selected version with its immediate predecessor. Restore copies it into a new version and uses optimistic concurrency, so a connection changed after inspection must be fetched and reviewed again.

Search and inspect

Search indexed tool names and descriptions, optionally within one connection. Policy inspection shows the live intersection of workspace, access-profile, and client rules and names the layer that restricted each result.

npx --yes rayrun@latest clients list
npx --yes rayrun@latest tools search create issue --connection <connection-id>
npx --yes rayrun@latest policy inspect <client-uid> --query issue
npx --yes rayrun@latest approvals list
npx --yes rayrun@latest activity list

Approvals and activity expose the same operational state as the dashboard. Add --json for machine-readable output. Add --limit up to 100 and pass the printed value back with --cursor, or use --paginate to follow every page. Combine --fields with --json to select fields from every returned item.

Author hosted tool hooks

Pull writes the editable TypeScript source and optional generated declaration file. Test compiles the same source and runs it with supplied arguments and an optional mock upstream result without making a live upstream call.

npx --yes rayrun@latest hooks pull <connection-id> <tool-uid>   --output hook.ts --types-output rayrun-hooks.d.ts

npx --yes rayrun@latest hooks test <connection-id> <tool-uid>   --file hook.ts --arguments '{"query":"release"}' --mock-result '{"items":[]}'

npx --yes rayrun@latest hooks save <connection-id> <tool-uid>   --file hook.ts --reason 'Normalize release results'

npx --yes rayrun@latest hooks history <connection-id> <tool-uid>
npx --yes rayrun@latest hooks diff <connection-id> <tool-uid> <draft-version-uid>
npx --yes rayrun@latest hooks restore <connection-id> <tool-uid> <draft-version-uid>   --reason 'Restore the reviewed mapping'

npx --yes rayrun@latest hooks deploy <connection-id> <tool-uid> --shadow

npx --yes rayrun@latest hooks logs <connection-id> <tool-uid>

Save creates an immutable, attributed draft version when source or non-secret config changes. History is cursor-paginated, diff compares a version with its predecessor, and restore copies a version into a new editable head.

Draft versions remain separate from compiled deployment revisions. Use hooks rollback to move a deployment pointer, hooks deactivate to remove it, and hooks logs to inspect retained outcomes.

Set up MCP clients

MCP client installation, preview, project scope, login, rollback, and automation now live in MCP clients.

Open MCP client setup →