a5c-ai/commander-js-scaffolder

Commander.js Scaffolder

Generate a complete Commander.js CLI application with TypeScript, proper project structure, and best practices.

Capabilities

• Generate TypeScript-based Commander.js CLI projects
• Create command structure with subcommands and options
• Set up proper argument parsing with type coercion
• Configure help text generation
• Implement version management
• Set up build and development workflows

Usage

Invoke this skill when you need to:

• Bootstrap a new CLI application using Commander.js
• Create a TypeScript CLI with proper structure
• Set up command hierarchies with subcommands
• Configure CLI options and arguments

Inputs

| Parameter | Type | Required | Description | |-----------|------|----------|-------------| | projectName | string | Yes | Name of the CLI project (kebab-case) | | description | string | Yes | Short description of the CLI | | commands | array | No | List of commands to scaffold | | typescript | boolean | No | Use TypeScript (default: true) | | packageManager | string | No | npm, yarn, or pnpm (default: npm) |

Command Structure

{
  "commands": [
    {
      "name": "init",
      "description": "Initialize a new project",
      "options": [
        { "flags": "-t, --template <name>", "description": "Template to use" },
        { "flags": "-f, --force", "description": "Overwrite existing files" }
      ],
      "arguments": [
        { "name": "<directory>", "description": "Target directory" }
      ]
    }
  ]
}

Output Structure

<projectName>/
├── package.json
├── tsconfig.json
├── .gitignore
├── README.md
├── src/
│   ├── index.ts              # Entry point with shebang
│   ├── cli.ts                # Main CLI setup
│   ├── commands/
│   │   ├── index.ts          # Command exports
│   │   └── <command>.ts      # Individual commands
│   ├── utils/
│   │   ├── logger.ts         # Logging utilities
│   │   └── config.ts         # Configuration helpers
│   └── types/
│       └── index.ts          # Type definitions
├── bin/
│   └── <projectName>         # Compiled binary entry
└── tests/
    └── commands/
        └── <command>.test.ts

Generated Code Patterns

Main CLI Entry (src/cli.ts)

import { Command } from 'commander';
import { version } from '../package.json';

const program = new Command();

program
  .name('<projectName>')
  .description('<description>')
  .version(version, '-v, --version', 'Display version number');

// Register commands
program.addCommand(initCommand);
program.addCommand(buildCommand);

// Global options
program
  .option('-d, --debug', 'Enable debug mode')
  .option('-q, --quiet', 'Suppress output');

// Error handling
program.exitOverride();

try {
  program.parse();
} catch (err) {
  // Handle gracefully
}

Command Template (src/commands/<name>.ts)

import { Command } from 'commander';

export const <name>Command = new Command('<name>')
  .description('<description>')
  .argument('<required>', 'Required argument description')
  .argument('[optional]', 'Optional argument description')
  .option('-o, --option <value>', 'Option description', 'default')
  .action(async (required, optional, options) => {
    // Command implementation
  });

Dependencies

{
  "dependencies": {
    "commander": "^12.0.0"
  },
  "devDependencies": {
    "@types/node": "^20.0.0",
    "typescript": "^5.0.0",
    "tsx": "^4.0.0",
    "vitest": "^1.0.0"
  }
}

Workflow

1. Validate inputs - Check project name, commands structure
2. Create directory structure - Set up folders and base files
3. Generate package.json - Configure project metadata and scripts
4. Generate tsconfig.json - TypeScript configuration
5. Create CLI entry point - Main program setup
6. Generate commands - Individual command files
7. Create utilities - Logger, config helpers
8. Set up tests - Test structure for commands
9. Initialize git - Optional git initialization

Best Practices Applied

• TypeScript strict mode enabled
• Proper error handling with exitOverride
• Consistent command naming conventions
• Help text formatting standards
• Version flag configuration
• Debug/verbose mode support
• Graceful error messages

References

• Commander.js Documentation: https://github.com/tj/commander.js
• Commander.js Examples: https://github.com/tj/commander.js/tree/master/examples
• Node.js CLI Best Practices: https://clig.dev/

Target Processes

• cli-application-bootstrap
• cli-command-structure-design
• argument-parser-setup