What causes "Error: command not found: %s" in gastownhall/beads?

Fix the command name passed to the doc generator (check `bd --help` for the exact path, e.g. 'mol pour' not 'molpour').

Error: command not found: %s

Error message

Error: command not found: %s

What it means

Returned by writeSingleCommandDoc when findCommand cannot locate cmdName under the root cobra command while generating per-command docs pages. It means the generic CLI doc generator was asked to document a command that does not exist.

Source

Thrown at cmd/bd/help_all.go:260

		fmt.Fprintf(w, "**Flags:**\n\n```\n%s```\n\n", localFlags.FlagUsages())
	}

	// Embedded doc supplement (raw Markdown, no MDX escaping).
	if sup, ok := commandDocSupplements[cmd.CommandPath()]; ok {
		fmt.Fprintf(w, "%s\n\n", strings.TrimSpace(sup))
	}
}

// writeSingleCommandDoc generates one command's documentation page as generic
// Markdown: title/description frontmatter and portable CommonMark. bd never
// emits site-generator-specific output (Docusaurus ids/slugs, Mintlify JSX,
// navigation fragments) — repo post-processors adapt these pages to whatever
// the documentation site needs.
func writeSingleCommandDoc(w io.Writer, root *cobra.Command, cmdName string) error {
	// Find the command (handle nested commands like "mol pour")
	cmd := findCommand(root, cmdName)
	if cmd == nil {
		return fmt.Errorf("Error: command not found: %s", cmdName)
	}

	docCommand := strings.TrimSpace(strings.TrimPrefix(commandPath(cmd), root.Name()))
	if docCommand == "" {
		return errors.New("Error: cannot generate docs for root command")
	}

	fmt.Fprintf(w, "---\n")
	fmt.Fprintf(w, "title: %q\n", "bd "+docCommand)
	if cmd.Short != "" {
		fmt.Fprintf(w, "description: %q\n", cmd.Short)
	}
	fmt.Fprintf(w, "---\n\n")
	fmt.Fprintf(w, "<!-- AUTO-GENERATED: do not edit manually -->\n\n")
	fmt.Fprintf(w, "Generated from `bd help --doc %s`.\n\n", docCommand)

	// The frontmatter title serves as the page heading, so the top command
	// emits its body without a duplicate heading; subcommands start at ##.

View on GitHub (pinned to 71377f2769)

Solutions

Fix the command name passed to the doc generator (check `bd --help` for the exact path, e.g. 'mol pour' not 'molpour').
Remove the stale entry from the docs command list if the command was deleted.
Regenerate docs after syncing to a version that contains the command.

Example fix

// before: command removed in refactor
commands := []string{"mol pour", "mol pour old-name"}
// after
commands := []string{"mol pour"}

Defensive patterns

Strategy: validation

Validate before calling

// verify each command exists before generating docs
for _, name := range commands {
	if findCommand(root, name) == nil {
		return fmt.Errorf("unknown command in docs list: %s", name)
	}
}

Try / catch

if err := writeSingleCommandDoc(&out, root, name); err != nil {
	if strings.HasPrefix(err.Error(), "Error: command not found") {
		// skip or fix the stale entry and continue
	}
}

Prevention

Generate the docs command list from the cobra tree instead of hand-maintaining it.
Update the docs pipeline whenever commands are renamed or removed.
Add a CI test that generates docs for every registered command.

When it happens

Trigger: writeSingleCommandDoc is called (directly or via writeGenericCLIDocsDir/writeGeneratedCLIDocs, or tests) with a cmdName that findCommand(root, cmdName) cannot resolve, including nested names like 'mol pour' that are misspelled or removed.

Common situations: Docs pipeline lists a command that was renamed or deleted in a refactor, typo in the commands list, stale docs generation config referencing an old subcommand, or invoking the doc writer with a user-supplied command name.

Related errors

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