Node CLI Tool Building skill for Codex

A good CLI does the obvious thing with no flags, explains itself with --help, never prompts when it is not attached to a terminal, writes data to stdout and everything else to stderr, and exits non-zero on any failure. It installs and runs from npx on a clean machine, not just from the author’s checkout.

Stack defaults

Need	Default	Notes
Argument parsing, subcommands, help	commander	Current major needs Node 20+; check engines before bumping
Interactive prompts, spinners	@clack/prompts	Every prompt must have a flag equivalent
Tiny script, one or two flags	node:util parseArgs	No dependency at all
Colours	node:util styleText or picocolors	Respect NO_COLOR and non-TTY output
Build TypeScript	tsc or tsup to dist/	Ship JS, not .ts; tsx only in dev

Read AGENTS.md and package.json first: package manager, module type, Node version, lint and test commands. Installing dependencies needs network; ask for approval in a sandbox with network off. For Python CLIs use $python-cli-tools; for Rust, $rust-clap-cli.

Package layout

{
  "name": "@acme/envcheck",
  "version": "0.1.0",
  "type": "module",
  "bin": { "envcheck": "./dist/cli.js" },
  "files": ["dist"],
  "engines": { "node": ">=20" },
  "scripts": {
    "build": "tsc -p tsconfig.json",
    "test": "node --test",
    "prepublishOnly": "npm run build && npm test"
  },
  "dependencies": { "@clack/prompts": "^0.11.0", "commander": "^14.0.0" }
}

• The bin target must start with #!/usr/bin/env node. tsc keeps a shebang on the first line of the source file.
• files whitelists what ships; check with npm pack --dry-run.
• A package named create-foo makes npm create foo (and npx create-foo) work.
• Pin versions to what npm view <pkg> version reports when adding dependencies; the ranges above are examples.

Entry point

#!/usr/bin/env node
import { Command, Option } from 'commander';
import { readFile } from 'node:fs/promises';
import { checkEnv } from './check.js';

const pkg = JSON.parse(await readFile(new URL('../package.json', import.meta.url), 'utf8'));
const program = new Command();

program
  .name('envcheck')
  .description('Compare a .env file against .env.example')
  .version(pkg.version);

program
  .command('check')
  .description('report missing and extra keys')
  .argument('[file]', 'env file to check', '.env')
  .option('-e, --example <path>', 'reference file', '.env.example')
  .addOption(new Option('-f, --format <type>', 'output format').choices(['text', 'json']).default('text'))
  .option('--strict', 'exit 1 when extra keys exist')
  .action(async (file: string, opts) => {
    const result = await checkEnv(file, opts.example);
    if (opts.format === 'json') {
      process.stdout.write(JSON.stringify(result, null, 2) + '\n');
    } else {
      for (const k of result.missing) console.log(`missing  ${k}`);
      for (const k of result.extra) console.log(`extra    ${k}`);
    }
    if (result.missing.length || (opts.strict && result.extra.length)) process.exitCode = 1;
  });

program.parseAsync().catch((err: Error) => {
  console.error(`envcheck: ${err.message}`);
  process.exitCode = 2;
});

Set process.exitCode instead of calling process.exit() mid-flight so pending output flushes. Throw user-facing errors with a clear message; show a stack only with --debug.

Interactive flows with Clack

import * as p from '@clack/prompts';

export async function init(opts: { name?: string; template?: string; yes?: boolean }) {
  const interactive = process.stdin.isTTY && process.stdout.isTTY && !process.env.CI && !opts.yes;
  if (!interactive) {
    if (!opts.name) throw new Error('--name is required in non-interactive mode');
    return create(opts.name, opts.template ?? 'basic');
  }
  p.intro('create-acme-app');
  const name = opts.name ?? await p.text({
    message: 'Project name?',
    placeholder: 'my-app',
    validate: (v) => (/^[a-z0-9-]+$/.test(v ?? '') ? undefined : 'lowercase letters, digits, hyphens'),
  });
  if (p.isCancel(name)) { p.cancel('Cancelled'); process.exit(130); }
  const template = opts.template ?? await p.select({
    message: 'Template',
    options: [{ value: 'basic', label: 'Basic' }, { value: 'api', label: 'API server', hint: 'Hono' }],
  });
  if (p.isCancel(template)) { p.cancel('Cancelled'); process.exit(130); }
  const s = p.spinner();
  s.start('Copying files');
  await create(name, template);
  s.stop('Project created');
  p.outro(`cd ${name} && npm install`);
}

Rules: every prompt has a flag; --yes accepts defaults; check isCancel after every prompt (Ctrl-C returns a symbol, not an exception); never prompt when stdin is not a TTY, because CI and pipes will hang forever.

Output contract

Stream / signal	Use
stdout	The result: data, paths, JSON. Pipeable
stderr	Progress, spinners, warnings, errors, prompts
exit 0	Success, including “nothing to do”
exit 1	The check ran and found problems
exit 2	Usage or configuration error
exit 130	Cancelled by the user (Ctrl-C)

Offer --json (or --format json) on any command whose output someone might script. Disable colour and spinners when !process.stdout.isTTY or NO_COLOR is set. Help text quality (examples, man pages) is covered in $cli-help-text.

Testing

// test/cli.test.js - run the built binary as a user would
import { test } from 'node:test';
import assert from 'node:assert/strict';
import { execFileSync } from 'node:child_process';

test('json output lists missing keys', () => {
  let out;
  try {
    execFileSync('node', ['dist/cli.js', 'check', 'test/fixtures/.env',
      '-e', 'test/fixtures/.env.example', '-f', 'json'], { encoding: 'utf8' });
  } catch (err) {
    assert.equal(err.status, 1);
    out = JSON.parse(err.stdout);
  }
  assert.deepEqual(out.missing, ['DATABASE_URL']);
});

Test the core logic as plain functions, and a handful of end-to-end runs of the binary for exit codes, stdout shape and non-TTY behaviour (spawned processes are not TTYs, so these tests also prove prompts are skipped).

Release checklist

- [ ] npm run build && npm test
- [ ] npm pack --dry-run: only dist/, README, LICENSE, package.json listed
- [ ] npm pack, then in a temp dir: npx /path/to/acme-envcheck-0.1.0.tgz --help
- [ ] npm link, run from another directory, npm unlink
- [ ] Version bumped (npm version patch|minor|major) and changelog updated
- [ ] User confirms, then npm publish (scoped public packages need --access public)

Publishing is outward-facing and irreversible for that version number: never run npm publish without the user’s explicit go-ahead. From GitHub Actions, prefer trusted publishing or npm publish --provenance over long-lived tokens.

Gotchas

• __dirname does not exist in ESM; use new URL('./x', import.meta.url) or import.meta.dirname.
• Windows has no shebangs; npm generates .cmd shims from bin, so the entry must be a plain JS file, not a shell script.
• Forgetting files publishes src/, tests and sometimes .env; forgetting dist/ in files publishes a package that cannot run.
• A postinstall script that downloads things breaks offline and locked-down installs; avoid it.
• Top-level await with program.parse() (sync) skips async action errors; use parseAsync.
• npx foo resolves the npm package named foo, which may not be yours if your bin name differs from the package name; document npx @acme/envcheck.

Handoff

State the command surface (envcheck check [file] -e -f --strict), exit codes, how to run locally (npm link), what was tested, and whether it is published or awaiting approval.