CLI Management

Core commands for creating, initializing, and maintaining oclif CLI projects, including project setup and documentation generation.

Capabilities

Generate New CLI Project

Creates a complete oclif CLI project from scratch with all necessary files and dependencies.

oclif generate [NAME]

Arguments:

• NAME (string, required) - Directory name of the new project

Flags:

• --author (string) - Author name for package.json
• --bin (string) - Binary name for the CLI
• --description (string) - Description for package.json
• --license (string) - License type (default: MIT)
• --module-type (esm|commonjs) - Module system to use
• --name (string) - Package name override
• --owner (string) - GitHub owner/organization
• --package-manager (npm|yarn|pnpm) - Package manager preference
• --repository (string) - GitHub repository URL
• --dry-run, -n (boolean) - Preview changes without creating files
• --output-dir, -d (string) - Output directory path
• --yes, -y (boolean) - Skip all prompts with default values

Usage Examples:

# Interactive generation
oclif generate my-awesome-cli

# Automated generation with options
oclif generate my-cli --author="John Doe" --module-type=esm --package-manager=npm --yes

# Preview without creating files
oclif generate my-cli --dry-run

Initialize Existing Project

Converts an existing Node.js project into an oclif CLI by adding necessary configuration and dependencies.

oclif init

Flags:

• --bin (string) - Binary name for the CLI
• --module-type (esm|commonjs) - Module system to use
• --package-manager (npm|yarn|pnpm) - Package manager preference
• --topic-separator (colons|spaces) - Separator for nested commands (default: spaces)
• --output-dir, -d (string) - Output directory path
• --yes, -y (boolean) - Skip all prompts with default values

Usage Examples:

# Interactive initialization
oclif init

# Initialize with specific options
oclif init --bin=mycli --module-type=esm --yes

Generate README Documentation

Automatically generates or updates README.md with comprehensive command documentation, including usage examples and command descriptions.

oclif readme

Flags:

• --aliases (boolean) - Include command aliases in documentation
• --dry-run (boolean) - Preview README changes without writing
• --multi (boolean) - Generate multi-command CLI documentation format
• --nested-topics-depth (number) - Maximum nesting depth for topics
• --output-dir (string) - Output directory for README.md
• --plugin-directory (string) - Directory containing plugins to document
• --readme-path (string) - Path to README.md file (default: ./README.md)
• --repository-prefix (string) - GitHub repository prefix for links
• --tsconfig-path (string) - Path to TypeScript config file
• --version (string) - Version string for documentation

Usage Examples:

# Generate README for current project
oclif readme

# Preview changes without writing
oclif readme --dry-run

# Generate with custom options
oclif readme --multi --aliases --nested-topics-depth=3

Create Plugin Manifest

Generates oclif.manifest.json containing plugin metadata, command definitions, and configuration for efficient CLI loading.

oclif manifest [PATH]

Arguments:

• PATH (string, default: ".") - Path to plugin or CLI project

Flags:

• --jit (boolean) - Include JIT (Just-In-Time) plugin commands in manifest

Usage Examples:

# Generate manifest for current directory
oclif manifest

# Generate manifest for specific path
oclif manifest ./plugins/my-plugin

# Include JIT plugin commands
oclif manifest --jit

Legacy Lock Command (Deprecated)

Copies yarn.lock to oclif.lock for plugin dependency locking. This command is deprecated and will be removed in future versions.

oclif lock

Status: Hidden and deprecated - use modern dependency management instead

Usage Examples:

# Create oclif.lock from yarn.lock (deprecated)
oclif lock

Configuration

oclif projects are configured through package.json in the oclif section:

{
  "oclif": {
    "commands": "./lib/commands",
    "bin": "mycli",
    "dirname": "mycli",
    "plugins": [
      "@oclif/plugin-help"
    ],
    "topicSeparator": " ",
    "topics": {
      "pack": {
        "description": "Package CLI for distribution"
      }
    }
  }
}

Configuration Options

interface OclifConfig {
  /** Directory containing command files */
  commands?: string;
  /** Binary name for the CLI */
  bin?: string;
  /** Directory name for CLI installation */
  dirname?: string;
  /** Array of oclif plugins to load */
  plugins?: string[];
  /** Separator for nested command topics */
  topicSeparator?: string;
  /** Topic definitions with descriptions */
  topics?: Record<string, { description: string }>;
  /** macOS-specific configuration */
  macos?: { identifier: string };
  /** Auto-update configuration */
  update?: UpdateConfig;
}

interface UpdateConfig {
  autoupdate?: {
    rollout?: number;
    debounce?: number;
  };
  node?: { version: string };
  s3?: S3UpdateConfig;
}

interface S3UpdateConfig {
  bucket: string;
  indexVersionLimit?: number;
  folder?: string;
  acl?: string;
  host?: string;
  xz?: boolean;
}