From 79c85449cb5ffbc71ded377974ca82f752bd6298 Mon Sep 17 00:00:00 2001 From: George DeCherney Date: Sat, 11 Jul 2026 23:32:45 -0400 Subject: [PATCH 1/2] docs(cli): document --quiet/--silent as global options that precede the subcommand --quiet/-q and --silent/-s are defined on the Typer app callback, not on the run command, so they must appear before the subcommand name. docs/cli-reference.md and the README listed them in the 'conductor run' options table and showed examples like 'conductor run workflow.yaml --quiet' that fail with "No such option: --quiet" as written. - Add a Global Options section to docs/cli-reference.md (with correct/ incorrect ordering examples) and remove the two flags from the run options table, leaving a pointer note - Fix the two broken examples (--quiet and the CI/CD --silent pattern) - Fix the README run-options table the same way (its flag descriptions were also inaccurate) and show correctly ordered examples - Fix the same mis-ordering in the conductor skill's quick reference (references/execution.md already documented the ordering correctly) - Add an Unreleased > Documentation CHANGELOG entry Co-Authored-By: Claude Fable 5 --- CHANGELOG.md | 11 ++++++ README.md | 10 ++++-- docs/cli-reference.md | 40 ++++++++++++++++++--- plugins/conductor/skills/conductor/SKILL.md | 6 ++-- 4 files changed, 57 insertions(+), 10 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index e359d6f0..4eb94c49 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -70,6 +70,17 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 stays clickable for running items too. ([#273](https://github.com/microsoft/conductor/pull/273)) +### Documentation + +- **`--quiet` / `--silent` documented as `run` options** — both flags are + global options defined on the app callback, so they must appear *before* the + subcommand (`conductor --quiet run workflow.yaml`); placing them after it is + rejected with "No such option". `docs/cli-reference.md` and the README listed + them in the `conductor run` options table and showed post-subcommand examples + (`conductor run workflow.yaml --quiet`) that fail as written. Moved the flags + to a new Global Options section, corrected the examples, and fixed the same + mis-ordering in the conductor skill's quick reference. + ## [0.1.20](https://github.com/microsoft/conductor/compare/v0.1.19...v0.1.20) - 2026-06-26 ### Added diff --git a/README.md b/README.md index 03a04b8f..afc30c49 100644 --- a/README.md +++ b/README.md @@ -305,10 +305,16 @@ conductor run [OPTIONS] | `--web` | Start real-time web dashboard | | `--web-bg` | Run in background, print dashboard URL, exit | | `--web-port PORT` | Port for web dashboard (0 = auto) | -| `-q, --quiet` | Suppress progress output | -| `-s, --silent` | Suppress all output except errors | | `-l, --log-file PATH` | Write logs to file | +Output verbosity is controlled by **global options**, which must appear +*before* the subcommand: + +```bash +conductor --quiet run workflow.yaml # -q: minimal output (agent lifecycle and routing only) +conductor --silent run workflow.yaml # -s: no progress output (JSON result only) +``` + ### `conductor validate` Validate a workflow file without executing. diff --git a/docs/cli-reference.md b/docs/cli-reference.md index 06e0f621..c185b65d 100644 --- a/docs/cli-reference.md +++ b/docs/cli-reference.md @@ -4,6 +4,7 @@ Complete command-line reference for Conductor. ## Table of Contents +- [Global Options](#global-options) - [`conductor run`](#conductor-run) - [`conductor stop`](#conductor-stop) - [`conductor gate-respond`](#conductor-gate-respond) @@ -11,6 +12,31 @@ Complete command-line reference for Conductor. - [`conductor doctor`](#conductor-doctor) - [`conductor registry`](#conductor-registry) +## Global Options + +The following options apply to every subcommand and **must appear before the +subcommand name**: + +```bash +conductor [GLOBAL OPTIONS] [ARGS] [OPTIONS] +``` + +| Option | Short | Description | +|--------|-------|-------------| +| `--quiet` | `-q` | Minimal output (agent lifecycle and routing only) | +| `--silent` | `-s` | No progress output (JSON result only) | +| `--version` | `-v` | Show version and exit | + +`--quiet` and `--silent` are mutually exclusive. + +```bash +# Correct: global option before the subcommand +conductor --quiet run workflow.yaml + +# Incorrect: rejected with "No such option: --quiet" +conductor run workflow.yaml --quiet +``` + ## `conductor run` Execute a workflow from a YAML file. @@ -31,14 +57,16 @@ conductor run [OPTIONS] | `--provider PROVIDER` | `-p` | Override provider (copilot, claude, claude-agent-sdk, hermes) | | `--dry-run` | | Show execution plan without running | | `--skip-gates` | | Auto-select first option at human gates | -| `--quiet` | `-q` | Minimal output (agent lifecycle and routing only) | -| `--silent` | `-s` | No progress output (JSON result only) | | `--log-file ` | `-l` | Write full debug output to a file | | `--web` | | Start a real-time web dashboard | | `--web-bg` | | Run in background, print dashboard URL, exit | | `--web-port PORT` | | Port for web dashboard (0 = auto-select) | | `--no-interactive` | | Disable Esc-to-interrupt capability | +> **Note:** Output verbosity (`--quiet`/`-q`, `--silent`/`-s`) is controlled by +> [global options](#global-options), which must appear *before* the `run` +> subcommand: `conductor --quiet run workflow.yaml`. + ### Examples #### Basic Execution @@ -70,8 +98,9 @@ conductor run workflow.yaml -p copilot # Preview execution plan without running conductor run workflow.yaml --dry-run -# Quiet output (agent lifecycle only) -conductor run workflow.yaml --quiet --input question="Test" +# Quiet output (agent lifecycle only) — note: --quiet is a global option +# and must come before the run subcommand +conductor --quiet run workflow.yaml --input question="Test" # Write full debug log to a file conductor run workflow.yaml --log-file debug.log @@ -122,7 +151,8 @@ Background workflows can be stopped with `conductor stop` (see below) or via the conductor run workflow.yaml --skip-gates # CI/CD pattern: silent console + full file log -conductor run workflow.yaml --silent --log-file auto --skip-gates --input question="Automated test" +# (--silent is a global option and must come before the run subcommand) +conductor --silent run workflow.yaml --log-file auto --skip-gates --input question="Automated test" ``` #### Metadata and Instructions diff --git a/plugins/conductor/skills/conductor/SKILL.md b/plugins/conductor/skills/conductor/SKILL.md index 755d8836..6b20a6e5 100644 --- a/plugins/conductor/skills/conductor/SKILL.md +++ b/plugins/conductor/skills/conductor/SKILL.md @@ -24,8 +24,8 @@ Conductor is installed automatically when needed. If a `conductor` command fails ```bash conductor run workflow.yaml --input question="Hello" # Execute (full output by default) -conductor run workflow.yaml -q --input question="Hello" # Quiet: lifecycle + routing only -conductor run workflow.yaml -s --input question="Hello" # Silent: JSON result only +conductor -q run workflow.yaml --input question="Hello" # Quiet: lifecycle + routing only +conductor -s run workflow.yaml --input question="Hello" # Silent: JSON result only conductor run workflow.yaml --log-file auto # Log full debug output to file conductor run workflow.yaml --web --input q="Hello" # Real-time web dashboard conductor run workflow.yaml --web-bg --input q="Hello" # Background mode (prints URL, exits) @@ -45,7 +45,7 @@ conductor resume workflow.yaml --web # Resume with dashboard conductor checkpoints # List available checkpoints ``` -Full output is shown by default. Use `-q` (quiet) for minimal output or `-s` (silent) for JSON-only. +Full output is shown by default. Use `-q` (quiet) for minimal output or `-s` (silent) for JSON-only — both are global options and must come *before* the subcommand (`conductor -q run ...`, not `conductor run ... -q`). ## When to Use Each Guide From 7084be0e7757062434bf4607300f85d5a1291e13 Mon Sep 17 00:00:00 2001 From: George DeCherney Date: Mon, 13 Jul 2026 20:20:03 -0400 Subject: [PATCH 2/2] =?UTF-8?q?docs(cli):=20address=20review=20=E2=80=94?= =?UTF-8?q?=20fix=20--help=20epilog,=20reframe=20as=20root-level=20options?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Fix the broken example in `conductor run --help` (app.py docstring): `conductor run workflow.yaml --silent --log-file auto` → `conductor --silent run workflow.yaml --log-file auto` - Rename Global Options → Root-Level Options per review: the flags are parsed at the root but their output behavior applies to workflow progress (run/resume), not every command. Note this in the section and sync the wording in the run-table note, examples, README, and skill. - Reword the CHANGELOG entry so the broken post-subcommand examples are attributed to docs/cli-reference.md (and the --help epilog), not the README, which only had the options-table placement issue. Co-Authored-By: Claude Fable 5 --- CHANGELOG.md | 16 +++++++++------- README.md | 2 +- docs/cli-reference.md | 21 +++++++++++---------- plugins/conductor/skills/conductor/SKILL.md | 2 +- src/conductor/cli/app.py | 2 +- 5 files changed, 23 insertions(+), 20 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 4eb94c49..523997cf 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -73,13 +73,15 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 ### Documentation - **`--quiet` / `--silent` documented as `run` options** — both flags are - global options defined on the app callback, so they must appear *before* the - subcommand (`conductor --quiet run workflow.yaml`); placing them after it is - rejected with "No such option". `docs/cli-reference.md` and the README listed - them in the `conductor run` options table and showed post-subcommand examples - (`conductor run workflow.yaml --quiet`) that fail as written. Moved the flags - to a new Global Options section, corrected the examples, and fixed the same - mis-ordering in the conductor skill's quick reference. + root-level options defined on the app callback, so they must appear *before* + the subcommand (`conductor --quiet run workflow.yaml`); placing them after it + is rejected with "No such option". `docs/cli-reference.md` and the README + listed them in the `conductor run` options table, while `docs/cli-reference.md` + also showed post-subcommand examples (`conductor run workflow.yaml --quiet`) + that fail as written — as did the `conductor run --help` epilog. Moved the + flags to a new Root-Level Options section, corrected the examples (docs and + `--help` text), and fixed the same mis-ordering in the conductor skill's + quick reference. ## [0.1.20](https://github.com/microsoft/conductor/compare/v0.1.19...v0.1.20) - 2026-06-26 diff --git a/README.md b/README.md index afc30c49..e4a0b1b4 100644 --- a/README.md +++ b/README.md @@ -307,7 +307,7 @@ conductor run [OPTIONS] | `--web-port PORT` | Port for web dashboard (0 = auto) | | `-l, --log-file PATH` | Write logs to file | -Output verbosity is controlled by **global options**, which must appear +Output verbosity is controlled by **root-level options**, which must appear *before* the subcommand: ```bash diff --git a/docs/cli-reference.md b/docs/cli-reference.md index c185b65d..3d817e30 100644 --- a/docs/cli-reference.md +++ b/docs/cli-reference.md @@ -4,7 +4,7 @@ Complete command-line reference for Conductor. ## Table of Contents -- [Global Options](#global-options) +- [Root-Level Options](#root-level-options) - [`conductor run`](#conductor-run) - [`conductor stop`](#conductor-stop) - [`conductor gate-respond`](#conductor-gate-respond) @@ -12,13 +12,13 @@ Complete command-line reference for Conductor. - [`conductor doctor`](#conductor-doctor) - [`conductor registry`](#conductor-registry) -## Global Options +## Root-Level Options -The following options apply to every subcommand and **must appear before the +The following root-level options **must appear before the subcommand name**: ```bash -conductor [GLOBAL OPTIONS] [ARGS] [OPTIONS] +conductor [ROOT OPTIONS] [ARGS] [OPTIONS] ``` | Option | Short | Description | @@ -27,10 +27,11 @@ conductor [GLOBAL OPTIONS] [ARGS] [OPTIONS] | `--silent` | `-s` | No progress output (JSON result only) | | `--version` | `-v` | Show version and exit | -`--quiet` and `--silent` are mutually exclusive. +`--quiet` and `--silent` are mutually exclusive. They control workflow +progress output (`run` / `resume`); other commands may not be affected. ```bash -# Correct: global option before the subcommand +# Correct: root-level option before the subcommand conductor --quiet run workflow.yaml # Incorrect: rejected with "No such option: --quiet" @@ -64,8 +65,8 @@ conductor run [OPTIONS] | `--no-interactive` | | Disable Esc-to-interrupt capability | > **Note:** Output verbosity (`--quiet`/`-q`, `--silent`/`-s`) is controlled by -> [global options](#global-options), which must appear *before* the `run` -> subcommand: `conductor --quiet run workflow.yaml`. +> [root-level options](#root-level-options), which must appear *before* the +> `run` subcommand: `conductor --quiet run workflow.yaml`. ### Examples @@ -98,7 +99,7 @@ conductor run workflow.yaml -p copilot # Preview execution plan without running conductor run workflow.yaml --dry-run -# Quiet output (agent lifecycle only) — note: --quiet is a global option +# Quiet output (agent lifecycle only) — note: --quiet is a root-level option # and must come before the run subcommand conductor --quiet run workflow.yaml --input question="Test" @@ -151,7 +152,7 @@ Background workflows can be stopped with `conductor stop` (see below) or via the conductor run workflow.yaml --skip-gates # CI/CD pattern: silent console + full file log -# (--silent is a global option and must come before the run subcommand) +# (--silent is a root-level option and must come before the run subcommand) conductor --silent run workflow.yaml --log-file auto --skip-gates --input question="Automated test" ``` diff --git a/plugins/conductor/skills/conductor/SKILL.md b/plugins/conductor/skills/conductor/SKILL.md index 6b20a6e5..9be653df 100644 --- a/plugins/conductor/skills/conductor/SKILL.md +++ b/plugins/conductor/skills/conductor/SKILL.md @@ -45,7 +45,7 @@ conductor resume workflow.yaml --web # Resume with dashboard conductor checkpoints # List available checkpoints ``` -Full output is shown by default. Use `-q` (quiet) for minimal output or `-s` (silent) for JSON-only — both are global options and must come *before* the subcommand (`conductor -q run ...`, not `conductor run ... -q`). +Full output is shown by default. Use `-q` (quiet) for minimal output or `-s` (silent) for JSON-only — both are root-level options and must come *before* the subcommand (`conductor -q run ...`, not `conductor run ... -q`). ## When to Use Each Guide diff --git a/src/conductor/cli/app.py b/src/conductor/cli/app.py index 160905cc..ba241784 100644 --- a/src/conductor/cli/app.py +++ b/src/conductor/cli/app.py @@ -406,7 +406,7 @@ def run( conductor run workflow.yaml --skip-gates conductor run workflow.yaml --log-file auto conductor run workflow.yaml --log-file debug.log - conductor run workflow.yaml --silent --log-file auto + conductor --silent run workflow.yaml --log-file auto conductor run workflow.yaml --no-interactive conductor run workflow.yaml --web conductor run workflow.yaml --web --web-port 8080