npx CLI Tool Development (Bun-First)

Build and publish npx-executable command-line tools using Bun as the primary runtime and toolchain, producing binaries that work for all npm/npx users (Node.js runtime).

When to Use This Skill

Use when:

• Creating a new CLI tool from scratch

• Building an npx-executable binary

• Setting up argument parsing, sub-commands, or terminal UX for a CLI

• Publishing a CLI tool to npm

• Adding a CLI to an existing library package

Do NOT use when:

• Building a library without a CLI (use the npm-package skill)

• Building an application (not a published package)

• Working in a monorepo (this skill targets single-package repos)

Toolchain

Concern Tool Why

Runtime / package manager Bun Fast install, run, transpile

Bundler Bunup Bun-native, dual entry (lib + cli), .d.ts

Argument parsing citty ~3KB, TypeScript-native, auto-help, runMain()

Terminal colors picocolors ~7KB, CJS+ESM, auto-detect

TypeScript module: "nodenext" , strict: true

• extras Maximum correctness

Formatting + basic linting Biome v2 Fast, single tool

Type-aware linting ESLint + typescript-eslint Deep type safety

Testing Vitest Isolation, mocking, coverage

Versioning Changesets File-based, explicit

Publishing npm publish --provenance

Trusted Publishing / OIDC

Scaffolding a New CLI

Run the scaffold script:

bun run <skill-path>/scripts/scaffold.ts ./my-cli
--name my-cli
--bin my-cli
--description "What this CLI does"
--author "Your Name"
--license MIT

Options:

• --bin <name> — Binary name for npx (defaults to package name without scope)

• --cli-only — No library exports, CLI binary only

• --no-eslint — Skip ESLint, use Biome only

Then install dependencies:

cd my-cli bun install bun add -d bunup typescript vitest @vitest/coverage-v8 @biomejs/biome @changesets/cli bun add citty picocolors bun add -d eslint typescript-eslint # unless --no-eslint

Project Structure

Dual (Library + CLI) — Default

my-cli/ ├── src/ │ ├── index.ts # Library exports (programmatic API) │ ├── index.test.ts # Unit tests for library │ ├── cli.ts # CLI entry point (imports from index.ts) │ └── cli.test.ts # CLI integration tests ├── dist/ │ ├── index.js # Library bundle │ ├── index.d.ts # Type declarations │ └── cli.js # CLI binary (with shebang) ├── .changeset/ │ └── config.json ├── package.json ├── tsconfig.json ├── bunup.config.ts ├── biome.json ├── eslint.config.ts ├── vitest.config.ts ├── .gitignore ├── README.md └── LICENSE

CLI-Only (No Library Exports)

Same structure minus src/index.ts and src/index.test.ts . No exports field in package.json, only bin .

Architecture Pattern

Separate logic from CLI wiring. The CLI entry (cli.ts ) is a thin wrapper that:

• Parses arguments with citty

• Calls into the library/core modules

• Formats output for the terminal

All business logic lives in importable modules (index.ts or internal modules). This makes logic unit-testable without spawning processes.

cli.ts → imports from → index.ts / core modules ↑ unit tests

Key Rules (Non-Negotiable)

All rules from the npm-package skill apply here. These additional rules are specific to CLI packages:

Binary Configuration

Always use #!/usr/bin/env node in published bin files. Never #!/usr/bin/env bun . The vast majority of npx users don't have Bun installed.

Point bin at compiled JavaScript in dist/ . Never at TypeScript source. npx consumers won't have your build toolchain.

Ensure the bin file is executable. The build script includes chmod +x dist/cli.js after compilation.

Build with Node.js as the target. Bunup's output must run on Node.js, not require Bun runtime features.

Package Configuration

Always use "type": "module" in package.json.

types must be the first condition in every exports block.

Use files: ["dist"] . Whitelist only.

For dual packages (library + CLI): The exports field exposes the library API. The bin field exposes the CLI. They are independent — bin is NOT part of exports .

Code Quality

any is banned. Use unknown and narrow.

Use import type for type-only imports.

Handle errors gracefully. CLI users should never see raw stack traces. Use citty's runMain() which handles this automatically, plus process.on('SIGINT', ...) for cleanup.

Exit with appropriate codes. 0 for success, 1 for errors, 2 for bad arguments, 130 for SIGINT.

Reference Documentation

Read these before modifying configuration:

• reference/cli-patterns.md — bin setup, citty patterns, sub-commands, error handling, terminal UX, testing CLI binaries

• reference/esm-cjs-guide.md — exports map, dual package hazard, common mistakes

• reference/strict-typescript.md — tsconfig, Biome rules, ESLint type-aware rules, Vitest config

• reference/publishing-workflow.md — Changesets, files field, Trusted Publishing, CI pipeline

Argument Parsing with citty

Single Command

import { defineCommand, runMain } from 'citty';

const main = defineCommand({ meta: { name: 'my-cli', version: '1.0.0', description: '...' }, args: { input: { type: 'positional', description: 'Input file', required: true }, output: { alias: 'o', type: 'string', description: 'Output path', default: './out' }, verbose: { alias: 'v', type: 'boolean', description: 'Verbose output', default: false }, }, run({ args }) { // args is fully typed }, });

void runMain(main);

Sub-Commands

import { defineCommand, runMain } from 'citty';

const init = defineCommand({ meta: { name: 'init' }, /* ... / }); const build = defineCommand({ meta: { name: 'build' }, / ... */ });

const main = defineCommand({ meta: { name: 'my-cli', version: '1.0.0' }, subCommands: { init, build }, });

void runMain(main);

See reference/cli-patterns.md for complete examples including error handling, colors, and spinners.

Testing Strategy

Unit Tests — Test the Logic

// src/index.test.ts import { describe, it, expect } from 'vitest'; import { processInput } from './index.js';

describe('processInput', () => { it('handles valid input', () => { expect(processInput('test')).toBe('expected'); }); });

Integration Tests — Test the Binary

Build first (bun run build ), then spawn the compiled binary:

// src/cli.test.ts import { describe, it, expect } from 'vitest'; import { execFile } from 'node:child_process'; import { promisify } from 'node:util';

const exec = promisify(execFile);

describe('CLI', () => { it('prints help', async () => { const { stdout } = await exec('node', ['./dist/cli.js', '--help']); expect(stdout).toContain('my-cli'); }); });

Development Workflow

Write code and tests

bun run test:watch # Vitest watch mode

Check everything

bun run lint # Biome + ESLint bun run typecheck # tsc --noEmit bun run test # Vitest

Build and try the CLI locally

bun run build node ./dist/cli.js --help node ./dist/cli.js some-input

Prepare release

bunx changeset bunx changeset version

Publish

bun run release # Build + npm publish --provenance

Adding Sub-Commands Later

• Create a new file per sub-command: src/commands/init.ts , src/commands/build.ts

• Each exports a defineCommand() result

• Import and wire into the main command's subCommands

• Keep logic in testable modules, commands are thin wrappers

Converting a CLI-Only Package to Dual (Library + CLI)

• Create src/index.ts with the public API

• Update bunup.config.ts to include both entry points

• Add exports field to package.json alongside the existing bin

• Add .d.ts generation: dts: { entry: ['src/index.ts'] }

Bun-Specific Gotchas

• bun build does not generate .d.ts files. Use Bunup or tsc --emitDeclarationOnly .

• bun build does not downlevel syntax. ES2022+ ships as-is.

• bun publish does not support --provenance . Use npm publish .

• bun publish uses NPM_CONFIG_TOKEN , not NODE_AUTH_TOKEN .

• Never use #!/usr/bin/env bun in published packages. Your users don't have Bun.

• Bunup banner adds the shebang to ALL output files, including the library entry. If this is a problem, use a post-build script to add the shebang only to dist/cli.js .