> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/warpdotdev/warp/llms.txt
> Use this file to discover all available pages before exploring further.

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

```bash theme={null}
oz --help
```

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

```bash theme={null}
warp agent run --prompt "Build anything"
```

## Quick examples

```bash theme={null}
oz agent run --prompt "Build anything"
oz mcp list
```

## Global options

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

<ParamField path="--api-key" type="string">
  API key for authentication. Equivalent to setting the `WARP_API_KEY` environment variable. Use this for CI/CD pipelines and non-interactive environments.
</ParamField>

<ParamField path="--output-format" type="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.
</ParamField>

<ParamField path="--debug" type="boolean">
  Enable verbose debug logging. Useful when troubleshooting unexpected behaviour.
</ParamField>

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

```bash theme={null}
# 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.

```bash theme={null}
# 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.

<Tabs>
  <Tab title="bash">
    Add the following line to your `~/.bashrc`:

    ```bash theme={null}
    source <(oz completions bash)
    ```
  </Tab>

  <Tab title="zsh">
    Add the following line to your `~/.zshrc`:

    ```bash theme={null}
    source <(oz completions zsh)
    ```
  </Tab>

  <Tab title="fish">
    Add the following line to your `~/.config/fish/config.fish`:

    ```bash theme={null}
    oz completions fish | source
    ```
  </Tab>

  <Tab title="PowerShell">
    Add the following line to your `$PROFILE`:

    ```bash theme={null}
    oz completions powershell | Out-String | Invoke-Expression
    ```
  </Tab>
</Tabs>

## Commands

<CardGroup cols={2}>
  <Card title="oz agent" icon="robot" href="/cli/agent">
    Run and manage AI coding agents locally and in the cloud.
  </Card>

  <Card title="oz run" icon="list" href="/cli/run">
    List and inspect agent task runs.
  </Card>

  <Card title="oz environment" icon="box" href="/cli/environment">
    Create and manage cloud environments for agent runs.
  </Card>

  <Card title="oz mcp" icon="plug" href="/cli/mcp">
    Manage Model Context Protocol servers.
  </Card>

  <Card title="oz secret" icon="lock" href="/cli/secret">
    Store and retrieve secrets for use in agent runs.
  </Card>

  <Card title="oz schedule" icon="clock" href="/cli/schedule">
    Schedule agents to run on a cron schedule.
  </Card>

  <Card title="oz model" icon="cpu" href="/cli/model">
    List available AI models.
  </Card>
</CardGroup>