oclif

Node.js Open CLI Framework

CLI
oclif/oclifoclif.iooclif

README




oclif: Node.JS Open CLI Framework
=================================
Version CircleCI Downloads/week License


🗒 Description
🚀 Getting Started Tutorial
✨ Features
📌 Requirements
📌 Migrating from V1
🏗 Usage
📚 Examples
🔨 Commands
🏭 Related Repositories
🦔 Learn More
📣 Feedback


🗒 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 - Everything in the core of oclif is written in TypeScript and the generator will build fully configured TypeScript CLIs. 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:

  1. ```
  2. $ heroku info --app=<tab><tab> # will complete with all the Heroku apps a user has in their account
  3. ```

📌 Requirements


Currently, Node 12+ 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.

📌 Migrating from V1


If you have been using version 1 of the [oclif CLI](https://github.com/oclif/oclif/tree/v1.18.4) there are some important differences to note when using the latest version.

Breaking Changes


- oclif multi, oclif plugin, and oclif single have all been removed in favor of oclif generate, which generates an oclif based CLI using the hello-world example repo.
  - The reason is that there's not enough of a meaningful difference between a "multi command cli", a "single command cli", and a "plugin" to justify the maintenance cost. The generated CLI can be easily used for any of those use cases.
- oclif hook is now oclif generate:hook
- oclif command is now oclif generate:command

New Commands


Version 2 now includes all the commands from the [oclif-dev CLI](https://github.com/oclif/dev-cli). This means that you can now use a single CLI for all your oclif needs. These commands include:
- oclif manifest
- oclif pack
- oclif pack:deb
- oclif pack:macos
- oclif pack:win
- oclif upload (formerly known as oclif-dev publish)
- oclif upload:deb (formerly known as oclif-dev publish:deb)
- oclif upload:macos (formerly known as oclif-dev publish:macos)
- oclif upload:win (formerly known as oclif-dev publish:win)
- oclif readme


🏗 Usage


Creating a CLI:

  1. ```sh-session
  2. $ npx oclif generate mynewcli
  3. ? npm package name (mynewcli): mynewcli
  4. $ cd mynewcli
  5. $ ./bin/run --version
  6. mynewcli/0.0.0 darwin-x64 node-v9.5.0
  7. $ ./bin/run --help
  8. USAGE
  9.   $ mynewcli [COMMAND]

  11. COMMANDS
  12.   hello
  13.   help   display help for mynewcli

  15. $ ./bin/run hello
  16. hello world from ./src/hello.js!
  17. ```

📚 Examples


Hello-World
Salesforce CLI
Heroku CLI

🔨 Commands



[oclif generate NAME](#oclif-generate-name)
[oclif generate command NAME](#oclif-generate-command-name)
[oclif generate hook NAME](#oclif-generate-hook-name)
[oclif help [COMMAND]](#oclif-help-command)
[oclif manifest [PATH]](#oclif-manifest-path)
[oclif pack deb](#oclif-pack-deb)
[oclif pack macos](#oclif-pack-macos)
[oclif pack tarballs](#oclif-pack-tarballs)
[oclif pack win](#oclif-pack-win)
[oclif promote](#oclif-promote)
[oclif readme](#oclif-readme)
[oclif upload deb](#oclif-upload-deb)
[oclif upload macos](#oclif-upload-macos)
[oclif upload tarballs](#oclif-upload-tarballs)
[oclif upload win](#oclif-upload-win)

oclif generate NAME


generate a new CLI

  1. ```
  2. USAGE
  3.   $ oclif generate [NAME]

  5. ARGUMENTS
  6.   NAME  directory name of new project

  8. DESCRIPTION
  9.   generate a new CLI

  11.   This will clone the template repo 'oclif/hello-world' and update package properties
  12. ```

_See code: src/commands/generate.ts_

oclif generate command NAME


add a command to an existing CLI or plugin

  1. ```
  2. USAGE
  3.   $ oclif generate command [NAME] [--force]

  5. ARGUMENTS
  6.   NAME  name of command

  8. FLAGS
  9.   --force  overwrite existing files

  11. DESCRIPTION
  12.   add a command to an existing CLI or plugin
  13. ```

oclif generate hook NAME


add a hook to an existing CLI or plugin

  1. ```
  2. USAGE
  3.   $ oclif generate hook [NAME] [--force] [--event <value>]

  5. ARGUMENTS
  6.   NAME  name of hook (snake_case)

  8. FLAGS
  9.   --event=<value>  [default: init] event to run hook on
  10.   --force          overwrite existing files

  12. DESCRIPTION
  13.   add a hook to an existing CLI or plugin
  14. ```

oclif help [COMMAND]


Display help for oclif.

  1. ```
  2. USAGE
  3.   $ oclif help [COMMAND] [-n]

  5. ARGUMENTS
  6.   COMMAND  Command to show help for.

  8. FLAGS
  9.   -n, --nested-commands  Include all nested commands in the output.

  11. DESCRIPTION
  12.   Display help for oclif.
  13. ```

_See code: @oclif/plugin-help_

oclif manifest [PATH]


generates plugin manifest json

  1. ```
  2. USAGE
  3.   $ oclif manifest [PATH]

  5. ARGUMENTS
  6.   PATH  [default: .] path to plugin

  8. DESCRIPTION
  9.   generates plugin manifest json
  10. ```

_See code: src/commands/manifest.ts_

oclif pack deb


pack CLI into debian package

  1. ```
  2. USAGE
  3.   $ oclif pack deb -r <value> [-t <value>]

  5. FLAGS
  6.   -r, --root=<value>     (required) [default: .] path to oclif CLI root
  7.   -t, --tarball=<value>  optionally specify a path to a tarball already generated by NPM

  9. DESCRIPTION
  10.   pack CLI into debian package
  11. ```

oclif pack macos


pack CLI into macOS .pkg

  1. ```
  2. USAGE
  3.   $ oclif pack macos -r <value> [-t <value>]

  5. FLAGS
  6.   -r, --root=<value>     (required) [default: .] path to oclif CLI root
  7.   -t, --tarball=<value>  optionally specify a path to a tarball already generated by NPM

  9. DESCRIPTION
  10.   pack CLI into macOS .pkg
  11. ```

oclif pack tarballs


packages oclif CLI into tarballs

  1. ```
  2. USAGE
  3.   $ oclif pack tarballs -r <value> [-t <value>] [--xz] [--parallel] [-l <value>]

  5. FLAGS
  6.   -l, --tarball=<value>  optionally specify a path to a tarball already generated by NPM
  7.   -r, --root=<value>     (required) [default: .] path to oclif CLI root
  8.   -t, --targets=<value>  comma-separated targets to pack (e.g.: linux-arm,win32-x64)
  9.   --parallel             build tarballs in parallel
  10.   --[no-]xz              also build xz

  12. DESCRIPTION
  13.   packages oclif CLI into tarballs

  15.   This can be used to create oclif CLIs that use the system node or that come preloaded with a node binary.
  16. ```

oclif pack win


create windows installer from oclif CLI

  1. ```
  2. USAGE
  3.   $ oclif pack win -r <value> [-t <value>]

  5. FLAGS
  6.   -r, --root=<value>     (required) [default: .] path to oclif CLI root
  7.   -t, --tarball=<value>  optionally specify a path to a tarball already generated by NPM

  9. DESCRIPTION
  10.   create windows installer from oclif CLI

  12.   This command requires WINDOWS_SIGNING (prefixed with the name of your executable, e.g. OCLIF_WINDOWS_SIGNING_PASS) to
  13.   be set in the environment
  14. ```

oclif promote


promote CLI builds to a S3 release channel

  1. ```
  2. USAGE
  3.   $ oclif promote -r <value> --version <value> --sha <value> --channel <value> [-t <value>] [-d] [-m] [-w]
  4.     [-a <value>] [--xz] [--indexes]

  6. FLAGS
  7.   -a, --max-age=<value>  [default: 86400] cache control max-age in seconds
  8.   -d, --deb              promote debian artifacts
  9.   -m, --macos            promote macOS pkg
  10.   -r, --root=<value>     (required) [default: .] path to the oclif CLI project root
  11.   -t, --targets=<value>  comma-separated targets to promote (e.g.: linux-arm,win32-x64)
  12.   -w, --win              promote Windows exe
  13.   --channel=<value>      (required) [default: stable] which channel to promote to
  14.   --indexes              append the promoted urls into the index files
  15.   --sha=<value>          (required) 7-digit short git commit SHA of the CLI to promote
  16.   --version=<value>      (required) semantic version of the CLI to promote
  17.   --[no-]xz              also upload xz

  19. DESCRIPTION
  20.   promote CLI builds to a S3 release channel
  21. ```

_See code: src/commands/promote.ts_

oclif readme


adds commands to README.md in current directory

  1. ```
  2. USAGE
  3.   $ oclif readme --dir <value> [--multi] [--aliases]

  5. FLAGS
  6.   --[no-]aliases  include aliases in the command list
  7.   --dir=<value>   (required) [default: docs] output directory for multi docs
  8.   --multi         create a different markdown page for each topic

  10. DESCRIPTION
  11.   adds commands to README.md in current directory

  13.   The readme must have any of the following tags inside of it for it to be replaced or else it will do nothing:

  15.   # Usage

  17.   

  19.   # Commands

  21.   

  23.   Customize the code URL prefix by setting oclif.repositoryPrefix in package.json.
  24. ```

_See code: src/commands/readme.ts_

oclif upload deb


upload deb package built with pack:deb

  1. ```
  2. USAGE
  3.   $ oclif upload deb -r <value>

  5. FLAGS
  6.   -r, --root=<value>  (required) [default: .] path to oclif CLI root

  8. DESCRIPTION
  9.   upload deb package built with pack:deb
  10. ```

oclif upload macos


upload macos installers built with pack:macos

  1. ```
  2. USAGE
  3.   $ oclif upload macos -r <value>

  5. FLAGS
  6.   -r, --root=<value>  (required) [default: .] path to oclif CLI root

  8. DESCRIPTION
  9.   upload macos installers built with pack:macos
  10. ```

oclif upload tarballs


upload an oclif CLI to S3

  1. ```
  2. USAGE
  3.   $ oclif upload tarballs -r <value> [-t <value>] [--xz]

  5. FLAGS
  6.   -r, --root=<value>     (required) [default: .] path to oclif CLI root
  7.   -t, --targets=<value>  comma-separated targets to upload (e.g.: linux-arm,win32-x64)
  8.   --[no-]xz              also upload xz

  10. DESCRIPTION
  11.   upload an oclif CLI to S3

  13.   "aws-sdk" will need to be installed as a devDependency to upload.
  14. ```

oclif upload win


upload windows installers built with pack:win

  1. ```
  2. USAGE
  3.   $ oclif upload win -r <value>

  5. FLAGS
  6.   -r, --root=<value>  (required) [default: .] path to oclif CLI root

  8. DESCRIPTION
  9.   upload windows installers built with pack:win
  10. ```


🏭 Related Repositories


@oclif/core - Base library for oclif. This can be used directly without the generator.
@oclif/cli-ux - Library for common CLI UI utilities.
@oclif/test - Test helper for oclif.

🦔 Learn More


Salesforce Release Announcement
Heroku Release Announcement

📣 Feedback


If you have any suggestions or want to let us know what you think of oclif, send us a message at