node-cli

Node CLI

src structure

src/
├── index.ts              # Entry point — wires Commander, calls updateNotifier
├── update-notifier.d.ts  # Type shim for update-notifier package
├── commands/             # One file per CLI command
│   ├── add.ts
│   └── remove.ts
├── lib/                  # Pure domain logic, no Commander concerns
│   ├── github.ts         # single-file feature → stays flat
│   ├── linker.ts
│   └── push/             # 2+ files → grouped into a feature folder, prefix dropped
│       ├── index.ts      # barrel: re-exports the feature's public surface
│       ├── workflow.ts
│       └── validation.ts
└── utils/                # Generic helpers — mix flat files and nested groups freely
    ├── format.ts         # flat single-purpose helper
    └── fs/               # related helpers grouped under one folder
        ├── read.ts
        └── write.ts
tests/                    # Mirrors src/ structure, one test file per module
├── add.test.ts
└── linker.test.ts

conventions:

• commands/ — each file exports a single Command instance; all CLI concerns (prompts, flags, output) live here
• lib/ — framework-agnostic helpers imported by commands; keep them testable in isolation
• Directories don't have to be flat. Keep a feature flat by default, and group it into a folder only once it owns 2+ files — a folder holding one file is just noise. When you group, the folder already names the feature, so drop the redundant prefix from filenames (lib/push/workflow.ts, not lib/push/push-workflow.ts), and use dir/index.ts as the feature's public surface (a barrel re-exporting what commands import, or, for a provider-style seam, the interface/contract itself). Commands import the folder, not its internals: import { planPush } from '../lib/push/index.js', so each feature's internal file split can change without touching call sites.

Entry point structure

#!/usr/bin/env node
import { Command } from 'commander'
import updateNotifier from 'update-notifier'
import packageJson from '../package.json' with { type: 'json' }

// Call before parseAsync — notify() defers display to process exit so it
// never interleaves with command output.
updateNotifier({ pkg: packageJson }).notify()

const program = new Command('your-cli')
  .description('...')
  .version(packageJson.version)

program.addCommand(fooCommand)

await program.parseAsync()