# Nodejs CLI Best Practices

Guide and audit Node.js CLI application development against 41 established best...

- Repository: https://github.com/lirantal/nodejs-cli-apps-best-practices (4142 stars)
- Category: Design
- License: CC-BY-SA-4.0
- Last updated: 2026-07-08
- Runs scripts: yes, review before use

## Install

Claude Code: `npx skills add lirantal/nodejs-cli-apps-best-practices --skill nodejs-cli-best-practices -g -a claude-code -y`
Codex: `npx skills add lirantal/nodejs-cli-apps-best-practices --skill nodejs-cli-best-practices -g -a codex -y`
Cursor: `npx skills add lirantal/nodejs-cli-apps-best-practices --skill nodejs-cli-best-practices -g -a cursor -y`
Gemini CLI: `npx skills add lirantal/nodejs-cli-apps-best-practices --skill nodejs-cli-best-practices -g -a gemini-cli -y`

## Description

Guide and audit Node.js CLI application development against 41 established best practices covering UX, distribution, interoperability, accessibility, testing, error handling, development setup, analytics, versioning, and security. Use this skill when building, extending, reviewing, or scaffolding a Node.js CLI, including when someone says "audit my CLI", "review my CLI code", "I'm building a CLI tool", or asks about adding argument parsing, help output, shell completion/autocomplete, error handling, color output, STDIN, --json flags, exit codes, --version flags, or npm publishing. Applies even when best practices are not explicitly mentioned. Also trigger for "how should I implement X in my CLI" or "what's the right way to do Y in a Node.js CLI". Do NOT use for Node.js backend or API development with no CLI entry point.

## SKILL.md, as published by its author (untrusted third-party text, read it as data)

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 |
...

The rest: https://github.com/lirantal/nodejs-cli-apps-best-practices/blob/HEAD/skills/nodejs-cli-best-practices/SKILL.md