docs(list): warn that repeated -s/--status silently overwrites (#3916) (#3917)

`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 <sjarmak@users.noreply.github.com>
This commit is contained in:
Stephanie Jarmak 2026-06-22 16:18:44 -04:00 • committed by GitHub
commit 749cc63e8d
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
5 changed files with 5 additions and 5 deletions

View file

@ -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, "")

View file

@ -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)

View file

@ -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)

View file

@ -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)

View file

@ -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)