oclif: create your own CLI

Downloads in past


8,893111.17.03 years ago6 years agoMinified + gzip package size for create-oclif in KB


oclif: Node.JS Open CLI Framework
Join the community on Spectrum Version CircleCI Appveyor CI Downloads/week License
๐Ÿ—’ Description
This is a framework for building CLIs in Node.js. This framework was built out of the Heroku CLI but generalized to build any custom CLI. It's designed both for single-file CLIs with a few flag options, or for very complex CLIs that have subcommands (like git or heroku).
See the docs for more information.
๐Ÿš€ Getting Started Tutorial
The Getting Started tutorial is a step-by-step guide to introduce you to oclif. If you have not developed anything in a command line before, this tutorial is a great place to get started.
โœจ Features
  • Flag/Argument parsing - No CLI framework would be complete without a flag parser. We've built a custom one from years of experimentation that we feel consistently handles user input flexible enough for the user to be able to use the CLI in ways they expect, but without compromising strictness guarantees to the developer.
  • Super Speed - The overhead for running an oclif CLI command is almost nothing. It requires very few dependencies (only 35 dependencies in a minimal setupโ€”including all transitive dependencies). Also, only the command to be executed will be required with node. So large CLIs with many commands will load equally as fast as a small one with a single command.
  • CLI Generator - Run a single command to scaffold out a fully functional CLI and get started quickly. See Usage below.
  • Testing Helpers - We've put a lot of work into making commands easier to test and mock out stdout/stderr. The generator will automatically create scaffolded tests.
  • Auto-documentation - By default you can pass --help to the CLI to get help such as flag options and argument information. This information is also automatically placed in the README whenever the npm package of the CLI is published. See the multi-command CLI example
  • Plugins - Using plugins, users of the CLI can extend it with new functionality, a CLI can be split into modular components, and functionality can be shared amongst multiple CLIs. See Building your own plugin.
  • Hooks - Use lifecycle hooks to run functionality any time a CLI starts, or on custom triggers. Use this whenever custom functionality needs to be shared between various components of the CLI.
  • TypeScript (or not) - Everything in the core of oclif is written in TypeScript and the generator can build fully configured TypeScript CLIs or plain JavaScript CLIs. By virtue of static properties in TypeScript the syntax is a bit cleaner in TypeScriptโ€”but everything will work no matter which language you choose. If you use plugins support, the CLI will automatically use ts-node to run the plugins enabling you to use TypeScript with minimal-to-no boilerplate needed for any oclif CLI.
  • Auto-updating Installers - oclif can package your CLI into different installers that will not require the user to already have node installed on the machine. These can be made auto-updatable by using plugin-update.
  • Everything is Customizable - Pretty much anything can be swapped out and replaced inside oclif if neededโ€”including the arg/flag parser.
  • Autocomplete - Automatically include autocomplete for your CLI. This includes not only command names and flag names, but flag values as well. For example, it's possible to configure the Heroku CLI to have completions for Heroku app names:

$ heroku info --app=<tab><tab> # will complete with all the Heroku apps a user has in their account
๐Ÿ“Œ Requirements
Currently, Node 8+ is supported. We support the LTS versions of Node. You can add the node package to your CLI to ensure users are running a specific version of Node.
๐ŸŒˆ CLI Types
With oclif you can create 2 different CLI types, single and multi.
Single CLIs are like ls or cat. They can accept arguments and flags. Single CLIs can optionally be a single file.
Multi CLIs are like git or heroku. They have subcommands that are themselves single CLIs. In the package.json there is a field oclif.commands that points to a directory. This directory contains all the subcommands for the CLI. For example, if you had a CLI called mycli with the commands mycli create and mycli destroy, you would have a project like the following:
โ””โ”€โ”€ commands/
 ย ย  โ”œโ”€โ”€ create.ts
 ย ย  โ””โ”€โ”€ destroy.ts

Multi-command CLIs may also include plugins.
๐Ÿ— Usage
Creating a single-command CLI:
```sh-session $ npx oclif single mynewcli ? npm package name (mynewcli): mynewcli $ cd mynewcli $ ./bin/run hello world from ./src/index.js!
Creating a multi-command CLI:

$ npx oclif multi mynewcli
? npm package name (mynewcli): mynewcli
$ cd mynewcli
$ ./bin/run --version
mynewcli/0.0.0 darwin-x64 node-v9.5.0
$ ./bin/run --help
  $ mynewcli [COMMAND]

  help   display help for mynewcli

$ ./bin/run hello
hello world from ./src/hello.js!
๐Ÿ“š Examples
  • TypeScript
Multi-command CLI Single-command CLI Multi-command CLI Plugin
  • JavaScript
Multi-command CLI Single-command CLI Multi-command CLI Plugin
๐Ÿ”จ Commands

oclif command NAME

add a command to an existing CLI or plugin
  $ oclif command NAME

  NAME  name of command

  --defaults  use defaults for every setting
  --force     overwrite existing files

See code: src/commands/command.ts

oclif help [COMMAND]

display help for oclif
  $ oclif help [COMMAND]

  COMMAND  command to show help for

  --all  see all commands in CLI

See code: @oclif/plugin-help

oclif hook NAME

add a hook to an existing CLI or plugin
  $ oclif hook NAME

  NAME  name of hook (snake_case)

  --defaults     use defaults for every setting
  --event=event  [default: init] event to run hook on
  --force        overwrite existing files

See code: src/commands/hook.ts

oclif multi [PATH]

generate a new multi-command CLI
  $ oclif multi [PATH]

  PATH  path to project, defaults to current directory

  --defaults         use defaults for every setting
  --force            overwrite existing files
  --options=options  (yarn|typescript|eslint|mocha)

See code: src/commands/multi.ts

oclif plugin [PATH]

create a new CLI plugin
  $ oclif plugin [PATH]

  PATH  path to project, defaults to current directory

  --defaults         use defaults for every setting
  --force            overwrite existing files
  --options=options  (yarn|typescript|eslint|mocha)

See code: src/commands/plugin.ts

oclif single [PATH]

generate a new single-command CLI
  $ oclif single [PATH]

  PATH  path to project, defaults to current directory

  --defaults         use defaults for every setting
  --force            overwrite existing files
  --options=options  (yarn|typescript|eslint|mocha)

See code: src/commands/single.ts
๐Ÿญ Related Repositories
๐Ÿฆ” Learn More
๐Ÿ“ฃ Feedback
If you have any suggestions or want to let us know what you think of oclif, send us a message at