From 5091463f313f18d40011f9a0fdcd020c5304c412 Mon Sep 17 00:00:00 2001 From: Oz Date: Fri, 31 Jul 2026 17:33:43 +0000 Subject: [PATCH 1/2] 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 e6844f42..75479ba1 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/2] 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 75479ba1..533655dc 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