Warp CLI (oz) reference overview

Complete reference for the oz CLI — the command-line tool for launching, managing, and orchestrating Warp cloud agents from your terminal.

The oz CLI is the primary command-line interface for Warp’s cloud agent orchestration platform. It lets you run AI coding agents in the cloud, manage environments and secrets, schedule recurring tasks, and inspect run history — all from your terminal. The binary is distributed as oz (with warp available as an alias) and is bundled directly with the Warp application, so no separate installation step is required.

Installation

The oz CLI ships inside the Warp application bundle. Once Warp is installed, the oz binary is available in your PATH automatically. You can confirm it is working by running:

oz --help

If you use the warp alias instead, every command works identically:

warp agent run --prompt "Build anything"

Quick examples

oz agent run --prompt "Build anything"
oz mcp list

Global options

Every oz command accepts the following flags, regardless of subcommand.

--api-key · string

API key for authentication. Equivalent to setting the WARP_API_KEY environment variable. Use this for CI/CD pipelines and non-interactive environments.

--output-format · string · default: "pretty"

Controls how command output is rendered. Accepted values: pretty (human-readable, default), json, ndjson, text. Equivalent to setting the WARP_OUTPUT_FORMAT environment variable.

--debug · boolean

Enable verbose debug logging. Useful when troubleshooting unexpected behaviour.

Output formats

All oz commands support four output formats, selectable via --output-format or the WARP_OUTPUT_FORMAT environment variable:

Value	Description
pretty	Human-readable output with colour and formatting (default)
json	Full JSON object per response, suitable for jq and scripting
ndjson	Newline-delimited JSON — one JSON object per line, ideal for streaming pipelines
text	Plain text output with no decoration

# Machine-readable JSON
oz run list --output-format json

# Streaming pipeline
oz run list --output-format ndjson | jq '.state'

The help system

Every command and subcommand supports a --help flag that prints its full usage, flags, and a description.

# Top-level help
oz help

# Help for a specific command
oz agent --help
oz agent run --help
oz run list --help

Shell completions

The oz CLI can generate shell completion scripts for bash, zsh, fish, and PowerShell.

bash

Add the following line to your ~/.bashrc:

source <(oz completions bash)

zsh

Add the following line to your ~/.zshrc:

source <(oz completions zsh)

fish

Add the following line to your ~/.config/fish/config.fish:

oz completions fish | source

PowerShell

Add the following line to your $PROFILE:

oz completions powershell | Out-String | Invoke-Expression

Commands

oz agent

Run and manage AI coding agents locally and in the cloud.

oz run

List and inspect agent task runs.

oz environment

Create and manage cloud environments for agent runs.

oz mcp

Manage Model Context Protocol servers.

oz secret

Store and retrieve secrets for use in agent runs.

oz schedule

Schedule agents to run on a cron schedule.

oz model

List available AI models.