CLI Generator

CLI Generator

SPEC → Bun CLI. Production-ready. Autocomplete, --help, token-aware output.

Quick Start

/cli-generator from-spec <spec-file>          — OpenAPI / JSON Schema → CLI
/cli-generator from-api <url>                 — live API → CLI (probe endpoints)
/cli-generator from-description "<text>"      — natural language → CLI
/cli-generator validate <cli-dir>             — check generated CLI against spec

Input Sources

Output — What You Get

my-cli/
├── package.json          # bin entry, dependencies
├── tsconfig.json         # Bun-optimized TS config
├── src/
│   ├── index.ts          # entry point, commander setup
│   ├── commands/         # one file per subcommand
│   │   ├── list.ts
│   │   ├── get.ts
│   │   ├── create.ts
│   │   ├── update.ts
│   │   └── delete.ts
│   ├── lib/
│   │   ├── client.ts     # typed API client (generated)
│   │   ├── format.ts     # output formatters (json, table, yaml)
│   │   └── config.ts     # env vars, config file handling
│   └── types.ts          # generated from spec
├── completions/
│   ├── bash.sh
│   ├── zsh.sh
│   └── fish.sh
├── man/
│   └── my-cli.1          # man page
├── test/
│   └── commands.test.ts  # bun test suite
├── README.md             # usage docs
└── Makefile              # build, install, test

Workflow — Spec to CLI

Claude will:

Phase 1: Parse

1. Read the input (OpenAPI, JSON Schema, markdown, or NL)
2. Extract: commands, subcommands, flags, args, types
3. Infer missing details (descriptions, defaults, validation rules)
4. Confirm the command tree with user before generating

Phase 2: Generate

1. Scaffold project structure with package.json + tsconfig.json
2. Generate typed API client from spec (if OpenAPI/GraphQL)
3. Generate one file per subcommand with commander/args
4. Wire up autocomplete (bash/zsh/fish)
5. Generate man page
6. Generate test suite with bun test

Phase 3: Verify

1. bun run src/index.ts --help — validates CLI boots
2. bun test — all generated tests pass
3. bun run build — compiles without errors
4. Output: ready to npm install -g or bun link

Generated Code Example

Input — OpenAPI snippet:

paths:
  /users:
    get:
      operationId: listUsers
      summary: List all users
      parameters:
        - name: role
          in: query
          schema:
            type: string
            enum: [admin, user, guest]
        - name: limit
          in: query
          schema:
            type: integer
            default: 20
        - name: offset
          in: query
          schema:
            type: integer
            default: 0
    post:
      operationId: createUser
      summary: Create a new user
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [name, email]
              properties:
                name:
                  type: string
                email:
                  type: string
                  format: email
                role:
                  type: string
                  enum: [admin, user, guest]
                  default: user
  /users/{id}:
    get:
      operationId: getUser
      summary: Get user by ID
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
            format: uuid

Output — src/commands/list.ts:

import { Command } from 'commander'
import { client } from '../lib/client'
import { formatOutput } from '../lib/format'
import type { User } from '../types'

export const listUsersCommand = new Command('list')
  .description('List all users')
  .option('--role <role>', 'Filter by role (admin, user, guest)')
  .option('--limit <number>', 'Max results', '20')
  .option('--offset <number>', 'Pagination offset', '0')
  .action(async (opts) => {
    const { data, error } = await client.GET('/users', {
      params: {
        query: {
          role: opts.role,
          limit: Number(opts.limit),
          offset: Number(opts.offset),
        },
      },
    })

    if (error) {
      console.error(`Error: ${error.message}`)
      process.exit(1)
    }

    formatOutput<User[]>(data, {
      columns: ['id', 'name', 'email', 'role'],
      format: opts.format ?? 'table',
    })
  })

Bundled Runtime — Token-Aware Output

Every generated CLI includes src/lib/format.ts with three modes:

--format tokens strips whitespace, deduplicates, and outputs only essential fields — minimizing context window consumption when a CLI is invoked by an AI agent.

Validation

/cli-generator validate ./my-cli

Checks:

• ✓ All spec endpoints have corresponding commands
• ✓ All required params are enforced
• ✓ Types match between spec and generated code
• ✓ Autocomplete covers all flags
• ✓ Tests exist for every command
• ✓ Build succeeds
• ✓ --help output is complete

Frameworks Used

• Runtime: Bun — fast startup, native TS, built-in test runner
• Arg parsing: commander (most mature) or citty (lighter, Bun-native)
• API client: generated openapi-fetch wrapper (typed) or fetch with Zod validation
• Output: custom --format tokens mode for AI harness consumption

Design Decisions

1. One file per command — keeps files small, AI-navigable
2. Typed client from spec — no manual fetch calls, full autocomplete
3. Token-aware by default — every CLI ships with --format tokens
4. Tests generated alongside code — not an afterthought
5. Shell completions built-in — no extra install step

Example Session

User: /cli-generator from-spec ./openapi.yaml
Claude:
  ✓ Parsed OpenAPI 3.1 — 12 endpoints, 5 schemas
  Command tree:
    users list [--role] [--limit] [--offset]
    users get <id>
    users create --name --email [--role]
    users update <id> [--name] [--email] [--role]
    users delete <id>
  Confirm? (y/n)

User: y
Claude:
  ✓ Scaffolded project (8 files)
  ✓ Generated typed client
  ✓ Generated 5 command files
  ✓ Generated autocomplete (bash/zsh/fish)
  ✓ Generated man page
  ✓ Generated 12 tests
  ✓ Build passing
  ✓ CLI boots: my-cli --help

  Done. Try:
    cd my-cli && bun link && my-cli users list --format tokens