system-create-cli

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)

READ: references/tier-comparison.md for detailed framework comparison, performance metrics, and migration paths

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 QARA

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: bun test (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:

• Deterministic - Same input → Same output

• Clean - Single responsibility

• Composable - JSON output pipes to other tools

• Documented - Comprehensive help and examples

• 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

READ: references/tier-comparison.md for comprehensive framework comparison including:

• Detailed feature comparison (Tier 1 vs 2 vs 3)

• Performance metrics (startup time, memory usage)

• Migration paths between tiers

• Decision algorithm for tier selection

• Real-world examples and recommendations

READ: references/cli-examples-basic.md and references/cli-examples-advanced.md for 6 complete examples covering:

• API clients (GitHub, Notion)

• File processors (markdown, CSV)

• Data pipelines (complex workflows)

• Database operations (PostgreSQL)

• Common patterns and testing approaches

• Documentation templates

PHILOSOPHY

Why This Skill Exists

User repeatedly creates CLIs for APIs and tools. Each time:

• Starts with bash script

• Realizes it needs error handling

• Realizes it needs help text

• Realizes it needs type safety

• Rewrites in TypeScript

• Adds documentation

• Now has production CLI

This skill automates steps 1-7.

The llcli Pattern

The llcli CLI (Limitless.ai API) proves this pattern works:

• 327 lines of TypeScript

• Zero dependencies (no framework)

• Complete error handling

• Comprehensive documentation

• Production-ready immediately

This skill replicates that success.

Design Principles

• Start Simple - Default to Tier 1 (llcli-style)

• Escalate When Needed - Tier 2 only when justified

• Complete, Not Scaffold - Every CLI is production-ready

• Documentation First - README explains "why" not just "how"

• Type Safety - TypeScript strict mode always

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, 1 error)

3. Documentation

• ✅ README explains philosophy and usage

• ✅ QUICKSTART has common examples

• ✅ --help text comprehensive

• ✅ All flags/options documented

4. Code Quality

• ✅ Type-safe throughout

• ✅ Clean function separation

• ✅ Error messages actionable

• ✅ Configuration externalized

5. Integration

• ✅ Follows PAI tech stack (Bun, TypeScript)

• ✅ CLI-First Architecture principles

• ✅ Deterministic output (JSON)

• ✅ Composable with other tools

This skill turns "I need a CLI for X" into production-ready tools in minutes, following proven patterns from llcli and PAI's CLI-First Architecture.