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

# CLI Reference

> Every Zero Runtime CLI command, grouped by what you use it for, with its flags and defaults.

A complete reference for the `zeroruntime` CLI. For a guided walkthrough, see
[Deploy an Agent](/deployments/deploy-an-agent) and
[Managing Deployments](/deployments/managing-deployments).

Install the CLI with pip (Python 3.11+):

```bash theme={null}
pip install zeroruntime
```

<Tip>
  Add `--help` to any command to see its flags, e.g. `zeroruntime up --help`. Most commands read
  missing values (agent ID, image, version) from `zeroruntime.yaml` in the current folder, so you
  rarely pass them by hand. Run commands from your project root.
</Tip>

## How values are resolved

Every value a command needs is found in this order:

1. The flag you pass on the command line.
2. The matching field in `zeroruntime.yaml` (e.g. `agent.id`, `build.image`).
3. A built-in default, otherwise the command tells you what's missing.

## The typical flow

These are the commands you'll run most, in the order you'll use them:

| Command                     | What it does                                                       |
| --------------------------- | ------------------------------------------------------------------ |
| `zeroruntime auth login`    | Sign in (opens the browser).                                       |
| `zeroruntime quickstart`    | Download an example agent and run it locally.                      |
| `zeroruntime run <project>` | Run an agent project locally.                                      |
| `zeroruntime init`          | Register the agent and generate `zeroruntime.yaml` + `Dockerfile`. |
| `zeroruntime up`            | Deploy your agent to Zero Runtime Cloud.                           |
| `zeroruntime invoke`        | Start your deployed agent in a room so you can talk to it.         |
| `zeroruntime logs`          | Stream your agent's console logs.                                  |
| `zeroruntime down`          | Take the agent offline.                                            |

## Authentication

| Command                   | Description                                               |
| ------------------------- | --------------------------------------------------------- |
| `zeroruntime auth login`  | Sign in to your Zero Runtime account (opens the browser). |
| `zeroruntime auth logout` | Sign out on this machine.                                 |
| `zeroruntime --version`   | Print the CLI version.                                    |

## Quickstart

`zeroruntime quickstart` downloads a ready-made example, drops it in a new folder, and runs it
locally so you can talk to it immediately. If you're not signed in, it logs you in first.

```bash theme={null}
zeroruntime quickstart                              # pick an example interactively
zeroruntime quickstart --template <example-id>      # use a specific example, skip the picker
zeroruntime quickstart --no-open                    # run locally but don't open the browser
```

| Flag                | Description                                | Default |
| ------------------- | ------------------------------------------ | ------- |
| `--template` / `-t` | Example id to use (skips the picker).      | prompt  |
| `--no-open`         | Don't open the playground in your browser. | off     |

## Run locally

`zeroruntime run <project>` runs an agent on your machine. Point it at a project folder or a single
`.py` file. It creates a virtual environment, installs `requirements.txt` once, and reads
provider keys from the project's `.env`.

```bash theme={null}
zeroruntime run my-agent --open       # playground mode, open in the browser
zeroruntime run my-agent --console    # console mode, talk in the terminal
zeroruntime run main.py --console     # run a single file
```

| Flag                  | Description                                                   | Default      |
| --------------------- | ------------------------------------------------------------- | ------------ |
| `--playground` / `-p` | Run in playground mode.                                       | on (default) |
| `--console` / `-c`    | Run in console mode (talk in the terminal). Requires sign-in. | off          |
| `--open` / `-o`       | Open the playground in your browser once the agent starts.    | off          |
| `--reset-env`         | Re-pick the Python environment for this file.                 | off          |

## Initialize

`zeroruntime init` registers an agent + deployment, writes the IDs to `zeroruntime.yaml`, and generates a
`Dockerfile` if your project doesn't have one.

```bash theme={null}
zeroruntime init --name my-agent
```

| Flag                | Description                              | Default          |
| ------------------- | ---------------------------------------- | ---------------- |
| `--name` / `-n`     | Agent name.                              | server-generated |
| `--template` / `-t` | Template id to associate with the agent. | none             |

## Deploy

`zeroruntime up` deploys your agent to Zero Runtime Cloud in a single command, using sensible
defaults.

```bash theme={null}
zeroruntime up                    # deploy the agent
zeroruntime up --env .env         # also upload provider keys from .env as secrets
```

| Flag             | Description                                                      | Default                 |
| ---------------- | ---------------------------------------------------------------- | ----------------------- |
| `--env` / `-e`   | Upload keys from this `.env` file as a secret set for the agent. | none                    |
| `--image` / `-i` | Image name and tag (e.g. `my-agent:0.0.1`).                      | `build.image` from yaml |
| `--file` / `-f`  | Path to the Dockerfile.                                          | `./Dockerfile`          |

On success, the new `version.id` is saved to `zeroruntime.yaml`.

## Take it down

`zeroruntime down` deactivates all active versions so they stop using resources.

```bash theme={null}
zeroruntime down            # confirms first
zeroruntime down --yes      # skip the confirmation
zeroruntime down --force    # deactivate even versions with active sessions
```

| Flag           | Description                                    | Default |
| -------------- | ---------------------------------------------- | ------- |
| `--yes` / `-y` | Skip the confirmation prompt.                  | off     |
| `--force`      | Deactivate even versions with active sessions. | off     |

## Versions

A **version** is one immutable, deployed configuration. Every `zeroruntime up` creates a new one.

```bash theme={null}
zeroruntime version list                          # all versions (the active one is marked)
zeroruntime version status                        # rollout state of the latest version
zeroruntime version describe -v <version-id>      # full details for one version
zeroruntime version activate -v <version-id>      # make a version live
zeroruntime version deactivate -v <version-id>    # take a version offline
```

| Command                                  | Description                                                   |
| ---------------------------------------- | ------------------------------------------------------------- |
| `zeroruntime version list`               | List all versions (paginated).                                |
| `zeroruntime version status`             | Rollout status of a version (latest if no `-v`).              |
| `zeroruntime version describe`           | Full details for a version.                                   |
| `zeroruntime version activate -v <id>`   | Activate a version.                                           |
| `zeroruntime version deactivate -v <id>` | Deactivate a version (`--force` to override active sessions). |

### `version list` flags

| Flag         | Description                          | Default |
| ------------ | ------------------------------------ | ------- |
| `--page`     | Page number (`1`+).                  | `1`     |
| `--per-page` | Items per page (`1` to `100`).       | `10`    |
| `--sort`     | `-1` newest first, `1` oldest first. | `-1`    |

## Secrets

Secrets are environment variables (provider keys, tokens) injected into your running
agent. The easiest way to set them is `zeroruntime up --env .env`; you can also manage sets
directly:

```bash theme={null}
zeroruntime secrets list                       # all secret sets
zeroruntime secrets create my-secrets -f .env  # create a set from a file
zeroruntime secrets describe my-secrets        # show keys (values hidden)
zeroruntime secrets add my-secrets             # add keys interactively
zeroruntime secrets remove my-secrets          # remove keys interactively
zeroruntime secrets delete my-secrets          # delete the whole set
```

| Command                                     | Description                                                       |
| ------------------------------------------- | ----------------------------------------------------------------- |
| `zeroruntime secrets list`                  | List all secret sets.                                             |
| `zeroruntime secrets create <name> -f .env` | Create a set from a file (omit `-f` to enter keys interactively). |
| `zeroruntime secrets describe <name>`       | Show the keys in a set (values hidden).                           |
| `zeroruntime secrets add [name]`            | Add keys interactively (picks a set if `name` is omitted).        |
| `zeroruntime secrets remove <name>`         | Remove keys interactively.                                        |
| `zeroruntime secrets delete <name>`         | Delete the whole set.                                             |

## Invoke

`zeroruntime invoke` starts your deployed agent in a room so you can talk to it.

```bash theme={null}
zeroruntime invoke                          # start in a fresh room, print a playground link
zeroruntime invoke --console                # start, then talk to it in your terminal
zeroruntime invoke --room-id <room-id>      # start in a specific room
```

| Flag                | Description                                           | Default              |
| ------------------- | ----------------------------------------------------- | -------------------- |
| `--agent-id` / `-a` | Agent to start.                                       | `agent.id` from yaml |
| `--room-id` / `-r`  | Room to join.                                         | new room             |
| `--console` / `-c`  | Talk to the agent in your terminal. Requires sign-in. | off                  |

## Sessions

A session is one live conversation. `zeroruntime invoke` starts one; `session` lists and stops them.

```bash theme={null}
zeroruntime session list                      # sessions for this agent
zeroruntime session stop --room-id <room-id>  # stop a session by room
zeroruntime session stop --session-id <id>    # stop a session by session id
```

| Command                                 | Description                                                    |
| --------------------------------------- | -------------------------------------------------------------- |
| `zeroruntime session list`              | List sessions for the agent.                                   |
| `zeroruntime session stop -r <room-id>` | Stop a session by room (`-s <session-id>` to stop by session). |

### `session list` flags

| Flag         | Description                          | Default |
| ------------ | ------------------------------------ | ------- |
| `--room-id`  | Only sessions in this room.          | none    |
| `--page`     | Page number (`1`+).                  | `1`     |
| `--per-page` | Items per page (`1` to `100`).       | `10`    |
| `--sort`     | `-1` newest first, `1` oldest first. | `-1`    |

## Logs

`zeroruntime logs` streams console output from your running agent.

```bash theme={null}
zeroruntime logs                        # most recent 50 lines, newest first
zeroruntime logs --limit 200 --sort 1   # 200 lines, oldest first
zeroruntime logs --since 1h             # last hour
zeroruntime logs --since 30m --until 5m # a specific window
```

| Flag                  | Description                                              | Default              |
| --------------------- | -------------------------------------------------------- | -------------------- |
| `--limit` / `-n`      | Number of log lines (`1` to `1000`).                     | `50`                 |
| `--sort`              | `-1` newest first, `1` oldest first.                     | `-1`                 |
| `--since`             | Start of the window (e.g. `30m`, `2h`, `1d`, or a date). | none                 |
| `--until`             | End of the window.                                       | now                  |
| `--version-id` / `-v` | Logs for a specific version.                             | latest               |
| `--agent-id`          | Agent to read logs for.                                  | `agent.id` from yaml |

## The `zeroruntime.yaml` file

The CLI stores deployment state in `zeroruntime.yaml` so commands can run without repeating flags.
You rarely edit it by hand; each command fills in the values it produces.

```yaml zeroruntime.yaml theme={null}
version: "1.0"
agent:
  id: ag_xxxxxxxx          # set by `zeroruntime init`
  name: my-agent
build:
  image: my-agent:0.0.1    # set by `zeroruntime up`
deploy:
  id: dep_xxxxxxxx         # set by `zeroruntime init`
  version: vr_xxxxxxxx     # set by `zeroruntime up`
secrets:
  env: my-secrets          # set by `zeroruntime up --env` / `zeroruntime secrets create`
```