/cli-builder

name: cli-builder
description: "Build production-quality CLIs with language detection and a five-step approval-gated workflow. Use when wrapping an existing module or app. Don't use for GUI/TUI apps, web APIs, or one-off shell scripts."
license: MIT
effort: high
metadata:
  version: 1.3.0
  author: "Luong NGUYEN <luongnv89@gmail.com>"

CLI Builder

Build production-quality CLI tools for any module or application, in any language.

Reference files (read each one on demand, not upfront, to keep the agent's context budget small):

• `references/cli-libraries.md` — read during Step 2 (Design) to recommend libraries and during Step 4 (Execute) for starter scaffolds
• `references/btop-style.md` — read during Step 2 (Design) to write the Visual style section and during Step 4 (Execute) to build the style module and its tests
• `references/testing-patterns.md` — read during Step 4 (Execute) when writing tests
• `references/final-report.md` — read during Step 5 (Summarize) to write the final report

Repo Sync Before Edits (mandatory)

Run this section once, before Step 1, so the analysis reads the current code. If `git rev-parse --git-dir` fails, the directory is not a git repository: skip this section, the Branch-First Safety Rule, and the Step 4 commits, and list `no git repository: no branch or commits` under `Uncertainty:` in the final report.

In a git repository, sync the current branch with remote:

branch="$(git rev-parse --abbrev-ref HEAD)"
git fetch origin
git pull --rebase origin "$branch"

If the working tree is not clean, stash first, sync, then restore:

git stash push -u -m "pre-sync"
branch="$(git rev-parse --abbrev-ref HEAD)"
git fetch origin && git pull --rebase origin "$branch"
git stash pop

If `origin` is missing, pull is unavailable, or rebase/stash conflicts occur, stop and ask the user before continuing.

Branch-First Safety Rule

Run this rule at the start of Step 4, before the first file write, with `CLI_NAME` set to the tool name approved in Step 2. Only create a new branch if on `main` or `master` — otherwise continue on the existing branch (the user likely set it up already or is resuming work):

current_branch="$(git rev-parse --abbrev-ref HEAD)"
if [ "$current_branch" = "main" ] || [ "$current_branch" = "master" ]; then
  slug="$(echo "${CLI_NAME:-cli}" | tr '[:upper:] ' '[:lower:]-' | tr -cd 'a-z0-9-')"
  ts="$(date +%Y%m%d-%H%M%S)"
  git checkout -b "feat/cli-${slug}-${ts}"
fi

Mandatory 5-Step Workflow (approval-gated)

**Explicit approval** is a user reply that accepts the presented item as it stands, such as "approved" or "looks good, go ahead". A question, a change request, or no reply is not approval. Steps 1-3 write no files.

Step 1: Analyze

Understand the project before proposing anything.

**Auto-detect language** by checking for manifest files:

• `package.json` / `tsconfig.json` -> JavaScript/TypeScript
• `pyproject.toml` / `setup.py` / `setup.cfg` / `requirements.txt` -> Python
• `go.mod` -> Go
• `Cargo.toml` -> Rust
• `pom.xml` / `build.gradle` / `build.gradle.kts` -> Java/Kotlin
• `Gemfile` / `*.gemspec` -> Ruby

**Identify existing CLI/entry points**: check for `bin` fields, `__main__.py`, `main.go`, `fn main()`, existing arg parsing code, or `scripts` in package.json.

**Record the module structure**: list the public functions or classes the CLI will expose, their inputs and outputs, the core data types, and runtime dependencies.

**Ask clarifying questions** (only what cannot be inferred):

• Primary use case (automation, developer tool, data processing, admin)
• Target audience (developers, ops, end users)
• Single command or multi-command (subcommand tree)
• Output formats needed (text, JSON, table, CSV)
• Distribution method (pip/npm/go install, standalone binary, source)

Present the findings: detected language, entry points, the list of exposed functions, and the open questions. Wait for explicit approval before Step 2.

---

Step 2: Design

Present a structured CLI design document:

• **Tool name** and binary/entry point name
• **Command tree** (visual hierarchy for multi-command tools)
• **Arguments and options per command** (name, type, required/optional, default, help text)
• **Global options** (verbose, quiet, output format, config file, no-color)
• **I/O behavior** (stdin support, stdout/stderr separation, piping)
• **Config strategy** (CLI args > env vars > config file > defaults)
• **Example invocations** (at least 3 realistic examples showing common use cases)
• **Visual style** (in every design) — the btop-inspired look from `references/btop-style.md`: components per command, theme roles, fallbacks, the styling library or zero-dependency module, and a mockup of one command's styled output. Use another style only when the user explicitly declines this one.

Approval loop: 1. Present the design document. 2. Ask for feedback. 3. If the reply is not explicit approval, revise the design and return to 1.

**No implementation before design approval.** If the user ends the run without approving the design, stop; the final status is `BLOCKED`.

---

Step 3: Plan

Break implementation into three phases, each with granular tasks.

**Phase 1 — Foundation** (get a working CLI skeleton):

• Entry point and arg parsing setup
• One core command (the most important one)
• Help text and version flag
• Basic tests (help output, version, one command)

**Phase 2 — Complete** (full feature set):

• All remaining commands
• Input validation and error handling
• Output formatting (text, JSON, table as designed) through one style module that follows the approved Visual style
• Comprehensive tests

**Phase 3 — Polish** (optional; include it only when the user confirms it):

• Config file support
• Environment variable overrides
• Shell completions (bash, zsh, fish)
• Distribution/packaging setup (setup.py, package.json bin, goreleaser, etc.)

Each task includes:

• **Goal**: one sentence
• **Files*