> For the complete documentation index, see [llms.txt](https://docs.computesdk.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.computesdk.com/platform/cli.md). # CLI reference Install and use the \`compute\` CLI (@computesdk/cli) to drive the ComputeSDK Platform — Actions dispatch, run logs, artifacts, provider credentials, secrets and variables, connected repos, sandboxes, a ## Install ```bash pnpm dlx @computesdk/cli # zero-install, always latest npm i -g @computesdk/cli # or install once ``` The binary is `compute`. Pass `--json` on almost any platform command for machine-readable output. With `--json`, failures are written to stderr as a single JSON envelope and the process exits 1: ```json { "ok": false, "error": { "code": "forbidden", "message": "Owner or admin access required", "httpStatus": 403, "retryable": false } } ``` `code` is one of `bad_request`, `unauthenticated`, `forbidden`, `not_found`, `conflict`, `payload_too_large`, `rate_limited`, `server_error`, `http_error` (API responses — `httpStatus` is set), or `no_credentials`, `untrusted_host`, `untrusted_host_stored_auth`, `insecure_transport`, `invalid_argument`, `workflow_not_found`, `network`, `unknown` (raised locally — no `httpStatus`). `retryable` is `true` for 429/502/503/504 and network failures. `details` is present only when the API returned a `details` object. ## Authentication Auth resolves in this order: `--api-key` flag → `COMPUTE_API_KEY` env var → `BENCHMARKS_PLATFORM_API_KEY` (legacy) → stored platform OAuth credentials (`~/.benchsdk/credentials.json`, written by `compute login` or `compute bench auth login`; an expired access token is refreshed silently). Actions commands never start the login flow themselves; with no key anywhere they fail with `no_credentials`. `compute login` runs the platform's OAuth device flow (the same one `bench auth login` uses) and writes to `~/.benchsdk/credentials.json`; `compute logout` clears it. `compute --login` / `compute --logout` are shortcuts for the same thing. After login the CLI prints the active org; `compute whoami` (or `compute org current`) shows it again via `GET /api/v1/me`. ### Organizations ```bash compute org list # your organizations (* = active) compute org use # switch the stored login's active org compute org current # current user + active org ``` The active org is stored per user and client on the platform, so `compute org use` applies to every machine sharing the login. A one-off override is `--org ` (root flag, or on any `sandboxes` / `actions` / `market` subcommand) or the `COMPUTE_ORG` env var — it sends `X-Org-Slug` on the request, which the platform accepts for CLI logins (membership is checked) and ignores for org API keys. Precedence: `--org` > `COMPUTE_ORG` > the stored login's org. The bearer key is only sent to `computesdk.com` and loopback hosts unless you pass `--allow-untrusted-host`, and only over HTTPS — plain `http://` is accepted for `localhost`/`127.0.0.1`/`::1` only. `--allow-untrusted-host` does not relax the HTTPS requirement, and it only applies to an explicit `--api-key` / `COMPUTE_API_KEY` / `BENCHMARKS_PLATFORM_API_KEY` credential: stored `compute bench auth login` credentials are never resolved or refreshed for a non-`computesdk.com`, non-loopback host (`untrusted_host_stored_auth`). ```bash export COMPUTE_API_KEY="csdk_..." compute actions runs myorg/myrepo ``` `--base-url` (or `COMPUTE_PLATFORM_URL` / `BENCHMARKS_PLATFORM_URL`) selects a different platform deployment. Default: `https://platform.computesdk.com`. ## `compute actions` — drive CI on the platform ```bash # See what you can run compute actions repos # org's connected repos compute actions repos connect # connect a generic git remote compute actions repos enable / # enable / disable scheduling compute actions repos disable / # Provider credentials (owner/admin key required) compute actions providers # registered providers, regions, status compute actions providers configure --key [--verify] # save the org's credential compute actions providers configure --field name=value ... # multi-field credentials compute actions providers verify # probe it with a real sandbox compute actions providers remove # Secrets and variables (owner/admin key required) compute actions vault ls [--repo /] [--kind secret|variable] compute actions vault set [--repo] [--kind] [--revealable] [--description] [--labels a,b] [--from-file ] compute actions vault get [--repo] [--kind] compute actions vault rm [--repo] [--kind] # Dispatch and follow runs compute actions dispatch --workflow [--ref] [--inputs k=v ...] compute actions dispatch --workflow --manual # run even without workflow_dispatch (then no inputs) compute actions runs [--status ...] [--branch ...] compute actions history --workflow [--branch] [--job] [--limit n] compute actions run # jobs, provider:region placement compute actions summary # failure digest, redacted log tails compute actions inspect # resolved image, caches, secrets, concurrency compute actions logs [--job] [--step ] [--follow] compute actions cancel compute actions rerun compute actions artifacts [--job] [--out ] ``` Notes: * `--workflow` matches the full file path, the display name, or the workflow id — not the basename. * `logs --follow` is resumable: it tracks byte offsets, so a reconnect picks up where it left off. * `history` is how you tell a new failure from a flaky one — it reports per-job and per-step failure rates over a window of recent runs. * `vault set` reads the value from stdin (or `--from-file`) and stores it exactly as read — no trimming, so `printf '%s' "$VALUE" | compute actions vault set NAME` avoids a trailing newline. Values are never accepted as arguments. * `vault ls` prints names and metadata, never values. `vault get` prints a variable, or a secret created with `--revealable`; any other secret is `forbidden` — replace it instead of reading it. `--revealable` and `--labels` are fixed when the item is created. * `vault set` and `vault get` only talk to `computesdk.com` and loopback hosts, even with `--allow-untrusted-host`. * Run dashboard URLs look like `https://platform.computesdk.com//actions/runs/`. ## `compute bench` — the benchmarks toolchain `compute bench` folds the full `@benchsdk/runner` bench binary under `compute`: ```bash compute bench auth # browser login / credential management compute bench org # organization info compute bench benchmarks # list benchmarks compute bench runs # list runs compute bench results # query results compute bench iterations # per-iteration data compute bench artifacts # download run artifacts compute bench logs # run logs compute bench export # export results compute bench run # execute a benchmark run compute bench check # validate a benchmark definition ``` ## `compute sandboxes` ```bash compute sandboxes create # place a sandbox compute sandboxes list # list sandboxes compute sandboxes exec uname -a # run a one-shot command compute sandboxes spawn --cwd /app -e NODE_ENV=production -- npm run dev compute sandboxes ps # detached processes compute sandboxes url --port 3000 # public URL for an exposed port ``` For `exec` and `spawn`, everything after the command's first word goes to the sandbox untouched — flags like `uname -a` or `node -e` are not CLI options. Pass CLI options (`--json`, `--timeout-ms`, `--cwd`, `-e/--env`, `--stdin`, `--org`) before the command; a bare `--` before the command is optional but supported. ## `compute providers` ```bash compute providers # list sandbox providers and their credential status ``` --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters: ``` GET https://docs.computesdk.com/platform/cli.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `build a script that syncs our docs to a CMS` lets GitBook tailor the answer to that use case. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.