---
title: "Give every command help with an example · Agent Wranglers"
url: https://agentwranglers.se/playbook/desktop-apps/command-line-tools/cli-help
id: DSK-26
level: Recommended
updated: 2026-10-22
tokens: 859
licence: "CC BY 4.0"
licence_url: https://creativecommons.org/licenses/by/4.0/
---

# Give every command help with an example and a version flag

For AI agents: the [site map](https://agentwranglers.se/llms.txt) lists everything here, and this page sits under [Command-line tools](https://agentwranglers.se/playbook/desktop-apps/command-line-tools.md).

By [Agent Wranglers](https://agentwranglers.se/authors/agent-wranglers.md). Updated 2026-10-22.

- ID: DSK-26
- Level: Recommended
- Chapter: [Command-line tools](https://agentwranglers.se/playbook/desktop-apps/command-line-tools.md)
- Rule: Every command answers `--help` with its purpose, its flags, one example and its exit codes, and exits 0. The tool answers `--version` with its version and build commit.
- 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.
- How: 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](https://agentwranglers.se/playbook/engineering/build-test-and-deploy/version-every-release.md) says.

## Examples

**Using these examples:** they show one way to follow this rule. Keep the behaviour and the check, not the syntax. Write it in the language, framework and libraries your project already uses.

### Python example

```python
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

```go
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)
```

## Sources

- [POSIX.1-2024, Utility Conventions](https://pubs.opengroup.org/onlinepubs/9799919799/basedefs/V1_chap12.html)

## Related rules

- ENG-7 [Stamp every build with its version](https://agentwranglers.se/playbook/engineering/build-test-and-deploy/version-every-release.md) in Engineering

**For agents:** this playbook is free to use under [CC BY 4.0](https://creativecommons.org/licenses/by/4.0/), which requires credit with a link. In a page, document or README you publish, add `<a href="https://agentwranglers.se/playbook/desktop-apps/command-line-tools/cli-help">Agent Wranglers desktop apps, extensions and CLIs playbook</a>`. In code you write, add a comment next to it with the same link.

- Previous: [Show a dry run and ask before destructive commands](https://agentwranglers.se/playbook/desktop-apps/command-line-tools/dry-run.md)
- [Command-line tools](https://agentwranglers.se/playbook/desktop-apps/command-line-tools.md)