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

1. •plugin-package.json - Plugin package.json
2. •plugin-command.ts - Plugin command
3. •plugin-hooks.ts - Hook implementations
4. •plugin-manifest.json - Plugin manifest

Testing

1. •test-command.ts - Command unit test
2. •test-helpers.ts - Test utilities
3. •test-setup.ts - Test configuration
4. •test-integration.ts - Integration test

Configuration

1. •tsconfig.json - TypeScript config
2. •package.json - oclif package.json
3. •.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.