CLI Reference

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

pip install zeroruntime

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.

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

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.

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.

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.

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.

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.

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:

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.

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.

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.

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.

zeroruntime.yaml

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`

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 `zeroruntime.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 zeroruntime.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 `zeroruntime.yaml` file