|
1 | | -# oclif getting started tutorial |
2 | | - |
3 | | -This 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. |
4 | | - |
5 | | -## Before you begin |
6 | | - |
7 | | -oclif is written in Node. You'll need Node as well as npm, which is a package manager for Javascript and a software registry. |
8 | | - |
9 | | -If you do not have them already, follow the instructions here to install npm and Node together: https://docs.npmjs.com/getting-started/installing-node |
10 | | - |
11 | | -## Creating Your First CLI with oclif |
12 | | - |
13 | | -Now you're ready to create your first CLI with oclif. There are three stages: CLI creation, command development, and publishing to NPM. |
14 | | - |
15 | | -### CLI Creation |
16 | | - |
17 | | -Let's start with a multi-command CLI. You can call your CLI anything you like by replacing `mynewcli` with a name of your choice. The name of your CLI can be anything you like as long as it meets the [npm restrictions](https://docs.npmjs.com/files/package.json#name). |
18 | | - |
19 | | -```sh-session |
20 | | -$ npx oclif multi mynewcli |
21 | | -``` |
22 | | - |
23 | | -*npx is included in npm and automatically runs and installs the oclif generator.* |
24 | | - |
25 | | -Alternatively, to setup without npx: |
26 | | - |
27 | | -```sh-session |
28 | | -$ npm install -g oclif |
29 | | -$ oclif multi mynewcli |
30 | | -``` |
31 | | - |
32 | | -You'll now see some questions asking you to describe various aspects of your CLI. Once you register your CLI with npm, these would feed into the listing for your CLI. For now, feel free to just use the defaults for each option. |
33 | | - |
34 | | -For reference, here are the options and what they do: |
35 | | - |
36 | | -* **npm package name** the name of the package as it will be listed on npm. |
37 | | -* **command bin name the CLI will export** the word the user will type to invoke the cli, e.g., “heroku” in the case of the Heroku command line interface. You may use any word here but be careful about using a word that may conflict with commonly used command line terms such as grep. In the case of conflict, the terminal will use what is loaded in the path sooner. |
38 | | -* **description** this description is part of the npm package details. This description will stay local until you publish to npm |
39 | | -* **author** The author is listed when you register your CLI on NPM |
40 | | -* **version** each time you publish a new version this number will automatically increment. |
41 | | -* **license** MIT License is set as default |
42 | | -* **node version supported** oclif only supports versions of Node greater than 8.0, which is the default set here |
43 | | -* **github owner of repository (https://github.com/OWNER/repo)** owner of the Github repo |
44 | | -* **github name of repository (https://github.com/owner/REPO)** name of the Github repo |
45 | | - |
46 | | -When your CLI is ready, you'll see a message ending with the following: |
47 | | - |
48 | | -``` |
49 | | -Created mynewcli in /Users/nsamsami/mynewcli |
50 | | -``` |
51 | | - |
52 | | -Your CLI has been created locally and the relevant code is in the `mynewcli` directory. You can go over there by running: |
53 | | - |
54 | | -```sh-session |
55 | | -$ cd mynewcli |
56 | | -``` |
57 | | - |
58 | | -For trying your CLI locally, `$ ./bin/run` is the equivalent of the command `$ mynewcli` when users install your CLI. You can now run the CLI which includes one "hello world" command: |
59 | | - |
60 | | -```sh-session |
61 | | -$ ./bin/run hello |
62 | | -hello world from ./src/commands/hello.ts! |
63 | | -$ ./bin/run help |
64 | | -USAGE |
65 | | - $ mynewcli [COMMAND] |
66 | | - |
67 | | -COMMANDS |
68 | | - hello describe the command here |
69 | | - help display help for mynewcli |
70 | | -$ ./bin/run help hello |
71 | | -describe the command here |
72 | | - |
73 | | -USAGE |
74 | | - $ mynewcli hello [FILE] |
75 | | - |
76 | | -OPTIONS |
77 | | - -f, --force |
78 | | - -n, --name=name name to print |
79 | | - |
80 | | -EXAMPLES |
81 | | - $ example-multi-ts hello |
82 | | - hello world from ./src/hello.ts! |
83 | | -``` |
84 | | - |
85 | | -To run `$ mynewcli` instead of `$ ./bin/run` you'll need to link your CLI locally using npm: |
86 | | - |
87 | | -```sh-session |
88 | | -$ npm link |
89 | | -$ mynewcli |
90 | | -USAGE |
91 | | -... |
92 | | -``` |
93 | | - |
94 | | -_**Note:** You can also use `mynewcli hello --help`. The `--help` flag works anywhere the user places it and cannot be overridden._ |
95 | | - |
96 | | -### Command Development |
97 | | - |
98 | | -Create a new command called "goodbye" either by moving `./src/commands/hello.ts` to `./src/commands/goodbye.ts` or by running the command generator with `npx oclif command goodbye`. Open `./src/commands/goodbye.ts` and replace it with the following |
99 | | - |
100 | | -```js |
101 | | -import {Command} from '@oclif/command' |
102 | | -export class GoodbyeCommand extends Command { |
103 | | - async run() { |
104 | | - console.log('goodbye, world!') |
105 | | - } |
106 | | -} |
107 | | -``` |
108 | | - |
109 | | -<!-- TODO: link to command API reference --> |
110 | | - |
111 | | -### Publishing to npm |
112 | | - |
113 | | -When you're ready to release your CLI, simply publish to npm: |
114 | | - |
115 | | -```sh-session |
116 | | -$ npm publish |
117 | | -$ npm install -g mynewcli |
118 | | -$ mynewcli |
119 | | -# OR |
120 | | -$ npx mynewcli |
121 | | -``` |
122 | | - |
123 | | -*You'll need to [register with npm](https://www.npmjs.com/signup) and have verified your email address in order to publish.* |
124 | | -*You'll also need to select a package name for your CLI that is not already in use. (Note: if you attempt to publish under an existing package name, npm will have restricted publishing to the user associated with that package, so you will see a permission error.)* |
| 1 | +Moved to https://oclif.io/docs/introduction.html |
0 commit comments