gastownhall/beads · error

unknown argument %q; did you mean %q or 'bd %s'?

Error message

unknown argument %q; did you mean %q or 'bd %s'?

What it means

bd list's Args validator rejects any positional argument that matches a known old flag name, offering the new flag spelling and the 'bd <arg>' subcommand as alternatives. It exists to catch users who migrated from versions where things like 'blocked' were flags on list. The error is surfaced through cobra since SilenceErrors is true (handled by the root command's error printer).

Source

Thrown at cmd/bd/list.go:163

	"all":     "--all",
	"long":    "--long",
	"watch":   "--watch",
	"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)
	},
}

View on GitHub (pinned to 71377f2769)

Solutions

1. Use the suggested flag: `bd list --<hint>` as shown in the message
2. Use the suggested subcommand: `bd <arg>` (e.g. `bd blocked`)
3. Run `bd list --help` to see the current flag set
4. For filtering by text, use `bd list --search <term>` or pipe through grep

Example fix

// before
bd list blocked
// after
bd list --blocked   # or: bd blocked

// In scripts, prefer flags/subcommands over positional args to bd list
if [[ "$1" == "blocked" ]]; then set -- --blocked; fi
bd list "$@"

// Check exit output for 'unknown argument' and retry with the hinted flag
if ! out=$(bd list "$@" 2>&1); then
  echo "$out"; echo "bd list is flag-only; see bd list --help"
fi

When it happens

Trigger: Running `bd list <arg>` where <arg> is a key in knownListFlags (e.g. a legacy flag name like 'blocked' or 'unassigned'). The Args function only runs when at least one positional arg is given.

Common situations: Users upgrading bd and typing old flag syntax (`bd list ready` instead of `bd list --ready`), or trying to pass an issue ID/substring to list expecting grep-like filtering.

Related errors

• bd list does not accept positional arguments; use flags inst
• positional argument %q contains '=', which no issue id does
• invalid variable format '%s', expected 'key=value'
• invalid dependency format %q, expected 'type:id' or 'id'
• cannot combine %s

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