nodejs-cli-best-practices

This skill operates in two modes — audit for reviewing existing CLI code and development guide for building new features or tools.

Critical

Always read references/best-practices.md before producing any output. It contains the complete reference for all 41 practices with code examples and recommended packages. It is the source of truth for both modes — do not rely on general knowledge alone, as several practices (specific package recommendations, §X.X numbering, configuration precedence order) are specific to this guide.

Determining the mode

Trigger	Mode	Action
User provides existing CLI code or files to review	Audit	Produce a structured audit report
User asks how to build or implement something	Development guide	Surface relevant practices with examples
User says "review and help me improve"	Both	Audit first, then provide concrete guidance for each failing practice

---

Audit mode

Systematically compare the provided code against the practices in references/best-practices.md. Focus on what is verifiable from the code. Use judgment to mark practices as not applicable (➖) when there's genuinely no way to assess them from static analysis (e.g., Docker support when the project shows no distribution intent).

Prioritize by user impact — a missing exit code (§6.4) or absent --version flag (§9.1) affects every user and every CI pipeline; missing Docker image (§4.1) is low priority for most projects.

Audit report format

## Node.js CLI Best Practices Audit

### Summary
✅ N practices followed  ⚠️ N need attention  ❌ N not implemented  ➖ N not applicable

---

### 1. Command Line Experience
| # | Practice | Status | Finding |
|---|----------|--------|---------|
| 1.1 | Respect POSIX args | ✅ | Uses yargs with proper short/long aliases |
| 1.2 | Build empathic CLIs | ❌ | No interactive fallback when required args absent |
...

[Repeat for each section with applicable practices]

---

### Priority recommendations

**High priority** (user-facing or CI-breaking):
- **§6.4 Exit codes** — `process.exit()` called without a code
  ```js
  // Fix
  process.exit(1); // on error
  process.exit(0); // on success

Medium priority:

• ...

Low priority / nice to have:

• ...

Keep findings concise and tied to specific code patterns. Always include a concrete fix with code for each ❌.

---

## Development guide mode