> ## 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 with its flags and defaults.

Every `zeroruntime` command and flag. For walkthroughs, start at
[Zero Runtime Cloud](/runtime-sdk/deployments/zeroruntime-cloud) or [Operate](/runtime-sdk/deployments/operate/overview).

<Tip>
  Add `--help` to any command to see its flags, such as `zeroruntime up --help`. Values you
  don't pass are read from `zeroruntime.yaml`; see
  [how the CLI tracks state](/runtime-sdk/deployments/operate/overview#how-the-cli-tracks-state).
</Tip>

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

Download an example agent into a new folder and run it locally. Signs you in first if needed.

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

`zeroruntime run <project>` runs an agent locally. `<project>` is a folder or a single `.py`
file. It creates a virtual environment, installs `requirements.txt` once, and reads keys from
the project's `.env`.

| Flag | Description | Default |
| - | - | - |
| `--playground` / `-p` | Run in playground mode. | on |
| `--console` / `-c` | Talk to the agent in your 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 |

## `init`

Register an agent and deployment, write their IDs to `zeroruntime.yaml`, and generate a
`Dockerfile` if the project doesn't have one.

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

## `up`

Build the next image and deploy it to Zero Runtime Cloud. Saves the new `version.id` to
`zeroruntime.yaml`. See [Version Management](/runtime-sdk/deployments/operate/version-management) for how
image tags are chosen.

| Flag | Description | Default |
| - | - | - |
| `--env` / `-e` | Upload keys from this `.env` file as a secret set for the agent. | none |
| `--version` | Version to build, as `vX.Y`. Build only. | next version |
| `--image` / `-i` | Image to build or deploy, as `<agent-id>:vX.Y`. | `build.image` from yaml |
| `--skip-build` | Deploy an existing image instead of building. Use with `--image`. | off |
| `--file` / `-f` | Path to the Dockerfile. | `./Dockerfile` |

## `down`

Deactivate all active versions of the deployment.

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

## `version`

Commands that take `-v` use the `vr_…` version ID shown by `version list`.

| Command | Description |
| - | - |
| `zeroruntime version list` | List all versions (paginated). |
| `zeroruntime version describe` | Rollout status of a version (latest if no `-v`). |
| `zeroruntime version describe -v <id>` | 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`

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

Start your deployed agent in a room and print a playground link.

| 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 |

## `session`

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

Stream console output from your running agent.

| 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 |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.