> ## Documentation Index > Fetch the complete documentation index at: https://docs.sailresearch.com/llms.txt > Use this file to discover all available pages before exploring further. # CLI reference > Every sail command, grouped by area The `sail` CLI manages sailboxes and apps from the terminal. To install it, see [Install the CLI](/cli). Run `sail --help` or `sail --help` for the same information at the prompt. ## Interactive shell For interactive use, `sail shell` is usually the most convenient option. It opens a REPL on your machine that accepts every command below without the leading `sail` (so `box list`, `box create ...`), and adds touches the one-shot commands do not: line editing and history, a picker menu when you omit a sailbox id, and confirmation prompts. ```bash theme={null} sail shell ``` The individual `sail ` subcommands are non-interactive and take their arguments up front, which suits scripts and agents (add `--json` for machine-readable output). Mind the naming: `sail shell` is a shell for *managing* sailboxes from your machine. It is not a shell *inside* a box. To open a shell inside a running sailbox, use `sail box shell` (below). ## Global options These work on any command. | Option | Effect | | -------- | ---------------------------------------------------------- | | `--json` | Emit machine-readable JSON instead of human-readable text. | | `--help` | Show help for the CLI or a command. | `sail --version` prints the CLI version (top-level only). Authentication comes from `SAIL_API_KEY`, falling back to the credential stored by `sail auth login`. See [Configuration](/sdk-configuration). ## Authentication ```bash theme={null} sail auth login [--api-key ] # browser login, or store/validate a key (also reads a piped key) sail auth whoami # show the active key sail auth logout # remove the stored key ``` ## Apps ```bash theme={null} sail app find # find an app by name sail app create # create an app (returns the existing one if present) sail app list # list apps in the current org ``` ## Sailbox lifecycle | Command | Description | | ------------------------------------------ | -------------------------------------------------------- | | `sail box show ` | Show a single sailbox. | | `sail box list` | List sailboxes in the current org (see flags below). | | `sail box terminate ` | Permanently terminate a sailbox. | | `sail box sleep ` | Checkpoint and release compute. | | `sail box pause ` | Freeze in place. | | `sail box resume ` | Resume a paused or sleeping sailbox. | | `sail box checkpoint ` | Checkpoint a running sailbox. | | `sail box from-checkpoint ` | Create a new sailbox from a checkpoint (`--name`). | | `sail box upgrade ` | Upgrade the runtime (now if running, else at next wake). | ### `sail box create` ```bash theme={null} sail box create --app --name [options] ``` | Option | Description | | ------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `--app ` | App name (created if missing). Required. | | `--name ` | Sailbox name within the app. Required. | | `--arch ` | Base image architecture (default `arm`). | | `--port ` | HTTP ingress port to expose. Repeatable. | | `--size ` | Resource size (default `m`): `s` = 1 vCPU, 16 GB memory, 32 GB disk; `m` = 4 vCPU, 32 GB memory, 128 GB disk. Billing is by usage, so a bigger size costs no more on its own. `s` gives the fastest cold starts, forks, and resumes, and its lower ceilings cap what a runaway workload can consume. | | `--memory-gib ` | Memory ceiling in whole GiB, within the size's range: 2-64 for `s`, 8-128 for `m`. The size's default when omitted. | | `--disk-gib ` | Disk size in whole GiB, within the size's range: 8-128 for `s`, 32-512 for `m`. The size's default when omitted. | | `--enable-ssh` | Expose port 22, trust your org's CA, and start sshd. | | `--identity-file ` | Local SSH key to authenticate with (implies `--enable-ssh`). | ### `sail box list` | Option | Description | | ------------------- | ---------------------------- | | `--app ` | Filter by app name. | | `--status ` | Filter by status. | | `--search ` | Filter by id/name substring. | | `--limit ` | Maximum rows. | | `--offset ` | Rows to skip. | ## Run commands and connect ### `sail box exec` Run a command in a sailbox, streaming its output. ```bash theme={null} sail box exec [options] -- [args...] ``` | Option | Description | | ----------------- | ---------------------------------------------------------------- | | `--cwd ` | Working directory inside the guest. | | `--timeout ` | Kill the command after this long (e.g. `30s`, `5m`). | | `-i`, `--stdin` | Pipe local stdin to the guest command. | | `-t`, `--tty` | Run under a pseudo-terminal driven by your terminal. | | `--background` | Start the command and return once accepted (no output captured). | ### `sail box run` Create an ephemeral sailbox, run a command, then terminate it. A shortcut for `create` + `exec` + `terminate`; for workflows that reuse a sailbox, use those directly. ```bash theme={null} sail box run --app [options] -- [args...] ``` Takes the same `create` sizing/port flags plus `--name` (default `run-`), `--cwd`, `--timeout`, and `--keep` (leave the sailbox running instead of terminating it). ### `sail box shell` ```bash theme={null} sail box shell [--shell ] ``` Open an interactive shell inside a running sailbox. This is the simplest and preferred way in: it runs a PTY over `exec`, so it opens no port and does not count against your org's port allocation. (Not to be confused with `sail shell`, the local REPL for managing boxes.) ### `sail box cp` ```bash theme={null} sail box cp ``` Copy a file to or from a sailbox; `:` denotes the remote side. ## Networking ```bash theme={null} sail box expose [--tcp] [--allowlist ]... # expose a guest port at runtime sail box unexpose # remove a runtime ingress port sail box listeners # list a sailbox's ingress listeners sail box address # print the external address for one port ``` `--tcp` exposes raw TCP instead of HTTP. `--allowlist` restricts sources to a CIDR prefix (e.g. `203.0.113.0/24`), or, for HTTP listeners, a Sail app name. See [Networking](/sailboxes-networking) for the full model. ## SSH `sail box ssh` sets up SSH access so you can reach a box as `ssh .sail`. For a quick interactive shell, prefer [`sail box shell`](#sail-box-shell): it needs no open port. Reach for SSH when you need a real SSH endpoint rather than a PTY over `exec`, such as `scp`/`rsync`, an editor's remote mode, or a devbox you work in day to day. Enabling it exposes port 22 as a TCP ingress port, which counts against your org's port allocation. ```bash theme={null} sail box ssh enable [--identity-file ] [--no-wait] [--timeout ] sail box ssh alias ... [--identity-file ] sail box ssh disable ``` * **enable**: turn on SSH for a box (expose port 22, install your org's CA, start sshd), certify your key on this machine, and add the `.sail` shortcut. * **alias**: add `ssh .sail` shortcuts for boxes already SSH-enabled elsewhere (e.g. from the SDK), without waking them. * **disable**: stop SSH on a box and drop its local shortcut. Only the public half of your key is certified; the private key is referenced in your SSH config, never read. ## Configuration Manage `~/.sail/config.toml`. ```bash theme={null} sail config get [key] # print one value, or the whole file sail config set ... # set one or more entries sail config unset ... # remove one or more keys sail config reset # reset user-settable settings (run 'sail auth logout' to remove the stored key) ```