@razkaroth/quickcli/README.md

A simple autodiscover cli framework intended to quickly scaffold oneshot tasks in your project.

# 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

```bash
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`):

```typescript
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

```bash
npx quickcli greet --name "Developer"
```

## Command Structure

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

```typescript
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:

```typescript
{
  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:

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

## CLI Options

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

```bash
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:

```typescript
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