CLI Tool Design & Implementation (Node.js/Go)

## ROLE

You are an expert CLI developer who has built widely-used command-line tools adopted by thousands of developers. You have deep experience with both Node.js CLI frameworks like Commander, Yargs, Oclif, and Ink, as well as Go CLI frameworks like Cobra, urfave/cli, and Kong. You understand the principles that make command-line tools feel professional and intuitive — consistent flag conventions, helpful error messages, progressive disclosure of complexity, machine-readable output modes, and cross-platform compatibility. You have studied the UX patterns of tools like git, docker, kubectl, npm, and gh, understanding why they feel natural to experienced developers and how their design choices evolved over years of user feedback.

## OBJECTIVE

Design and implement a production-quality CLI tool called [TOOL NAME] that solves [PROBLEM: project scaffolding / deployment automation / database migration / API testing / log analysis / infrastructure provisioning / documentation generation / dependency management / code generation / workflow orchestration]. The target users are [AUDIENCE: individual developers / DevOps engineers / data engineers / frontend developers / full-stack teams / open-source maintainers]. The implementation language is [LANGUAGE: Node.js with TypeScript / Go]. The distribution method is [DISTRIBUTION: npm registry / Homebrew tap / GitHub releases with binaries / Docker image / all of the above].

## TASK: COMPLETE CLI TOOL DESIGN & IMPLEMENTATION

### Section 1 — Command Architecture & Information Design

Design the command hierarchy following the noun-verb pattern used by modern CLI tools. The top-level command is the tool name, with subcommands organized by resource or domain. Map out every command with this template: command path (e.g., tool resource action), description in one sentence, required arguments with type and validation rules, optional flags with short and long forms and default values, example usage showing the most common invocation, and output format for both human-readable and machine-readable modes. Define [NUMBER: 3-7] primary subcommand groups, each containing [NUMBER: 2-5] actions. For example: [TOOL] init creates a new configuration, [TOOL] [RESOURCE] list displays all items, [TOOL] [RESOURCE] create adds a new item, [TOOL] [RESOURCE] update modifies an existing item, [TOOL] [RESOURCE] delete removes an item, [TOOL] config manages tool configuration, and [TOOL] completion generates shell completions. Include global flags available on all commands: --verbose or -v for detailed output, --quiet or -q for minimal output, --output or -o with json, table, and yaml formats, --config to specify a custom configuration file path, --no-color to disable colored output for piping, and --help for command-specific help text. Design the help text hierarchy: running the tool with no arguments shows a brief usage summary, running with --help shows detailed help with all flags and examples, and running [TOOL] help [COMMAND] shows command-specific documentation with usage examples.

### Section 2 — Argument Parsing & Validation

Implement robust argument parsing using [FRAMEWORK: Commander.js / Yargs / Oclif / Cobra / urfave/cli]. Define validation rules for every argument and flag: type checking ensures strings, numbers, booleans, and arrays are correctly parsed, required argument validation fails fast with a clear message indicating which argument is missing, enum validation restricts certain flags to a predefined set of values with suggestions for typos, file path validation checks existence, readability, and correct file type before processing begins, and URL validation ensures proper format with optional reachability checking. Implement smart defaults that minimize the number of required flags for common use cases — the tool should work with zero configuration for the most common scenario, requiring explicit flags only for non-default behavior. Add environment variable support for every flag using a consistent naming convention like [TOOL_UPPER]_[FLAG_UPPER] so that MYTOOL_OUTPUT=json is equivalent to --output json. Define the precedence order: explicit flags override environment variables which override configuration file values which override hardcoded defaults. Implement flag coercion and aliasing: --no-color and --color=false should behave identically, --verbose --verbose should increase verbosity level, and common misspellings should trigger a did-you-mean suggestion.

### Section 3 — Configuration Management

Design the configuration system that stores persistent user preferences and project-specific settings. Support multiple configuration scopes: global configuration stored in the user home directory at [PATH: ~/.config/[TOOL]/config.yaml / ~/.toolrc / ~/.[TOOL].json], project configuration stored in the repository root at [PATH: .[TOOL].yaml / .[TOOL]rc / [TOOL].config.js], and local overrides stored in [PATH: .[TOOL].local.yaml] that are gitignored by convention. Define the configuration schema with [NUMBER: 10-20] settings organized into sections: general settings (default output format, color preference, verbosity level, telemetry opt-in), connection settings (API endpoints, authentication tokens, timeout values, retry configuration), project settings (default resource types, naming conventions, template paths), and plugin settings (enabled plugins, plugin-specific configuration). Implement the config subcommand group: [TOOL] config init creates a configuration file interactively by prompting the user for each setting with sensible defaults, [TOOL] config get [KEY] displays a single configuration value with its source (global, project, or default), [TOOL] config set [KEY] [VALUE] updates a configuration value in the specified scope, and [TOOL] config list displays all active configuration with source annotations. Handle secret management properly — API tokens and passwords should be stored in the system keychain using [LIBRARY: keytar for Node.js / zalando/go-keyring for Go] rather than plaintext configuration files, with a fallback to environment variables for CI and Docker environments.

### Section 4 — Output Formatting & User Experience

Design the output system that makes the tool pleasant to use in both interactive and scripted contexts. Implement three output modes: human mode is the default for interactive terminals and uses colors, spinners, progress bars, tables with aligned columns, and emoji indicators for status, machine mode is activated by --output json and outputs structured JSON with a consistent schema including a success boolean, data object, and optional error object, and quiet mode activated by --quiet suppresses all output except errors and the essential result. Build the table formatter that automatically adjusts column widths based on terminal width, truncates long values with ellipsis, and aligns numeric columns to the right. Implement a spinner or progress indicator for long-running operations using [LIBRARY: ora / cli-spinners for Node.js / briandowns/spinner for Go] that shows elapsed time, current operation description, and gracefully degrades to simple log lines when the output is not a TTY. Design the color scheme: green for success, red for errors, yellow for warnings, cyan for informational highlights, dim for secondary information, and bold for emphasis. Use [LIBRARY: chalk / kleur for Node.js / fatih/color for Go] and always respect the NO_COLOR environment variable and --no-color flag. Implement interactive prompts for destructive operations using [LIBRARY: inquirer / prompts for Node.js / AlecAivazis/survey for Go]: before deleting resources, show exactly what will be deleted and require confirmation, with a --force or --yes flag to skip confirmation in scripts.

### Section 5 — Error Handling & Debugging

Build a robust error handling system that helps users fix problems quickly. Define error categories: user errors are caused by invalid input or misconfiguration and should include a clear explanation of what went wrong plus a suggestion for how to fix it, network errors should include the URL that failed, the HTTP status code, whether the error is retryable, and a suggestion to check network connectivity or API status pages, authentication errors should guide the user through re-authentication with the exact command to run, and internal errors should apologize, provide a bug report URL with pre-filled context, and log detailed diagnostics to a file. Implement structured error output with an error code, human-readable message, suggestion for resolution, and documentation URL. For machine-readable output, errors should follow the same JSON schema with an error object containing code, message, and details fields. Build the --verbose and --debug output system: normal mode shows only essential information and final results, verbose mode adds progress steps and intermediate results, and debug mode logs every API request and response, configuration resolution steps, file system operations, and timing information. Write debug output to stderr so it does not interfere with stdout piping. Implement retry logic for transient failures with exponential backoff, configurable maximum retries, and clear indication to the user that a retry is happening and why.

### Section 6 — Testing, Packaging & Distribution

Create the testing and distribution pipeline. For testing, implement unit tests for every command handler, argument parser, and output formatter, integration tests that execute the compiled CLI binary as a subprocess and assert stdout, stderr, and exit codes, and snapshot tests for help text output to catch unintended changes to the user interface. For Node.js, use [FRAMEWORK: Jest / Vitest / Ava] with mock filesystem and HTTP interceptors. For Go, use the standard testing package with testify assertions and httptest for API mocking. Achieve [COVERAGE: 80-90]% code coverage with mandatory coverage checks in CI. For packaging, create builds for all target platforms: Node.js projects should publish to npm with a bin field in package.json and optionally bundle with pkg or vercel/ncc for standalone binaries, and Go projects should cross-compile for linux/amd64, linux/arm64, darwin/amd64, darwin/arm64, and windows/amd64. Set up automated release using GitHub Actions: on tag push, run tests, build binaries, create a GitHub release with checksums, publish to the npm registry or Homebrew tap, and build and push a Docker image to [REGISTRY: Docker Hub / GitHub Container Registry]. Include a Homebrew formula or tap for macOS users and shell completion scripts for bash, zsh, and fish that are installed automatically or available via [TOOL] completion [SHELL].