> ## 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 `zrt` 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 zrt
```

<Tip>
  Add `--help` to any command to see its flags, e.g. `zrt up --help`. Most commands read
  missing values (agent ID, image, version) from `zrt.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 `zrt.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                                               |
| ------------------- | ---------------------------------------------------------- |
| `zrt auth login`    | Sign in (opens the browser).                               |
| `zrt quickstart`    | Download an example agent and run it locally.              |
| `zrt run <project>` | Run an agent project locally.                              |
| `zrt init`          | Register the agent and generate `zrt.yaml` + `Dockerfile`. |
| `zrt up`            | Deploy your agent to Zero Runtime Cloud.                   |
| `zrt invoke`        | Start your deployed agent in a room so you can talk to it. |
| `zrt logs`          | Stream your agent's console logs.                          |
| `zrt down`          | Take the agent offline.                                    |

## Authentication

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

## Quickstart

`zrt 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}
zrt quickstart                              # pick an example interactively
zrt quickstart --template <example-id>      # use a specific example, skip the picker
zrt 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

`zrt 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}
zrt run my-agent --open       # playground mode, open in the browser
zrt run my-agent --console    # console mode, talk in the terminal
zrt 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

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

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

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

## Deploy

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

```bash theme={null}
zrt up                    # deploy the agent
zrt 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 `zrt.yaml`.

## Take it down

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

```bash theme={null}
zrt down            # confirms first
zrt down --yes      # skip the confirmation
zrt 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 `zrt up` creates a new one.

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

| Command                          | Description                                                   |
| -------------------------------- | ------------------------------------------------------------- |
| `zrt version list`               | List all versions (paginated).                                |
| `zrt version status`             | Rollout status of a version (latest if no `-v`).              |
| `zrt version describe`           | Full details for a version.                                   |
| `zrt version activate -v <id>`   | Activate a version.                                           |
| `zrt 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 `zrt up --env .env`; you can also manage sets
directly:

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

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

## Invoke

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

```bash theme={null}
zrt invoke                          # start in a fresh room, print a playground link
zrt invoke --console                # start, then talk to it in your terminal
zrt 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. `zrt invoke` starts one; `session` lists and stops them.

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

| Command                         | Description                                                    |
| ------------------------------- | -------------------------------------------------------------- |
| `zrt session list`              | List sessions for the agent.                                   |
| `zrt 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

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

```bash theme={null}
zrt logs                        # most recent 50 lines, newest first
zrt logs --limit 200 --sort 1   # 200 lines, oldest first
zrt logs --since 1h             # last hour
zrt 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 `zrt.yaml` file

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

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