quickcli

A simple auto-discover CLI framework for quickly scaffolding one-shot tasks in your project.

Features

• 🔍 Auto-discovery: Automatically discovers commands from your commands/ directory
• 📦 Namespace support: Organize commands with namespaces (e.g., db:migrate, api:deploy)
• ⚡ Zero config: Just create command files and start using them
• 🎯 TypeScript-first: Built with TypeScript, full type safety included
• 🛠️ Simple API: Easy-to-use command structure with options and handlers

Installation

npm install @razkaroth/quickcli

Quick Start

1. Create a command file

Create a file in your project's commands/ directory (e.g., commands/greet.ts):

import { type Command } from '@razkaroth/quickcli'

export const command: Command = {
  name: 'greet',
  description: 'Greet a user',
  options: [
    {
      name: '--name',
      description: 'Name to greet',
      type: 'string',
      default: 'World',
    },
  ],
  handler: async (args) => {
    const name = args.name || 'World'
    console.log(`Hello, ${name}!`)
  },
}

2. Run your command

npx quickcli greet --name "Developer"

Command Structure

Commands are TypeScript/JavaScript files that export a command object:

export const command: Command = {
  name: string              // Command name (can include namespace like 'db:migrate')
  description: string       // Brief description for help text
  options?: Option[]        // Optional array of command-line options
  handler: async (args) => {} // Async function that executes the command
}

Options Configuration

Each option supports:

{
  name: string           // Flag name (e.g., '--name', '-n')
  description: string    // Help text
  type?: 'string' | 'boolean' | 'number'
  required?: boolean     // Whether the option is required
  default?: any          // Default value if not provided
}

Namespaces

Organize commands with namespaces by creating subdirectories:

commands/
  db/
    migrate.ts    → db:migrate
    seed.ts       → db:seed
  api/
    deploy.ts     → api:deploy

Use namespaced commands:

npx quickcli db:migrate
npx quickcli api:deploy --env production

CLI Options

• --target-dir <path>: Specify custom commands directory (default: src/quickcli)

npx quickcli greet --target-dir ./my-commands

Built-in Commands

• help: Show all available commands
• help <command>: Show detailed help for a specific command

Programmatic Usage

You can also use quickcli programmatically:

import { Registry, discoverCommands } from '@razkaroth/quickcli'

const registry = new Registry()
const commands = await discoverCommands('./commands')

commands.forEach(cmd => registry.register(cmd))

const myCommand = registry.get('greet')
await myCommand?.handler({ name: 'World' })

Examples

See the examples/ directory for more command examples.

License

MIT