CLI commands
The full anyray-connect command reference. Anyray Connect explains
what a run actually changes.
Install it
The installer downloads a standalone binary to ~/.anyray/bin (override with $ANYRAY_HOME),
verifies its SHA-256 checksum, and runs it once with whatever flags you pass. No Node needed.
- macOS / Linux
- Windows PowerShell
curl -fsSL https://app.anyray.ai/connect.sh | sh -s
& ([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:
- macOS / Linux
- Windows PowerShell
curl -fsSL https://app.anyray.ai/connect.sh | sh -s -- --enroll https://app.anyray.ai/enroll/enl_example --yes
& ([scriptblock]::Create((irm https://app.anyray.ai/connect.ps1))) "--enroll" "https://app.anyray.ai/enroll/enl_example" --yes
Before handing off, the script reconnects stdin to your terminal (the script itself arrived on
stdin), so prompts work; with no readable terminal (CI, a sandbox, an MDM run) it appends --yes
for you. npx anyray-connect@latest also works: npm is a bootstrapper, and Connect downloads the
same checksum-verified standalone binary before the first persistent change, then points every
hook, MCP registration, and background service at ~/.anyray/bin/anyray-connect.
Running it
anyray-connect <command> [options]
The gateway URL resolves in this order: the --gateway flag, then $ANYRAY_GATEWAY_URL, then
the ~/.anyray cache, then http://localhost:8787. After the first run it's cached.
anyray-connect --help shows the everyday commands; --help --all (or --help-all) the
complete reference; <command> --help one command's 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 --sign-in | Sign in in your browser and connect to the deployment mapped to your company email. |
anyray-connect --revert | Undo everything Connect wrote and clear your enrollment. |
With --sign-in, --sso, --enroll, --claim, or a service key in ANYRAY_CLIENT_KEY,
--json streams NDJSON events named sso_grant, enrolled, applied, and error for a program
driving the enrollment. It requires --yes, never opens a browser, cannot be combined with
--dry-run, and every failure emits an error event before the non-zero exit.
sso_grant carries the official page in verificationUriComplete and the separate verification
code in userCode; display both rather than deriving a code from the URL.
An agent host runs the same headless apply with a service key in its environment; what changes on that lane is in Service keys.
The wizard asks how to connect (enrollment link, SSO, or a gateway URL), shows only installed tools in a keyboard checklist, prints the complete plan, and asks once before writing. A stored enrollment is reused. Tools that move inference spend from your own subscription to the org API bill are never preselected, and the checklist's toggle all key skips them; select one row explicitly to opt in.
Your admin generates the enrollment link (Users → Add user in the console). --enroll links
(enl_…) are the org's shared link by default; a roster row's Regenerate action mints an
email-bound personal one. --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
Editors that were already running keep their old config until you restart them.
Setup flags belong to the CLI, never to curl: a flag on the curl line is consumed by curl.
When anyray-connect isn't on this shell's PATH yet, go through the installer and put the
flag after sh -s --:
- macOS / Linux
- Windows PowerShell
curl -fsSL https://app.anyray.ai/connect.sh | sh -s -- --revert
& ([scriptblock]::Create((irm https://app.anyray.ai/connect.ps1))) "--revert"
--revert unpicks the tool configs, services, and stored enrollment; the binary stays in
~/.anyray/bin, ready to re-enroll. A full --revert never leaves a background process waiting:
where a scoped --tools <id> --revert queues work until the app closes, the full one removes
what it can immediately and tells you what is left (with Cursor open, only its saved OpenAI BYOK
settings wait; quit Cursor and re-run).
Follow the revert with rm -rf ~/.anyray (%USERPROFILE%\.anyray on Windows), then restart any
editor or terminal that was running; each loaded our hooks at startup and keeps running them
from memory until it restarts.
Reverting on a fleet-managed machine
A full --revert still holds on a fleet-managed machine: with no enrollment certificate left,
the machine cannot mint a key, so the fleet's refresh pass finds nothing to renew, the drift pass
finds nothing to re-apply, and the machine stops counting against your org's routing checks. Two
things it does not reach, by design:
- Machine-wide settings your IT pushed. A
managed-settings.jsondeployed by MDM outranks your own config; an administrator removes it withsudo anyray-connect managed --revert. - The fleet agent itself.
anyray-connectnever installed it and cannot remove it. Ask whoever runs your device management.
An admin can also revert a seat from the console's Machines page; it lands on the machine's next check-in and the seat shows as offboarded rather than failing.
A revert clears the enrollment. If your org uses SSO, run anyray-connect --sso and sign in;
otherwise ask an admin for a new enrollment link, since the old one is spent.
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, with the 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, plus queued migration of eligible local profile data | claude-desktop |
| Codex (app, CLI, IDE) | ~/.codex/config.toml, where 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 |
| OpenClaw | its anthropic and openai providers, plus the prompt-cache setting its custom-host mode skips | openclaw |
| 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 |
Third-party gateway mode signs Claude Desktop out of claude.ai
(the trade). If your org
manages the app from the claude.ai admin console, name the tools you want
(--tools claude-code,codex) instead of letting a bare run configure everything. Undo with
anyray-connect desktop disconnect.
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 status --json | Write and print the content-free seat status document used by machine policy checks. |
anyray-connect doctor | Diagnose gateway reachability and each tool's config. Exits non-zero when something is wrong. |
anyray-connect device-url | Print this machine's device-page URL, the same page the tray's "Open my device page" opens. |
anyray-connect models | List the Copilot models your seat can run on the Anyray lane (--json for scripts); models <id> switches the Copilot CLI's startup model, validated with a live one-token chat first. The Copilot CLI's own /models cannot list models on a custom provider, so this command is the picker. |
anyray-connect copilot-login | Sign Anyray in to GitHub Copilot through GitHub's device flow, so the Copilot CLI seat lane can run your plan's current models. Use it when Connect reports no current models, or the CLI answers 400 The requested model is not supported. |
anyray-connect connectors authorize <name> | Connect one of your org's OAuth connectors to your own account: opens the consent page and finishes the grant when the browser comes back. Over SSH, rerun with --claim <code>. Flags and fallbacks: Connect reference. |
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 # machine-readable report to send to support
anyray-connect doctor --quick # local checks only, no network
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. |
--quick | Local checks only: skips the gateway probe, the auth probe, and the fleet-health report, so background pollers can run it every few seconds. Skipped legs read null in --json, never as failures. Can't be combined with --verify. |
--security-review | Prints the service names, unit-file paths, outbound hosts, and self-update footprint your security team needs to allow-list. |
device-url prints <gateway>/device?dt=<token>, minting a replacement short-lived token on
demand. stdout carries the URL alone, so it's safe to pipe:
open "$(anyray-connect device-url)".
Automate seat maintenance
Stable entries for fleet scripts, launch agents, systemd units, and scheduled tasks. They never
prompt or read from a TTY; each writes one JSON document to stdout, diagnostics to stderr, and
updates ~/.anyray/status.json atomically with owner-only permissions.
| Command | What it does |
|---|---|
anyray-connect reconcile | Pull the org tool policy, apply its tier rules, and repair managed routing drift. |
anyray-connect refresh | Renew the personal key and enrollment certificate when due, then re-assert managed configuration. |
anyray-connect repair | Run the full doctor --repair pass without prompts. |
anyray-connect status --json | Run the local status checks and print the same document stored in ~/.anyray/status.json. |
anyray-connect offboard | Revert managed tool configuration, remove background units, and clear the user's enrollment. |
The JSON contains metadata only: Connect version, enrollment state, refresh timestamps, managed
tool ids and policy tiers, routing booleans, and the last verb's exit code. Never a gateway key,
device private key, SSO token, authorization header, or credential-bearing URL. On a
fleet-managed machine these commands skip ambient self-update and relaunch paths (a remediation
run cannot replace the binary executing it); the gateway directs stale seats to update through
the per-seat directive lane instead. Off the fleet, refresh keeps its trailing self-update: the
scheduled refresh tick is the only unattended update path an unmanaged seat has.
| Exit code | Meaning |
|---|---|
0 | Success. The seat is healthy, or offboarding completed. |
1 | An unexpected error stopped the command. |
2 | Usage error, such as an unknown flag or argument. |
3 | Authentication is broken. Re-enroll the seat; machine remediation cannot repair it. |
4 | Partial. The command ran, but drift remains, such as a quit-gated tool still running. |
doctor --repair remains supported for people and existing scripts. Use repair for new
automation; its JSON and exit-code contract is stable.
Keep the CLI current
The managed standalone binary updates itself about every 30 minutes, whether the first run used
connect.sh or npm/npx. On a fleet-managed machine the ambient updater stands down and the
gateway queues an update directive when the seat's version is stale, applied on a maintenance
tick with the same verified, smoke-tested updater, normally within one cycle of a release.
| Command | What it does |
|---|---|
anyray-connect --version | Print the installed Connect version. If a newer release exists, stderr also shows the latest version and the update command. |
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 exceptionA release marked mandatory (a security or correctness fix) still installs; everything else waits for you. Two exceptions to the exception: inside a container, self-update never runs regardless; and a fleet update policy outranks the mandatory release too.
Fleet update policy
--auto off is one developer's switch. An administrator sets the posture for every machine in
Console → Tools → Connect updates, and it reaches each seat on its next policy pull.
| Policy | What machines do |
|---|---|
| Automatic (default) | Each seat checks about every 30 minutes and installs a new release itself. |
| Administrator-directed | No machine downloads anything on its own. The gateway stops queuing updates for stale seats, and a version lands only when an administrator sends an update from Machines. |
| Off | No Anyray process fetches a binary. Deploy each version with your own tooling (MDM). anyray-connect update reports the policy and changes nothing, and the console refuses to queue an update. |
The two restricted modes exist for fleets running behavioral endpoint security (Bitdefender
GravityZone ATC, SentinelOne, and similar): the updater downloads a binary, marks it executable
and runs it, a shape those products score as behavior, so a code signature does not clear it.
The policy only ever restricts; it never turns a developer's --auto off back on. Seats left
behind a release stay visible in Machines and in anyray-connect doctor, which
reports the posture rather than advising --auto on.
An existing npx-enrolled seat whose integrations still point at a version-pinned npm runtime
migrates on its next automatic refresh; anyray-connect update migrates immediately, and
update --check reports what would happen. The new standalone binary must pass a --version
smoke test before Connect repoints any registration.
If no standalone asset is published for the current OS and architecture, Connect keeps the
durable npm runtime and reports self-update as unavailable in --version, update, and
doctor. Use npx anyray-connect@latest to stay current on that platform.
Inside a devcontainer or Codespace, Connect skips both self-update and the npm-to-managed-binary migration; the image updates by rebuilding. See Remote and ephemeral machines. SSH remotes are unaffected.
Sync team content
anyray-connect sync
Pulls the organization's Skills and Guidance into each managed tool's skills directory right
now. The background service does the same on every policy pull, and every successful apply ends
with the same pull, so this command is for "apply it now", not a step anyone has to remember. Codex, Cursor, Copilot, OpenCode and OpenClaw all
read the shared ~/.agents/skills. Claude Code installs them as plugins instead: Connect
registers the gateway's marketplace in ~/.claude/settings.json (extraKnownMarketplaces,
enabledPlugins) and Claude Code fetches the hash-pinned archives itself on its next launch,
so nothing is copied into ~/.claude/skills for those. Claude Code only installs archives
over https, so a gateway whose public URL is plain http keeps getting file copies instead. A
skill the admin removes disappears everywhere. ~/.anyray
remembers the per-skill versions it last wrote, so a re-run only touches what changed or went
missing. The same pull
places the organization's connectors: when the deployment runs the
MCP hub, every managed tool gets one anyray-org remote MCP server in
its own config, and loses it again when the hub is withdrawn.
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>] | Copy portable Claude Desktop local data; optionally restore a claude.ai export. |
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).
The export the history and migrate --export commands take comes from claude.ai →
Settings → Privacy → Export data (Anyray can't fetch it; it needs your Claude login).
restore takes the .zip with Claude Desktop quit; import takes the conversations.json
inside it; running both is fine. Full flows:
Your existing conversations.
Roll out to a fleet
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 bootstrap file carrying the org SSO link. Needs --sso. |
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.
--out, not >, on Windowsanyray-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.
While CLAUDE_CODE_USE_BEDROCK or CLAUDE_CODE_USE_VERTEX is set, Claude Code builds its own
cloud client and never reads ANTHROPIC_BASE_URL, so every routing key above is inert, and no
per-user configuration can override a value the managed file sets. Add --scrub-direct-mode to
pin both switches to "", Claude Code's documented unset:
sudo anyray-connect managed --write --gateway https://gateway.example.com --scrub-direct-mode
Off by default because those switches are normally the organization's own policy; the gateway
calls the same Bedrock or Vertex with the same credentials once its provider is configured.
--revert removes only the empty pin Anyray writes, never a value someone else set.
Add --lock-skills to make the organization's Skills and Guidance the only skills Claude Code
loads on the fleet. The file then registers the gateway's plugin marketplace and sets
strictPluginOnlyCustomization.skills, so a developer's loose ~/.claude/skills folder stops
loading. Without the flag, each enrolled machine still registers the marketplace at user scope;
the lock is the only part that needs the managed file.
desktop
Covers what settings.json can't reach: the Claude desktop app and Codex app/IDE/CLI fleets.
# This machine: connect through the normal enrollment/update/healing lifecycle
anyray-connect desktop
# Undo: removes only Anyray-owned config
anyray-connect desktop disconnect
| Subcommand | What it does |
|---|---|
desktop fleet bootstrap <os> <url> <out> | Emit Claude's stable MDM trust anchor for a centrally refreshed policy; --oidc for an existing IdP. |
desktop fleet static <os> <helper-path> <out> | Emit a complete static policy artifact (macOS profile / Windows registry / Linux JSON). |
desktop helper --write | Install the credential and bootstrap-headers helper wrappers (--print for MDM packaging). |
desktop codex | Emit the Codex fleet artifact (--mobileconfig, or a Windows managed TOML). |
Local setup queues migration of eligible user-owned profile data automatically; on MDM-managed
Desktop, Connect may copy that data but never writes or supplements the managed policy
(the boundary). Exact
artifact commands, helper installation, and the fleet flows:
Managed desktop fleets and the
Desktop reference. The one biting
flag: --helper-path must be a fleet-stable absolute path, or the artifact breaks every machine
but yours.
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 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, or the short …/i/<token> form of it. Resolves the gateway from the link, so --gateway isn't needed. |
--sso <link> | Enterprise SSO from an …/sso/<tenantId> link, or the short …/i/<tenantId> form of it. Device sign-in against your company IdP. |
--sign-in | Browser sign-in that connects to the deployment mapped to your verified company email. Uses $ANYRAY_CP_ORIGIN, then the default portal. |
--machine | For a machine-mode provisioning token: enroll by machine id instead of an email. |
These enrollment flows save an Ed25519 keypair plus a signed cert (~/.anyray/dev-key.pem, mode 600) and mint a
gateway key from it. A separate device-proof heartbeat extends that same key before expiry, with
no re-enrollment or tool credential rewrite.
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. |
--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. The lane is per
enrollment command, not per deployment, so one gateway can serve both at once; an admin can also
assign it per user and per team in the console, which overrides these flags. See
mixing both lanes.
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 device-proof heartbeat that extends your key out of band. Leave it alone unless you must. |
--revert | Undo a previous run and clear the stored enrollment. Each reverted tool is tombstoned so fleet policy never re-enrolls it behind your back (an admin locked-tier tool refuses a scoped --tools <id> --revert; re-running anyray-connect --tools <id> clears the tombstone). Can't be combined with --sso or --enroll. |
--verbose | After a successful apply, also show the masked curl re-test recipe and revert hint. |
--help, -h | Show everyday help. Add --all, or use --help-all, for every command and flag. |