CLI commands

anyray-connect is the CLI a developer runs on their own machine. This page is the full command reference; Anyray Connect explains what a run actually changes.

Install it

The installer downloads a standalone binary to ~/.anyray/bin and runs it once with whatever flags you pass. No Node needed.

bash

macOS / Linux

curl -fsSL https://app.anyray.ai/connect.sh | sh -s

powershell

Windows PowerShell

& ([scriptblock]::Create((irm https://app.anyray.ai/connect.ps1)))

Everything after sh -s -- is passed straight to the CLI, so a first run usually installs and enrolls in one line:

bash

macOS / Linux

curl -fsSL https://app.anyray.ai/connect.sh | sh -s -- --enroll https://app.anyray.ai/enroll/enl_example --yes

powershell

Windows PowerShell

& ([scriptblock]::Create((irm https://app.anyray.ai/connect.ps1))) "--enroll" "https://app.anyray.ai/enroll/enl_example" --yes

The script verifies the download's SHA-256 checksum, installs to ~/.anyray/bin/anyray-connect (override with $ANYRAY_HOME), then hands off to the binary. In a real terminal it reconnects stdin to /dev/tty, so you still get the wizard and confirm prompts through the pipe. Where there's no terminal — CI, a sandbox, an MDM run — it can't prompt, so it appends --yes for you.

Running it

Once installed, anyray-connect is on your PATH and every command below is a direct call:

anyray-connect <command> [options]

The gateway URL is resolved in this order: the --gateway flag, then $ANYRAY_GATEWAY_URL, then the ~/.anyray cache, then http://localhost:8787. After your first run it's cached, so you rarely pass it again.

Run anyray-connect --help for the command list in your terminal, or <command> --help for one command's own flags.

Set up

Command	What it does
anyray-connect	Point your installed tools at the gateway. On a terminal it runs the wizard; in a script it uses your flags.
anyray-connect wizard	Force the guided setup, even when flags are present.
anyray-connect login	Sign in through browser SSO, pick a team, and mint your personal gateway key.
anyray-connect --enroll <link>	Enroll with a passwordless link from your admin. No browser sign-in.
anyray-connect --sso <link>	Enroll through your company IdP (Okta, Entra, Google Workspace, Ping).
anyray-connect --revert	Undo everything Connect wrote and clear your enrollment.

Your admin gives you the enrollment link — Users → Add user in the console generates it, already wrapped in the installer command above. --enroll links (enl_…) are the org's shared link by default — the same one works for everyone, and a roster row's Regenerate action mints an email-bound personal one instead. --sso links are organization-wide and safe to share in Slack.

# Enroll through your company IdP
anyray-connect --sso https://app.anyray.ai/sso/tnt_example

# Preview the changes without writing anything
anyray-connect --dry-run

# Only configure two tools, no prompts
anyray-connect --tools claude-code,codex --yes

Restart your editor after a run

Editors that were already running keep their old config until you restart them.

What a run configures

Connect edits each tool's own config so its requests go through the gateway. Tools you don't have installed are skipped. The ID column is what --tools accepts.

Tool	What Connect changes	ID
Claude (API)	the env block in ~/.claude/settings.json — ark_ key as token	claude-code
Claude (Subscription)	same env block — your own Claude sign-in stays	claude-code
Claude Desktop	its third-party gateway mode	claude-desktop
Codex (app, CLI, IDE)	~/.codex/config.toml — anyray becomes the default provider	codex
Cursor	OpenAI custom endpoint (BYOK) for Ask/Plan chat	cursor
VS Code Copilot Chat	an Anyray chat provider (VS Code 1.121+)	copilot
GitHub Copilot CLI	COPILOT_PROVIDER_* env in your shell profile — seat-billed via the gateway's Copilot carrier route when a Copilot sign-in is readable, org-billed BYOK under --org / with no seat	copilot-cli
OpenCode	its direct API providers and its Copilot provider	opencode
JetBrains AI Assistant	Anyray Claude and Codex agents in its agent registry	jetbrains
Devin Desktop	Anyray Claude and Codex agents in its agent registry	windsurf
Shell & SDKs	base-URL env vars in the shell profile	shell-env

Check your setup

Command	What it does
anyray-connect status	Show which tools point at the gateway, plus your gateway, name, team, and savings.
anyray-connect doctor	Diagnose gateway reachability and each tool's config. Exits non-zero when something is wrong.

doctor is the one to run when a tool suddenly stops working:

anyray-connect doctor                     # what's broken
anyray-connect doctor --verify            # also send two tiny live requests
anyray-connect doctor --repair            # re-apply tools whose config drifted
anyray-connect doctor --json              # content-free report to send to support
anyray-connect doctor --security-review   # allow-list for your EDR/endpoint team

Flag	What it does
--verify	Runs an auth smoke probe and a retrieval-loop probe — two tiny real requests.
--repair	Re-applies routing for tools a previous run configured. A tool you reverted stays reverted.
--json	Prints a shareable report with no prompt content in it.
--security-review	Prints the service names, unit-file paths, and loopback-only network posture your security team needs to allow-list.

Keep the CLI current

A connect.sh install updates itself about every 30 minutes. These commands let you drive it by hand.

Command	What it does
anyray-connect update	Install the published version now instead of waiting.
anyray-connect update --check	Report which version is published. Changes nothing.
anyray-connect update --auto off	Stop automatic updates on this machine.
anyray-connect update --auto on	Resume automatic updates, and update now.
anyray-connect update --json	Emit the result as JSON (for scripts).

--auto off has one exception

A release marked mandatory — a security or correctness fix — still installs. Everything else waits for you.

An npx anyray-connect@latest install already resolves the current release on every run, so update reports that and changes nothing.

Sync team content

anyray-connect sync

Pulls your team's shared skills and instructions into each tool's skills directory. ~/.anyray remembers the per-skill versions it last wrote, so a re-run only fetches what changed.

Find past context

Anyray moves large tool outputs out of your context window and leaves a · retrieve ctx_… marker behind. These commands get the content back.

Command	What it does
anyray-connect retrieve <ctx_…>	Print the original content behind a marker.
anyray-connect recall <query>	Semantic search over your externalized outputs.
anyray-connect migrate [--export <file.zip>]	Bring what Claude Desktop was showing you onto Anyray — local sessions plus an optional claude.ai export, in one command.
anyray-connect history import <file>	Load a Claude data export so past conversations stay searchable.
anyray-connect history restore <file>	Put those conversations back in Claude Desktop's sidebar.
anyray-connect history status	Show where the archive lives and how much it holds.

retrieve writes the content to stdout byte-for-byte and diagnostics to stderr, so it pipes cleanly:

anyray-connect retrieve ctx_example123 > output.txt
anyray-connect retrieve ctx_example123 | jq .

recall prints one match per line as handle<TAB>score<TAB>preview, and exits 1 when nothing matches — like grep:

anyray-connect recall "migration rollback plan"
anyray-connect recall "failing auth test" --k 5

Both accept --source auto|claude|profile to choose which config resolves the gateway (auto is the default).

Getting a Claude data export

Anyray can't fetch this for you — it needs your Claude login.

1

Request the export

Open claude.ai → Settings → Privacy → Export data. Anthropic emails you a download link.

2

Pick the command

restore takes the .zip; import takes the conversations.json inside it. Quit Claude Desktop before running restore.

restore puts the conversations back in Claude Desktop's own sidebar, clickable, while staying on Anyray. import makes the archive searchable from any Anyray-connected client. Running both is fine.

Roll out to a fleet

These are for admins packaging Anyray through MDM, not for individual developers.

Command	What it does
anyray-connect managed	Emit or install the fleet-wide Claude Code managed-settings.json.
anyray-connect desktop	Set up desktop-app routing (Claude desktop app, Codex fleets).
anyray-connect print-key	Print the enrolled developer's short-lived gateway key for helper integrations.

managed

managed-settings.json reads at a higher precedence than a user's own ~/.claude/settings.json, so it survives a developer editing or wiping their settings. No credential is ever written to it — each user still enrolls once so the gateway can attribute their requests.

# Emit for MDM packaging (Jamf, Ansible…)
anyray-connect managed --print --gateway https://gateway.example.com

# Write to the OS system path — merges, preserves non-Anyray keys
sudo anyray-connect managed --write --gateway https://gateway.example.com

# Remove only the Anyray-owned keys
sudo anyray-connect managed --revert

Pick one mode — --print, --write, or --revert — then pick the artifact with --tool:

--tool	What it emits
claude-code	The managed-settings.json above. Default.
jetbrains	acp.json registering the Anyray ACP agents. Needs --bin and --npx.
shell	A /etc/profile.d snippet exporting the gateway base URLs. Never a key.
bootstrap	A content-free bootstrap file carrying the org SSO link. Needs --sso.
proxy	A launchd plist or systemd user unit for the loopback key-refresh daemon. Needs --bin and --platform.

Everything but claude-code is --print only. Pass --bin with a fleet-stable absolute path (/usr/local/bin/anyray-connect), and pass your real gateway URL — the localhost default is almost never what a fleet wants. --team, --intent, and --session set static attribution metadata on the fleet artifact.

Use --out, not >, on Windows

anyray-connect managed --print --out managed-settings.json writes UTF-8 with no BOM. A PowerShell 5.1 redirect writes UTF-16LE, which no JSON reader accepts.

desktop

Covers what settings.json can't reach: the Claude desktop app and Codex app/IDE/CLI fleets.

# This machine, per-user, no admin needed
anyray-connect desktop --apply

# Undo — removes only Anyray-owned config
anyray-connect desktop --revert

# Fleet artifacts (macOS profile / Windows registry)
anyray-connect desktop --mobileconfig ./anyray.mobileconfig \
  --helper-path /usr/local/bin/anyray-credential-helper
anyray-connect desktop --reg ./anyray.reg \
  --helper-path "C:\Program Files\Anyray\anyray-credential-helper.cmd"

# Codex fleets
anyray-connect desktop codex --helper-path /usr/local/bin/anyray-credential-helper

Before activating a fleet artifact, package the credential helper it points at:

anyray-connect desktop helper --write --platform posix \
  --bin /usr/local/bin/anyray-connect

--helper-path must be fleet-stable

Use /usr/local/bin/anyray-credential-helper on macOS and Linux, or C:\Program Files\Anyray\anyray-credential-helper.cmd on Windows. A path that only exists on your machine breaks every other one.

print-key

anyray-connect print-key                       # the ark_ key alone
anyray-connect print-key --json                # {"token":"ark_…","headers":{…}}
anyray-connect print-key --passthrough-headers # header object only

Carries the short-lived client key, never a seat OAuth token. Prefer print-key --json over scraping desktop output when you're automating.

Common flags

These work on the apply flow (anyray-connect with no subcommand, and wizard).

Identity and attribution

Flag	What it does
--gateway <url>	Gateway origin. Cached after the first run.
--user <id>	Attribute spend to this user. Defaults to the cached name, then git user.name/user.email, then the OS user. '' clears it.
--team <id>	Attribute spend to this team. '' clears it.
--intent <id>	Tag traffic with an intent — filterable as intent:<id> in the console.
--intent-label <s>	Human-readable label for that intent.
--session <id>	Group requests under a session id in the console.

Enrollment

Flag	What it does
--enroll <link>	Passwordless enrollment from an …/enroll/<token> link. Resolves the gateway from the link, so --gateway isn't needed.
--sso <link>	Enterprise SSO from an …/sso/<tenantId> link. Device sign-in against your company IdP.
--machine	For a machine-mode provisioning token: enroll by machine id instead of an email.

Both save an Ed25519 keypair plus a signed cert (~/.anyray/dev-key.pem, mode 600) and mint a short-lived gateway key from it. Re-running re-mints a fresh key from the stored cert — no re-enrollment until the cert expires.

Billing lane

Flag	What it does
(default)	AUTO — each tool uses your own subscription where supported, org API billing otherwise.
--subscription	Always use your own seat. Your tool's OAuth token rides through the gateway.
--org	Always use org API billing. Your personal ark_ key still identifies you.
--upstream <url>	Route to your org's own Anthropic-compatible endpoint (e.g. a LiteLLM proxy). Requires --upstream-key.
--upstream-key <key>	Your personal key for that endpoint. Stored locally, never sent to Anyray's control plane.

--subscription is honored by Claude Code, Codex, and Claude Desktop on verified macOS builds. Cursor is the exception: it stays on native Team mode unless you pass --org.

Run behavior

Flag	What it does
--tools <ids>	Comma-separated subset of the ids in What a run configures.
--project	Write committable, credential-free routing config into the current repo (.claude/settings.json + .codex/config.toml) instead of this machine's user config, so every checkout routes — see Remote and ephemeral machines. Org API lane only; combine with --revert to remove.
--dry-run	Show what would change. Writes nothing.
--yes, -y	Skip confirmation prompts, for scripted rollout.
--force	Skip the gateway reachability check before writing.
--skip-verify	Skip the post-apply smoke test.
--no-key-refresh	Turn off the default-on loopback key refresh for subscription Claude Code and Codex.
--revert	Undo a previous run and clear the stored enrollment. Can't be combined with --sso or --enroll.
--help, -h	Show help.

Leave --no-key-refresh alone unless you must

By default a small loopback daemon fills a freshly minted key into each request, so a long session never 401s on an expired key mid-flight. --no-key-refresh forces the older lane that bakes the key once at launch.