[Tool Name]

A small TypeScript CLI. Installs from npm, runs anywhere Node 22+ runs.

Source of truth

GitHub. Published to npm under your scope (@yourname/your-tool). Every release is a git tag plus an npm publish.

Tech stack

Node 22 + TypeScript + tsx (for dev; ships compiled to ESM in dist/). commander for arg parsing. kleur for colors (small, no deps). ora for spinners. prompts for interactive input. execa for spawning subprocesses. Tests via Vitest.

Deploy

• Local dev: npm run dev -- your-args (tsx watches and re-runs)
• Build: npm run build (tsc -> dist/)
• Release: npm version patch && npm publish && git push --follow-tags

File map

• src/cli.ts shebang line, commander setup, command routing
• src/commands/ one file per subcommand
• src/lib/ shared helpers (config loader, fs ops)
• package.json "bin" field pointing at dist/cli.js
• tsconfig.json ESM + NodeNext + strict
• vitest.config.ts

.env keys

None at runtime. CLI reads config from ~/.config/yourtool/config.json (xdg-compliant) and CLI flags.

Hard rules

• Shebang line on src/cli.ts is #!/usr/bin/env node (NOT node22 or any version). Lets users with any modern Node run it.
• package.json "bin" points at the BUILT file in dist/, not src/.
• "type": "module" and ESM only. Don't dual-publish CJS in 2026.
• Every command has a --help example in the description. Test it.
• Exit codes: 0 on success, 1 on user error, 2 on internal error. Catch unhandled rejections and exit cleanly.
• No process.cwd() for finding the package root. Use import.meta.url resolution.

Recent significant changes

• 2026-04-28: Scaffolded. Locked: tsx for dev, plain tsc for build, commander for parsing (yargs is overkill).

Next session: start here

1. Set name in package.json (scoped is safest: @yourname/tool).
2. npm init -w for the bin entry, set "bin" mapping.
3. Implement first command under src/commands/.
4. npm link locally to test the binary as if installed.
5. npm publish --access public when ready.