hermes

Write a command-line tool

Designs and implements a small command-line tool with subcommands, help text, exit codes, config precedence and tests. Use when turning a manual workflow into a reusable command.

context

A good CLI behaves the way experienced terminal users expect without reading its source. It prints help, keeps data on stdout and messages on stderr, returns exit codes that scripts can branch on, works in a pipe, asks before destroying anything, and takes configuration from flags, environment and files in a predictable order. Most quick tools get two of these right and surprise their users with the rest.

task

Build a command-line tool in for this purpose:

Planned commands: (if empty, design the smallest command set that covers the purpose).

  1. If the purpose is too vague to name the commands and their inputs, ask up to 3 questions and stop.
  2. Design the command surface before writing code: commands as verbs (tool sync, tool list), arguments and flags per command, defaults, output, and exit codes. Use -h/--help and --version everywhere. Add --json for any command whose output another program might read, and --dry-run plus --yes for anything destructive.
  3. Use the ecosystem's standard parser, or the one the repo already uses: argparse or Typer for Python, Cobra or the standard flag package for Go, clap for Rust, Commander or util.parseArgs for Node.
  4. Configuration precedence, highest first: flags, then environment variables with a tool prefix (TOOL_*), then a project config file, then a user config file under the platform config directory ($XDG_CONFIG_HOME on Linux), then defaults. Document it in --help and in the README.
  5. Behaviour rules:
  • Exit codes: 0 success, 1 failure, 2 usage error. Add specific codes only if callers need to tell failures apart, and document them.
  • Data to stdout and progress, warnings and errors to stderr. Errors say what failed and what to do next.
  • Detect a non-interactive terminal: no colours, spinners or prompts when piped. Respect NO_COLOR. Accept - for stdin where a file is expected.
  • On Ctrl-C, stop cleanly, leave no partial files, and exit 130.
  1. Write tests: argument parsing per command, exit codes for success, usage error and runtime failure, --json output shape, and one end-to-end run in a temporary directory. Do not test against the real network or the user's home directory.
  2. Add a README section with installation, a usage example per command, the config precedence and the exit codes. Run the tests and a --help smoke check.
constraints
  • Keep it small: no plugin system, no global state, and no dependencies beyond the parser and what the purpose truly needs.
  • Never print secrets, including in --verbose or debug output.
  • Keep business logic in plain functions the CLI layer calls, so it can be tested without a subprocess.
  • Before saying the work is done, run the check that proves it (tests, build, type check or the command the user gave) and report the real result.
  • If you could not run a check, say so plainly and say which one.
output format

Command surface

| Command | Arguments and flags | Output | Exit codes | Then the config precedence in one line.

Files

A tree, then each file in its own code block.

Tests

One line per test: what it proves.

Decisions

Choices you made that the purpose did not dictate, one line each.

Verification

Commands run (tests, --help) and their actual results.

1 required value still a placeholder; the assistant will ask for it.

details

kind
Prompt: a task you run by name to get one finished thing back
domain
Software engineering
category
Implementation
level
Intermediate
depth
Specific
made for
Software engineer, DevOps / platform engineer, Site reliability engineer
needs
repo-read, file-write, shell
risk
runs-commands
version
v1.0.0 · incubating
reviewed
2026-10-02
works in
Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, Antigravity, OpenCode, Windsurf, Zed, Continue, AGENTS.md

Edit on GitHubReport a problem

use in

Hodios CLI
npx @hermes-hq/hodios install write-cli-tool --target claude-code
Agent Skills
npx skills add hermes-hq/hodios-dist --skill write-cli-tool -a claude-code
Add the Hodios marketplace (once)
claude plugin marketplace add hermes-hq/hodios-dist
Install the software-engineering plugin
claude plugin install hodios-software-engineering@hodios

The plugin brings every entry in this domain at once.

more in implementation

All of Implementation
PromptImplementation

Build a feature

Builds a feature from an idea rather than a full spec, asking the few questions that change the design, proposing a small plan, then implementing and testing it. Start here for new features.

build-a-feature
PersonaImplementation

Backend engineer

Acts as a backend engineer focused on correct data handling, clear API contracts, explicit failure modes and services that are easy to operate. Use as a builder or reviewer persona for server code.

backend-engineer
PersonaImplementation

Frontend engineer

Acts as a frontend engineer who balances UX, accessibility, performance and maintainable components, and checks work in a real browser. Use to build or review web UI.

frontend-engineer
PersonaImplementation

Game developer

Acts as a game developer who prototypes fast, tunes game feel through playtesting, keeps every system inside the frame budget and scopes ruthlessly to ship. Use for gameplay code in any engine.

game-developer
PromptImplementation

Implement transactional email

Implements transactional email with templates, a provider integration, retries, bounce and complaint handling, and deliverability settings. Use when an app must send receipts, resets or alerts.

implement-transactional-email
PromptImplementation

Integrate payments

Implements a payment integration with the provider's official SDK, covering checkout, webhooks, idempotency, refunds and reconciliation. Use when adding one-time payments or subscriptions.

integrate-payments