CLI commands
The full anyray-connect command reference. Anyray Connect explains what a run
changes.
Managed Claude profiles provision source hooks with either credential lane. --bin selects the
command hook; without it, the env lane uses HTTP. doctor and status --json report installation
and retrieval separately as sourceHook. See source trims.
Install it
- macOS / Linux
- Windows PowerShell
curl -fsSL https://app.anyray.ai/connect.sh | sh -s
& ([scriptblock]::Create((irm https://app.anyray.ai/connect.ps1)))
It downloads a standalone binary to ~/.anyray/bin (override with $ANYRAY_HOME), checks its
SHA-256, and runs it once. No Node needed.
Everything after sh -s -- goes straight to the CLI, so one line installs and enrolls:
- 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
A flag on the curl line is eaten by curl. It must come after sh -s --.
The script reconnects stdin to your terminal before handing off, so prompts work even though the
script itself arrived on stdin. With no readable terminal (CI, a sandbox, an MDM run) it appends
--yes for you.
npx anyray-connect@latest works too. npm is only a bootstrapper: 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, $ANYRAY_GATEWAY_URL, the ~/.anyray
cache, then http://localhost:8787. After the first run it is cached.
anyray-connect --help shows the everyday commands, --help --all (or --help-all) the complete
reference, and <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 --agent <name> | Mint a key for a CI job or service account, attributed to that name. |
anyray-connect --revert | Undo a previous run and clear the stored enrollment. |
Which tools a run configures, and what it writes to each: What Connect changes.
Reverting
--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: a
scoped --tools <id> --revert queues work until the app closes, while the full one removes what it
can immediately and names what is left. With Cursor open, only its saved OpenAI BYOK settings wait.
To remove Connect completely, follow the revert with rm -rf ~/.anyray (%USERPROFILE%\.anyray on
Windows), then restart any editor or terminal that was running. Each loaded the hooks at startup and
keeps running them from memory until it restarts.
A revert clears the enrollment, so reconnecting needs anyray-connect --sso or a fresh enrollment
link. The old link is spent.
Reverting on a fleet-managed machine
A full --revert still holds. 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 within about two minutes on the desktop app and within 30 minutes on CLI-only machines, and the seat shows as offboarded rather than failing.
Claude Desktop is the one tool with an organization-level effect
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 it 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. |
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. Cannot 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 pipes: 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 and diagnostics to stderr.
| 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 directives [--desktop-channel <staging|stable> --desktop-current <version>] | Pull and run one supported pending admin directive from the console. The desktop app passes both optional flags so an update directive targets its channel and running version. |
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. |
anyray-connect desktop-update --channel <staging|stable> --current <version> | Stage a desktop app update for the tray: download, verify checksum and code signature, print where it is. |
A writing command resolves the available engine before it runs. An npm, npx, or secondary CLI invocation forwards to that engine with the same arguments and standard streams, and returns its exit code. If the recorded app is gone, CLI setup can run again. A CLI release older than engine forwarding must be updated to gain this behavior.
Two kinds of command never forward: diagnostics (doctor --json, status --json) stay available
from the copy you invoked, and credential helpers including print-key run locally with no app
discovery.
| 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 stays supported for people and existing scripts. Use repair for new automation,
because its JSON and exit-code contract is stable.
What the seat maintenance JSON holds
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. The file
(~/.anyray/status.json) is written atomically with owner-only permissions.
On a fleet-managed machine these commands skip ambient self-update and relaunch paths, because 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.
Directive pulls run on every enrolled seat. A staged desktop update also reports its version and local path. Other admin commands take priority over a waiting desktop update, so postponing an installation does not block an offboard or credential repair.
Keep the CLI current
| Command | What it does |
|---|---|
anyray-connect --version | Print the selected engine version. Update notices and installation conflicts go to stderr. |
anyray-connect --version --local | Print only the invoked executable version, without discovery or an update check. |
anyray-connect update | Install the published standalone version now. A desktop-bundled engine reports that the app owns updates and exits successfully. |
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. |
Outside the desktop app, the managed standalone binary updates itself about every 30 minutes,
whether the first run used connect.sh or npm. The desktop app updates itself instead: it checks
every few hours, downloads in the background, and installs when nothing else is running. On Windows
you confirm from the tray menu. The app reopens after the installer finishes, even when you cancel.
The engine inside the app never updates on its own.
--auto off has one exception. A release marked mandatory, meaning a security or correctness
fix, still installs. Two exceptions to that: inside a container self-update never runs at all, and a
fleet update policy outranks a mandatory release too.
Conflicting installations
Run anyray-connect doctor --repair when different terminals report different versions.
It repairs supported user-owned launchers and lists copies that need administrator or package-manager
action. Before removing a copy, repoint any tools that use it.
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, the 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, such as Bitdefender GravityZone ATC or SentinelOne. 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.
Migrating an npx-enrolled seat
An existing npx 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.
Platforms without a standalone binary, and containers
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 there.
Inside a devcontainer or Codespace, Connect skips both self-update and the npm-to-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 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".
| Tool | Where the skills land |
|---|---|
| Codex, Cursor, Copilot, OpenCode, OpenClaw | The shared ~/.agents/skills |
| Claude Code | Installed as plugins. 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 |
Claude Code installs archives over https only, 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 policy includes the
organization MCP endpoint, every managed tool gets one anyray-org remote
MCP server in its own config. Connect removes that entry if the endpoint is no longer advertised.
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 cannot fetch it, because it needs your Claude login. restore takes
the .zip with Claude Desktop quit, import takes the conversations.json inside it, and running
both is fine. Full flows: Bring your data across.
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, and 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. The 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, because the localhost default is
almost never what a fleet wants. --team, --intent, and --session set static attribution
metadata on the artifact.
On Windows use --out, not >. anyray-connect managed --print --out managed-settings.json writes
UTF-8 with no BOM, while a PowerShell 5.1 redirect writes UTF-16LE, which no JSON reader accepts.
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.
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, and 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.
desktop
Covers what settings.json cannot reach: the Claude desktop app and Codex app, IDE, and 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, or 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 on its own. On MDM-managed Desktop, Connect may copy that data but never writes or supplements the managed policy (the boundary).
The one biting flag: --helper-path must be a fleet-stable absolute path, or the artifact breaks
every machine but yours. Exact artifact commands and the fleet flows:
Managed fleet and the
Desktop reference.
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 or 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. Resolves the gateway from the link, so --gateway is not needed. |
--sso <link> | Enterprise SSO from an …/sso/<tenantId> link, or the short …/i/<tenantId> form. 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. |
--endpoint | Also install the signed endpoint agent, so the device reports compliance. One sudo prompt. |
--json | Emit NDJSON enrollment events on stdout, human output on stderr. Requires --yes, and opens no browser. |
These 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 and no 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 OpenAI- or Anthropic-compatible endpoint, such as a LiteLLM proxy. Both lanes forward your key. 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 tool ids in What Connect changes. |
--project | Write committable, credential-free routing config into the current repo (.claude/settings.json plus .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. |
--quit-apps | Close and reopen the editors whose environment is stale. The only way a scripted run closes anything. |
--no-quit-apps | Never close anything, whatever else is passed. |
--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. Cannot 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. |
doctor and status --json include the verified key’s sourceTrim.state. State vocabulary and grace period. sdk-agent is a metadata ID for manually integrated tool loops, not a Connect --tools adapter.