create-cli

name

create-cli

description

Design and build command-line tools, both the interface spec (args, flags, subcommands, help, output modes, errors, exit codes, config) per clig.dev and the implementation using Magnus's agent-ready Rust house style (clap derive, global --json, keychain/op/file secret backends, in-repo agent skills, AGENTS.md) modeled on sparebank1-cli and skatteetaten-cli. Use when the user wants to create a new CLI, design a CLI interface, scaffold a command-line tool, or make an existing CLI agent-friendly.

Create CLI

Two modes. Pick from what the user asked for:

• Design: produce an interface spec the user (or a later session) can implement. Language-agnostic.
• Build: scaffold and implement, defaulting to the house style (Rust + clap) unless the user names another stack.

Do This First

• Read references/cli-guidelines.md (condensed clig.dev; the baseline rubric for any CLI).
• Read references/house-style.md (Magnus's agent-ready skeleton, with ~/dev/personal/sparebank1-cli and ~/dev/personal/skatteetaten-cli as living exemplars to copy from).

Clarify (fast, then proceed with defaults)

• Name + one-sentence purpose. Short 2-3 char binary name?
• Primary consumers: humans, scripts, AI agents, or all three. (Default here: agents are first-class consumers.)
• Read-only or mutating? Mutating means confirm-prompts, -y, and scope restrictions from day one. Read-only as a design invariant is worth stating explicitly.
• Auth/secrets involved? Which backend story (keychain/op/file)?
• Distribution: personal (install.sh + cargo) or public (crates.io, release matrix)?

Design mode: deliverables

Produce a compact spec:

• Command tree + USAGE synopsis (noun-verb grouping; the --help tree is how agents discover capabilities, so make it a deterministic search tree).
• Args/flags table: types, defaults, required/optional, examples.
• Output contract: stdout vs stderr, --json (table stakes for agents), TTY detection, --quiet/--verbose, color rules (NO_COLOR).
• Error + exit-code map for the top failure modes, with messages that state the fix.
• Safety rules: confirmations, -y/--force, --no-input, dry-run story.
• Config/env precedence: flags > env > project config > user config.
• 5-10 example invocations, including piped/stdin and agent (--json) use.

Build mode: house style

Follow references/house-style.md. The short version: clap derive with global --json and --mask, stdout-is-data discipline, three-backend secret store defaulting to keychain, thiserror + anyhow two-layer errors, confirm-before-mutation, polite API etiquette (honest User-Agent, no retry loops), co-located tests for pure logic, fmt/clippy/test CI, and the install.sh + tag-driven release pipeline. Copy secrets.rs, install.sh, error.rs, and the workflows from an exemplar repo and rename.

Every CLI ships its agent surface in the same repo:

• AGENTS.md at root with explicit operating rules for agents.
• skills/<tool>-shared/SKILL.md as the runtime contract (command map, storage table, output contract, etiquette), plus per-area skills when the command surface grows.

Notes

• Full upstream guidelines: https://clig.dev/
• Check current library docs (clap etc.) via find-docs/ctx7 before coding; do not trust memorized API details.
• If the request is design-only, do not drift into implementation.