diff --git a/CHANGELOG.md b/CHANGELOG.md index e359d6f0..523997cf 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -70,6 +70,19 @@ 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 + 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 ### Added diff --git a/README.md b/README.md index 03a04b8f..e4a0b1b4 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 **root-level 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..3d817e30 100644 --- a/docs/cli-reference.md +++ b/docs/cli-reference.md @@ -4,6 +4,7 @@ Complete command-line reference for Conductor. ## Table of Contents +- [Root-Level Options](#root-level-options) - [`conductor run`](#conductor-run) - [`conductor stop`](#conductor-stop) - [`conductor gate-respond`](#conductor-gate-respond) @@ -11,6 +12,32 @@ Complete command-line reference for Conductor. - [`conductor doctor`](#conductor-doctor) - [`conductor registry`](#conductor-registry) +## Root-Level Options + +The following root-level options **must appear before the +subcommand name**: + +```bash +conductor [ROOT 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. They control workflow +progress output (`run` / `resume`); other commands may not be affected. + +```bash +# Correct: root-level 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 +58,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 +> [root-level options](#root-level-options), which must appear *before* the +> `run` subcommand: `conductor --quiet run workflow.yaml`. + ### Examples #### Basic Execution @@ -70,8 +99,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 root-level 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 +152,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 root-level 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..9be653df 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 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