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.