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.

Publish services to your customers

show prints the address your customers add to their AI clients and the callback URL your provider must allow. sign-in set defines the whole provider: scopes default to openid,email,profile and the auth method to client_secret_basic.

Read the publishing guide →

rayrun publications create acme-issues --name 'Acme issues' --services <connection-id>
printf %s "$OIDC_CLIENT_SECRET" | \
  rayrun publications sign-in set <publication-uid> \
  --issuer https://login.example.com --client-id rayrun-acme-issues --client-secret-stdin
rayrun publications publish <publication-uid> --reason 'Launch'
rayrun publications show <publication-uid>
rayrun publications end-users <publication-uid>
rayrun publications approvals <publication-uid>
rayrun publications domain set <publication-uid> mcp.example.com
rayrun publications domain check <publication-uid>

Settings, sign-in provider changes, and restores create attributed configuration versions; history, diff, and restore work as they do for connections. domain set prints the TXT and CNAME records to create. CI keys need publications:write, which the Manage publications preset holds.

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.

Version and roll out access policies

Run rayrun login as a workspace administrator, or use a scoped CI API key. Export, plan, and review require policies:read; mutations require policies:write. Creation starts with block-all. Commit exported JSON for review: it contains the workspace, profile, live expectedVersion, and complete name, description, default mode, and tool rules.

rayrun policy create --name "Support"
rayrun policy export <profile-uid> --output support.json
# Edit support.json, then validate the proposed configuration.
rayrun policy plan --file support.json
rayrun policy draft --file support.json --draft-revision 0 --reason "Support rollout"
rayrun policy review <profile-uid> <draft-uid>
rayrun policy activate <profile-uid> <draft-uid> --reason "Reviewed rollout"
rayrun policy drafts <profile-uid>
rayrun policy history <profile-uid>

Draft revision and live expectedVersion are separate concurrency guards. The first draft expects --draft-revision 0; later saves require the newest draft revision from policy drafts. Saving leaves live access unchanged. Review compares an exact immutable draft; it is not an approval record and does not require a second person.

Activation revalidates current tools and the saved live expectedVersion before applying the exact draft. A stale version requires a fresh export and reviewed draft. High-risk grants require --confirm-risk. Drafts use --before-revision pagination; live history uses --cursor. Both remain readable after archival.

Apply a reviewed policy document

For a reviewed document without a server-side draft, run rayrun policy apply --file support.json --reason "Reviewed in PR 42" after policy plan. Apply atomically replaces the complete configuration; omitted tool rules revert to the profile default. Identical current configurations create no history entry.

The API and @rayrun/sdk expose the same access-profile lifecycle. Client assignments and content-scanning configuration are outside the policy document. Rayrun has no Terraform provider.

Clone, deactivate, or archive a policy

Run rayrun policy clone <profile-uid> --name "Support trial" --expected-version <live-version> to create an unassigned block-all profile with the source configuration as its first draft. Assignments, owners, and budgets are not copied.

Run rayrun policy deactivate <profile-uid> --expected-version <live-version> to set block-all and clear every exception while retaining assignments. Restore historical configuration or activate a fresh draft to resume access.

Run rayrun policy archive <profile-uid> --expected-version <live-version> to retire an unused profile. Archive refuses profiles assigned to clients or Skills.

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 →

Crash reporting and opt-out

Failed commands send an error report so that real-world failures get fixed. A report carries the error message and stack trace, the exit code, the name of the command that ran, and the CLI, Node.js, and operating system versions.

export RAYRUN_TELEMETRY=0
# or
export DO_NOT_TRACK=1

Credentials are removed before a report is sent: bearer tokens, API keys, OAuth codes, client secrets, and JWTs are redacted, and your home directory path becomes ~.

The command name can only be one the CLI publishes in its own help output, so connections credential <connection-id> reports as connections credential. Options, their values, positional arguments, endpoint URLs, and tool arguments are never collected.

Set RAYRUN_TELEMETRY=0 or DO_NOT_TRACK=1 to opt out. RAYRUN_TELEMETRY wins, so RAYRUN_TELEMETRY=1 opts back in where DO_NOT_TRACK is set globally. Point RAYRUN_SENTRY_DSN at your own Sentry project to keep reports in-house.