Clirk - The CLI Clerk

📦 @simbo/clirk

A utility that makes creating Node.js CLIs easier by providing common functionality out of the box, with excellent performance and a minimal footprint.

Features

• ⚙️ Parses command-line arguments with minimist

• ℹ️ Auto-handles --help and --version flags (unless overridden)

• 📝 Provides formatted help and version messages

• 🛑 Handles SIGINT (Ctrl+C) gracefully with customizable messages

• 📊 Exposes structured metadata (title, description, parameters, options, examples)

• 🏎️ Optimized for performance with a minimal dependency footprint

• 📘 Fully typed with TypeScript

Installation

Install @simbo/clirk from the npm registry:

npm i [-D] @simbo/clirk

Usage

For a complete API reference, see the documentation.

Define Your CLI

The ClirkOptions interface provides flexible configuration for parsing arguments, generating help and version output, and customizing overall CLI behavior.

📄 ./cli-config.ts

import type { ClirkOptions } from '@simbo/clirk';

export const CLI_CONFIG: ClirkOptions = {
  importMetaDirname: import.meta.dirname, // required for CLI module context
  argsOptions: {
    // minimist options for parsing command line arguments
  },
  name: 'my-cli',
  title: 'My CLI Tool',
  description: 'An awesome CLI tool.',
  // Add more details here for better --help output.
};

[!NOTE]
If your environment does not support import.meta.dirname, use another way to resolve the absolute directory path of your CLI module, such as dirname(fileURLToPath(import.meta.url)).

Bootstrap Your CLI

The ClirkContext returned by clirk() contains the parsed arguments and relevant CLI metadata.

📄 ./main.ts

import { clirk } from '@simbo/clirk';
import { CLI_CONFIG } from './cli-config.js';

export async function main() {
  const { args } = await clirk(CLI_CONFIG);
  // Arguments are parsed.
  // --help and --version flags are handled automatically.
  // SIGINT handling is set up.
}

Error Handling with clitch

In your entrypoint script, wrap the main function with clitch() to log errors consistently and exit the process gracefully.

📄 ./cli.ts (set as bin in package.json)

#!/usr/bin/env node
import { clitch } from '@simbo/clirk/clitch';
import { main } from './main.js';

await clitch(main);

Related Packages

• @simbo/graceful-exit
• @simbo/stringify-error
• @simbo/user-facing-error

License

MIT © Simon Lepel