CLI Reference

A complete reference for the zrt CLI. For a guided walkthrough, see Deploy an Agent and Managing Deployments. Install the CLI with pip (Python 3.11+):

pip install zrt

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.

How values are resolved

Every value a command needs is found in this order:

The flag you pass on the command line.
The matching field in zrt.yaml (e.g. agent.id, build.image).
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.

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.

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.

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.

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.

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.

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:

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.

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.

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.

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.

zrt.yaml

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`

Get started

Operate

Reference

How values are resolved

The typical flow

Authentication

Quickstart

Run locally

Initialize

Deploy

Take it down

Versions

`version list` flags

Secrets

Invoke

Sessions

`session list` flags

Logs

The `zrt.yaml` file

​How values are resolved

​The typical flow

​Authentication

​Quickstart

​Run locally

​Initialize

​Deploy

​Take it down

​Versions

​version list flags

​Secrets

​Invoke

​Sessions

​session list flags

​Logs

​The zrt.yaml file

How values are resolved

The typical flow

Authentication

Quickstart

Run locally

Initialize

Deploy

Take it down

Versions

`version list` flags

Secrets

Invoke

Sessions

`session list` flags

Logs

The `zrt.yaml` file