From 7df3dbe598188c70162045f1252b7b0b3d8e00bb Mon Sep 17 00:00:00 2001 From: hongyi-chen Date: Fri, 21 Aug 2026 17:16:48 +0000 Subject: [PATCH] docs(cli): document run-cloud --title and --parent-run-id Both flags are new on `oz agent run-cloud`: `--title` sets the run and conversation title, and `--parent-run-id` starts the run as an orchestration child of an existing run. Co-Authored-By: Warp --- src/content/docs/reference/cli/index.mdx | 29 ++++++++++++++++++++++++ 1 file changed, 29 insertions(+) diff --git a/src/content/docs/reference/cli/index.mdx b/src/content/docs/reference/cli/index.mdx index a2076ce7..5fa74123 100644 --- a/src/content/docs/reference/cli/index.mdx +++ b/src/content/docs/reference/cli/index.mdx @@ -264,6 +264,8 @@ oz agent run-cloud \ * `--no-environment` — run without an environment (not recommended). * `--open` — view the agent's session in Warp once it's available. * `--name ` (`-n`) — label the run for grouping and traceability (see [Naming runs](/reference/cli/#naming-runs) below). +* `--title ` — set the title shown for the run and its conversation (see [Titling runs](/reference/cli/#titling-runs) below). +* `--parent-run-id <RUN_ID>` — start the run as an orchestration child of an existing run (see [Starting a run as an orchestration child](/reference/cli/#starting-a-run-as-an-orchestration-child) below). * `--agent <UID>` — 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 <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. @@ -325,6 +327,33 @@ oz agent run-cloud \ --prompt "review the latest PR" ``` +#### Titling runs + +The `--title` flag sets the title shown for the run and its conversation in Warp and the [{VARS.WEB_APP}](/platform/oz-web-app/). Use it when the auto-generated title isn't descriptive enough: + +```sh +oz agent run-cloud \ + --environment <ENVIRONMENT_ID> \ + --title "Upgrade Postgres driver to 5.2" \ + --prompt "Upgrade the Postgres driver and fix any resulting build errors" +``` + +`--title` and `--name` do different things: `--name` sets the run's config name, which groups related runs under a shared label, while `--title` labels this one run for humans reading it. + +#### Starting a run as an orchestration child + +The `--parent-run-id` flag attaches the new run to an existing run as an [orchestration](/platform/orchestration/multi-agent-runs/) child. The child inherits the parent's lineage and scope, and it appears alongside the parent's other children instead of as a standalone run: + +```sh +oz agent run-cloud \ + --environment <ENVIRONMENT_ID> \ + --parent-run-id <PARENT_RUN_ID> \ + --title "Backfill integration tests" \ + --prompt "Add integration tests for the new endpoints" +``` + +Pass the run ID of the run doing the spawning. Omit the flag for ordinary standalone runs. + **When cloud runs fail** * Verify your environment has the correct repository and context.