gh-vanman2024-cli-builder-plugins-cli-builder/skills/oclif-patterns/SKILL.md

name, description, allowed-tools

name	description	allowed-tools
oclif-patterns	Enterprise CLI patterns using oclif framework with TypeScript. Use when building oclif CLIs, creating plugins, implementing commands with flags/args, adding auto-documentation, testing CLI commands, or when user mentions oclif, enterprise CLI, TypeScript CLI, plugin system, or CLI testing.	Read, Write, Edit, Bash, Glob, Grep

oclif Enterprise CLI Patterns

Provides comprehensive patterns for building production-grade CLIs with oclif framework.

Core Capabilities

1. Command Structure

• Single and multi-command CLIs
• Flag definitions (string, boolean, integer, custom)
• Argument parsing with validation
• Command inheritance and base classes
• Async command execution

2. Plugin System

• Installable plugins
• Plugin discovery and loading
• Hook system for extensibility
• Plugin commands and lifecycle

3. Auto-Documentation

• Auto-generated help text
• README generation
• Command reference docs
• Flag and argument documentation

4. Testing Patterns

• Command unit tests
• Integration testing
• Mock stdin/stdout
• Fixture management
• Test helpers

Implementation Guide

Command Creation

Use templates:

• templates/command-basic.ts - Simple command with flags
• templates/command-advanced.ts - Complex command with validation
• templates/command-async.ts - Async operations
• templates/base-command.ts - Custom base class

Key patterns:

1. Import Command from '@oclif/core'
2. Define flags using Flags object
3. Define args using Args object
4. Implement async run() method
5. Use this.log() for output
6. Use this.error() for errors

Flag Patterns

Common flags:

• String: Flags.string({ description, required, default })
• Boolean: Flags.boolean({ description, allowNo })
• Integer: Flags.integer({ description, min, max })
• Custom: Flags.custom<T>({ parse: async (input) => T })
• Multiple: Flags.string({ multiple: true })

Best practices:

• Always provide clear descriptions
• Use char for common short flags
• Set required vs optional explicitly
• Provide sensible defaults
• Validate in parse function for custom flags

Argument Patterns

Definition:

static args = {
  name: Args.string({ description: 'Name', required: true }),
  file: Args.file({ description: 'File path', exists: true })
}

Access in run():

const { args } = await this.parse(MyCommand)

Plugin Development

Use templates:

• templates/plugin-package.json - Plugin package.json
• templates/plugin-command.ts - Plugin command structure
• templates/plugin-hooks.ts - Hook implementations

Plugin structure:

my-plugin/
├── package.json (oclif configuration)
├── src/
│   ├── commands/ (plugin commands)
│   └── hooks/ (lifecycle hooks)
├── test/ (plugin tests)
└── README.md

Testing Setup

Use templates:

• templates/test-command.ts - Command test template
• templates/test-helpers.ts - Test utilities
• templates/test-setup.ts - Test configuration

Testing approach:

1. Use @oclif/test for test helpers
2. Mock stdin/stdout with fancy-test
3. Test flag parsing separately
4. Test command execution
5. Test error handling
6. Use fixtures for file operations

Auto-Documentation

Generated automatically:

• Command help via --help flag
• README.md with command reference
• Usage examples
• Flag and argument tables

Use scripts:

• scripts/generate-docs.sh - Generate all documentation
• scripts/update-readme.sh - Update README with commands

Quick Start Examples

Create Basic Command

# Use template
./scripts/create-command.sh my-command basic

# Results in: src/commands/my-command.ts

Create Plugin

# Use template
./scripts/create-plugin.sh my-plugin

# Results in: plugin directory structure

Run Tests

# Use test helpers
npm test
# or with coverage
npm run test:coverage

Validation Scripts

Available validators:

• scripts/validate-command.sh - Check command structure
• scripts/validate-plugin.sh - Verify plugin structure
• scripts/validate-tests.sh - Ensure test coverage

Templates Reference

TypeScript Commands

1. command-basic.ts - Simple command pattern
2. command-advanced.ts - Full-featured command
3. command-async.ts - Async/await patterns
4. base-command.ts - Custom base class
5. command-with-config.ts - Configuration management

Plugin System

6. plugin-package.json - Plugin package.json
7. plugin-command.ts - Plugin command
8. plugin-hooks.ts - Hook implementations
9. plugin-manifest.json - Plugin manifest

Testing

10. test-command.ts - Command unit test
11. test-helpers.ts - Test utilities
12. test-setup.ts - Test configuration
13. test-integration.ts - Integration test

Configuration

14. tsconfig.json - TypeScript config
15. package.json - oclif package.json
16. .eslintrc.json - ESLint config

Examples Directory

See examples/ for complete working examples:

• examples/basic-cli/ - Simple CLI with commands
• examples/plugin-cli/ - CLI with plugin support
• examples/enterprise-cli/ - Full enterprise setup

Common Patterns

Error Handling

if (!valid) {
  this.error('Invalid input', { exit: 1 })
}

Spinner/Progress

const spinner = ux.action.start('Processing')
// ... work
ux.action.stop()

Prompts

const answer = await ux.prompt('Continue?')

Table Output

ux.table(data, { columns: [...] })

Requirements

• Node.js 18+
• TypeScript 5+
• @oclif/core ^3.0.0
• @oclif/test for testing
• Knowledge of TypeScript decorators (optional but helpful)

Best Practices

1. Command Design: Keep commands focused, single responsibility
2. Flags: Use descriptive names, provide help text
3. Testing: Test command parsing and execution separately
4. Documentation: Let oclif generate docs, keep them updated
5. Plugins: Design for extensibility from the start
6. Error Messages: Provide actionable error messages
7. TypeScript: Use strict mode, define proper types
8. Async: Use async/await, handle promises properly

Advanced Features

Custom Flag Types

Create reusable custom flag parsers for complex validation.

Hook System

Implement hooks for: init, prerun, postrun, command_not_found.

Topic Commands

Organize commands into topics (e.g., mycli topic:command).

Auto-Update

Use @oclif/plugin-update for automatic CLI updates.

Analytics

Integrate analytics to track command usage.