[DO NOT MERGE] Version 2.0.0

[mdonnalley]

Breaking Changes

Command Args

We updated the Command.args to more closely resemble flags

Before

import { Command } from '@oclif/core'

export default MyCommand extends Command {
  static args = [{name: arg1, description: 'an argument', required: true}]

  public async run(): Promise<void> {
    const {args} = await this.parse(MyCommand) // args is useless {[name: string]: any}
  }
}

After

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

export default MyCommand extends Command {
  static args = {
    arg1: Args.string({description: 'an argument', required: true})
  }

  public async run(): Promise<void> {
    const {args} = await this.parse(MyCommand) // args is { arg1: string }
  }
}

These are the available Args:

• string
• integer
• boolean
• url
• file
• directory
• custom

Interfaces

• Removed Interfaces.Command since they were not usable for tests. These are replaced by types that are available under the Command namespace

Interfaces.Command => Command.Cached
Interfaces.Command.Class => Command.Class
Interfaces.Command.Loadable => Command.Lodable

• Removed the following interfaces from the export. Exporting all of these made it difficult to make non-breaking changes when modifying types and/or fixing compilation bugs. We are open to PRs to reintroduce these to the export if they are needed for your project
  • Arg
  • ArgInput
  • ArgToken
  • CLIParseErrorOptions
  • CompletableFlag
  • CompletableOptionFlag
  • Completion
  • CompletionContext
  • Default
  • DefaultContext
  • Definition
  • EnumFlagOptions
  • FlagBase
  • FlagInput
  • FlagOutput
  • FlagToken
  • FlagUsageOptions
  • Input
  • List
  • ListItem
  • Metadata
  • OptionalArg
  • OptionFlagProps
  • OutputArgs
  • OutputFlags
  • ParseFn
  • ParserArg
  • ParserInput
  • ParserOutput
  • ParsingToken
  • RequiredArg

CliUx

We flattened CliUx.ux into ux for ease of use

Before

import {CliUx} from '@oclif/core'

CliUx.ux.log('Hello World')

After

import {ux} from '@oclif/core'

ux.log('Hello World')

Flags

• Flags.custom replaces Flags.build, Flags.enum, and Flags.option
• Removed builtin color flag
• Renamed globalFlags to baseFlags
  • globalFlags was a misleading name because the flags added there weren't actually global to the entire CLI. Instead, they were just flags that would be inherited by any command that extended the command class they were defined in.

Flag and Arg Parsing

• In v1, any input that didn't match a flag definition was assumed to be an argument. This meant that misspelled flags, e.g. --hekp were parsed as arguments, instead of throwing an error. In order to handle this, oclif now assumes that anything that starts with a hypen must be a flag and will throw an error if no corresponding flag definition is found. In other words, your command can no longer accept arguments that begin with a hyphen (fixes https://github.com/oclif/core/issues/526)

TODO

• [ ] More unit tests for arg parsing
• [ ] Handle will-fix-in-v2 issues
• [ ] Update oclif.io docs
• [ ] Update migration guide