From 2866cc6bc83318e5a4e2e6300c34d28c534f62fc Mon Sep 17 00:00:00 2001 From: Scott Werner Date: Wed, 16 Sep 2026 16:28:13 -0400 Subject: [PATCH 1/3] Document run approval versus human interview answers --- docs/public/workflows/human-in-the-loop.mdx | 8 ++++++++ 1 file changed, 8 insertions(+) diff --git a/docs/public/workflows/human-in-the-loop.mdx b/docs/public/workflows/human-in-the-loop.mdx index f1cb0bfa7..934e50b77 100644 --- a/docs/public/workflows/human-in-the-loop.mdx +++ b/docs/public/workflows/human-in-the-loop.mdx @@ -19,6 +19,14 @@ approve -> skip [label="[S] Skip"] When execution reaches the gate, the user sees the previous stage's output followed by the node's label ("Approve Plan") and the available options. In the CLI, this appears as an interactive menu. In the web UI, blocked runs show an interview dock on the run page where the user can answer the pending question. + +`fabro approve` and `fabro deny` grant or deny permission to **start a run** waiting +for execution approval. To answer a human gate during execution, use the +interactive CLI prompt or the run page's interview dock. API clients can list +pending questions with `GET /api/v1/runs/{id}/questions` and answer a specific +question with `POST /api/v1/runs/{id}/questions/{qid}/answer`. + + ### Keyboard accelerators The prefixes `[A]`, `[R]`, `[S]` in edge labels serve as keyboard accelerators. Fabro supports three formats: From 1630d263548457712cdbe8fe3dfdcfa7ff432655 Mon Sep 17 00:00:00 2001 From: Scott Werner Date: Thu, 17 Sep 2026 14:54:00 -0400 Subject: [PATCH 2/3] Clarify interview guidance in approval command help --- docs/public/reference/cli.mdx | 8 ++-- lib/apps/fabro-cli/src/args.rs | 6 +++ lib/apps/fabro-cli/tests/it/cmd/approve.rs | 46 ++++++++++++++++---- lib/apps/fabro-cli/tests/it/cmd/deny.rs | 50 +++++++++++++++++----- 4 files changed, 87 insertions(+), 23 deletions(-) diff --git a/docs/public/reference/cli.mdx b/docs/public/reference/cli.mdx index 659b31bf2..39a72d299 100644 --- a/docs/public/reference/cli.mdx +++ b/docs/public/reference/cli.mdx @@ -63,7 +63,7 @@ fabro [OPTIONS] [COMMAND] | Command | Description | | --- | --- | -| `fabro approve` | Approve pending workflow runs | +| `fabro approve` | Approve pending workflow runs.

Controls permission to start a run. For human interview gates during execution, use the questions API. | | `fabro archive` | Mark terminal runs as archived (reviewed, no further action needed). Archived runs are hidden from default listings | | `fabro artifact` | Inspect and copy run artifacts (screenshots, reports, traces) | | `fabro ask` | Ask Fabro a read-only question about a run | @@ -71,7 +71,7 @@ fabro [OPTIONS] [COMMAND] | `fabro auth` | Manage CLI authentication state | | `fabro completion` | Generate shell completions | | `fabro create` | Register a workflow version and create a submitted run | -| `fabro deny` | Deny pending workflow runs | +| `fabro deny` | Deny pending workflow runs.

Controls permission to start a run. For human interview gates during execution, use the questions API. | | `fabro discord` | Open the Discord community in the browser | | `fabro docs` | Open the docs website in the browser | | `fabro doctor` | Check environment and integration health | @@ -111,7 +111,7 @@ fabro [OPTIONS] [COMMAND] ### `fabro approve` -Approve pending workflow runs +Approve pending workflow runs.

Controls permission to start a run. For human interview gates during execution, use the questions API. ```bash fabro approve [OPTIONS] ... @@ -371,7 +371,7 @@ fabro create [OPTIONS] ### `fabro deny` -Deny pending workflow runs +Deny pending workflow runs.

Controls permission to start a run. For human interview gates during execution, use the questions API. ```bash fabro deny [OPTIONS] ... diff --git a/lib/apps/fabro-cli/src/args.rs b/lib/apps/fabro-cli/src/args.rs index 09d7a01dc..1c09c47a2 100644 --- a/lib/apps/fabro-cli/src/args.rs +++ b/lib/apps/fabro-cli/src/args.rs @@ -1358,8 +1358,14 @@ pub(crate) enum RunsCommands { /// Show detailed information about a workflow run Inspect(InspectArgs), /// Approve pending workflow runs. + /// + /// Controls permission to start a run. For human interview gates during + /// execution, use the questions API. Approve(RunsApproveArgs), /// Deny pending workflow runs. + /// + /// Controls permission to start a run. For human interview gates during + /// execution, use the questions API. Deny(RunsDenyArgs), /// Mark terminal runs as archived (reviewed, no further action needed). /// Archived runs are hidden from default listings. diff --git a/lib/apps/fabro-cli/tests/it/cmd/approve.rs b/lib/apps/fabro-cli/tests/it/cmd/approve.rs index 2f4d23ad9..9af2123bb 100644 --- a/lib/apps/fabro-cli/tests/it/cmd/approve.rs +++ b/lib/apps/fabro-cli/tests/it/cmd/approve.rs @@ -14,21 +14,49 @@ fn help() { success: true exit_code: 0 ----- stdout ----- - Approve pending workflow runs + Approve pending workflow runs. + + Controls permission to start a run. For human interview gates during execution, use the questions API. Usage: fabro approve [OPTIONS] ... Arguments: - ... Run IDs or workflow names to approve + ... + Run IDs or workflow names to approve Options: - --json Output as JSON [env: FABRO_JSON=] - --server Fabro server target: http(s) URL or absolute Unix socket path [env: FABRO_SERVER=] - --debug Enable DEBUG-level logging (default is INFO) [env: FABRO_DEBUG=] - --no-upgrade-check Disable automatic upgrade check [env: FABRO_NO_UPGRADE_CHECK=true] - --quiet Suppress non-essential output [env: FABRO_QUIET=] - --verbose Enable verbose output [env: FABRO_VERBOSE=] - -h, --help Print help + --json + Output as JSON + + [env: FABRO_JSON=] + + --server + Fabro server target: http(s) URL or absolute Unix socket path + + [env: FABRO_SERVER=] + + --debug + Enable DEBUG-level logging (default is INFO) + + [env: FABRO_DEBUG=] + + --no-upgrade-check + Disable automatic upgrade check + + [env: FABRO_NO_UPGRADE_CHECK=true] + + --quiet + Suppress non-essential output + + [env: FABRO_QUIET=] + + --verbose + Enable verbose output + + [env: FABRO_VERBOSE=] + + -h, --help + Print help (see a summary with '-h') ----- stderr ----- "); } diff --git a/lib/apps/fabro-cli/tests/it/cmd/deny.rs b/lib/apps/fabro-cli/tests/it/cmd/deny.rs index 867b65907..2638138c3 100644 --- a/lib/apps/fabro-cli/tests/it/cmd/deny.rs +++ b/lib/apps/fabro-cli/tests/it/cmd/deny.rs @@ -14,22 +14,52 @@ fn help() { success: true exit_code: 0 ----- stdout ----- - Deny pending workflow runs + Deny pending workflow runs. + + Controls permission to start a run. For human interview gates during execution, use the questions API. Usage: fabro deny [OPTIONS] ... Arguments: - ... Run IDs or workflow names to deny + ... + Run IDs or workflow names to deny Options: - --json Output as JSON [env: FABRO_JSON=] - --server Fabro server target: http(s) URL or absolute Unix socket path [env: FABRO_SERVER=] - --debug Enable DEBUG-level logging (default is INFO) [env: FABRO_DEBUG=] - --reason Reason for denying execution - --no-upgrade-check Disable automatic upgrade check [env: FABRO_NO_UPGRADE_CHECK=true] - --quiet Suppress non-essential output [env: FABRO_QUIET=] - --verbose Enable verbose output [env: FABRO_VERBOSE=] - -h, --help Print help + --json + Output as JSON + + [env: FABRO_JSON=] + + --server + Fabro server target: http(s) URL or absolute Unix socket path + + [env: FABRO_SERVER=] + + --debug + Enable DEBUG-level logging (default is INFO) + + [env: FABRO_DEBUG=] + + --reason + Reason for denying execution + + --no-upgrade-check + Disable automatic upgrade check + + [env: FABRO_NO_UPGRADE_CHECK=true] + + --quiet + Suppress non-essential output + + [env: FABRO_QUIET=] + + --verbose + Enable verbose output + + [env: FABRO_VERBOSE=] + + -h, --help + Print help (see a summary with '-h') ----- stderr ----- "); } From e5ba7e3a0f3f378d49abcacade736fcc3c9afdce Mon Sep 17 00:00:00 2001 From: Scott Werner Date: Thu, 17 Sep 2026 15:15:42 -0400 Subject: [PATCH 3/3] Keep approval help concise and document attaching to interviews --- docs/public/reference/cli.mdx | 8 ++-- docs/public/workflows/human-in-the-loop.mdx | 8 ++-- lib/apps/fabro-cli/src/args.rs | 10 +---- lib/apps/fabro-cli/tests/it/cmd/approve.rs | 46 ++++--------------- lib/apps/fabro-cli/tests/it/cmd/deny.rs | 50 +++++---------------- lib/apps/fabro-cli/tests/it/cmd/fabro.rs | 4 +- 6 files changed, 31 insertions(+), 95 deletions(-) diff --git a/docs/public/reference/cli.mdx b/docs/public/reference/cli.mdx index 39a72d299..f18744a08 100644 --- a/docs/public/reference/cli.mdx +++ b/docs/public/reference/cli.mdx @@ -63,7 +63,7 @@ fabro [OPTIONS] [COMMAND] | Command | Description | | --- | --- | -| `fabro approve` | Approve pending workflow runs.

Controls permission to start a run. For human interview gates during execution, use the questions API. | +| `fabro approve` | Approve a pending run for execution | | `fabro archive` | Mark terminal runs as archived (reviewed, no further action needed). Archived runs are hidden from default listings | | `fabro artifact` | Inspect and copy run artifacts (screenshots, reports, traces) | | `fabro ask` | Ask Fabro a read-only question about a run | @@ -71,7 +71,7 @@ fabro [OPTIONS] [COMMAND] | `fabro auth` | Manage CLI authentication state | | `fabro completion` | Generate shell completions | | `fabro create` | Register a workflow version and create a submitted run | -| `fabro deny` | Deny pending workflow runs.

Controls permission to start a run. For human interview gates during execution, use the questions API. | +| `fabro deny` | Deny execution of a pending run | | `fabro discord` | Open the Discord community in the browser | | `fabro docs` | Open the docs website in the browser | | `fabro doctor` | Check environment and integration health | @@ -111,7 +111,7 @@ fabro [OPTIONS] [COMMAND] ### `fabro approve` -Approve pending workflow runs.

Controls permission to start a run. For human interview gates during execution, use the questions API. +Approve a pending run for execution ```bash fabro approve [OPTIONS] ... @@ -371,7 +371,7 @@ fabro create [OPTIONS] ### `fabro deny` -Deny pending workflow runs.

Controls permission to start a run. For human interview gates during execution, use the questions API. +Deny execution of a pending run ```bash fabro deny [OPTIONS] ... diff --git a/docs/public/workflows/human-in-the-loop.mdx b/docs/public/workflows/human-in-the-loop.mdx index 934e50b77..b64e953e2 100644 --- a/docs/public/workflows/human-in-the-loop.mdx +++ b/docs/public/workflows/human-in-the-loop.mdx @@ -21,10 +21,10 @@ When execution reaches the gate, the user sees the previous stage's output follo `fabro approve` and `fabro deny` grant or deny permission to **start a run** waiting -for execution approval. To answer a human gate during execution, use the -interactive CLI prompt or the run page's interview dock. API clients can list -pending questions with `GET /api/v1/runs/{id}/questions` and answer a specific -question with `POST /api/v1/runs/{id}/questions/{qid}/answer`. +for execution approval. To answer a human gate during execution, run +`fabro attach ` for an interactive prompt or use the run page's interview dock. +API clients can list pending questions with `GET /api/v1/runs/{id}/questions` and +answer a specific question with `POST /api/v1/runs/{id}/questions/{qid}/answer`. ### Keyboard accelerators diff --git a/lib/apps/fabro-cli/src/args.rs b/lib/apps/fabro-cli/src/args.rs index 1c09c47a2..b85da48c1 100644 --- a/lib/apps/fabro-cli/src/args.rs +++ b/lib/apps/fabro-cli/src/args.rs @@ -1357,15 +1357,9 @@ pub(crate) enum RunsCommands { Rm(RunsRemoveArgs), /// Show detailed information about a workflow run Inspect(InspectArgs), - /// Approve pending workflow runs. - /// - /// Controls permission to start a run. For human interview gates during - /// execution, use the questions API. + /// Approve a pending run for execution. Approve(RunsApproveArgs), - /// Deny pending workflow runs. - /// - /// Controls permission to start a run. For human interview gates during - /// execution, use the questions API. + /// Deny execution of a pending run. Deny(RunsDenyArgs), /// Mark terminal runs as archived (reviewed, no further action needed). /// Archived runs are hidden from default listings. diff --git a/lib/apps/fabro-cli/tests/it/cmd/approve.rs b/lib/apps/fabro-cli/tests/it/cmd/approve.rs index 9af2123bb..919d21341 100644 --- a/lib/apps/fabro-cli/tests/it/cmd/approve.rs +++ b/lib/apps/fabro-cli/tests/it/cmd/approve.rs @@ -14,49 +14,21 @@ fn help() { success: true exit_code: 0 ----- stdout ----- - Approve pending workflow runs. - - Controls permission to start a run. For human interview gates during execution, use the questions API. + Approve a pending run for execution Usage: fabro approve [OPTIONS] ... Arguments: - ... - Run IDs or workflow names to approve + ... Run IDs or workflow names to approve Options: - --json - Output as JSON - - [env: FABRO_JSON=] - - --server - Fabro server target: http(s) URL or absolute Unix socket path - - [env: FABRO_SERVER=] - - --debug - Enable DEBUG-level logging (default is INFO) - - [env: FABRO_DEBUG=] - - --no-upgrade-check - Disable automatic upgrade check - - [env: FABRO_NO_UPGRADE_CHECK=true] - - --quiet - Suppress non-essential output - - [env: FABRO_QUIET=] - - --verbose - Enable verbose output - - [env: FABRO_VERBOSE=] - - -h, --help - Print help (see a summary with '-h') + --json Output as JSON [env: FABRO_JSON=] + --server Fabro server target: http(s) URL or absolute Unix socket path [env: FABRO_SERVER=] + --debug Enable DEBUG-level logging (default is INFO) [env: FABRO_DEBUG=] + --no-upgrade-check Disable automatic upgrade check [env: FABRO_NO_UPGRADE_CHECK=true] + --quiet Suppress non-essential output [env: FABRO_QUIET=] + --verbose Enable verbose output [env: FABRO_VERBOSE=] + -h, --help Print help ----- stderr ----- "); } diff --git a/lib/apps/fabro-cli/tests/it/cmd/deny.rs b/lib/apps/fabro-cli/tests/it/cmd/deny.rs index 2638138c3..29e760006 100644 --- a/lib/apps/fabro-cli/tests/it/cmd/deny.rs +++ b/lib/apps/fabro-cli/tests/it/cmd/deny.rs @@ -14,52 +14,22 @@ fn help() { success: true exit_code: 0 ----- stdout ----- - Deny pending workflow runs. - - Controls permission to start a run. For human interview gates during execution, use the questions API. + Deny execution of a pending run Usage: fabro deny [OPTIONS] ... Arguments: - ... - Run IDs or workflow names to deny + ... Run IDs or workflow names to deny Options: - --json - Output as JSON - - [env: FABRO_JSON=] - - --server - Fabro server target: http(s) URL or absolute Unix socket path - - [env: FABRO_SERVER=] - - --debug - Enable DEBUG-level logging (default is INFO) - - [env: FABRO_DEBUG=] - - --reason - Reason for denying execution - - --no-upgrade-check - Disable automatic upgrade check - - [env: FABRO_NO_UPGRADE_CHECK=true] - - --quiet - Suppress non-essential output - - [env: FABRO_QUIET=] - - --verbose - Enable verbose output - - [env: FABRO_VERBOSE=] - - -h, --help - Print help (see a summary with '-h') + --json Output as JSON [env: FABRO_JSON=] + --server Fabro server target: http(s) URL or absolute Unix socket path [env: FABRO_SERVER=] + --debug Enable DEBUG-level logging (default is INFO) [env: FABRO_DEBUG=] + --reason Reason for denying execution + --no-upgrade-check Disable automatic upgrade check [env: FABRO_NO_UPGRADE_CHECK=true] + --quiet Suppress non-essential output [env: FABRO_QUIET=] + --verbose Enable verbose output [env: FABRO_VERBOSE=] + -h, --help Print help ----- stderr ----- "); } diff --git a/lib/apps/fabro-cli/tests/it/cmd/fabro.rs b/lib/apps/fabro-cli/tests/it/cmd/fabro.rs index 2972f10b8..5687c37a6 100644 --- a/lib/apps/fabro-cli/tests/it/cmd/fabro.rs +++ b/lib/apps/fabro-cli/tests/it/cmd/fabro.rs @@ -31,8 +31,8 @@ fn help() { dump Export a run's durable state to a directory rm Remove one or more workflow runs inspect Show detailed information about a workflow run - approve Approve pending workflow runs - deny Deny pending workflow runs + approve Approve a pending run for execution + deny Deny execution of a pending run archive Mark terminal runs as archived (reviewed, no further action needed). Archived runs are hidden from default listings unarchive Restore archived runs to their prior terminal status model List and test LLM models