system-createcli

system-createcli

Automated CLI Generation System

Generate production-ready TypeScript CLIs with comprehensive documentation, type safety, error handling, and PAI's CLI-First Architecture principles.

🎯 WORKFLOW ROUTING (SYSTEM PROMPT)

When user requests CLI creation, follow this routing:

Primary Workflow: Create New CLI

Triggers: "create CLI", "build command-line tool", "make CLI for X", "generate CLI" Route to: workflows/create-cli.md Action: Generate complete CLI from requirements

Extension Workflow: Add Command

Triggers: "add command to CLI", "extend CLI with", "add feature to existing CLI" Route to: workflows/add-command.md Action: Add new command to existing CLI

Migration Workflow: Upgrade Complexity Tier

Triggers: "upgrade CLI", "migrate to Commander", "CLI needs more complexity" Route to: workflows/upgrade-tier.md Action: Migrate Tier 1 → Tier 2 (manual → Commander.js)

Testing Workflow: Add Test Suite

Triggers: "add tests to CLI", "test scaffolding", "need CLI tests" Route to: workflows/add-testing.md Action: Generate comprehensive test suite

Distribution Workflow: Setup Publishing

Triggers: "publish CLI", "distribute CLI", "make standalone binary" Route to: workflows/setup-distribution.md Action: Configure npm publishing or binary distribution

🚀 WHEN TO ACTIVATE THIS SKILL

Activate when you see these patterns:

Direct Requests

• "Create a CLI for [API/service/tool]"
• "Build a command-line interface for X"
• "Make a CLI that does Y"
• "Generate a TypeScript CLI"
• "I need a CLI tool for Z"

Context Clues

• User describes repetitive API calls → Suggest CLI
• User mentions "I keep typing this command" → Suggest CLI wrapper
• User has bash script doing complex work → Suggest TypeScript CLI replacement
• User working with API that lacks official CLI → Suggest creating one

Examples

• ✅ "Create a CLI for the GitHub API"
• ✅ "Build a command-line tool to process CSV files"
• ✅ "Make a CLI for my database migrations"
• ✅ "Generate a CLI that wraps this API"
• ✅ "I need a tool like llcli but for Notion API"

💡 CORE CAPABILITIES

Three-Tier Template System

Tier 1: llcli-Style (DEFAULT - 80% of use cases)

• Manual argument parsing (process.argv)
• Zero framework dependencies
• Bun + TypeScript
• Type-safe interfaces
• ~300-400 lines total
• Perfect for: API clients, data transformers, simple automation

When to use Tier 1:

• ✅ 2-10 commands
• ✅ Simple arguments (flags, values)
• ✅ JSON output
• ✅ No subcommands
• ✅ Fast development

Tier 2: Commander.js (ESCALATION - 15% of use cases)

• Framework-based parsing
• Subcommands + nested options
• Auto-generated help
• Plugin-ready
• Perfect for: Complex multi-command tools

When to use Tier 2:

• ❌ 10+ commands needing grouping
• ❌ Complex nested options
• ❌ Plugin architecture
• ❌ Multiple output formats

Tier 3: oclif (REFERENCE ONLY - 5% of use cases)

• Documentation only (no templates)
• Enterprise-grade plugin systems
• Perfect for: Heroku CLI, Salesforce CLI scale (rare)

What Every Generated CLI Includes

1. Complete Implementation

• TypeScript source with full type safety
• All commands functional and tested
• Error handling with proper exit codes
• Configuration management

2. Comprehensive Documentation

• README.md with philosophy, usage, examples
• QUICKSTART.md for common patterns
• Inline help text (--help)
• API response documentation

3. Development Setup

• package.json (Bun configuration)
• tsconfig.json (strict mode)
• .env.example (configuration template)
• File permissions configured

4. Quality Standards

• Type-safe throughout
• Deterministic output (JSON)
• Composable (pipes to jq, grep)
• Error messages with context
• Exit code compliance

🏗️ INTEGRATION WITH KAI

Technology Stack Alignment

Generated CLIs follow PAI's standards:

• ✅ Runtime: Bun (NOT Node.js)
• ✅ Language: TypeScript (NOT JavaScript or Python)
• ✅ Package Manager: Bun (NOT npm/yarn/pnpm)
• ✅ Testing: Vitest (when tests added)
• ✅ Output: Deterministic JSON (composable)
• ✅ Documentation: README + QUICKSTART (llcli pattern)

Repository Placement

Generated CLIs go to:

• ${PAI_DIR}/bin/[cli-name]/ - Personal CLIs (like llcli)
• ~/Projects/[project-name]/ - Project-specific CLIs
• ~/Projects/PAI/examples/clis/ - Example CLIs (PUBLIC repo)

SAFETY: Always verify repository location before git operations

CLI-First Architecture Principles

Every generated CLI follows:

1. Deterministic - Same input → Same output
2. Clean - Single responsibility
3. Composable - JSON output pipes to other tools
4. Documented - Comprehensive help and examples
5. Testable - Predictable behavior

📚 EXTENDED CONTEXT

For detailed information, read these files:

Workflow Documentation

• workflows/create-cli.md - Main CLI generation workflow (decision tree, 10-step process)
• workflows/add-command.md - Add commands to existing CLIs
• workflows/upgrade-tier.md - Migrate simple → complex
• workflows/add-testing.md - Test suite generation
• workflows/setup-distribution.md - Publishing configuration

Reference Documentation

• framework-comparison.md - Manual vs Commander vs oclif (with research)
• patterns.md - Common CLI patterns (from llcli analysis)
• testing-strategies.md - CLI testing approaches (Jest, Vitest, Playwright)
• distribution.md - Publishing strategies (npm, standalone binaries)
• typescript-patterns.md - Type safety patterns (from tsx, vite, bun research)

Tools & Templates

• tools/templates/tier1/ - llcli-style templates (default)
• tools/templates/tier2/ - Commander.js templates (escalation)
• tools/generators/ - Generation scripts (TypeScript)
• tools/validators/ - Quality gates (validation)

Examples

• examples/api-cli/ - API client (reference: llcli)
• examples/file-processor/ - File operations
• examples/data-transform/ - Complex CLI (Commander.js)

📖 EXAMPLES

Example 1: API Client CLI (Tier 1)

User Request: "Create a CLI for the GitHub API that can list repos, create issues, and search code"

Generated Structure:

${PAI_DIR}/bin/ghcli/
├── ghcli.ts              # 350 lines, complete implementation
├── package.json          # Bun + TypeScript
├── tsconfig.json         # Strict mode
├── .env.example          # GITHUB_TOKEN=your_token
├── README.md             # Full documentation
└── QUICKSTART.md         # Common use cases

Usage:

ghcli repos --user danielmiessler
ghcli issues create --repo pai --title "Bug fix"
ghcli search "typescript CLI"
ghcli --help

Example 2: File Processor (Tier 1)

User Request: "Build a CLI to convert markdown files to HTML with frontmatter extraction"

Generated Structure:

${PAI_DIR}/bin/md2html/
├── md2html.ts
├── package.json
├── README.md
└── QUICKSTART.md

Usage:

md2html convert input.md output.html
md2html batch *.md output/
md2html extract-frontmatter post.md

Example 3: Data Pipeline (Tier 2)

User Request: "Create a CLI for data transformation with multiple formats, validation, and analysis commands"

Generated Structure:

${PAI_DIR}/bin/data-cli/
├── data-cli.ts           # Commander.js with subcommands
├── package.json
├── README.md
└── QUICKSTART.md

Usage:

data-cli convert json csv input.json
data-cli validate schema data.json
data-cli analyze stats data.csv
data-cli transform filter --column=status --value=active

✅ QUALITY STANDARDS

Every generated CLI must pass these gates:

1. Compilation

• ✅ TypeScript compiles with zero errors
• ✅ Strict mode enabled
• ✅ No any types except justified

2. Functionality

• ✅ All commands work as specified
• ✅ Error handling comprehensive
• ✅ Exit codes correct (0 success,