# CLI reference

The CLI creates and manages disposable computers. Run `celesto COMMAND --help` for the current options on your installed version; this page helps you choose the right command. `celesto sandbox` is an equivalent spelling for every `celesto computer` subcommand.

## Prepare your machine

| Command | Use it to |
| --- | --- |
| `celesto setup` | Install or check local runtime dependencies. Add `--macos` to prepare the runtime for macOS computers. |
| `celesto doctor` | Check whether this machine can run computers. Use `--backend vz` to check macOS computer support. |
| `celesto bridge check BRIDGE` | Check an existing Linux bridge before connecting a computer to it. |
| `celesto update` | Upgrade to the latest stable release. |
| `celesto prune` | Remove stale cached images (alias for `celesto image prune`). |

On Linux, `celesto setup` stores Firecracker—the program that starts a computer—in `~/.celesto/bin`. Use `--firecracker-dir` to choose another folder for one setup run:

```bash
celesto setup --firecracker-dir "$HOME/.local/bin"
```

Set `CELESTO_FIRECRACKER_DIR` when future commands also need to find a folder that is not on `PATH`. See [Install Celesto](../installation.md) for Fedora Atomic and build-machine setup.

## Local usage telemetry

Celesto gives you a first-use notice before local CLI usage telemetry starts. It counts active installations and broad features used. It does not send commands, file paths, URLs, or computer names as event properties. PostHog may derive an approximate location, such as country or city, from the IP address used to deliver an event and may retain that address. See the [privacy policy](https://celesto.ai/legal/privacy-policy) for details.

```bash
celesto config telemetry       # Show the effective setting
celesto config telemetry off   # Stop sending usage events
celesto config telemetry on    # Allow usage events again
```

The Python SDK reads the same saved setting. Set `CELESTO_NO_TELEMETRY=1` or `DO_NOT_TRACK=1` in the CLI or SDK environment to turn telemetry off without using the command. Those environment settings take precedence over `celesto config telemetry on`. CI and pytest runs do not send usage events.

## Work with computers

Run these in the order you need them:

| Command | Use it to |
| --- | --- |
| `celesto computer create` | Create a minimal local computer. Add `--desktop` for a computer with a Linux desktop, `--os macos` or `--os windows` for another operating system, or `--cloud` for Celesto Cloud. Add `--network bridge --bridge BRIDGE` when a local computer should appear on an existing network bridge. |
| `celesto computer list` / `info` | Find or inspect local computers. Add `--desktop` to list computers created with `--desktop`, or `--cloud` for cloud computers. |
| `celesto computer shell` / `ssh` | Open a shell. `shell` uses Celesto's fast control channel when available; `ssh` explicitly uses SSH. |
| `celesto computer desktop` | Open a macOS computer's screen in the Screen Sharing app on your Mac. Add `--start` to start a stopped computer first. For computers created with `--desktop`, use `celesto computer open` instead. |
| `celesto computer exec` | Run one command and return its exit code. Put the command after `--`, e.g. `celesto computer exec demo -- ls -la`. Add `--start` to start a stopped local computer first, `--desktop` for a computer created with `--desktop`, or `--cloud` for a cloud computer. |
| `celesto computer logs` | Show a computer's boot and console logs. Add `--follow` to keep printing new lines. |
| `celesto computer start` / `stop` | Start or stop a computer. |
| `celesto computer pause` / `resume` | Temporarily freeze and continue a running computer. |
| `celesto computer delete` | Remove one or more local computers. Add `--desktop` for a computer created with `--desktop`, or `--cloud` for a cloud computer. |
| `celesto computer prune` | Delete disks and logs left behind by computers that no longer exist. Add `--dry-run` to list those files without deleting them. Disks you asked Celesto to save are kept unless you add `--include-saved`. |

### Computer data and connections

| Command | Use it to |
| --- | --- |
| `celesto computer file upload` / `download` | Copy a file in or out. |
| `celesto computer env set` / `unset` / `list` | Manage persistent environment variables. |
| `celesto computer port expose` / `close` / `list` | Manage local port forwarding. |
| `celesto computer snapshot create` / `restore` / `list` / `delete` | Save and restore a supported computer's state. |

## Manage downloaded images

The first time you start a computer or agent, Celesto downloads the files it boots from and keeps them on disk so later starts are fast. These commands manage that storage, and they work like Docker's image commands if you know those:

| Command | Use it to |
| --- | --- |
| `celesto image pull <preset>` | Download an image ahead of time, for example before going offline. |
| `celesto image pull --all` | Download every image available for this machine in one go. |
| `celesto images` (or `image list` / `image ls`) | See which images are downloaded, when, and how much space they use. |
| `celesto image inspect <name>` | See one image in detail: files, checksums, and where it came from. |
| `celesto image build -t NAME .` | Build a custom image from a Dockerfile (needs Docker installed). |
| `celesto image build --os macos --ipsw latest -t NAME` | Prepare a reusable macOS image locally from an Apple restore file. |
| `celesto image save <name> -o FILE` / `image load -i FILE` | Copy an image to a machine without internet access. |
| `celesto image rm <name>` | Remove a downloaded image to free disk space. |
| `celesto image prune` | Remove images left behind by older Celesto versions. |

Images are stored in `~/.celesto/images`. To keep them somewhere else, set the `CELESTO_IMAGE_DIR` environment variable — computers read it too, so images you pull are found when a computer starts. The `--image-dir` option points a single `celesto image` command at a different folder; computers do not read that folder.

## Desktops, cloud computers, browsers, and services

| Command | Use it to |
| --- | --- |
| `celesto browser start` / `open` / `list` / `logs` / `stop` | Manage browser sessions. |
| `celesto auth login` | Save a cloud API key for later `--cloud` commands. |
| `celesto computer create --desktop --name NAME` | Start a local computer with a Linux desktop, a browser-based viewer, and Chromium. |
| `celesto computer list --desktop` / `open NAME` / `delete NAME --desktop` | Find that computer, open its desktop viewer in your browser, or delete it. |
| `celesto computer create --cloud` / `list --cloud` / `info ID --cloud` | Create, find, or inspect cloud computers. |
| `celesto computer start ID --cloud` / `stop ID --cloud` | Resume or stop a cloud computer. Without `--cloud`, `start` and `stop` act on local computers. |
| `celesto computer port publish` / `unpublish` | Publish or unpublish a cloud computer's port on a public URL. Local `port expose` only forwards to your machine. |
| `celesto computer templates` | List the available desktop templates. |
| `celesto ui` | Start the local dashboard and open the private sign-in link it prints. |
| `celesto server start` | Start the local HTTP API; use its printed token in `Authorization: Bearer <token>`. |
| `celesto windows build-image` | Build a Windows qcow2 image. |

Computer commands select local execution by default; `--local` makes that choice explicit.
Set `CELESTO_DASHBOARD_TOKEN` or `CELESTO_SERVER_TOKEN` before binding the corresponding service beyond localhost. See [secure local access](../security.md#open-the-dashboard) for token handling and browser-origin requirements.
Use `--cloud` for cloud `create`, `list`, `info`, `start`, `stop`, `ssh`, `exec`, and `delete` commands; it cannot be combined with `--local`.
Cloud `list` requests at most 50 computers by default; add `--limit NUMBER` to request more. If the response fills the limit, Celesto warns that more computers may exist, and JSON output sets `possibly_truncated` to `true`.
The existing `open`, `logs`, and `templates` commands remain local-only.
See [Run locally or in the cloud](../local-first.md) for setup, examples, and current cloud limits.

## Shell completion

Turn on tab completion so your shell can finish `celesto` commands, options, and the names of your existing computers as you type. One command sets it up:

```bash
celesto completion bash --install   # also works with: zsh, fish
```

Open a new shell afterward, then type `celesto computer ssh` followed by a space and press Tab to complete a computer name.

Prefer to wire it up yourself? Run the same command without `--install` to print the script, then load it your own way:

```bash
# bash — add to ~/.bashrc
eval "$(celesto completion bash)"

# zsh — add to ~/.zshrc
eval "$(celesto completion zsh)"

# fish — create the folder once, then write the completion file
mkdir -p ~/.config/fish/completions
celesto completion fish > ~/.config/fish/completions/celesto.fish
```

## Common options

`--json` is available on commands that return structured output. `--backend` selects `auto`, `firecracker`, `qemu`, `libkrun`, or `vz` where the command supports that runtime. The `vz` choice is only for macOS computers on Apple Silicon. `--boot-timeout` controls how long an operation waits for a computer to be ready.

**Implementation notes:** the command definitions are the source of truth in [`src/celesto/cli/commands/app.py`](../../src/celesto/cli/commands/app.py), including available flags and help text. The CLI command surface is tested by [`tests/cli/test_cli.py`](../../tests/cli/test_cli.py).