/cli-framework-cli-commander

name: cli-framework-cli-commander
description: Node.js CLI development with Commander.js and @clack/prompts - command structure, interactive prompts, wizard state machines, config hierarchies, exit codes, cancellation handling

CLI Application Development with Commander.js

> **Quick Guide:** Use Commander.js for command structure and option parsing. Use @clack/prompts for interactive UX (spinners, selects, confirms). Always handle Ctrl+C cancellation with `p.isCancel()`. Use named exit code constants. Use `parseAsync()` for async actions. Structure commands in separate files. Resolve config with precedence: flag > env > project > global > default.

---

<critical_requirements>

CRITICAL: Before Building CLI Applications

> **All code must follow project conventions in CLAUDE.md** (kebab-case, named exports, import ordering, `import type`, named constants)

**(You MUST handle SIGINT (Ctrl+C) gracefully and exit with appropriate codes)**

**(You MUST use `p.isCancel()` to detect cancellation in ALL @clack/prompts calls and handle gracefully)**

**(You MUST use named constants for ALL exit codes - NEVER use magic numbers like `process.exit(1)`)**

**(You MUST use `parseAsync()` for async actions to properly propagate errors)**

**(You MUST stop spinners before any console output or error display)**

</critical_requirements>

---

**Auto-detection:** Commander.js, commander, @clack/prompts, picocolors, p.spinner, p.select, p.confirm, p.text, p.isCancel, p.tasks, p.multiselect, p.group, process.exit, exit codes, SIGINT handling, interactive prompts, wizard state machine, config hierarchy, CLI error handling, parseAsync, subcommand

**When to use:**

• Building command-line tools with Node.js using Commander.js
• Creating interactive terminal prompts and wizards with @clack/prompts
• Implementing multi-step wizard flows with back navigation
• Managing hierarchical configuration (flag > env > project > global)
• Structuring CLI applications with subcommands and global options

**When NOT to use:**

• Simple scripts with no user interaction (just use process.argv directly)
• Web server frameworks (use your API framework skill)
• Single-prompt scripts (use readline or raw @clack/prompts without Commander)

**Key patterns covered:**

• CLI entry point with SIGINT handling and global options
• Standardized exit codes with named constants
• Command definition with typed options and subcommands
• @clack/prompts for interactive UX (spinners, selects, confirms, text)
• Cancellation handling (`p.isCancel()`) on every prompt
• Wizard state machines with back navigation
• Configuration hierarchy resolution
• Dry-run mode implementation

**Detailed Resources:**

• [examples/core.md](examples/core.md) - Entry point, exit codes, commands, prompts, cancellation
• [examples/wizard-patterns.md](examples/wizard-patterns.md) - State machines, config hierarchy, dry-run mode

---

<philosophy>

Philosophy

**User experience first.** CLI tools should be intuitive, provide helpful feedback, and fail gracefully. Users should always know what's happening (spinners), what went wrong (clear errors), and how to fix it (actionable messages).

**Consistency across commands.** Every command follows the same patterns: options at top, spinner feedback, success/error messaging, and proper exit codes. This makes the CLI predictable and learnable.

**Graceful degradation.** Always handle cancellation (Ctrl+C), invalid input, and errors. Never leave users in an unknown state. Stop spinners before displaying errors.

**When to use Commander.js:**

• Multi-command CLI tools (git-like interfaces)
• Tools with complex option parsing and subcommands
• Applications needing auto-generated help text
• TypeScript-first development

**When to use @clack/prompts:**

• Interactive setup wizards and multi-step flows
• User confirmation before destructive actions
• Selection from lists of options
• Any user input beyond simple flags

</philosophy>

---

<patterns>

Core Patterns

Pattern 1: CLI Entry Point Structure

Register commands, handle SIGINT, use `parseAsync()` for async error propagation. See [examples/core.md](examples/core.md#pattern-1-cli-entry-point-structure) for full implementation.

// Handle Ctrl+C gracefully
process.on("SIGINT", () => {
  console.log(pc.yellow("\nCancelled"));
  process.exit(EXIT_CODES.CANCELLED);
});

// Use parseAsync for proper async error handling
await program.parseAsync(process.argv);

---

Pattern 2: Standardized Exit Codes

Define all exit codes as named constants. Never use magic numbers. See [examples/core.md](examples/core.md#pattern-2-standardized-exit-codes) for the full constant definition.

export const EXIT_CODES = {
  SUCCESS: 0,
  ERROR: 1,
  INVALID_ARGS: 2,
  CANCELLED: 4,
  VALIDATION_ERROR: 7,
} as const;

// GOOD: Named constant
process.exit(EXIT_CODES.VALIDATION_ERROR);

// BAD: Magic number
process.exit(1); // What does 1 mean?

This table is the authority for the whole CLI

Once a CLI defines this table, every exit in the process comes from it -- including the ones inside prompt handlers. A prompt library's own examples typically show a bare `process.exit(0)` after printing a cancellation message; those examples are making the point that you must exit at all, and they have no table to draw a value from. This CLI has one, so cancellation exits `EXIT_CODES.CANCELLED` wherever it happens.

The one value that is wrong everywhere is `0`. Cancellation is not success: `0` makes `mycli init && mycli deploy` run the deploy against a project the user abandoned halfway through, and makes a CI step pass on a run that did nothing. Any non-zero code is recoverable by a caller; `0` destroys the information.

**Choosing the number:** `2` for usage errors and `130` (128 + SIGINT) for interruption are the conventions callers are most likely to recognise. Beyond those, the specific integers matter far less than that they are named, dis