Skip to main content

Introduction

oclif is a framework for building CLIs in Node. It can be used like a simple flag parser but is capable of much more. It's designed to be extensible so that you can easily add plugins such as the update warning plugin or build your own for users to install at runtime.

The oclif generator creates a CLI project in TypeScript to get you started quickly. It requires very few runtime dependencies and has minimal overhead.

Everything is customizable in oclif. Even the flag parser and help generation is optional and can be replaced. It's a platform to build upon that provides smart defaults without locking you in to any specific tools or behavior.

Requirements​

Only LTS Node versions are supported. You can add the node package to your CLI to ensure users are on a specific Node version.

Create oclif project from scratch​

To create a new oclif project from scratch, you can run the oclif generate command:

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

This will create a new project based on our templates. To learn more about what's included in these templates, we encourage you to read over their documentation here.

Once oclif generate is complete, you can run your CLI using the included bin scripts

Use bin/dev.js to run your CLI in development mode:

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

Use bin/run.js to run your CLI in production mode:

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

Initialize oclif in an existing project​

If you'd like to start using oclif inside an existing project of yours, then you can use the oclif init command to add the necessary files, dependencies, and configuration.

$ npx 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

oclif init will add the following:

  • bin scripts: bin/run.js, bin/run.cmd, bin/dev.js, and bin/dev.cmd. See bin scripts for more.
  • oclif section to package.json with bin, dirname, commands, and topicSeparator set. See Configuring Your CLI for more.
  • @oclif/core to dependencies in your package.json (if it's not already there)
  • ts-node to devDependencies in your package.json (if it's not already there)

Next Steps​

Add commands​

Once you've generated an oclif project or initialized it in your existing project, you can begin adding new commands:

npx oclif generate command foo:bar

This will create a new command in src/commands/foo/bar.ts that can be customized to do whatever you need it to do.

The documentation for flags and args covers how to add these to your command and the documentation for commands covers the other options you can set on your command.

Add hooks​

You can also add hooks to your CLI that allow you to further customize the behavior of your CLI:

npx oclif generate hook my-hook --event init

Further customizations​

Other Tutorials​

Our friend, @joshcanhelp, wrote a fantastic tutorial on his blog that we encourage you to read as well.