# The CLI `caas` is the caas.sh command line. Use it to run commands in new sandboxes, manage sandboxes and their snapshots, deploy MCP servers, push images, start workflows, connect credentials and manage billing from a terminal or a script. It calls the same API as the console, with an API key from your workspace. ## Install the CLI The CLI needs Node 22 or later. Install the `@caascade/cli` package globally: ```sh npm i -g @caascade/cli ``` > The package isn't on npm yet. Once it's published, this command installs it. This installs the `caas` command. To list every command and option, run `caas help`, or `caas` on its own. Adding `--help` to any command does the same. Some commands use other tools: `caas registry login` runs Docker, and `--from` uses Git. ## Connect the CLI to your workspace The CLI doesn't sign in with your email and password. It uses an API key, which belongs to one workspace, together with that workspace's tenant ID. ### Create an API key 1. Sign in to the [console](https://console.caas.sh/) and open **Settings**. 2. Under **Workspace**, copy the **Tenant ID**. 3. Under **API keys**, enter a **Key name**, such as `my laptop`. If you're an owner and want to use `caas billing`, check **Billing access**. 4. Choose **Create key**, then copy the key. It starts with `ck_`, and the console shows it only once. Owners and operators can create keys. Viewers can't. ### Configure the CLI Save the tenant ID and key: ```sh caas configure --tenant --key ``` The CLI saves them in `~/.config/caas/config.json`, or in `$XDG_CONFIG_HOME/caas/config.json` if `XDG_CONFIG_HOME` is set. Only you can read the file. Every later command uses what you saved. To check that everything works, list your sandboxes: ```sh caas sandboxes list ``` Running `caas configure` again replaces the saved tenant ID and key. ### What a key can do A new key can: - list, create, start, stop and delete sandboxes, and run commands in them - deploy MCP servers and manage their client tokens - push and pull images in the registry - start and control workflow runs - read credentials, egress rules and the audit log A key with **Billing access** can also read the balance and usage and add funds (`caas billing`). A key can never do more than the member who created it. An operator's key can't use `caas billing`, and only an owner's key can connect or remove credentials or apps, or change egress rules. If the member who created a key leaves the workspace, the key stops working. To revoke a key, choose **Revoke** next to it under **Settings** → **API keys**. ## Choose a workspace The CLI always works in one workspace: the one whose tenant ID you pass, with a key created in that workspace. A key from one workspace doesn't work in another. To work in another workspace: 1. In the console, open the workspace card at the top of the sidebar and switch to that workspace. 2. Create an API key there, as in [Create an API key](#create-an-api-key), and copy that workspace's tenant ID. 3. Either save the new pair, which replaces the one you saved before: ```sh caas configure --tenant --key ``` Or pass the pair to a single command and keep what you saved: ```sh caas sandboxes list --tenant --key ``` ## Options for every command | Option | What it does | | --- | --- | | `--tenant ID` | Use this workspace instead of the saved one. Pass `--key` with it. | | `--key KEY` | Use this API key instead of the saved one. | | `--api-url URL` | Use another API address. The default is `https://api.caas.sh`. It must use `https://`, except on `localhost`. `caas configure` saves it. | | `--json` | Print the API's JSON response instead of the text output. | | `--help` | Print every command and option. | `caas run`, `caas mcp deploy`, `caas sandboxes exec`, `caas workflows run` and `caas billing add-funds` send their request with an idempotency key. If the CLI can't reach the API, the error names the key. Run the same command again with `--idempotency-key KEY` to retry without creating a second sandbox, command, run or payment. ### Exit codes | Code | Meaning | | --- | --- | | `0` | Success. | | `1` | The request or the command failed. | | `2` | The command line isn't valid, for example an unknown option, a missing value or a value out of range. Nothing was changed. | | `3` | The API or the registry refused the key: it's revoked, from another workspace, or lacks the access the command needs. | `caas run` and `caas sandboxes exec` exit with the command's own exit code when it's between 1 and 125, and with `1` for any other failure. Errors are printed to standard error as `caas: `. When the workspace is out of funds, the error also links to the console page where an owner adds them. ## Sizes `--size` sets a sandbox's vCPU, memory and disk. The default is `m`. | Size | `--size` | vCPU | Memory | Disk | | --- | --- | --- | --- | --- | | XS | `xs` | 1/16 | 256 MiB | 2 GB | | S | `s` | 1/4 | 1 GiB | 4 GB | | M | `m` | 1/2 | 4 GiB | 8 GB | | L | `l` | 1 | 6 GiB | 12 GB | | XL | `xl` | 2 | 8 GiB | 16 GB | | 2XL | `2xl` | 4 | 12 GiB | 20 GB | | Custom | `custom` | 1 to 4 | At least 3 GiB per vCPU, at most 12 GiB | 2 to 20 GB | For a custom size, add `--vcpu N --memory GIB --disk GB`, all whole numbers: ```sh caas run --size custom --vcpu 2 --memory 6 --disk 12 -- node --version ``` A sandbox that runs your own image needs size M or larger. vCPU bills only while the sandbox computes; memory and disk bill while it runs. See [pricing](/pricing.html) for the rates. ## Run a command in a new sandbox `caas run` creates a sandbox, runs one command in it, waits for the command to end, and prints its output: ```sh caas run -- node --version caas run --from . node task.js caas run --name build-agent --size xl --from . node task.js caas run --image worker:latest -- python task.py caas run --from . --detach node long-task.js caas run --ephemeral --egress-host api.example.com -- node --version caas run --from . --expose 3000 -- node server.js ``` The command runs as an executable with its arguments, not through a shell. To use shell features, run a shell: ```sh caas run --from . -- sh -c 'node build.js && node test.js' ``` Options can come anywhere before `--`, and everything after `--` is the command. Put `--` before a command whose arguments start with `--`. Without `--image`, the sandbox uses the Default image: Alpine Linux with bash, coreutils, Node and Docker. It has no coding agents installed; install one in your command, or use your own image. The command has a time limit of two hours, and runs once. When `caas run` is done, the sandbox keeps running until its idle stop. Delete it with `caas sandboxes delete` when you no longer need it. | Option | What it does | | --- | --- | | `--from DIR` | Upload your code into `/workspace`. See [Upload your code](#upload-your-code). | | `--image IMAGE` | Run in your own image from the registry. See [Push images to the registry](#push-images-to-the-registry). Can't be combined with `--from`. | | `--name NAME` | Name the sandbox: up to 63 lowercase letters, digits and hyphens, starting and ending with a letter or digit, unique in the workspace. | | `--size SIZE` | The sandbox's size. See [Sizes](#sizes). | | `--egress-host HOST` | Allow outbound requests to this exact host. Repeat it for each host, up to 32. Other hosts are blocked unless you change the sandbox's [egress policy](#egress-policy). A command that starts with `npx` also gets `registry.npmjs.org`. | | `--expose PORT` | Serve this port at the sandbox's own URL: 1024 to 65535, except 8788. See [Sandbox URLs](#sandbox-urls). | | `--public` | With `--expose`: let anyone with the link open the URL, without an access token. | | `--idle-stop MINUTES` | Stop the sandbox after this many minutes with no command, file transfer, MCP request or URL request: 5 to 240. The default is 15. | | `--wake-on-request` | Let a command, a file transfer, an MCP request or a URL request start the sandbox again after you stopped it yourself. A sandbox that stopped while idle starts again on a request either way. | | `--ephemeral` | Keep nothing between restarts: the sandbox starts fresh each time, and the sandbox takes no automatic or nightly snapshots. Can't be combined with `--from`. | | `--detach` | Return as soon as the sandbox is created, without waiting for the command. | With `--detach`, the CLI prints the new sandbox and the ID of its first command, `initial-agent-command`. Check on the command later: ```sh caas sandboxes command initial-agent-command ``` ### Upload your code `--from DIR` uploads the committed Git tree of the repository at `DIR`, usually `.`, and unpacks it into `/workspace` when the sandbox first starts. You can use it with `caas run` and with `caas mcp deploy --stdio`. - `DIR` must be the root of a Git repository with at least one commit. - Commit your changes first. The CLI refuses a repository with uncommitted changes or untracked files. Files that Git ignores are never uploaded. - The CLI refuses to upload a repository that tracks a sensitive-looking file: `.env` files, `.dev.vars`, `.npmrc`, `id_rsa`, `credentials`, or any `.pem` or `.key` file. - The compressed upload can be at most 250 MiB. - A sandbox started from an upload keeps its state, so you can't combine `--from` with `--ephemeral`. caas.sh keeps the upload for seven days; after that, your files live on in the sandbox's own snapshots. ## Manage sandboxes `caas sandboxes` commands take the sandbox's ID, not its name. `caas sandboxes list` shows both. ### List and inspect ```sh caas sandboxes list caas sandboxes inspect caas sandboxes events ``` | Command | What it does | | --- | --- | | `caas sandboxes list` | Lists every sandbox and MCP server that isn't deleted: its ID, name, kind (`agent` or `mcp`) and record state (`active` once it's created). `inspect` shows whether it's running. | | `caas sandboxes inspect ID` | Shows the sandbox's details: its status, settings, size, URL, and usage, including what it costs per hour now and what it has cost today. | | `caas sandboxes events ID` | Lists the sandbox's events, such as its starts and stops. | ### Start, stop and delete ```sh caas sandboxes stop caas sandboxes start caas sandboxes delete ``` A sandbox that keeps state takes a snapshot as it stops, and starts again with its `/workspace`. ### Run commands in a sandbox ```sh caas sandboxes exec -- node --version caas sandboxes exec -- sh -c 'cd /workspace && ls -la' caas sandboxes exec --timeout-ms 1800000 --detach -- node long-task.js caas sandboxes command caas sandboxes cancel-command ``` | Command | What it does | | --- | --- | | `caas sandboxes exec ID -- COMMAND [ARGS...]` | Runs a command in the sandbox, waits for it, prints its output and exits with its exit code. | | `caas sandboxes command ID COMMAND_ID` | Shows a command's state, exit code and output. | | `caas sandboxes cancel-command ID COMMAND_ID` | Stops a running command. | `exec` takes these options before `--`: | Option | What it does | | --- | --- | | `--timeout-ms MS` | The command's time limit in milliseconds: 1000 (1 second) to 7200000 (2 hours). The default is 600000 (10 minutes). | | `--detach` | Print the command's ID and return without waiting. | As with `caas run`, the command runs without a shell. A command sent to a sandbox that stopped while idle starts it again. ### Snapshots A sandbox that keeps state takes a snapshot of `/workspace` every hour, when it stops, and every night, at 02:00 in the workspace's time zone unless you move it. You can also take your own. ```sh caas sandboxes snapshot --name before-upgrade caas sandboxes snapshots caas sandboxes stop caas sandboxes restore --snapshot caas sandboxes delete-snapshot caas sandboxes schedule --at 03:30 --time-zone Europe/Berlin caas sandboxes schedule --off ``` | Command | What it does | | --- | --- | | `caas sandboxes snapshot ID [--name NAME]` | Takes a snapshot of a running sandbox. Without `--name`, it's named `manual`. Names follow the same rules as sandbox names. | | `caas sandboxes snapshots ID` | Lists the snapshots: ID, name, kind, when each was taken, its size and which one is current. Then the bytes stored and the nightly schedule. | | `caas sandboxes restore ID --snapshot SNAPSHOT_ID` | Restores a snapshot onto a stopped or failed sandbox and starts it. Stop the sandbox first. | | `caas sandboxes delete-snapshot ID SNAPSHOT_ID` | Deletes a snapshot. | | `caas sandboxes schedule ID --at HH:MM [--time-zone ZONE]` | Moves the nightly snapshot to this 24-hour time, in an IANA time zone such as `Europe/Berlin`. | | `caas sandboxes schedule ID --off` | Turns the nightly snapshot off. | Snapshots you take stay until you delete them. caas.sh keeps the newest 7 nightly snapshots. See [Sandboxes](/docs/sandboxes) for how snapshots work. ### Sandbox URLs A sandbox can serve one HTTP port at its own address, `https://