1 |
|
2 | <img src="https://user-images.githubusercontent.com/449385/38243295-e0a47d58-372e-11e8-9bc0-8c02a6f4d2ac.png" width="260" height="73">
|
3 |
|
4 |
|
5 | oclif: Node.JS Open CLI Framework
|
6 | =================================
|
7 |
|
8 | [![Join the chat at https://gitter.im/oclif/oclif](https://badges.gitter.im/oclif/oclif.svg)](https://gitter.im/oclif/oclif?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge)
|
9 | [![Version](https://img.shields.io/npm/v/oclif.svg)](https://npmjs.org/package/oclif)
|
10 | [![CircleCI](https://circleci.com/gh/oclif/oclif/tree/master.svg?style=shield)](https://circleci.com/gh/oclif/oclif/tree/master)
|
11 | [![Appveyor CI](https://ci.appveyor.com/api/projects/status/github/oclif/oclif?branch=master&svg=true)](https://ci.appveyor.com/project/heroku/oclif/branch/master)
|
12 | [![Greenkeeper](https://badges.greenkeeper.io/oclif/oclif.svg)](https://greenkeeper.io/)
|
13 | [![Known Vulnerabilities](https://snyk.io/test/github/oclif/oclif/badge.svg)](https://snyk.io/test/github/oclif/oclif)
|
14 | [![Downloads/week](https://img.shields.io/npm/dw/oclif.svg)](https://npmjs.org/package/oclif)
|
15 | [![License](https://img.shields.io/npm/l/oclif.svg)](https://github.com/oclif/oclif/blob/master/package.json)
|
16 |
|
17 |
|
18 | * [🗒 Description](#-description)
|
19 | * [🚀 Getting Started Tutorial](#-getting-started-tutorial)
|
20 | * [✨ Features](#-features)
|
21 | * [📌 Requirements](#-requirements)
|
22 | * [🌈 CLI Types](#-cli-types)
|
23 | * [🏗 Usage](#-usage)
|
24 | * [📚 Examples](#-examples)
|
25 | * [🔨 Commands](#-commands)
|
26 | * [🏭 Related Repositories](#-related-repositories)
|
27 | * [🦔 Learn More](#-learn-more)
|
28 | * [📣 Feedback](#-feedback)
|
29 |
|
30 |
|
31 | # 🗒 Description
|
32 |
|
33 | This is a framework for building CLIs in Node.js. This framework was built out of the [Heroku CLI](https://cli.heroku.com) but generalized to build any custom CLI. It's designed both for simple CLIs that can be just a single file with a few flag options, or for very complex CLIs that have subcommands (like git or heroku).
|
34 |
|
35 | [See the docs for more information](http://oclif.io/docs/introduction.html).
|
36 |
|
37 | # 🚀 Getting Started Tutorial
|
38 |
|
39 | The [Getting Started tutorial](http://oclif.io/docs/introduction.html) 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.
|
40 |
|
41 | # ✨ Features
|
42 |
|
43 | * **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 easily use the CLI in ways they expect, but without comprisiming strictness guarantees to the developer.
|
44 | * **Super Speed** - The overhead for running an oclif CLI command is almost nothing. [It requires very few dependencies](https://www.npmjs.com/package/@oclif/command?activeTab=dependencies). Also, only the command to be executed will be required with node. So large CLIs with many commands will load just as fast as a small one with a single command.
|
45 | * **CLI Generator** - Run a single command to scaffold out a fully functional CLI and get started quickly. See [Usage](#-usage) below.
|
46 | * **Testing Helpers** - We've put a lot of work into making commands easily testable and easy to mock out stdout/stderr. The generator will automatically create [scaffolded tests](https://github.com/oclif/example-multi-ts/blob/master/test/commands/hello.test.ts).
|
47 | * **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](https://github.com/oclif/example-multi-ts)
|
48 | * **Plugins** - Using [plugins](https://oclif.io/docs/plugins.html), 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](https://oclif.io/docs/plugins.html#building-your-own-plugin).
|
49 | * **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.
|
50 | * **TypeScript (or not)** - Everything in the core of oclif is written in TypeScript and the generator can build fully configured TypeScript CLIs or just 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 making it easy and fast to use TypeScript with minimal-to-no boilerplate needed for any oclif CLI.
|
51 | * **Auto-updating Installers** - oclif can package your CLI into [different installers](https://oclif.io/docs/releasing.html) that will not require the user to already have node installed on the machine. These can be made auto-updatable by using [plugin-update](https://github.com/oclif/plugin-update).
|
52 | * **Everything is Customizable** - Pretty much anything can be swapped out and replaced inside oclif if needed—including the arg/flag parser.
|
53 | * **Coming soon: Autocomplete** - Automatically include autocomplete for your CLI. This includes not just command names and flag names, but flag values as well. For example, it's easy to configure the Heroku CLI to have completions for Heroku app names:
|
54 |
|
55 |
|
56 | ```
|
57 | $ heroku info --app=<tab><tab> # will complete with all the Heroku apps a user has in their account
|
58 | ```
|
59 |
|
60 | # 📌 Requirements
|
61 |
|
62 | Only Node 8+ is supported. Node 6 will reach end-of-life April 2019. At that point we will continue to support the current LTS version of node. You can add the [node](https://www.npmjs.com/package/node) package to your CLI to ensure users are on Node 8.
|
63 |
|
64 | # 🌈 CLI Types
|
65 |
|
66 | With oclif you can create 2 different CLI types, single and multi.
|
67 |
|
68 | Single CLIs are like `ls` or `cat`. They can accept arguments and flags. Single CLIs can [optionally be just be a single file](https://github.com/oclif/command).
|
69 |
|
70 | 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:
|
71 |
|
72 | ```
|
73 | package.json
|
74 | src/
|
75 | └── commands/
|
76 | ├── create.ts
|
77 | └── destroy.ts
|
78 | ```
|
79 |
|
80 | Multi-command CLIs may also include [plugins](https://oclif.io/docs/plugins.html).
|
81 |
|
82 | # 🏗 Usage
|
83 |
|
84 | Creating a single-command CLI:
|
85 |
|
86 | ```sh-session
|
87 | $ npx oclif single mynewcli
|
88 | ? npm package name (mynewcli): mynewcli
|
89 | $ cd mynewcli
|
90 | $ ./bin/run
|
91 | hello world from ./src/index.js!
|
92 | ```
|
93 |
|
94 | Creating a multi-command CLI:
|
95 |
|
96 | ```sh-session
|
97 | $ npx oclif multi mynewcli
|
98 | ? npm package name (mynewcli): mynewcli
|
99 | $ cd mynewcli
|
100 | $ ./bin/run --version
|
101 | mynewcli/0.0.0 darwin-x64 node-v9.5.0
|
102 | $ ./bin/run --help
|
103 | USAGE
|
104 | $ mynewcli [COMMAND]
|
105 |
|
106 | COMMANDS
|
107 | hello
|
108 | help display help for mynewcli
|
109 |
|
110 | $ ./bin/run hello
|
111 | hello world from ./src/hello.js!
|
112 | ```
|
113 |
|
114 | # 📚 Examples
|
115 |
|
116 | * TypeScript
|
117 | * [Multi-command CLI](https://github.com/oclif/example-multi-ts)
|
118 | * [Single-command CLI](https://github.com/oclif/example-single-ts)
|
119 | * [Multi-command CLI Plugin](https://github.com/oclif/example-plugin-ts)
|
120 | * JavaScript
|
121 | * [Multi-command CLI](https://github.com/oclif/example-multi-js)
|
122 | * [Single-command CLI](https://github.com/oclif/example-single-js)
|
123 | * [Multi-command CLI Plugin](https://github.com/oclif/example-plugin-js)
|
124 |
|
125 | # 🔨 Commands
|
126 |
|
127 |
|
128 | * [`oclif command NAME`](#oclif-command-name)
|
129 | * [`oclif help [COMMAND]`](#oclif-help-command)
|
130 | * [`oclif hook NAME`](#oclif-hook-name)
|
131 | * [`oclif multi [PATH]`](#oclif-multi-path)
|
132 | * [`oclif plugin [PATH]`](#oclif-plugin-path)
|
133 | * [`oclif single [PATH]`](#oclif-single-path)
|
134 |
|
135 | ## `oclif command NAME`
|
136 |
|
137 | add a command to an existing CLI or plugin
|
138 |
|
139 | ```
|
140 | USAGE
|
141 | $ oclif command NAME
|
142 |
|
143 | ARGUMENTS
|
144 | NAME name of command
|
145 |
|
146 | OPTIONS
|
147 | --defaults use defaults for every setting
|
148 | --force overwrite existing files
|
149 | ```
|
150 |
|
151 | _See code: [src/commands/command.ts](https://github.com/oclif/oclif/blob/v1.10.0/src/commands/command.ts)_
|
152 |
|
153 | ## `oclif help [COMMAND]`
|
154 |
|
155 | display help for oclif
|
156 |
|
157 | ```
|
158 | USAGE
|
159 | $ oclif help [COMMAND]
|
160 |
|
161 | ARGUMENTS
|
162 | COMMAND command to show help for
|
163 |
|
164 | OPTIONS
|
165 | --all see all commands in CLI
|
166 | ```
|
167 |
|
168 | _See code: [@oclif/plugin-help](https://github.com/oclif/plugin-help/blob/v2.0.5/src/commands/help.ts)_
|
169 |
|
170 | ## `oclif hook NAME`
|
171 |
|
172 | add a hook to an existing CLI or plugin
|
173 |
|
174 | ```
|
175 | USAGE
|
176 | $ oclif hook NAME
|
177 |
|
178 | ARGUMENTS
|
179 | NAME name of hook (snake_case)
|
180 |
|
181 | OPTIONS
|
182 | --defaults use defaults for every setting
|
183 | --event=event [default: init] event to run hook on
|
184 | --force overwrite existing files
|
185 | ```
|
186 |
|
187 | _See code: [src/commands/hook.ts](https://github.com/oclif/oclif/blob/v1.10.0/src/commands/hook.ts)_
|
188 |
|
189 | ## `oclif multi [PATH]`
|
190 |
|
191 | generate a new multi-command CLI
|
192 |
|
193 | ```
|
194 | USAGE
|
195 | $ oclif multi [PATH]
|
196 |
|
197 | ARGUMENTS
|
198 | PATH path to project, defaults to current directory
|
199 |
|
200 | OPTIONS
|
201 | --defaults use defaults for every setting
|
202 | --force overwrite existing files
|
203 | --options=options (yarn|typescript|tslint|semantic-release|mocha)
|
204 | ```
|
205 |
|
206 | _See code: [src/commands/multi.ts](https://github.com/oclif/oclif/blob/v1.10.0/src/commands/multi.ts)_
|
207 |
|
208 | ## `oclif plugin [PATH]`
|
209 |
|
210 | create a new CLI plugin
|
211 |
|
212 | ```
|
213 | USAGE
|
214 | $ oclif plugin [PATH]
|
215 |
|
216 | ARGUMENTS
|
217 | PATH path to project, defaults to current directory
|
218 |
|
219 | OPTIONS
|
220 | --defaults use defaults for every setting
|
221 | --force overwrite existing files
|
222 | --options=options (yarn|typescript|tslint|semantic-release|mocha)
|
223 | ```
|
224 |
|
225 | _See code: [src/commands/plugin.ts](https://github.com/oclif/oclif/blob/v1.10.0/src/commands/plugin.ts)_
|
226 |
|
227 | ## `oclif single [PATH]`
|
228 |
|
229 | generate a new single-command CLI
|
230 |
|
231 | ```
|
232 | USAGE
|
233 | $ oclif single [PATH]
|
234 |
|
235 | ARGUMENTS
|
236 | PATH path to project, defaults to current directory
|
237 |
|
238 | OPTIONS
|
239 | --defaults use defaults for every setting
|
240 | --force overwrite existing files
|
241 | --options=options (yarn|typescript|tslint|semantic-release|mocha)
|
242 | ```
|
243 |
|
244 | _See code: [src/commands/single.ts](https://github.com/oclif/oclif/blob/v1.10.0/src/commands/single.ts)_
|
245 |
|
246 |
|
247 | # 🏭 Related Repositories
|
248 |
|
249 | * [@oclif/command](https://github.com/oclif/command) - Base command for oclif. This can be used directly without the generator.
|
250 | * [@oclif/config](https://github.com/oclif/config) - Most of the core setup for oclif lives here.
|
251 | * [@oclif/errors](https://github.com/oclif/errors) - Renders and logs errors from commands.
|
252 | * [@oclif/cli-ux](https://github.com/oclif/cli-ux) - Library for common CLI UI utilities.
|
253 | * [@oclif/test](https://github.com/oclif/test) - Test helper for oclif.
|
254 |
|
255 | # 🦔 Learn More
|
256 |
|
257 | * [Salesforce Release Announcement](https://engineering.salesforce.com/open-sourcing-oclif-the-cli-framework-that-powers-our-clis-21fbda99d33a)
|
258 | * [Heroku Release Announcement](https://blog.heroku.com/open-cli-framework)
|
259 |
|
260 | # 📣 Feedback
|
261 |
|
262 | If you have any suggestions or just want to let us know what you think of oclif, send us a message at <heroku-cli@salesforce.com>
|