bd list does not accept positional arguments; use flags inst

Error message

bd list does not accept positional arguments; use flags instead (see bd list --help)

What it means

The generic branch of bd list's Args validator: list accepts no positional arguments at all, only flags. If an arg is not a recognized legacy flag, this error tells the user list is flag-only. It prevents silent misinterpretation of stray arguments.

Source

Thrown at cmd/bd/list.go:166

	"pretty":  "--pretty",
	"pinned":  "--pinned",
	"overdue": "--overdue",
}

var listCmd = &cobra.Command{
	Use:     "list",
	GroupID: "issues",
	Short:   "List issues",
	Args: func(cmd *cobra.Command, args []string) error {
		if len(args) == 0 {
			return nil
		}
		for _, arg := range args {
			if hint, ok := knownListFlags[arg]; ok {
				return fmt.Errorf("unknown argument %q; did you mean %q or 'bd %s'?", arg, hint, arg)
			}
		}
		return fmt.Errorf("bd list does not accept positional arguments; use flags instead (see bd list --help)")
	},
	SilenceUsage:  true,
	SilenceErrors: true,
	RunE: func(cmd *cobra.Command, args []string) error {
		evt := metrics.NewCommandEvent("list")
		defer func() {
			if c := metrics.Global(); c != nil {
				c.CloseEventAndAdd(evt)
			}
		}()

		return runListCore(cmd, args)
	},
}

// runListCore runs the list query and rendering without emitting a metrics
// event, so the caller owns emission: `bd list` emits "list" exactly once, and
// the `bd children` alias emits "children" exactly once. children sets listCmd's

View on GitHub (pinned to 71377f2769)

Solutions

Remove the positional argument and use flags only
Use `bd show <id>` to view a single issue
Check `bd list --help` for correct flag names
Remember flags need the leading `--` (e.g. --status, --assignee)

Example fix

// before
bd list status open
// after
bd list --status open

Defensive patterns

Strategy: validation

Validate before calling

// Ensure list invocations contain only flag arguments
for a in "$@"; do case "$a" in -*) ;; *) echo "positional arg not allowed: $a" >&2; exit 2;; esac; done
bd list "$@"

Try / catch

// Detect the positional-args error and route to the right subcommand
if ! out=$(bd list "$@" 2>&1); then
  case "$out" in *"does not accept positional arguments"*) bd show "$1";; *) echo "$out";; esac
fi

Prevention

Use `bd show <id>` for single issues, not `bd list <id>`
Quote flags correctly: --status open, not status open
Consult `bd list --help` when migrating scripts

When it happens

Trigger: `bd list <anything>` where <anything> is not in knownListFlags — e.g. an issue ID, free text, a misspelled flag without dashes, or a quoted phrase.

Common situations: Typing `bd list bd-123` expecting to show one issue (use `bd show` instead), forgetting `--` on a flag (`bd list status open` instead of `--status open`), or shell-quoting mistakes.

Related errors

AI-assisted analysis of gastownhall/beads@71377f2769 (2026-08-30). Data as JSON: /api/errors/f2ad7f44651241dd. Report an issue: GitHub.