@bitkai/cli

A modern, type-safe CLI framework for building command-line applications in TypeScript with interactive prompts and beautiful output.

Features

• 🎯 Type-safe: Full TypeScript support with proper type inference
• 💬 Interactive: Built-in support for interactive prompts and rich input types
• 🎨 Beautiful Output: Colored and formatted terminal output
• 🔒 Validation: Built-in argument validation
• 🚀 Modern: Built for ESM and modern Node.js
• 📝 Great DX: Intuitive and fluent API
• 🤖 Smart Prompts: Automatic fallback to interactive prompts for missing arguments

Installation

npm install @bitkai/cli

Quick Start

import { CLI } from '@bitkai/cli';

const cli = new CLI({
  name: 'mycli',
  version: '1.0.0',
  description: 'My awesome CLI tool'
});

cli.command('greet')
  .description('Greet someone by name')
  .argument('name', 'Name of the person to greet', { 
    type: 'text',
    required: true 
  })
  .option('loud', 'Print the greeting in uppercase', { 
    type: 'confirm',
    default: false 
  })
  .handler(async ({ args, options }) => {
    let message = `Hello, ${args.name}!`;
    if (options.loud) {
      message = message.toUpperCase();
    }
    console.log(message);
  });

cli.run();

Interactive Prompts

@bitkai/cli provides a rich set of interactive prompts that automatically engage when required arguments are missing. This creates a user-friendly experience where users can be guided through the command inputs.

Available Prompt Types

• text: Free-form text input
• number: Numeric input with optional validation
• confirm: Yes/No confirmation
• list: Multi-select from a list of choices
• select: Single selection from a list of choices

Prompt Behavior

• Prompts automatically trigger for missing required arguments
• Each prompt type provides appropriate validation
• Users can use arrow keys for navigation in list/select prompts
• Support for default values and initial inputs
• Tab completion for better UX

Example of how prompts work:

$ mycli init
? Project name: (required) my-project
? Select template: (Use arrow keys)
❯ typescript
  javascript
  react

API Reference

Creating a CLI

const cli = new CLI({
  name: string;      // Name of your CLI application
  version: string;   // Version number
  description: string; // Brief description
});

Defining Commands

cli.command(name: string)
  .description(description: string)
  .argument(name: string, description: string, options?: ArgumentOptions)
  .option(name: string, description: string, options?: OptionOptions)
  .handler(handler: (context: CommandContext) => Promise<void>)

Argument Options

type ArgumentOptions = {
  type: 'text' | 'number' | 'confirm' | 'list' | 'select';
  required?: boolean;
  initial?: any;
  choices?: string[];  // For 'list' and 'select' types
}

Option Options

type OptionOptions = {
  type: 'text' | 'number' | 'confirm' | 'list' | 'select';
  default?: any;
  initial?: any;
  choices?: string[];  // For 'list' and 'select' types
}

Command Context

The action handler receives a context object with:

type CommandContext = {
  args: Record<string, any>;    // Parsed command arguments
  options: Record<string, any>; // Parsed command options
  raw: string[];               // Raw command-line arguments
}

Examples

Basic Command with Prompts

cli.command('create')
  .description('Create a new resource')
  .argument('name', 'Resource name', { 
    type: 'text',
    required: true,
    initial: 'my-resource'
  })
  .argument('type', 'Resource type', {
    type: 'select',
    required: true,
    choices: ['component', 'service', 'model']
  })
  .option('path', 'Output path', { 
    type: 'text',
    default: './src' 
  })
  .handler(async ({ args, options }) => {
    const { name, type } = args;
    const { path } = options;
    console.log(`Creating ${type} "${name}" in ${path}`);
  });

Interactive Configuration

cli.command('config')
  .description('Configure application settings')
  .argument('settings', 'Settings to configure', {
    type: 'list',
    choices: ['database', 'api', 'logging', 'security'],
    required: true
  })
  .option('environment', 'Target environment', {
    type: 'select',
    choices: ['development', 'staging', 'production'],
    default: 'development'
  })
  .handler(async ({ args, options }) => {
    const { settings } = args;
    const { environment } = options;
    console.log(`Configuring ${settings.join(', ')} for ${environment}`);
  });

Multi-step Workflow

cli.command('deploy')
  .description('Deploy the application')
  .argument('stage', 'Deployment stage', {
    type: 'select',
    required: true,
    choices: ['staging', 'production']
  })
  .argument('services', 'Services to deploy', {
    type: 'list',
    required: true,
    choices: ['frontend', 'backend', 'database']
  })
  .option('force', 'Skip confirmation', {
    type: 'confirm',
    default: false
  })
  .handler(async ({ args, options }) => {
    const { stage, services } = args;
    const { force } = options;
    console.log(`Deploying ${services.join(', ')} to ${stage}`);
  });

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

License

ISC