oclif

https://oclif.io/docs
Admin
oclif is an open source framework for building command-line interfaces (CLIs) in Node.js and...
Tokens:29,584
Snippets:388
Trust Score:9.1
Update:2 months ago
Show doc for...
Tokens:
Raw
### Installing build dependencies for Windows installer

Source: https://oclif.io/docs/releasing

Install nsis and p7zip using Homebrew if they are not already present on your system.

```bash
brew install nsis  
brew install p7zip  
```

--------------------------------

### Install oclif CLI

Source: https://oclif.io/docs/introduction

Installs the oclif CLI globally. This is the first step to using oclif for CLI development.

```bash
npm install --global oclif
```

--------------------------------

### Install Debian Packages using apt

Source: https://oclif.io/docs/releasing

Commands to add a GPG key, configure the apt sources list, update the package index, and install a CLI package from a custom repository hosted on S3. This setup is for users on Ubuntu/Debian systems.

```bash
$ wget -qO- https://mys3bucket.s3.amazonaws.com/apt/release.key | apt-key add -
$ sudo echo "deb https://mys3bucket.s3.amazonaws.com/apt ./" > /etc/apt/sources.list.d/mycli.list
$ sudo apt update
$ sudo apt install -y mycli
```

--------------------------------

### Autocomplete Example

Source: https://oclif.io/docs/features

Demonstrates how to trigger command and flag completion in the terminal.

```bash
$ my-cli p<tab><tab> # lists all commands starting with 'p' for completion  
```

--------------------------------

### Configuring Windows installer signing

Source: https://oclif.io/docs/releasing

Set the signing password environment variable and configure package.json with the CLI name and key path for signed installers.

```json
{
  "oclif": {
    "windows": {
      "name": "My CLI",
      "keypath": "path/to/private.key"
    }
  }
}
```

--------------------------------

### Publishing a CLI to npm

Source: https://oclif.io/docs/releasing

Use these commands to manage versions, publish to npm, and install the CLI globally or via npx.

```bash
$ npm version (major|minor|patch) # bumps version, updates README, adds git tag  
$ npm publish  
$ npm install -g mynewcli  
$ mynewcli  
# OR  
$ npx mynewcli  
```

--------------------------------

### Example of Custom Command Help Output

Source: https://oclif.io/docs/help_classes

When help is invoked for a command after customizing 'showCommandHelp', the custom output is displayed.

```bash
$ my-cli login --help
Display my custom command help!

```

--------------------------------

### Configure JIT Plugins in package.json

Source: https://oclif.io/docs/jit_plugins

Add the `jitPlugins` configuration to the `oclif` section of your `package.json` to specify plugins that should be installed just-in-time.

```json
"oclif": {
  "jitPlugins": {
    "my-plugin": "^1.2.3",
    "another-plugin": "^1.2.3"
  }
}

```

--------------------------------

### Install oclif Globally

Source: https://oclif.io/docs/faqs

To improve the speed of the oclif generator when using `npx`, first install oclif globally. This ensures you are using the latest version available.

```bash
npm install -g oclif
```

--------------------------------

### Implement JitPluginNotInstalled Hook

Source: https://oclif.io/docs/jit_plugins

Implement the `jit_plugin_not_installed` hook to define the user experience for installing JIT plugins. This example prompts the user for confirmation before installing.

```typescript
import { Hook, Errors } from '@oclif/core';
import confirm from '@inquirer/confirm';

const hook: Hook.JitPluginNotInstalled = async function (opts) {
  try {
    const answer = await confirm({
      message: `${opts.command.pluginName} not installed. Would you like to install?`
    })
    if (answer) {
      await opts.config.runCommand('plugins:install', [`${opts.command.pluginName}@${opts.pluginVersion}`]);
    }
  } catch (error) {
    throw new Errors.CLIError(`Could not install ${opts.command.pluginName}`, 'JitPluginInstallError');
  }
};

export default hook;

```

--------------------------------

### Performance Tracking - Init

Source: https://oclif.io/docs/api_reference

Enabling performance tracking for oclif itself and custom code. This example shows initialization for performance monitoring.

```typescript
import {run} from '@oclif/core'

run().then(async () => {
  // performance tracking enabled
}).catch(this.catch)

```

--------------------------------

### Providing Logger to Config

Source: https://oclif.io/docs/logging

This example demonstrates how to provide a custom logger to oclif by passing it to the `Config.load` method. This is useful if you instantiate `Config` before running oclif commands.

```javascript
import {Config, run} from '@oclif/core'
const config = await config.load({
  logger,
});

await run(process.argv.slice(2), config)

```

--------------------------------

### Lifecycle Hooks - Init

Source: https://oclif.io/docs/api_reference

Example of an 'init' lifecycle hook. Hooks allow you to run code at specific points in the oclif lifecycle.

```typescript
import {Hook} from '@oclif/core'

const hook: Hook.Init = async function (opts) {
  // opts.id
  // opts.argv
  // opts.config
  // opts.error
  // opts.exit
  // opts.plugin
  // opts.warn
}

export default hook
```

--------------------------------

### Example Output of Performance Results

Source: https://oclif.io/docs/performance

Displays the structure of performance metrics captured, including module, method, details, and duration. This output is generated after running a command with performance metrics enabled.

```bash
❯ bin/run.js hello reader --from oclif  
hello reader from oclif! (./src/commands/hello/index.ts)  
Results Map(1) {  
  'my-plugin' => [  
    {  
      details: {  
        from: oclif,  
        person: reader  
      },  
      duration: 1003.4971249999999,  
      method: 'run',  
      module: 'hello',  
      name: 'hello.run',  
      scope: undefined  
    }  
  ]  
}  

```

--------------------------------

### Configure macOS Signing Identity in package.json

Source: https://oclif.io/docs/releasing

Specify the 'sign' property within the 'oclif.macos' section of package.json to provide the installer signing identity. Ensure the certificate is installed in the build machine's Keychain. Pay attention to escaped quotation marks for the certificate name.

```json
"macos": {
  "identifier": "com.myOclifApp",
  "sign": "\"3rd Party Mac Developer Installer: myOclifCompany (R2315646)\""
}
```

--------------------------------

### Comprehensive Performance Metrics Example in Oclif Command

Source: https://oclif.io/docs/performance

Instrument an oclif command's `run` method to measure its execution time and add custom details. Ensure performance metrics are enabled in your application's entry point.

```typescript
// ./src/commands/hello/index.ts  
import {Args, Command, Flags, Performance} from '@oclif/core'  
  
export default class Hello extends Command {  
  static args = {  
    person: Args.string({description: 'Person to say hello to', required: true}),  
  }  
  
  static flags = {  
    from: Flags.string({char: 'f', description: 'Who is saying hello', required: true}),  
  }  
  
  async run(): Promise<void> {  
    const {args, flags} = await this.parse(Hello)  
    const marker = Performance.mark('my-plugin', 'hello.run')  
    await new Promise((resolve) => {  
      setTimeout(resolve, 1000)  
    })  
    marker?.addDetails({from: flags.from, person: args.person})  
    marker?.stop()  
    this.log(`hello ${args.person} from ${flags.from}! (./src/commands/hello/index.ts)`)  
  }  
}  

```

--------------------------------

### Providing Logger to oclif execute

Source: https://oclif.io/docs/logging

This example shows how to provide a custom logger to oclif when using the `execute` function. The logger is passed within the `loadOptions`.

```javascript
// bin/run.js
#!/usr/bin/env node

async function main() {
  const {execute} = await import('@oclif/core');
  const { logger } = await import('../dist/oclif-logger.js');
  await oclif.execute({
    dir: import.meta.url,
    loadOptions: {
      root: import.meta.dirname,
      logger,
    },
  });
}

await main();

```

--------------------------------

### Command Arguments Example

Source: https://oclif.io/docs/api_reference

Declaring positional arguments for a command. These are passed to the command in the order they are defined.

```typescript
import {Args, Command, Flags} from '@oclif/core'

export default class MyCommand extends Command {
  static description = 'Describe the command here'

  static examples = [
    '$ oex hello
  ]

  static args = {
    name: Args.string({description: 'name to print'})
  }

  static flags = {
    // flag definitions
  }

  async run(): Promise<any> {
    const {args, flags} = await this.parse(MyCommand)

    this.log(`hello ${args.name} from /path/to/my/command/src/index.ts`)
  }
}
```

--------------------------------

### Add Explicit Help Command

Source: https://oclif.io/docs/help_classes

To add an explicit 'help' command to your CLI, install and configure '@oclif/plugin-help'.

```bash
$ my-cli help  

```

--------------------------------

### Specify NSIS Customization in package.json

Source: https://oclif.io/docs/nsis-installer_customization

Use the 'nsisCustomization' field in your package.json to point to your custom NSIS script. This script will be included in the installer during the packing phase.

```json
{
  "name": "mycli",
  "version": "0.0.0",
  "description": "My CLI",
  "main": "bin/run.js",
  "bin": "./bin/run.js",
  "oclif": {
    "nsisCustomization": "scripts/nsis.nsi"
  }
}
```

--------------------------------

### Run a command using this.config.runCommand

Source: https://oclif.io/docs/running_programmatically

Execute another installed command within your CLI using `this.config.runCommand`. This method is suitable when you know the command is available in the CLI environment.

```typescript
export class ConfigUpdate extends Command {
  static flags = {
    app: Flags.string({required: true})
  }

  async run() {
    const {flags} = await this.parse(ConfigUpdate)
    await this.doUpdate(flags.app)
    await this.config.runCommand('config:list', ['--global'])
  }
}
```

--------------------------------

### Basic Command in TypeScript

Source: https://oclif.io/docs/api_reference

A basic command structure in TypeScript. Ensure you have the necessary oclif dependencies installed.

```typescript
import {Command, Flags} from '@oclif/core'

export default class MyCommand extends Command {
  static description = 'Describe the command here'

  static examples = [
    '$ oex hello
  ]

  static flags = {
    name: Flags.string({
      char: 'n',
      description: 'Name to print',
      required: false,
    }),
  }

  async run(): Promise<any> {
    const {flags} = await this.parse(MyCommand)
    const name = flags.name ?? 'world'
    this.log(`hello ${name} from /path/to/my/command/src/index.ts`)
  }
}
```

--------------------------------

### Command Flags Example

Source: https://oclif.io/docs/api_reference

Defining flags for a command. Flags are options that modify command behavior and are typically preceded by a hyphen.

```typescript
import {Command, Flags} from '@oclif/core'

export default class MyCommand extends Command {
  static description = 'Describe the command here'

  static examples = [
    '$ oex hello --name=world'
  ]

  static flags = {
    name: Flags.string({
      char: 'n',
      description: 'Name to print',
      required: false,
    }),
  }

  async run(): Promise<any> {
    const {flags} = await this.parse(MyCommand)
    const name = flags.name ?? 'world'
    this.log(`hello ${name} from /path/to/my/command/src/index.ts`)
  }
}
```

--------------------------------

### Extend HelpBase Abstract Class

Source: https://oclif.io/docs/help_classes

Implement the minimum required methods for a custom help class by extending the HelpBase abstract class. This provides a starting point for custom help experiences.

```typescript
import {Command, HelpBase} from '@oclif/core';

export default class CustomHelp extends HelpBase {
  showHelp(args: string[]) {
    console.log('This will be displayed in multi-command CLIs')
  }

  showCommandHelp(command: Command.Loadable) {
    console.log('This will be displayed in single-command CLIs')
  }
}

```

--------------------------------

### Read Custom User Configuration

Source: https://oclif.io/docs/config

Reads a `config.json` file from the CLI's config directory. This is useful for providing custom user settings. Ensure `fs-extra` is installed.

```typescript
import { Command } from "@oclif/core"
import * as fs from "fs-extra"
import * as path from "path"

export class extends Command {
  async run() {
    const userConfig = await fs.readJSON(
      path.join(this.config.configDir, "config.json")
    )

    this.log("User config:")
    console.dir(userConfig)
  }
}

```

--------------------------------

### Initialize oclif in Existing Project

Source: https://oclif.io/docs/introduction

Integrates oclif into an existing project using the 'oclif init' command. This adds necessary scripts, configurations, and dependencies.

```bash
oclif init
? Command bin name the CLI will export (my-pkg): my-pkg
? Select topic separator: spaces
? Select a module type: CommonJS
? Select a package manager: npm

Created CLI in my-pkg
```

--------------------------------

### Lifecycle Hooks - CommandNotFound

Source: https://oclif.io/docs/api_reference

Example of a 'commandnotfound' lifecycle hook. This hook is triggered when a command is not found.

```typescript
import {Hook} from '@oclif/core'

const hook: Hook.CommandNotFound = async function (opts) {
  // opts.id
  // opts.argv
  // opts.config
  // opts.error
  // opts.exit
  // opts.plugin
  // opts.warn
}

export default hook
```

--------------------------------

### Configure Custom Help Class Path

Source: https://oclif.io/docs/help_classes

Define the relative filepath to your custom help class in the 'oclif.helpClass' field of your package.json. The path should not include the file extension.

```json
{
  "oclif": {
    "helpClass": "./dist/help"
  }
}

```

--------------------------------

### Directory Structure for Oclif Topics

Source: https://oclif.io/docs/topics

Organize commands into topics by placing them in subdirectories within the 'commands' folder. The help description for a topic is derived from the first command in its directory.

```tree
package.json  
src/  
└── commands/  
    └── config/  
        ├── index.ts  
        ├── set.ts  
        └── get.ts  

```

--------------------------------

### Generate a new CLI with oclif

Source: https://oclif.io

Use this command to scaffold a new CLI project. It prompts for the npm package name and then sets up the basic structure.

```bash
$ npx oclif generate mynewcli? npm package name (mynewcli): mynewcli$ cd mynewcli$ ./bin/run.js hello worldhello world! (./src/commands/hello/world.ts)
```

--------------------------------

### Extending Themes for Custom Logging

Source: https://oclif.io/docs/themes

Demonstrates how to use oclif's theming capabilities for custom logging within a command. Imports `Command` and `ux` from '@oclif/core'.

```typescript
import {Command, ux} from '@oclif/core'

export default class Hello extends Command {
  public async run(): Promise<void> {
    this.info('starting process!')
    // do some stuff...
    this.info('still making progress!')
    // do some more stuff...
    this.info('process complete!')
  }

  public info(msg: string): void {
    this.log(ux.colorize(this.config.theme?.info, 'info:'), msg)
  }
}
```

--------------------------------

### Advanced Command Options in TypeScript

Source: https://oclif.io/docs/commands

Demonstrates various static properties for configuring command behavior, help text, aliases, and JSON flag support.

```typescript
import {Command, Flags} from '@oclif/core'
  
export class MyCommand extends Command {
  static summary = 'A brief overview of your command.'
  static description = `  
An in-depth description of the command.  
It can be multiline.  
`  
  
  // hide the command from help  
  static hidden = false  

  // custom usage string for help  
  // this overrides the default usage  
  static usage = 'mycommand --myflag'

  // examples to add to help  
  // <%= config.bin %> resolves to the executable name  
  // <%= command.id %> resolves to the command name  
  static examples = [
    // Examples can be simple strings  
    '<%= config.bin %> <%= command.id %> --help',
    // Or objects that provide a description of the example command  
    {
      description: 'Force the command to execute',
      command: '<%= config.bin %> <%= command.id %> --force',
    }
  ]

  // this makes the parser not fail when it receives invalid arguments  
  // defaults to true  
  // set it to false if you need to accept a variable number of arguments  
  static strict = false  

  // define aliases that can execute this command.  
  static aliases = ['alternate:name:for:this:command']  

  // Set to true if you want to add the --json flag to your command.  
  // oclif will automatically suppress logs (if you use this.log, this.warn, or this.error) and  
  // display the JSON returned by the command's run method.  
  static enableJsonFlag = true  

  async run() {
    // show a warning  
    this.warn('uh oh!')
    // exit with an error message  
    this.error('uh oh!!!')
    // exit with status code  
    this.exit(1)
  }
}
```

--------------------------------

### Plugin Command Discovery - Touchfile

Source: https://oclif.io/docs/api_reference

Command discovery strategy using a touchfile. A file's existence indicates the presence of commands.

```typescript
import {Command} from '@oclif/core'

export default class MyCommand extends Command {
  static description = 'Describe the command here'

  async run(): Promise<any> {
    this.log('touchfile discovery')
  }
}
```

--------------------------------

### Configure pkg for Single Binary CLI

Source: https://oclif.io/docs/faqs

To create a single binary CLI, configure the `pkg` settings in your `package.json` to include your compiled JavaScript files. This ensures all necessary code is bundled.

```json
{
  "pkg": {
    "scripts": "./lib/**/*.js"
  }
}
```

--------------------------------

### Whoami Command Implementation

Source: https://oclif.io/docs/testing

This TypeScript command makes an API call to get the current user's email. It handles a 401 error by exiting with status 100.

```typescript
import {Command} from '@oclif/core'  
  
export class Whoami extends Command {  
  async run() {  
    try {  
      let {body: account} = await this.api.get('/account')  
      this.log(account.email)  
    } catch (err) {  
      if (err.statusCode === 401) {  
        this.error('not logged in', {exit: 100})  
      }  
      throw err  
    }  
  }  
}  

```

--------------------------------

### Import and run a command directly

Source: https://oclif.io/docs/running_programmatically

Instantiate and run a command directly by importing its class and calling its static `.run()` method with arguments. This approach requires direct access to the command's code.

```typescript
import {ConfigList} from './config/list'

export class ConfigUpdate extends Command {
  static flags = {
    app: Flags.string({required: true})
  }

  async run() {
    const {flags} = await this.parse(ConfigUpdate)
    await this.doUpdate(flags.app)
    await ConfigList.run(['--global'])
  }
}
```

--------------------------------

### Configure 'pattern' Strategy with Target Directory

Source: https://oclif.io/docs/command_discovery_strategies

This configuration achieves the same result as specifying a direct path for commands, explicitly setting the strategy to 'pattern'.

```json
{
  "oclif": {
    "commands": {
      "strategy": "pattern",
      "target": "./dist/commands"
    }
  }
}
```

--------------------------------

### Custom Logger Implementation

Source: https://oclif.io/docs/logging

An example of how to implement a custom logger for oclif. This function creates a logger instance that conforms to the oclif Logger interface, using a provided Logger class.

```typescript
// oclif-logger.ts
import { format } from 'node:util';
import { Interfaces } from '@oclif/core';
import { Logger } from './my-cli-logger';

export const customLogger = (namespace: string): Interfaces.Logger => {
  const myLogger = new Logger(namespace);
  return {
    child: (ns: string, delimiter?: string) => customLogger(`${namespace}${delimiter ?? ':'}${ns}`),
    debug: (formatter: unknown, ...args: unknown[]) => myLogger.debug(format(formatter, ...args)),
    error: (formatter: unknown, ...args: unknown[]) => myLogger.error(format(formatter, ...args)),
    info: (formatter: unknown, ...args: unknown[]) => myLogger.info(format(formatter, ...args)),
    trace: (formatter: unknown, ...args: unknown[]) => myLogger.trace(format(formatter, ...args)),
    warn: (formatter: unknown, ...args: unknown[]) => myLogger.warn(format(formatter, ...args)),
    namespace,
  };
};

export const logger = customLogger('my-cli');

```

--------------------------------

### Invoke CLI Help

Source: https://oclif.io/docs/help_classes

Users can invoke help for a CLI using the --help flag.

```bash
$ my-cli login --help  

```

--------------------------------

### Enable and Access Performance Results

Source: https://oclif.io/docs/performance

Configure performance metrics by setting `settings.performanceEnabled = true` and access results via `Performance.results` in your application's entry point. Ensure `flush()` is called to finalize metrics.

```javascript
// bin/run.js  
const {Performance, flush, handle, run, settings} = await import('@oclif/core')  
settings.performanceEnabled = true  
await run(process.argv.slice(2))  
  .catch(async (error) => handle(error))  
  .finally(async () => {  
    console.log('Results', Performance.results)  
    await flush()  
  })  

```

--------------------------------

### Define and Use a Custom Team Flag

Source: https://oclif.io/docs/flags

Define a reusable custom flag for selecting a team. This example shows how to create a custom flag type and then use it in a command, including asynchronous default value resolution.

```typescript
// src/flags.ts  
import {Flags} from '@oclif/core'  
  
class Team {  
  public name: string;  
  // etc...  
}  
  
function getTeam(): Promise<Team> {  
  // imagine this reads a configuration file or something to find the team  
  return new Team()  
}  
  
export const team = Flags.custom<Team>({
  char: 't',
  description: 'team to use',
  default: async () => getTeam(),
})

```

```typescript
// src/commands/mycommand.ts  
import {team} from '../flags'  
import {Command} from '@oclif/core'  
  
export class MyCLI extends Command {  
  static flags = {  
    team: team({
      required: true,
    }),
  }
  
  async run() {
    const {flags} = await this.parse(MyCLI)
    if (flags.team) console.log(`--team is ${flags.team.name}`)
  }
}

```

--------------------------------

### Alternative Flag Input Formats

Source: https://oclif.io/docs/flags

Demonstrates various ways users can provide input for flags, including boolean flags and string flags with different spacing and shorthand notations.

```bash
$ mycli --verbose

```

```bash
$ mycli -v

```

```bash
$ mycli --file=foo

```

```bash
$ mycli --file foo

```

```bash
$ mycli -f foo

```

```bash
$ mycli -f=foo

```

```bash
$ mycli -ffoo

```

```bash
$ mycli -vffoo

```

--------------------------------

### Shipping a Theme in package.json

Source: https://oclif.io/docs/themes

Configures your CLI to include a theme file. Ensure the theme file is listed in the 'files' array and specified in the 'oclif.theme' property.

```json
{
  "files": [
    "/theme.json",
    "/oclif.manifest.json",
    "/dist"
  ],
  "oclif": {
    "theme": "theme.json"
  }
}
```

--------------------------------

### Define Bin Aliases in package.json

Source: https://oclif.io/docs/aliases

Specify alternative names for your CLI in the `oclif.binAliases` property within `package.json`. Ensure the `bin` section also maps these aliases to your main run script.

```json
{
  "name": "mycli",
  "version": "0.0.0",
  "description": "My CLI",
  "main": "bin/run.js",
  "bin": {
    "mycli": "./bin/run.js",
    "mycli-alias": "./bin/run.js"
  },
  "oclif": {
    "binAliases": ["mycli", "mycli-alias"]
  }
}
```

--------------------------------

### Default bin/run.js with execute

Source: https://oclif.io/docs/error_handling

This is the standard bin/run.js file generated by oclif, which uses the execute function to run the CLI and catch errors.

```typescript
#!/usr/bin/env node  
  
import {execute} from '@oclif/core'  
  
await execute({dir: import.meta.url})  

```

--------------------------------

### Configure 'pattern' Strategy with Commands Directory

Source: https://oclif.io/docs/command_discovery_strategies

Use this configuration to tell oclif to look for command files in a specified directory. This is the default behavior.

```json
{
  "oclif": {
    "commands": "./dist/commands"
  }
}
```

--------------------------------

### Add Plugins to package.json

Source: https://oclif.io/docs/plugins

Configure plugins by adding them to your CLI's package.json dependencies and the oclif.plugins array. This method explicitly lists each plugin.

```json
{
  "name": "mycli",
  "version": "0.0.0",
  // ...
  "dependencies": {
    "@oclif/core": "^3",
    "@oclif/plugin-help": "^6",
    "@oclif/plugin-not-found": "^3"
  }
  "oclif": {
    "plugins": [
      "@oclif/plugin-help",
      "@oclif/plugin-not-found"
    ]
  }
}

```

--------------------------------

### Plugin Command Discovery - Classpath

Source: https://oclif.io/docs/api_reference

Command discovery strategy using classpath. Commands are discovered by oclif based on their file path.

```typescript
import {Command} from '@oclif/core'

export default class MyCommand extends Command {
  static description = 'Describe the command here'

  async run(): Promise<any> {
    this.log('classpath discovery')
  }
}
```

--------------------------------

### Configure oclif using .oclifrc.js

Source: https://oclif.io/docs/configuring_your_cli

Use an rc file, such as .oclifrc.js, for oclif configuration. This method does not require nesting options under an 'oclif' key.

```javascript
//.oclifrc.js

module.exports = {
  bin: "mycli",
  dirname: "mycli",
  commands: "./dist/commands",
  topicSeparator: " "
}

```

--------------------------------

### Basic JavaScript Command

Source: https://oclif.io/docs/commands

Defines a minimal oclif command in JavaScript. Static properties like description must be added after class declaration.

```javascript
const {Command} = require('@oclif/core')
  
class MyCommand extends Command {
  async run() {
    console.log('running my command')
  }
}

MyCommand.description = 'description of this example command'

module.exports = MyCommand
```

--------------------------------

### Generate New oclif Project

Source: https://oclif.io/docs/introduction

Creates a new oclif CLI project using the 'oclif generate' command. Follow the prompts to configure your project. After generation, you can run your CLI in development mode.

```bash
oclif generate mynewcli
Generating mynewcli in /Users/me/oclif/mynewcli
? Select a module type ESM
? NPM package name mynewcli
? Command bin name the CLI will export mynewcli
<more prompts...>

$ cd mynewcli
$ ./bin/dev.js hello world
hello world! (./src/commands/hello/world.ts)
```

```bash
./bin/dev.js hello world
hello world! (./src/commands/hello/world.ts)
```

```bash
./bin/run.js hello world
hello world! (./src/commands/hello/world.ts)
```

--------------------------------

### Declare Multiple Init Hooks in package.json

Source: https://oclif.io/docs/hooks

Declares multiple init hooks for the same event type using an array in package.json.

```json
"oclif": {
  "commands": "./lib/commands",
  "hooks": {
    "init": [
      "./lib/hooks/init/example",
      "./lib/hooks/init/another_hook"
    ]
  }
}


```

--------------------------------

### Enable Performance Tracking with settings

Source: https://oclif.io/docs/performance

Use this method when using the default bin scripts generated by oclif. Set `settings.performanceEnabled` to true before calling `execute`.

```typescript
#!/usr/bin/env node  
  
import {execute, settings} from '@oclif/core'  
settings.performanceEnabled = true  
await execute({dir: import.meta.url})
```

--------------------------------

### Update package.json bin script reference

Source: https://oclif.io/docs/esm

Change the reference in package.json's 'bin' field to use the .js extension for the run script to accommodate ESM.

```json
"bin": {
    "my-cli": "./bin/run.js"
  },

```

--------------------------------

### Nested Commands in Topics

Source: https://oclif.io/docs/api_reference

Organizing commands within topics by placing command files in subdirectories. This allows for hierarchical command structures.

```treeview
sf/
  config/
    get.ts
    set.ts
```

--------------------------------

### Generate a New CLI

Source: https://oclif.io/docs/generator_commands

Use this command to generate a new, fully functional oclif CLI. You can either be prompted for all necessary information or provide flags to skip prompts and set specific values. The `--yes` flag accepts all defaults.

```bash
oclif generate NAME [--author <value>] [--bin <value>] [--description <value>] [--license <value>] [--module-type CommonJS|ESM] [--name <value>] [--owner <value>] [--package-manager npm|yarn|pnpm] [--repository <value>] [-d <value>] [-y]
```

```bash
oclif generate my-cli
```

```bash
oclif generate my-cli --yes
```

```bash
oclif generate my-cli --module-type CommonJS --author "John Doe"
```

```bash
oclif generate my-cli --module-type CommonJS --author "John Doe" --yes
```

--------------------------------

### Customizing Oclif Topic Descriptions

Source: https://oclif.io/docs/topics

Customize the help description for topics by defining them in the 'oclif.topics' section of your 'package.json' file. This allows for more specific and user-friendly topic descriptions.

```json
{
  "oclif": {
    "topics": {
      "apps:favorites": { "description": "manage favorite apps" },
      "config": { "description": "manage heroku config variables" },
    }
  }
}

```

--------------------------------

### Enable Performance Tracking with Config

Source: https://oclif.io/docs/performance

Enable performance tracking directly on the `Config` class by setting `enablePerf: true` when loading the configuration. This is an alternative if it better suits your CLI implementation.

```typescript
import {Config, run} from '@oclif/core'  
import {fileUrlToPath} from 'node:url'  
  
const config = await Config.load({  
  root: resolve(fileURLToPath(import.meta.url), '..');,  
  enablePerf: true  
})  
  
await run(config)
```

--------------------------------

### Running a Dynamically Created Command

Source: https://oclif.io/docs/command_discovery_strategies

Execute a dynamically created command by setting the DYNAMIC_COMMAND environment variable and passing the command name and its arguments. This demonstrates the runtime execution of a command defined in src/index.ts.

```bash
❯ DYNAMIC_COMMAND=foo:bar:baz bin/run.js foo bar baz --flag1
hello from foo:bar:baz { flag1: true }

```

--------------------------------

### Configure 'explicit' Strategy with Target File and Identifier

Source: https://oclif.io/docs/command_discovery_strategies

Use the 'explicit' strategy to import commands from a single file. Specify the target file and the export identifier for the commands object.

```json
{
  "oclif": {
    "commands": {
      "strategy": "explicit",
      "target": "./dist/index.js",
      "identifier": "COMMANDS"
    }
  }
}
```

--------------------------------

### Capture Performance Metrics for a Code Block

Source: https://oclif.io/docs/performance

Create a marker using `Performance.mark` and stop it with `.stop()` to time a block of code. The owner and name arguments help distinguish markers.

```typescript
import {Performance} from '@oclif/core'  
// Create a new marker.  
// First argument is the owner of the marker (This allows Performance to be able to distinguish the origin of each marker)  
// Second argument is the name of the maker. Naming convention that oclif uses internally is <module>.<method>#scope. You are free, however, to name these however you like.  
const marker = Performance.mark('my-plugin', 'hello.run')  
  
// do things that take a while.  
  
// Add details to the marker that you might want to access later  
marker?.addDetails({from: flags.from, person: args.person})
// Stop the marker. This will capture the amount of time between the creation of the marker and the stopping of the marker.  
marker?.stop()  

```

--------------------------------

### Extend Default Help Class with Hooks

Source: https://oclif.io/docs/help_classes

Customize specific parts of the help output by extending the default Help class and overriding its 'hook' methods. This approach is recommended for most customization needs.

```typescript
import {Command, Help, Interfaces} from '@oclif/core'

export default class MyHelpClass extends Help {
  // acts as a "router"
  // and based on the args it receives
  // calls one of showRootHelp, showTopicHelp,
  // the formatting for an individual command
  formatCommand(command: Command.Loadable): string {}

  // the formatting for a list of commands
  formatCommands(commands: Command.Loadable[]): string {}

  // displayed for the root help
  formatRoot(): string {}

  // the formatting for an individual topic
  formatTopic(topic: Interfaces.Topic): string {}

  // the default implementations of showRootHelp
  // showTopicHelp and showCommandHelp
  // will call various format methods that
  // provide the formatting for their corresponding
  // help sections;
  // these can be overwritten as well

  // the formatting responsible for the header
  // the formatting for a list of topics
  protected formatTopics(topics: Interfaces.Topic[]): string {}

  // display help for a command
  showCommandHelp(command: Command.Loadable): void {}

  // or showCommandHelp
  showHelp(args: string[]): void {}

  // display the root help of a CLI
  showRootHelp(): void {}

  // display help for a topic
  showTopicHelp(topic: Interfaces.Topic): void {}
}


```

--------------------------------

### Enable Flexible Taxonomy in package.json

Source: https://oclif.io/docs/flexible_taxonomy

Configure your package.json to enable flexible command taxonomy and specify a hook for handling incomplete commands. This setting allows oclif to intelligently match user input to defined commands.

```json
{
  "oclif": {
    "flexibleTaxonomy": true,
    "hooks": {
      "command_incomplete": "./dist/hooks/command_incomplete.js"
    }
  }
}

```

--------------------------------

### Configure Topic Separator in package.json

Source: https://oclif.io/docs/topic_separator

Set the 'topicSeparator' property in the 'oclif' section of your package.json to use spaces instead of colons for separating command topics.

```json
{
  "oclif": {
    "topicSeparator": " "
  }
}

```

--------------------------------

### Generate an ESM Plugin with oclif

Source: https://oclif.io/docs/esm

Use the oclif generate command and select 'ESM' to create a new plugin using ECMAScript Modules.

```bash
$ npx oclif generate my-esm-plugin  
? Select a module type  
  CommonJS  
❯ ESM  

```

--------------------------------

### Declare Init Hook in package.json

Source: https://oclif.io/docs/hooks

Declares an init hook in the oclif section of package.json. The path points to the hook file.

```json
"oclif": {
  "commands": "./lib/commands",
  "hooks": {
    "init": "./lib/hooks/init/example"
  }
}


```

--------------------------------

### Plugin Command Discovery - Manifest

Source: https://oclif.io/docs/api_reference

Command discovery strategy using a manifest file. Commands are declared in a JSON manifest within the plugin.

```json
{
  "commands": [
    {
      "id": "mycommand",
      "load": "./dist/command.js",
      "pluginName": "myplugin"
    }
  ]
}
```

--------------------------------

### Dynamic Command Creation with Explicit Strategy

Source: https://oclif.io/docs/command_discovery_strategies

Use the 'explicit' strategy to define commands at runtime. This approach cannot be used with an oclif.manifest.json and may impact production performance. Ensure your dynamic command class extends oclif/core's Command.

```typescript
// src/index.ts
import {Command, Flags} from '@oclif/core'

import Hello from './commands/hello'
import HelloWorld from './commands/hello/world'

const dynamicCommands: Record<string, Command.Class> = {}
if (process.env.DYNAMIC_COMMAND) {
  dynamicCommands[process.env.DYNAMIC_COMMAND] = class extends Command {
    static flags = {
      flag1: Flags.boolean({description: 'flag1 description'})
    }

    async run(): Promise<void> {
      const {flags} = await this.parse(this.constructor as Command.Class)
      this.log('hello from', this.id, flags)
    }
  }
}

export const COMMANDS = {
  hello: Hello,
  'hello:world': HelloWorld,
  ...dynamicCommands,
}

```

--------------------------------

### Configure Flag Options

Source: https://oclif.io/docs/flags

Explore various options for configuring flags, such as aliases, help text, default values, and parsing logic. Note that some options are only applicable to non-boolean flags.

```typescript
static flags = {
  name: Flags.string({
    // The following can be set on both boolean and option flag (e.g. string, integer, url, custom, etc) types.
    char: 'n',
    summary: 'brief summary',
    helpLabel: '--my-flags',
    helpGroup: 'THE BEST FLAGS',
    description: 'in-depth overview',
    hidden: false,
    multiple: false,
    env: 'MY_NAME',
    options: ['a', 'b'],
    parse: async input => 'output',
    default: 'world',
    defaultHelp: 'a dynamic value',
    required: false,
    aliases: ['username', 'u'],
    charAliases: ['u', 'n'],
    deprecated: false,
    deprecateAliases: false,
    noCacheDefault: false,
    dependsOn: ['extra-flag'],
    exclusive: ['extra-flag'],
    exactlyOne: ['extra-flag', 'another-flag'],
    compatible: ['extra-flag'],
    relationships: [
      // Make this flag dependent on all of these flags
      {type: 'all', flags: ['flag-one', 'flag-two']}
      // Make this flag dependent on at least one of these flags
      {type: 'some', flags: ['flag-three', 'flag-four']}
      // Make this flag exclusive of all these flags
      {type: 'none', flags: ['flag-five', 'flag-six']}
      // Make this only compatible with these flags
      {type: 'only', flags: ['flag-one', 'flag-two']}

      // Make this flag dependent on all of these flags
      {type: 'all', flags: [
        'flag-one',
        'flag-two',
        // Include flag-seven but only when flag-eight is equal to FooBar
        {name: 'flag-seven', when: async (flags) => flags['flag-eight'] === 'FooBar'}
      ]}
    ],
    // The following properties cannot be set on boolean flags
    helpValue: '<name>',
    multipleNonGreedy: false,
    delimiter: ','
    allowStdin: false,
  })
}
```

--------------------------------

### Standard CLI Output

Source: https://oclif.io/docs/json

This is the typical output when the `--json` flag is not used.

```bash
$ my-cli hello  
hello, world!  


```

--------------------------------

### Generate a New Hook

Source: https://oclif.io/docs/generator_commands

Add a hook to an existing CLI or plugin. Hooks are triggered on specific events, with `--event` defaulting to 'init'. Use `--force` to overwrite existing files.

```bash
oclif generate hook NAME [--event <value>] [--force]
```

--------------------------------

### Add Plugins using Minimatch Patterns

Source: https://oclif.io/docs/plugins

Use minimatch patterns in the oclif.plugins array to include multiple plugins that match a pattern. This is useful for including all plugins from a specific scope.

```json
{
  "name": "mycli",
  "version": "0.0.0",
  // ...
  "dependencies": {
    "@oclif/core": "^3",
    "@oclif/plugin-help": "^6",
    "@oclif/plugin-not-found": "^3"
  }
  "oclif": {
    "plugins": [
      "@oclif/plugin-*"
    ]
  }
}

```

--------------------------------

### Piping Arguments via Stdin

Source: https://oclif.io/docs/args

Demonstrates how to pipe arguments to a command via standard input. This behavior can be disabled by setting `ignoreStdin` to `true` on the argument definition.

```bash
$ echo arg1 | mycli  
running my command with args: arg1  
```

--------------------------------

### Customize Command Help Output

Source: https://oclif.io/docs/help_classes

Override the 'showCommandHelp' method in your custom Help class to change how command-specific help is displayed. This change takes effect immediately when help is invoked for any command.

```typescript
import {Command, Help} from '@oclif/core';

export default class MyHelpClass extends Help {
  public showCommandHelp(command: Command.Loadable) {
    console.log('Display my custom command help!')
  }
}

```

--------------------------------

### Configure oclif in package.json

Source: https://oclif.io/docs/configuring_your_cli

Place oclif configuration options under the 'oclif' section in your package.json file. This method is suitable for most oclif projects.

```json
{
  "name": "my-cli",
  "version": "1.2.3",
  "dependencies": {
    "@oclif/core": "^3"
  },
  "oclif": {
    "bin": "mycli",
    "dirname": "mycli",
    "commands": "./dist/commands",
    "topicSeparator": " "
  }
}

```

--------------------------------

### Update bin/dev with oclif Settings

Source: https://oclif.io/docs/esm

Configure oclif settings, such as performance, before executing the CLI in development mode for an ESM plugin.

```typescript
#!/usr/bin/env -S node --loader ts-node/esm --no-warnings=ExperimentalWarning  
  
import {execute, settings} from '@oclif/core'  
  
settings.performanceEnabled = true  
  
await execute({development: true, dir: import.meta.url})  

```

--------------------------------

### Configure 'pattern' Strategy with Custom Glob Patterns

Source: https://oclif.io/docs/command_discovery_strategies

Customize the glob patterns used by the 'pattern' strategy to include or exclude specific command file types. This is useful for organizing test or helper files within the command directory.

```json
{
  "oclif": {
    "commands": {
      "strategy": "pattern",
      "target": "./dist/commands",
      "globPatterns": [
         "**/*.+(js|cjs|mjs|ts|tsx|mts|cts)",
        "!**/*.+(d.*|test.*|spec.*|helpers.*)?(x)"
      ]
    }
  }
}
```

--------------------------------

### Configure Argument Options

Source: https://oclif.io/docs/args

Configure various options for a string argument, such as its name, requirement, description, visibility, parsing logic, default value, and allowed options.

```typescript
static args = {  
  firstArg: Args.string(  
    {  
      name: 'file',                     // name of arg to show in help and reference with args[name]  
      required: false,                  // make the arg required with `required: true`  
      description: 'output file',       // help description  
      hidden: true,                     // hide this arg from help  
      parse: async input => 'output',   // instead of the user input, return a different value  
      default: 'world',                 // default value if no arg input. Can also be an async function.  
      defaultHelp: 'a dynamic value'    // dynamic default value to show in help output (e.g. current working directory). Can be an async function that returns a string or undefined  
      options: ['a', 'b'],              // only allow input to be from a discrete set  
      ignoreStdin: false,               // set to true to ignore any value provided by stdin  
      noCacheDefault: false,            // if true, the value returned by defaultHelp will not be cached in the oclif.manifest.json.  
      multiple: false                   // if true, this argument will support multiple inputs and parse them as an array  
    }
  ),
}
```

--------------------------------

### Export Hooks and Commands for 'explicit' Strategy

Source: https://oclif.io/docs/command_discovery_strategies

Export both commands and hooks from a single file when using the 'explicit' strategy. Ensure the hook identifier matches the export name.

```typescript
// src/index.ts
import Hello from './commands/hello'
import HelloWorld from './commands/hello/world'
export {default as INIT_HOOK} from './hooks/init/init.js'

export const COMMANDS = {
  hello: Hello,
  'hello:world': HelloWorld,
  howdy: Hello, // alias the `hello` command to `howdy`
}

```

--------------------------------

### Generate a New Command

Source: https://oclif.io/docs/generator_commands

Add a new command to an existing CLI or plugin. Use the `--force` flag to overwrite existing files if necessary. The `--commands-dir` flag specifies the directory to create the command in.

```bash
oclif generate command NAME [--commands-dir <value>] [--force]
```
Tokens:
Raw