cli-expert_skill

Overview

This skill is an expert guide for designing and building npm package CLIs that follow Unix philosophy, support robust argument parsing, detect project roots and monorepos automatically, and operate well in both interactive and non-interactive environments. It focuses on cross-platform reliability, distribution best practices, and performance patterns to keep startup times low and behavior predictable.

How this skill works

It inspects project layout, package.json bin entries, workspace markers, and environment variables to detect roots and monorepo types. It recommends libraries and patterns for parsing arguments, handling TTY vs piped input, and composing small tools that interoperate via text streams. It also provides diagnostic commands, validation checks, and test patterns to verify shebangs, permissions, and cross-platform behavior.

When to use it

• Building a new CLI package intended for npm distribution
• Refactoring a monorepo-aware CLI to support workspaces and hoisting
• Adding robust interactive and non-interactive modes with TTY detection
• Diagnosing install-time issues like broken shebangs or non-executable binaries
• Optimizing CLI startup time and reducing bundle size for faster launches

Best practices

• Design each binary to do one focused job and compose via pipes
• Detect interactive mode with process.stdin.isTTY/process.stdout.isTTY and respect CI env
• Use established parsers (parseArgs, Commander, Yargs) and allow unknown options for workspace tools
• Enforce LF and binary attributes (.gitattributes) to prevent shebang corruption
• Lazy-load commands and dynamic-import heavy modules to target <100ms startup
• Test on Windows, macOS, and Linux; include CI matrix and npm pack validation before publish

Example use cases

• Create a workspace-aware CLI that resolves the correct project root and runs workspace-specific tasks
• Implement a tool that reads JSON from stdin for use in Unix pipelines and prints pretty output when TTY
• Diagnose and fix a global install where the binary is not in PATH or lacks executable bit
• Split a large tool into multiple focused binaries (main, daemon, worker) to reduce memory and simplify testing
• Add graceful CI-safe behavior: no spinners, deterministic defaults, and machine-readable output