Give every command help with an example and a version flag

How to do it

An agent reads --help before it runs an unknown tool, much as it reads an API contract. One example teaches more than a list of flags. Accept -- to end the options, as POSIX utility conventions say, so a file name that starts with a dash still works. Print help to standard output when asked for, and a short usage line to standard error on wrong usage. Stamp the version as stamp every build with its version says.

Examples

Python example

parser = argparse.ArgumentParser(
    prog="ledgerly export",
    description="Export invoices for one month as CSV or JSON.",
    epilog="Example:\n  ledgerly export --month 2026-09 --json > september.json\n\n"
           "Exit codes:\n  0 done  1 failed  2 wrong usage  3 not found  4 try again later",
    formatter_class=argparse.RawDescriptionHelpFormatter,
)
parser.add_argument("--version", action="version", version=f"%(prog)s {VERSION} ({COMMIT})")

Go example

var exportCmd = &cobra.Command{
	Use:     "export",
	Short:   "Export invoices for one month as CSV or JSON",
	Example: "  ledgerly export --month 2026-09 --json > september.json",
	Long:    "Exit codes:\n  0 done  1 failed  2 wrong usage  3 not found  4 try again later",
}

rootCmd.Version = fmt.Sprintf("%s (%s)", version, commit)

How to check

A test runs --help on every command. Each exits 0 and its output contains Example and Exit codes. --version prints a version and a commit hash. tool rm -- -draft.csv treats -draft.csv as a file name.

Sources

• POSIX.1-2024, Utility Conventions

Related rules

• ENG-7 Stamp every build with its version in Engineering