> ## Documentation Index
> Fetch the complete documentation index at: https://docs.celesto.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Celesto CLI reference

> Use the celesto CLI to authenticate, create computers, run commands, publish ports, and manage sandbox lifecycle from the terminal.

The `celesto` CLI lets you manage Celesto from your terminal. Use it for one-off sandbox work, scripts, and debugging SDK workflows.

## Install and sign in

Install or upgrade the CLI:

```bash theme={null}
pip install -U celesto
```

Save your API key once:

```bash theme={null}
celesto auth login
```

Check or remove the saved key later:

```bash theme={null}
celesto auth status
celesto auth logout
```

## Create your first computer

Create a computer with the default `scratch` template. The command prints a generated name. Use that name in later commands.

```bash theme={null}
celesto computer create
# Name:   einstein
# ID:     cmp_123
# Status: creating
```

Inspect the computer by name or ID:

```bash theme={null}
celesto computer get einstein
# Name:   einstein
# Status: running
```

List your computers:

```bash theme={null}
celesto computer list
```

Run a command inside the computer:

```bash theme={null}
celesto computer run einstein "uname -a"
```

Open an interactive terminal. SSH means an interactive shell connection to the computer.

```bash theme={null}
celesto computer ssh einstein
```

Stop and start the same computer when you want to keep its files for later:

```bash theme={null}
celesto computer stop einstein
celesto computer start einstein
```

Delete the computer when you are done:

```bash theme={null}
celesto computer delete einstein
```

## Computer commands

| Command                                                                                | Description                            |
| -------------------------------------------------------------------------------------- | -------------------------------------- |
| `celesto computer create [--template ID] [--cpus N] [--memory MB] [--disk-size-mb MB]` | Create a computer                      |
| `celesto computer templates`                                                           | List templates with preinstalled tools |
| `celesto computer list [--status STATUS] [--template ID] [--project ID] [--limit N]`   | List matching computers                |
| `celesto computer get NAME`                                                            | Get one computer by name or ID         |
| `celesto computer run NAME "command" [--timeout N]`                                    | Run a command on a computer            |
| `celesto computer run NAME "command" --stream`                                         | Stream command output while it runs    |
| `celesto computer ssh NAME`                                                            | Open an interactive terminal           |
| `celesto computer stop NAME`                                                           | Stop a computer                        |
| `celesto computer start NAME`                                                          | Start a stopped computer               |
| `celesto computer delete [--force] NAME`                                               | Delete a computer                      |

## Templates and resources

List templates when you want a computer with tools already installed:

```bash theme={null}
celesto computer templates
```

Create a computer from a template:

```bash theme={null}
celesto computer create --template coding-agent
# Name:   curie
# Status: creating
```

Override the template's default CPU, memory, or disk size when the job needs more room:

```bash theme={null}
celesto computer create --template coding-agent --cpus 2 --memory 2048 --disk-size-mb 15360
```

## Port commands

Publish a port when a process inside the computer needs a public HTTPS URL:

```bash theme={null}
celesto computer port publish einstein --port 8000
# https://p-test.celesto.ai
```

List published ports:

```bash theme={null}
celesto computer port list einstein
```

Unpublish the port when you are done:

```bash theme={null}
celesto computer port unpublish einstein --port 8000
```

| Command                                           | Description                                              |
| ------------------------------------------------- | -------------------------------------------------------- |
| `celesto computer port publish NAME [--port N]`   | Expose a port on the public internet. Defaults to `8000` |
| `celesto computer port list NAME`                 | List published ports for a computer                      |
| `celesto computer port unpublish NAME [--port N]` | Stop exposing a port. Defaults to `8000`                 |

## Auto-resume stopped computers

The `run` and `ssh` commands automatically resume a stopped computer before executing. You can run a command or open a terminal session without calling `start` first.

```bash theme={null}
celesto computer run einstein "uname -a"
celesto computer ssh einstein
```

## JSON output

Most computer commands support `--json` or `-j` for structured output. Use JSON in scripts and automation.

```bash theme={null}
celesto computer list --json
celesto computer create --template coding-agent --json
celesto computer run einstein "uname -a" --json
```

`celesto computer ssh` is interactive and does not support JSON output.

## Update command

Run `celesto update` to upgrade the `celesto` package in your current Python environment.

```bash theme={null}
celesto update
```

The command upgrades `celesto` using `pip` when it is available, and falls back to `uv` when you installed Celesto with `uv` or are running inside a `uv run` environment.

If neither `pip` nor `uv` is available, the command prints the exact command to run yourself, for example:

```bash theme={null}
uv pip install --python /path/to/python --upgrade celesto
```