@dephub/cli 🛠️

A minimalist CLI toolkit for Node.js with intuitive command definition and parsing.

Features ✨

• 🎯 Simple API - Fluent interface for command definition
• 📚 Subcommands - Nested command support with automatic delegation
• 🏗️ Type Safe - Full TypeScript support with zero configuration
• 🔧 Auto Help - Built-in --help and --version flags
• ⚡ Lightweight - Minimal dependencies, focused functionality
• 🎨 Flexible - Use pre-configured instance or create custom commands

Installation 📦

npm install @dephub/cli
# or
pnpm add @dephub/cli
# or
yarn add @dephub/cli

Quick Start 🚀

Basic Command

import { cli } from '@dephub/cli';

cli
  .option('--port', 'Server port number')
  .flag('--watch', 'Watch for file changes')
  .argument('<file>', 'Input file to process')
  .action(({ args, flags, options }) => {
    console.log('Processing file:', args[0]);
    if (flags.watch) console.log('Watching for changes...');
    if (options.port) console.log('Port:', options.port);
  });

await cli.run();

Usage:

my-app input.txt --port 3000 --watch

With Subcommands

import { cli } from '@dephub/cli';

// Build command
cli
  .command('build', 'Build the project')
  .option('--outDir', 'Output directory')
  .action(({ options }) => {
    console.log('Building to:', options.outDir);
  });

// Dev command
cli
  .command('dev', 'Start development server')
  .option('--port', 'Server port')
  .action(({ options }) => {
    console.log('Starting server on port:', options.port);
  });

await cli.run();

Usage:

my-app build --outDir=dist
my-app dev --port 3000

Advanced Usage 🔧

Custom CLI Instance

import { createCLI } from '@dephub/cli';

const cli = createCLI({
  name: 'my-tool',
  version: '1.0.0',
  description: 'My custom CLI tool',
});

cli.flag('--verbose', 'Enable verbose logging').action(({ flags }) => {
  if (flags.verbose) console.log('Verbose mode enabled');
});

await cli.run();

Programmatic Parsing

import { Command } from '@dephub/cli';

const command = new Command()
  .name('parser')
  .option('--config', 'Config file path');

// Parse arguments without executing
const result = command.parse(['--config', 'app.json']);
console.log(result.options.config); // 'app.json'

Command Aliases

import { cli } from '@dephub/cli';

cli
  .command('start', 'Start the application')
  .alias('s', 'run') // Multiple aliases
  .action(() => {
    console.log('Application started');
  });

// All these work:
// my-app start
// my-app s
// my-app run

API Reference 📚

Core Methods

Command Class

• .name(string) - Set command name
• .version(string) - Set command version
• .description(string) - Set command description
• .option(flag, description) - Define option with value
• .flag(flag, description) - Define boolean flag
• .argument(name, description) - Define positional argument
• .command(name, description) - Create subcommand
• .alias(...names) - Add command aliases
• .action(function) - Set execution function
• .run() - Execute command with process arguments
• .parse(args) - Parse arguments without execution
• .help() - Display help information

Factory Function

• createCLI(options?) - Create pre-configured CLI instance

Action Parameters

action(({ args, flags, options }) => {
  // args: string[] - Positional arguments in order
  // flags: Record<string, boolean> - Boolean flags (true if present)
  // options: Record<string, string | undefined> - Option values
});

Argument Types

• <required> - Required positional argument
• [optional] - Optional positional argument
• --option - Option that requires a value
• --flag - Boolean flag (no value needed)

Examples 📝

File Processor CLI

import { cli } from '@dephub/cli';
import { readFile, writeFile } from '@dephub/read-write';

cli
  .name('file-processor')
  .version('1.0.0')
  .option('--output', 'Output file path')
  .flag('--minify', 'Minify the output')
  .argument('<input>', 'Input file to process')
  .action(async ({ args, flags, options }) => {
    const content = await readFile(args[0]);
    let processed = content.toUpperCase();

    if (flags.minify) processed = processed.replace(/\s+/g, '');

    const outputPath = options.output || 'output.txt';
    await writeFile(outputPath, processed);
    console.log(`Processed ${args[0]} -> ${outputPath}`);
  });

await cli.run();

Multi-command Development Tool

import { cli } from '@dephub/cli';

// Build command
cli
  .command('build', 'Build project for production')
  .option('--minify', 'Minify output')
  .action(({ options }) => {
    console.log('Building production version...');
    if (options.minify) console.log('With minification');
  });

// Test command
cli
  .command('test', 'Run test suite')
  .option('--coverage', 'Generate coverage report')
  .action(({ options }) => {
    console.log('Running tests...');
    if (options.coverage) console.log('With coverage');
  });

// Default action
cli.action(() => {
  console.log('Please specify a command: build, test');
});

await cli.run();

License 📄

MIT License – see LICENSE for details.

Author: Estarlin R (estarlincito.com)