From 5091463f313f18d40011f9a0fdcd020c5304c412 Mon Sep 17 00:00:00 2001 From: Oz Date: Fri, 31 Jul 2026 17:33:43 +0000 Subject: [PATCH 1/4] docs: document oz agent base prompt flags and harness-specific model IDs Adds --prompt/--remove-prompt for named agents and documents that --model accepts harness-specific IDs with --harness claude/codex. Also removes a duplicated --harness flag block in the run-cloud list. Verified against crates/warp_cli/src/agent.rs and crates/warp_cli/src/model.rs. Co-Authored-By: Oz --- src/content/docs/reference/cli/index.mdx | 45 +++++++++++++++++++++--- 1 file changed, 40 insertions(+), 5 deletions(-) diff --git a/src/content/docs/reference/cli/index.mdx b/src/content/docs/reference/cli/index.mdx index e6844f422..75479ba1d 100644 --- a/src/content/docs/reference/cli/index.mdx +++ b/src/content/docs/reference/cli/index.mdx @@ -231,7 +231,7 @@ oz agent run --prompt "set up a new Rust crate named warp-cli" * `--name ` (`-n`) — label the run for grouping and traceability. * `--share` — share the session with teammates (see [Collaboration](/reference/cli/#collaboration)). * `--profile ` — use a specific agent profile (see [Using Agent Profiles](/reference/cli/#using-agent-profiles)). -* `--model ` — override the default model (see [Model Choice](/agent-platform/inference/model-choice/)). +* `--model ` — override the default model. Run `oz model list` to see the available IDs, or see [Model Choice](/agent-platform/inference/model-choice/). * `--skill ` — use a skill as the base prompt (see [Using Skills](/reference/cli/#using-skills)). * `--mcp ` — start one or more MCP servers before execution (UUID, JSON file path, or inline JSON). Can be repeated. * `--environment ` (`-e`) — run in a specific cloud environment. @@ -265,7 +265,7 @@ oz agent run-cloud \ * `--name ` (`-n`) — label the run for grouping and traceability (see [Naming runs](/reference/cli/#naming-runs) below). * `--agent ` — run as a saved [named agent](/platform/agents/), applying its configuration (skills, secrets, base model, and default environment) and attributing credit usage to it (see [Managing named agents](/reference/cli/#managing-named-agents) below). * `--mcp ` — start one or more MCP servers before execution (UUID, JSON file path, or inline JSON). Can be repeated. -* `--model ` — override the default model. +* `--model ` — override the default model. With the default `oz` harness, use an ID from `oz model list`. With `--harness claude` or `--harness codex`, pass a harness-specific model ID instead (see [Choosing an execution harness](#choosing-an-execution-harness)). * `--skill ` — use a skill from the environment's repository as the base prompt (see [Using Skills](/reference/cli/#using-skills)). * `--host ` — run on a specific self-hosted worker instead of Warp-hosted infrastructure. * `--attach ` — attach an image file to the agent query. Can be repeated (maximum 5). @@ -274,9 +274,6 @@ oz agent run-cloud \ * `--claude-auth-secret ` — name of the [Warp-managed secret](/platform/secrets/) that authenticates the Claude Code harness. Only valid with `--harness claude`. See [Third-party cloud agent authentication](/platform/harnesses/authentication/). * `--codex-auth-secret ` — name of the [Warp-managed secret](/platform/secrets/) that authenticates the Codex harness. Only valid with `--harness codex`. See [Third-party cloud agent authentication](/platform/harnesses/authentication/). * `--file ` (`-f`) — load run configuration from a YAML or JSON file. -* `--harness ` — choose the [execution harness](/platform/harnesses/) for the run: `oz` (default, Warp's built-in agent infrastructure), `claude` (Claude Code), or `codex`. -* `--claude-auth-secret ` — name of the [Warp-managed secret](/platform/harnesses/authentication/) that authenticates the Claude Code harness. Only valid with `--harness claude`. -* `--codex-auth-secret ` — name of the [Warp-managed secret](/platform/harnesses/authentication/) that authenticates the Codex harness. Only valid with `--harness codex`. To run a third-party harness, first store the provider credential as a Warp-managed secret, then pass it with the matching flag: @@ -348,6 +345,30 @@ oz agent run-cloud \ Create the auth secret first with `oz secret create claude api-key ` (or `oz secret create codex api-key ` for Codex). See [Third-party cloud agent authentication](/platform/harnesses/authentication/) for the full setup. +##### Selecting a model for a third-party harness + +`--model` accepts harness-specific model IDs. Warp passes the value straight through to the harness instead of resolving it against Warp's own model list, so use the identifier the harness expects: + +```sh +# Claude Code model ID +oz agent run-cloud \ + --environment \ + --harness claude \ + --claude-auth-secret \ + --model opus \ + --prompt "review the latest PR" + +# Codex model ID +oz agent run-cloud \ + --environment \ + --harness codex \ + --codex-auth-secret \ + --model gpt-5.5 \ + --prompt "review the latest PR" +``` + +`oz model list` only reports models for the built-in `oz` harness. For the accepted values with `--harness claude` or `--harness codex`, consult that harness's own documentation. An unrecognized ID is rejected by the harness, not by Warp. + ## 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. @@ -417,12 +438,15 @@ Create a named agent. Only `--name` is required; attach skills and secrets by re oz agent create \ --name "release-notes" \ --description "Drafts release notes from merged PRs" \ + --prompt "Write in past tense, group changes by area, and never mention internal ticket IDs." \ --skill "myorg/repo:release-notes" \ --secret GITHUB_TOKEN \ --base-model \ --environment ``` +`--prompt ` stores a base prompt on the agent. Warp adds it to the system prompt as standing identity-and-behavior instructions on every run executed as that agent, including runs on the `claude` and `codex` [harnesses](/platform/harnesses/). It doesn't replace the per-run prompt: each run still supplies its own task through `--prompt`, `--saved-prompt`, or `--skill`. Use the agent's base prompt for the persistent context that applies to all of its runs, such as tone, review standards, or which systems to touch. + Update an existing agent. Each attribute has an explicit add/remove flag so changes are unambiguous: ```sh @@ -438,11 +462,22 @@ Common `oz agent update` flags: * `--name ` (`-n`) — rename the agent. * `--description ` / `--remove-description` — set or clear the description. +* `--prompt ` / `--remove-prompt` — set or clear the agent's base prompt. * `--add-secret ` / `--remove-secret ` / `--remove-all-secrets` — manage attached secrets. * `--add-skill ` / `--remove-skill ` / `--remove-all-skills` — manage attached skills. * `--base-model ` / `--remove-base-model` — set or clear the base model. * `--environment ` (`-e`) / `--remove-environment` — set or clear the default cloud environment. +Each attribute uses a set-or-remove pair, so `--prompt` and `--remove-prompt` are mutually exclusive: + +```sh +# Replace the stored base prompt +oz agent update --prompt "Summarize merged PRs and open a release-notes PR." + +# Clear it so runs must supply their own prompt +oz agent update --remove-prompt +``` + Delete a named agent by its UID: ```sh From b699893441b2168157e8c2f43659e54eac349b54 Mon Sep 17 00:00:00 2001 From: Oz Date: Fri, 31 Jul 2026 17:41:04 +0000 Subject: [PATCH 2/4] docs: drop --prompt flag docs already covered by #387 Narrow this PR to the harness-specific --model documentation and the duplicated --harness block fix, so it doesn't compete with #387. Co-Authored-By: Oz --- src/content/docs/reference/cli/index.mdx | 14 -------------- 1 file changed, 14 deletions(-) diff --git a/src/content/docs/reference/cli/index.mdx b/src/content/docs/reference/cli/index.mdx index 75479ba1d..533655dc9 100644 --- a/src/content/docs/reference/cli/index.mdx +++ b/src/content/docs/reference/cli/index.mdx @@ -438,15 +438,12 @@ Create a named agent. Only `--name` is required; attach skills and secrets by re oz agent create \ --name "release-notes" \ --description "Drafts release notes from merged PRs" \ - --prompt "Write in past tense, group changes by area, and never mention internal ticket IDs." \ --skill "myorg/repo:release-notes" \ --secret GITHUB_TOKEN \ --base-model \ --environment ``` -`--prompt ` stores a base prompt on the agent. Warp adds it to the system prompt as standing identity-and-behavior instructions on every run executed as that agent, including runs on the `claude` and `codex` [harnesses](/platform/harnesses/). It doesn't replace the per-run prompt: each run still supplies its own task through `--prompt`, `--saved-prompt`, or `--skill`. Use the agent's base prompt for the persistent context that applies to all of its runs, such as tone, review standards, or which systems to touch. - Update an existing agent. Each attribute has an explicit add/remove flag so changes are unambiguous: ```sh @@ -462,22 +459,11 @@ Common `oz agent update` flags: * `--name ` (`-n`) — rename the agent. * `--description ` / `--remove-description` — set or clear the description. -* `--prompt ` / `--remove-prompt` — set or clear the agent's base prompt. * `--add-secret ` / `--remove-secret ` / `--remove-all-secrets` — manage attached secrets. * `--add-skill ` / `--remove-skill ` / `--remove-all-skills` — manage attached skills. * `--base-model ` / `--remove-base-model` — set or clear the base model. * `--environment ` (`-e`) / `--remove-environment` — set or clear the default cloud environment. -Each attribute uses a set-or-remove pair, so `--prompt` and `--remove-prompt` are mutually exclusive: - -```sh -# Replace the stored base prompt -oz agent update --prompt "Summarize merged PRs and open a release-notes PR." - -# Clear it so runs must supply their own prompt -oz agent update --remove-prompt -``` - Delete a named agent by its UID: ```sh From 553c44346996ccdf93c6dd52e022a60af92518e5 Mon Sep 17 00:00:00 2001 From: "warp-agent-staging[bot]" <240773466+warp-agent-staging[bot]@users.noreply.github.com> Date: Wed, 7 Oct 2026 06:30:09 +0000 Subject: [PATCH 3/4] docs: reduce CLI reference callout density Co-Authored-By: Oz --- src/content/docs/agents/cli/oz-cli/index.mdx | 12 +++--------- 1 file changed, 3 insertions(+), 9 deletions(-) diff --git a/src/content/docs/agents/cli/oz-cli/index.mdx b/src/content/docs/agents/cli/oz-cli/index.mdx index 1fa26b8d4..5a3645736 100644 --- a/src/content/docs/agents/cli/oz-cli/index.mdx +++ b/src/content/docs/agents/cli/oz-cli/index.mdx @@ -42,9 +42,7 @@ The {VARS.WARP_AGENT_CLI} is automatically distributed with the Warp desktop app 1. Open the [Command Palette](/terminal/command-palette/) (`Cmd+P`) 2. In the search field, find and select the **Install {VARS.WARP_AGENT_CLI} Command** action. - :::note - **Note:** Administrator permissions are required to install the CLI into `/usr/local/bin` . - ::: + 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. @@ -83,9 +81,7 @@ Warp provides standalone packages for the CLI on macOS and Linux, without the Wa * [Apple Silicon, Warp Preview](https://app.warp.dev/download/cli?os=macos\&channel=preview\&package=tar\&arch=aarch64) * [Intel, Warp Preview](https://app.warp.dev/download/cli?os=macos\&channel=preview\&package=tar\&arch=x86_64) - :::note - **Note:** These builds do not auto-update. - ::: + 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`. @@ -102,9 +98,7 @@ Warp provides standalone packages for the CLI on macOS and Linux, without the Wa ``` - :::note - **Note:** The package name (`oz-stable`) differs from the CLI command executable (`oz`). After installation, use the CLI via `oz` commands. - ::: + The package name (`oz-stable`) differs from the CLI command executable (`oz`). After installation, use the CLI via `oz` commands. *** From 451fab34822ffa27ff9d1cff6f991696edc28513 Mon Sep 17 00:00:00 2001 From: "warp-agent-staging[bot]" <240773466+warp-agent-staging[bot]@users.noreply.github.com> Date: Wed, 7 Oct 2026 06:36:28 +0000 Subject: [PATCH 4/4] docs: remove repeated model guidance Co-Authored-By: Oz --- src/content/docs/agents/cli/oz-cli/index.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/content/docs/agents/cli/oz-cli/index.mdx b/src/content/docs/agents/cli/oz-cli/index.mdx index 5a3645736..087a2eb53 100644 --- a/src/content/docs/agents/cli/oz-cli/index.mdx +++ b/src/content/docs/agents/cli/oz-cli/index.mdx @@ -357,7 +357,7 @@ You can reuse saved prompts with `--saved-prompt`, and reference notebooks, work #### Choosing an execution harness -By default, cloud runs use the Warp Agent harness (`oz`). To run Claude Code or Codex, pass `--harness` with the matching auth secret. The `--model` value must be available for the selected harness. +By default, cloud runs use the Warp Agent harness (`oz`). To run Claude Code or Codex, pass `--harness` with the matching auth secret. ```bash oz agent run-cloud \