Oz CLI

Use the Oz CLI to run, configure, and manage agents from the terminal.

warp-cli is deprecated and has been replaced by oz. If you have warp-cli installed, it will auto-update to oz. All the same commands are available, just replace warp-cli with oz in your scripts and workflows.

What is the Oz CLI?

The Oz CLI is the command-line tool that lets you run Cloud Agents from anywhere, including terminals, scripts, automated systems, or services.

It's the standard runtime entry point that turns a prompt plus configuration into an executable agent task that runs on either a Warp-hosted or self-hosted runner.

With the Oz CLI, you can:

• Run agents locally for development and debugging

• Run agents on remote machines

• Connect agents to MCP servers like GitHub and Linear

• Configure integrations that connect agents to Slack, Linear, and other trigger surfaces

Installing the CLI

You can install the Oz CLI as part of the Warp desktop app, or as a standalone package.

Bundled with Warp

The Oz CLI is automatically distributed with the Warp desktop app and can be used right away with the Warp terminal. To make the CLI globally available, add it your PATH.

macOS

To add the Oz CLI to your PATH:

1. Open the Command Palette (CMD+P )

2. In the search field, find and select the Install Oz CLI Command action.

Note: Administrator permissions are required to install the CLI into /usr/local/bin .

Windows

Linux

Standalone package

Warp provides standalone packages for the CLI on macOS and Linux, without the Warp app.

macOS

On macOS, we recommend that you install and update the standalone CLI with Homebrew, using the warpdotdev/warp tap:

$ brew tap warpdotdev/warp
$ brew update
$ brew install --cask oz

If you're using Warp Preview, install the preview version of the CLI instead:

brew install --cask oz@preview

---

You can also download the CLI directly from these URLs:

• Apple Silicon

• Intel

• Apple Silicon, Warp Preview

• Intel, Warp Preview

Note: These builds do not auto-update.

Linux

Windows

Running the CLI

The command to run the Oz CLI depends on your OS, whether you installed the CLI as part of Warp or as a standalone package, and whether you're using the stable build or Warp Preview.

OS	Installation Method	CLI Command	CLI Command (Preview)
macOS	Standalone	oz	oz-preview
macOS	Bundled	oz	oz-preview
Linux	Standalone	oz	oz-preview
Linux	Bundled	oz	oz-preview
Windows	Bundled	oz	oz-preview

Logging in

The Oz CLI supports two authentication methods, depending on where and how you're running agents.

• Interactive login — best for local machines where you have Warp installed and can authenticate through a browser.

• API keys — best for automated or remote environments that need to authenticate without human interaction.

Interactive login (local machines)

Use interactive login when you’re working on a machine where you already use the Warp app, or when you can open a browser to complete authentication.

If you use the CLI on a host where you're already signed in to Warp, it automatically reuses your existing credentials.

To authenticate interactively:

oz login

Replace oz with the appropriate command name for your installation method according to the table in Running the CLI.

The CLI prints out a URL that you can open in any browser to login to Warp.

API key authentication

Use an API key when the environment must authenticate on its own, such as CI pipelines, headless servers, VMs, Codespaces, or containers. API keys let the CLI authenticate non-interactively.

For detailed instructions on creating, managing, and using API keys, see API Keys.

Quick start:

$ export WARP_API_KEY="wk-xxx..."
$ oz agent run --prompt "analyze this codebase"

---

Running agents

The Oz CLI offers two ways to run agents, depending on where you want the work to happen:

Use oz agent run when:

• You're developing locally and want immediate feedback

• You need the agent to work with files in your current directory

• You want to inspect and modify the agent's work in real time

• You're debugging or iterating on prompts

Use oz agent run-cloud when:

• You want the agent to run on a remote machine or standardized environment

• You're triggering agent work from CI/CD or automated systems

• You need the agent to run independently of your local session

• You're delegating work that doesn't require your immediate attention

Running locally: `oz agent run`

To start an agent, use the oz agent run subcommand. You'll need to specify a prompt and, optionally, the MCP servers and agent profile to use.

oz agent run --prompt "set up a new Rust crate named warp-cli"
I'll run a few terminal commands to:
- Check if this is a Git repo and Cargo workspace
- Create a new binary crate named warp-cli

Key flags:

• --cwd <PATH> (-C) — run from a different directory.

• --name <NAME> (-n) — label the run for grouping and traceability.

• --share — share the session with teammates (see Collaboration).

• --profile <ID> — use a specific agent profile (see Using Agent Profiles).

• --model <MODEL_ID> — override the default model (see Model Choice).

• --skill <SPEC> — use a skill as the base prompt (see Using Skills).

• --mcp <SPEC> — start one or more MCP servers before execution (UUID, JSON file path, or inline JSON). Can be repeated.

• --environment <ID> (-e) — run in a specific cloud environment.

• --file <PATH> (-f) — load run configuration from a YAML or JSON file.

The agent will automatically carry out the task you gave it, printing out tool calls and responses as it works.

By default, the agent runs in your current working directory. To run from a different directory, use the -C/--cwd flag.

Running agents remotely: `oz agent run-cloud`

Cloud runs dispatch tasks to remote environments. Use cloud runs for:

• Background processing

• Standardized team configurations

• Remote execution on servers you don't directly access

oz agent run-cloud \
  --environment SVhg783GBFQHk1OfdPfFU9 \
  --name "Repo summary" \
  --prompt "Summarize this repo and list the top 5 risky areas" \
  --open

Key flags

• --environment <ENVIRONMENT_ID> (-e) — select the environment to run in.

• --no-environment — run without an environment (not recommended).

• --open — view the agent's session in Warp once it's available.

• --name <NAME> (-n) — label the run for grouping and traceability (see Naming runs below).

• --mcp <SPEC> — start one or more MCP servers before execution (UUID, JSON file path, or inline JSON). Can be repeated.

• --model <MODEL_ID> — override the default model.

• --skill <SPEC> — use a skill from the environment's repository as the base prompt (see Using Skills).

• --host <WORKER_ID> — run on a specific self-hosted worker instead of Warp-hosted infrastructure.

• --attach <PATH> — attach an image file to the agent query. Can be repeated (maximum 5).

• --computer-use / --no-computer-use — enable or disable Computer Use for this run.

• --file <PATH> (-f) — load run configuration from a YAML or JSON file.

Key differences from run

• No --cwd — the environment determines the working directory.

• No --share — sharing options are on run, not run-cloud.

• No --profile — cloud runs do not use agent profiles.

Naming runs

The --name flag assigns a config name to the run. Use it to group related runs under a shared label so you can filter, search, and track them later.

How names work:

• Skill-based runs — When you run an agent from a skill, the name is automatically set to the skill name. You don't need to pass --name explicitly.

• Custom runs — When you build your own automation (via the CLI, API, or SDK), set --name to a consistent value that describes the workflow's intent.

Why naming matters:

When your team runs many agents across schedules, integrations, and ad-hoc triggers, name lets you answer questions like "how many distinct workflows are we running?" and "how often does this particular workflow run?" You can filter runs by name using the name query parameter on GET /agent/runs in the Oz Agent API.

Examples:

# Name a recurring workflow for easy tracking
oz agent run-cloud \
  --environment SVhg783GBFQHk1OfdPfFU9 \
  --name "nightly-dependency-check" \
  --prompt "Check for outdated dependencies and open a PR with updates"

# Skill-based runs are named automatically
oz agent run-cloud \
  --environment SVhg783GBFQHk1OfdPfFU9 \
  --skill "myorg/backend:code-review" \
  --prompt "review the latest PR"

When cloud runs fail

• Verify your environment has the correct repository and context.

• Check that your profile allows the commands and MCP servers needed.

• Ensure environment variables are set in the environment, not your local shell.

Reusing saved prompts and Warp Drive objects

You can reuse saved prompts with --saved-prompt, and reference notebooks, workflows, and rules inline in any --prompt string. See Referencing Warp Drive objects for details.

Using agent profiles

Agent profiles control what the agent can do, how it behaves, and where it can act. Use the --profile flag with oz agent run to apply a specific profile.

See Agent profiles for how to find profile IDs and apply them.

Using MCP servers

MCP servers connect agents to external systems like GitHub, Linear, or Sentry. Use the --mcp flag with any of three formats: a Warp MCP server UUID, inline JSON, or a path to a JSON config file.

See MCP Servers for full details, including how to find UUIDs, combine multiple servers, and handle environment variables on remote machines.

Using skills

Skills are reusable instruction sets that teach agents how to perform specific tasks. Use the --skill flag to run an agent from a skill stored in a repository.

See Skills for supported spec formats and examples for both local and cloud agent runs.

Collaboration

In addition to text-based output, the CLI can share the agent's session for you to access on other devices or in a browser. To enable Agent Session Sharing, use the --share flag.

By default, the session is only accessible to the user running the CLI, but you can also share with Teams or other Warp users:

# Share the agent's session with yourself:
$ oz agent run --share --prompt "fix the compiler error"

# Give specific users view-only access to a session:
$ oz agent run --share [email protected] --share [email protected] --prompt "fix the compiler error"

# Let any user on your team edit the session:
$ oz agent run --share team:edit --prompt "fix the compiler error"

The --share flag can be repeated, and uses the following syntax:

• --share [email protected] or --share [email protected]:view — gives specified user read-only access to the session.

• --share [email protected]:edit — gives specified user [email protected] read/write access to the session.

• --share team or --share team:view — gives all members of your team read-only access to the session.

• --share team:edit — gives all members of your team read/write access to the session.

Additional commands

The following commands are available for managing and inspecting Oz resources.

oz agent list

List all available skills discovered from your environments. Optionally filter by repository:

oz agent list
oz agent list --repo owner/repo

oz run list / oz run get

List and inspect cloud agent runs:

# List recent runs (default: 10)
oz run list
oz run list --limit 20

# Get details for a specific run
oz run get <RUN_ID>

oz model list

List all available models:

oz model list

oz environment image list

List suggested base images for cloud environments:

oz environment image list

---

Troubleshooting

For built-in CLI help commands and solutions to common errors — including authentication issues, agent failures, environment problems, and Docker image issues — see Troubleshooting.