From 749cc63e8dd7267f9ec64bc2f4e7d044aeeabaa6 Mon Sep 17 00:00:00 2001 From: Stephanie Jarmak <36544495+sjarmak@users.noreply.github.com> Date: Mon, 22 Jun 2026 16:18:44 -0400 Subject: [PATCH] docs(list): warn that repeated -s/--status silently overwrites (#3916) (#3917) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit `bd list --status open --status in_progress` returns only `in_progress` matches because cobra's StringP flag silently overwrites prior values on repeat. The canonical multi-status form is the comma-separated variant (`--status open,in_progress`), and the help text already names it — but does not warn about the repeated-flag footgun. Add a one-sentence note to the --status help text and regenerate the checked-in CLI reference docs via ./scripts/generate-cli-docs.sh. No behavior change. Closes gastownhall/beads#3916. Co-authored-by: sjarmak --- cmd/bd/list.go | 2 +- docs/CLI_REFERENCE.md | 2 +- website/docs/cli-reference/list.md | 2 +- website/versioned_docs/version-1.0.0/cli-reference/list.md | 2 +- website/versioned_docs/version-1.0.4/cli-reference/list.md | 2 +- 5 files changed, 5 insertions(+), 5 deletions(-) diff --git a/cmd/bd/list.go b/cmd/bd/list.go index 49cd09baa..1bc6fcc73 100644 --- a/cmd/bd/list.go +++ b/cmd/bd/list.go @@ -662,7 +662,7 @@ var listCmd = &cobra.Command{ } func init() { - listCmd.Flags().StringP("status", "s", "", "Filter by stored status (open, in_progress, blocked, deferred, closed). Comma-separated for multiple: --status open,in_progress") + listCmd.Flags().StringP("status", "s", "", "Filter by stored status (open, in_progress, blocked, deferred, closed). Comma-separated for multiple: --status open,in_progress. Note: repeating -s/--status silently overwrites the previous value — always use the comma-separated form for multi-status filters.") listCmd.Flags().String("state", "", "Alias for --status") _ = listCmd.Flags().MarkHidden("state") registerPriorityFlag(listCmd, "") diff --git a/docs/CLI_REFERENCE.md b/docs/CLI_REFERENCE.md index 7d202d264..dad80690e 100644 --- a/docs/CLI_REFERENCE.md +++ b/docs/CLI_REFERENCE.md @@ -939,7 +939,7 @@ bd list [flags] --skip-labels Skip label hydration. The labels field in output will be empty regardless of actual labels. Use only when the caller does not depend on label data. Cannot combine with --label, --label-any, --label-pattern, --label-regex, --exclude-label, or --no-labels. --sort string Sort by field: priority, created, updated, closed, status, id, title, type, assignee --spec string Filter by spec_id prefix - -s, --status string Filter by stored status (open, in_progress, blocked, deferred, closed). Comma-separated for multiple: --status open,in_progress + -s, --status string Filter by stored status (open, in_progress, blocked, deferred, closed). Comma-separated for multiple: --status open,in_progress. Note: repeating -s/--status silently overwrites the previous value — always use the comma-separated form for multi-status filters. --title string Filter by title text (case-insensitive substring match) --title-contains string Filter by title substring (case-insensitive) --tree Hierarchical tree format (default: true; use --flat to disable) (default true) diff --git a/website/docs/cli-reference/list.md b/website/docs/cli-reference/list.md index f17389686..7d1aab83e 100644 --- a/website/docs/cli-reference/list.md +++ b/website/docs/cli-reference/list.md @@ -68,7 +68,7 @@ bd list [flags] --skip-labels Skip label hydration. The labels field in output will be empty regardless of actual labels. Use only when the caller does not depend on label data. Cannot combine with --label, --label-any, --label-pattern, --label-regex, --exclude-label, or --no-labels. --sort string Sort by field: priority, created, updated, closed, status, id, title, type, assignee --spec string Filter by spec_id prefix - -s, --status string Filter by stored status (open, in_progress, blocked, deferred, closed). Comma-separated for multiple: --status open,in_progress + -s, --status string Filter by stored status (open, in_progress, blocked, deferred, closed). Comma-separated for multiple: --status open,in_progress. Note: repeating -s/--status silently overwrites the previous value — always use the comma-separated form for multi-status filters. --title string Filter by title text (case-insensitive substring match) --title-contains string Filter by title substring (case-insensitive) --tree Hierarchical tree format (default: true; use --flat to disable) (default true) diff --git a/website/versioned_docs/version-1.0.0/cli-reference/list.md b/website/versioned_docs/version-1.0.0/cli-reference/list.md index f17389686..7d1aab83e 100644 --- a/website/versioned_docs/version-1.0.0/cli-reference/list.md +++ b/website/versioned_docs/version-1.0.0/cli-reference/list.md @@ -68,7 +68,7 @@ bd list [flags] --skip-labels Skip label hydration. The labels field in output will be empty regardless of actual labels. Use only when the caller does not depend on label data. Cannot combine with --label, --label-any, --label-pattern, --label-regex, --exclude-label, or --no-labels. --sort string Sort by field: priority, created, updated, closed, status, id, title, type, assignee --spec string Filter by spec_id prefix - -s, --status string Filter by stored status (open, in_progress, blocked, deferred, closed). Comma-separated for multiple: --status open,in_progress + -s, --status string Filter by stored status (open, in_progress, blocked, deferred, closed). Comma-separated for multiple: --status open,in_progress. Note: repeating -s/--status silently overwrites the previous value — always use the comma-separated form for multi-status filters. --title string Filter by title text (case-insensitive substring match) --title-contains string Filter by title substring (case-insensitive) --tree Hierarchical tree format (default: true; use --flat to disable) (default true) diff --git a/website/versioned_docs/version-1.0.4/cli-reference/list.md b/website/versioned_docs/version-1.0.4/cli-reference/list.md index f17389686..7d1aab83e 100644 --- a/website/versioned_docs/version-1.0.4/cli-reference/list.md +++ b/website/versioned_docs/version-1.0.4/cli-reference/list.md @@ -68,7 +68,7 @@ bd list [flags] --skip-labels Skip label hydration. The labels field in output will be empty regardless of actual labels. Use only when the caller does not depend on label data. Cannot combine with --label, --label-any, --label-pattern, --label-regex, --exclude-label, or --no-labels. --sort string Sort by field: priority, created, updated, closed, status, id, title, type, assignee --spec string Filter by spec_id prefix - -s, --status string Filter by stored status (open, in_progress, blocked, deferred, closed). Comma-separated for multiple: --status open,in_progress + -s, --status string Filter by stored status (open, in_progress, blocked, deferred, closed). Comma-separated for multiple: --status open,in_progress. Note: repeating -s/--status silently overwrites the previous value — always use the comma-separated form for multi-status filters. --title string Filter by title text (case-insensitive substring match) --title-contains string Filter by title substring (case-insensitive) --tree Hierarchical tree format (default: true; use --flat to disable) (default true)