Oz CLI
Use Oz agents from the terminal.
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
Quickstart Guide
Set up and run your first cloud agent in less than 5 minutes.
1. Installing the CLI
If you already have the Warp desktop app installed, the CLI is included and available in the Warp terminal.
If not, see Installing the CLI for installation options for all platforms.
2. Authenticate
For local development and first-time setup, authenticate interactively using the oz login command. Use the appropriate command name based on your installation method. For command names, refer to the table in Running the CLI.
For example, on macOS:
This command prints a sign-in URL in your terminal. Open the URL in your browser to login to Warp. Your credentials will be stored securely for future CLI use.
Interactive login works on both local and remote machines, and does not require API keys.
3. Run an agent
From any directory, run:
This uses the default agent profile, loads any available MCP servers, and executes the run locally. The output appears directly in your terminal.
What happens:
Warp starts a new cloud agent session.
The agent is given access to your current working directory.
The agent autonomously executes commands and streams output to your terminal.
4. Add GitHub context (optional)
If the directory is a Git repository, the Oz CLI can use GitHub as an MCP server:
You'll be prompted to authorize the Warp GitHub App if you haven't already.
5. Next steps
Once you've successfully set up and ran your agent, explore other configurations and workflows with the Oz CLI:
Customize behavior with agent profiles.
Reuse prompts with
--saved-prompt.Connect agents to external systems using MCP servers.
Authenticate with API keys for automated environments or workflows.
Get up-to-date information about the Oz CLI using the
helpcommand.
Continue reading to learn how to install the CLI on different platforms, authenticate in different environments, and configure agents for real-world workflows.
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.
To add the Oz CLI to your PATH,:
Open the Command Palette (
CMD+P)In the search field, find and select the
Install Oz CLI Commandaction.
Note: Administrator permissions are required to install the CLI into /usr/local/bin .
In the Warp installer, select Add Warp to PATH. If you are installing for all users, this will put the CLI on the system path. Otherwise, the CLI is only added to the path for your account.
To run the Oz CLI on Linux, use the same command that you'd use to start Warp normally. If you installed Warp via a package manager, it should already be on the system PATH.
Standalone package
Warp provides standalone packages for the CLI on macOS and Linux, without the Warp app.
On macOS, we recommend that you install and update the standalone CLI with Homebrew, using the warpdotdev/warp tap:
If you're using Warp Preview, install the preview version of the CLI instead:
You can also download the CLI directly from these URLs:
Note: These builds do not auto-update.
On Linux, we recommend that you install and update the standalone CLI through your distribution's package manager. We support apt, yum, and pacman.
Add the Warp package repository for your distribution (see the installation instructions).
Install either the stable or Preview package (replace
aptwithyumorpacmanas needed):
Note: The package name (oz-stable) differs from the CLI command executable (oz). After installation, use the CLI via oz commands.
You can also install the CLI by downloading a package directly. These installers automatically add the Warp repository, so future updates come through your package manager:
A standalone CLI package is not currently available on Windows. To use the Oz CLI on Windows, install the Warp app, which bundles the CLI.
You can install Warp using WinGet:
After installation, see Bundled with Warp for instructions on adding the CLI to your PATH.
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.
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:
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:
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.
Key flags:
--cwd <PATH>— run from a different directory.--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).
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
Key flags
--environment <ENVIRONMENT_ID> (-e)— select the environment to run in (this is the main knob that makes the run execute in the cloud).--open— view the agent's session in Warp once it's available.--name <NAME>— label the run for grouping and traceability (see Naming runs below).--profile <PROFILE_ID>— select an execution profile (defaults if omitted).--mcp <SPEC>— start one or more MCP servers before execution (UUID, JSON file path, or inline JSON).--model <MODEL_ID>— override the default model.--skill <SPEC>— use a skill from the environment's repository as the base prompt (see Using Skills).
Key differences from run
No
--cwd— the environment determines the working directory.No
--share— sharing options are onrun, notrun-cloud.
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
--nameexplicitly.Custom runs — When you build your own automation (via the CLI, API, or SDK), set
--nameto 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:
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
When you find prompts that work well, save them in Warp Drive to reuse across sessions, share with teammates, and integrate into automated workflows. For more information, see Prompts.
To reuse a prompt, first find its ID. The ID of a saved prompt will be the last part of its Warp Drive Sharing a drive object using links.
For example, in the URL:
... the ID is sgNpbUgDkmp2IImUVDc8kR.
You can reference saved prompts using the --saved-prompt flag:
Referencing Warp Drive objects
Use <workflow:id>, <notebook:id>, or <rule:id> in prompts to reference Warp Drive objects and rules as attached context. To quickly create these references, use the @ context menu in Warp to construct a prompt, and then copy it into your CLI command.
Using agent profiles
Agent profiles control three things:
What the agent can do — file access, command execution, and MCP server usage.
How the agent works — Model selection, autonomy level, and response style.
Where the agent can act — Directory allowlists/denylists.
You can create and configure agent profiles in the Warp app. For detailed instructions, see Agent Profiles & Permissions.
Agent profiles are automatically synced to each host that you have Warp installed on, so you can still use them remotely.
Tip: For CLI usage, create a dedicated profile. The CLI will fail if it tries to execute a prohibited action, so make sure your profile allows the directories, commands, and MCP servers that you'd like the agent to use.
The default profile for CLI usage is broadly permissive and gives the agent the ability to read/write files, apply code diffs, and execute commands (with a default denylist). The agent does not have the ability to use MCP servers by default.
To use an agent profile with the CLI, first find the profile ID using the oz agent profile list command:
Then, select that profile using the --profile flag:
Using MCP servers
MCP servers connect cloud agents to interact with external systems like GitHub, Linear, or Sentry. To use a Model Context Protocol (MCP) server from the CLI, you need:
An MCP server configured in Warp
An agent profile that allows for the MCP server you want to use
Environment variables for authentication (if required)
There are two ways to start MCP servers with the agent:
If the selected agent profile allows specific MCP servers, they will start automatically.
If the selected agent profile allows any MCP server, you must specify the ones to start using the
--mcp-serverflag.
To start specific MCP servers, first get the MCP server ID using oz mcp list:
Alternatively, you can copy the server ID from the MCP servers page in Warp:
Click your profile photo in the top-right corner, then click Settings.
In the sidebar, click MCP Servers.
Next, use --mcp-server to start the server:
Environment variables and remote execution
While Warp syncs MCP server configuration between hosts, it does not sync environment variables. When running on remote machines, you must set any required auth tokens:
Tip: consider using a password or secret manager CLI, such as op, pass, or gcloud secrets versions access to fetch MCP secrets on remote hosts.
Using Skills
Skills are reusable instruction sets that teach agents how to perform specific tasks. You can use skills from repositories in your environment with the --skill flag.
Skill spec format
The --skill flag accepts a skill specification that identifies which skill to use:
Supported formats:
owner/repo:skill-name— skill by name in a specific repository (recommended)owner/repo:path/to/SKILL.md— skill by full path in a repositoryrepo:skill-name— skill by name (only works when the repo is configured in your environment)
Using Skills with cloud agents
Skills are particularly useful with cloud agents (oz agent run-cloud) because they let you define reusable workflows that run consistently across environments:
When you specify a skill, it provides the base instructions for the agent. The --prompt adds additional context or parameters for that specific run.
Using Skills with local agents
For local agent runs, skills from your current repository are automatically discovered. You can also explicitly specify a skill:
For more information about creating and managing skills, see Skills.
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:
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 teamor--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.
Troubleshooting and help
The CLI includes built-in documentation for all commands:
Common errors
Command not found / CLI not installed correctly Verify your installation path and confirm the CLI version:
Authentication issues
Interactive login: ensure you’ve completed the browser-based flow with
oz login.API keys: confirm the key is valid, not expired, and exported correctly (
echo $WARP_API_KEY).
Agent or MCP errors Ensure your agent profile and MCP servers are configured properly, with correct permissions.
Last updated
Was this helpful?