cli-building

name	cli-building
description	Use when building TypeScript CLIs. Guides command structure, interactive prompts, and tab completion using citty, `@clack/prompts`, and `@bomb.sh/tab` — and shipping them: CI gates, versioning (Changesets / release-please), and npm or single-binary release.

Citty CLI

Quick Start

npm install citty `@bomb.sh/tab` `@clack/prompts`

Minimal command:

import { defineCommand, runMain } from 'citty';

export default defineCommand({
    meta: { name: 'greet', description: 'Say hello' },
    args: { name: { type: 'string', description: 'Your name', required: true } },
    run({ args }) { console.log(`Hello, ${args.name}!`); },
});

Critical Rules

1. Every command exports default defineCommand() — no exceptions
2. Lazy-load subcommands — () => import('./cmd').then(m => m.default)
3. Check isCancel() after every @clack/prompts call — never skip
4. Citty handles all arg parsing — no external parsers
5. Architecture is opt-in — only suggest cli/ structure when the user asks for project layout or scaffolding. Single-file CLIs are valid.

Architecture (only when user asks for structure)

See architecture for the full cli/ layout with commands, prompts, and lib directories. Do not impose this structure unless the user explicitly asks for scaffolding or project organization.

Workflow

1. Define commands — commands
2. Add prompts if interactive — prompts
3. Wire tab completion — tab-completion
4. Scaffold cli/ if multi-command — architecture
5. Configure bin entry — sidecar setup
6. Verify — run with --help to confirm command registration
7. Ship it — CI gates, versioning, npm or binary release — release

References

• Architecture — Structure and responsibilities
• Entrypoint — runMain + tab completion wiring
• Commands — defineCommand, args, subcommands
• Prompts — @clack/prompts reusable modules
• Tab Completion — @bomb.sh/tab adapter
• Sidecar Setup — bin entry, build config
• Citty API — Resolvable, plugins, CLIError
• Release — CI gates, Changesets/release-please, npm + binary distribution
• Versioning — named schemes (SemVer/CalVer), 0.x vs 1.0, pre-releases, which bump, decision matrix, recording the policy
• Update Command — ask-first self-update: install-mode routing, checksum-verified atomic swap, passive banner