oclif: The Open CLI Framework
  • Getting Started
  • API Reference
  • Blog
  • GitHub

›API Reference

Getting Started

  • Introduction
  • Features
  • FAQs
  • Generator Commands

Architecture

  • Command Execution
  • Plugin Loading

API Reference

  • Commands
  • Command Arguments
  • Command Flags
  • Configuration
  • Topics
  • Topic Separators
  • Hooks
  • Plugins
  • Help Classes
  • Error Handling
  • JSON

How to

  • Release
  • Testing
  • Running Commands Programmatically
  • Aliases
  • Custom Base Class
  • Prompting
  • Spinner
  • Table
  • Notifications
  • Debugging
  • Flexible Taxonomy
  • Global Flags
  • Single Command CLI
  • ESM

Also See

  • Examples
  • External Links
  • Related Repositories
  • How We Work
  • Feedback
Edit

Configuration

Inside a command, this.config provides useful properties you can use in your command. Here are a list of its methods and properties:

  • name - name of CLI
  • version - version of CLI
  • pjson - parsed and normalized CLI package.json
  • bin - CLI bin name
  • cacheDir - CLI cache directory
    • macOS: ~/Library/Caches/mycli
    • Unix: ~/.cache/mycli
    • Windows: %LOCALAPPDATA%\mycli
    • Can be overridden with XDG_CACHE_HOME
  • configDir - CLI config directory
    • Unix: ~/.config/mycli
    • Windows: %LOCALAPPDATA%\mycli
    • Can be overridden with XDG_CONFIG_HOME
  • dataDir - CLI data directory
    • Unix: ~/.data/mycli
    • Windows: %LOCALAPPDATA%\mycli
    • Can be overridden with XDG_DATA_HOME
  • dirname - dirname used with cacheDir|configDir|dataDir. Can be overridden in package.json.
  • errlog - path to error log inside of cacheDir
  • home - user home directory
  • platform - operating system darwin|linux|win32
  • arch - process architecture x64|x86
  • shell - current shell in use
  • userAgent - user-agent intended for http calls. example: mycli/1.2.3 (darwin-x64) node-9.0.0
  • windows - boolean
  • topicSeparator - the separator to use between topics - only colons (":") and spaces (" ") are supported.
  • debug - set to 1 if debug is enabled (with ${BIN}_DEBUG=1 or DEBUG=$BIN). In the future this may be used for multiple debug levels.
  • npmRegistry - current npm registry to use with the plugins plugin
  • plugins - loaded plugins
  • commands - all commands in CLI
  • default - default cli command
  • topics - all topics in CLI
  • commandIDs - string IDs of all commands
  • async runHook(event, opts) - trigger a hook

Custom User Configuration

Often it's useful to have a custom configuration for your users. One way to implement this is to read a config.json file from the CLI's config directory:

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)
  }
}

To share this logic between different commands, use a base class.

Last updated on 2/22/2023
← Command FlagsTopics →
Made with 💜 by Salesforce — MIT License