fix: readme improvements
MODIFY
README.md
README.md
@@ -120,14 +120,25 @@ $ ./bin/run hello
hello world from ./src/hello.js!
```
+# Examples
+
+* TypeScript
+ * [Multi-command CLI](https://github.com/oclif/example-multi-ts)
+ * [Single-command CLI](https://github.com/oclif/example-single-ts)
+ * [Multi-command CLI Plugin](https://github.com/oclif/example-single-ts)
+* JavaScript
+ * [Multi-command CLI](https://github.com/oclif/example-multi-js)
+ * [Single-command CLI](https://github.com/oclif/example-single-js)
+ * [Multi-command CLI Plugin](https://github.com/oclif/example-plugin-js)
+
# Command Options
-A basic command looks like the following:
+A basic command looks like the following in TypeScript:
```js
import Command from '@oclif/command'
-export default class extends Command {
+export class MyCommand extends Command {
static description = 'description of this example command'
async run() {
@@ -136,9 +147,27 @@ export default class extends Command {
}
```
-The only part that is required is the run function. Accept user input with arguments and flag options.
+The only part that is required is the run function. Accept user input with [arguments](#arguments) and [flag options](#flag-options).
+
+In JavaScript:
+
+```js
+const {Command} = require('@oclif/command')
+
+class MyCommand extends Command {
+ async run() {
+ console.log('running my command')
+ }
+}
+
+MyCommand.description = 'description of this example command'
+
+module.exports = MyCommand
+```
+
+Note that the following examples will be in TypeScript. As JavaScript does not yet have static class properties, you will have to add them to the class after it is declared like we did with the description above.
-## Arguments
+# Arguments
Arguments are positional arguments passed to the command. For example, if this command was run with `mycli arg1 arg2` it would be declared like this:
@@ -177,7 +206,7 @@ static args = [
]
```
-## Flag Options
+# Flag Options
Flag options are non-positional arguments passed to the command. For example, if this command was run with `mycli --force --output=./myfile` (= is optional) it would be declared like this:
@@ -233,7 +262,7 @@ For larger CLIs, it can be useful to declare a custom flag that can be shared am
```js
// flags.ts
import {flags} from '@oclif/command'
-function getTeam(): string | undefined {
+function getTeam() {
// imagine this reads a configuration file or something to find the team
}
export const team = flags.build({
@@ -255,20 +284,54 @@ export class MyCLI extends Command {
const {flags} = this.parse(MyCLI)
if (flags.team) console.log(`--team is ${flags.team}`)
}
+}
```
In the Heroku CLI, we use flags for our `--app` flag which takes advantage of a lot of functionality. It can be useful [to see how that is done](https://github.com/heroku/cli-engine-heroku/blob/oclif/src/flags/app.ts) to get ideas for making custom flags.
-# Examples
+# Aliases
-* TypeScript
- * [Multi-command CLI](https://github.com/oclif/example-multi-ts)
- * [Single-command CLI](https://github.com/oclif/example-single-ts)
- * [Multi-command CLI Plugin](https://github.com/oclif/example-single-ts)
-* JavaScript
- * [Multi-command CLI](https://github.com/oclif/example-multi-js)
- * [Single-command CLI](https://github.com/oclif/example-single-js)
- * [Multi-command CLI Plugin](https://github.com/oclif/example-plugin-js)
+Aliases let you define a string that maps to a command. This command can be run as `mycli config`, `mycli config:index`, or `mycli config:list`: (this only applies to multi-CLIs)
+
+```js
+import Command, {flags} from '@oclif/command'
+
+export class ConfigIndex extends Command {
+ static aliases = ['config:index', 'config:list']
+}
+```
+
+# Other Command Options
+
+```js
+import Command, {flags} from '@oclif/command'
+
+export class MyCommand extends Command {
+ static description = `
+description of my command
+can be multiline
+`
+
+ // hide the command from help
+ static hidden = false
+
+ // custom usage string for help
+ // this overrides the default usage
+ static usage = 'mycommand --myflag'
+
+ // examples to add to help
+ // each can be multiline
+ static examples = [
+ '$ mycommand --force',
+ '$ mycommand --help',
+ ]
+
+ // this makes the parser not fail when it receives invalid arguments
+ // defaults to true
+ // set it to false if you need to accept variable arguments
+ static strict = false
+}
+```
# Topics

MODIFY
templates/src/command.ts.ejs
templates/src/command.ts.ejs
@@ -6,21 +6,7 @@ class <%- klass %> extends Command {
<%_ } else { _%>
export default class <%- klass %> extends Command {
<%_ } _%>
- static description = `
-Describe the command here
-...
-Extra documentation goes here
-`
-<%_ if (type !== 'single') { _%>
- // hide the command from help
- // can also set hidden on args and flags
- // static hidden = true
-<%_ } _%>
-
- // usage is set by default
- // add your own by setting this variable
- // can be a string or array
- // static usage = 'title of command'
+ static description = 'describe the command here'
static examples = [
`$ <%- cmd %>
@@ -29,16 +15,7 @@ hello world from ./src/<%- name %>.ts!
`$ <%- cmd %> --name myname
hello myname from .src/<%- name %>.ts!
`,
- `$ <%- cmd %> ./afile
-# outputs "hello world!" to ./afile`,
- '$ <%- cmd %> --force',
- '$ <%- cmd %> --help',
]
-<%_ if (type !== 'single') { _%>
-
- // allow running this command by running `$ <%- bin %> foobar`
- // static aliases = ['foobar']
-<%_ } _%>
static flags = {
<%_ if (type === 'single') { _%>
@@ -49,53 +26,19 @@ hello myname from .src/<%- name %>.ts!
<%_ } _%>
// flag with a value (-n, --name=VALUE)
- name: flags.string({
- char: 'n', // shorter flag version
- description: 'name to print', // help description for flag
- hidden: false, // hide from help
- multiple: false, // allow setting this flag multiple times
- // env: 'MY_NAME', // default to value of environment variable
- // options: ['a', 'b'], // only allow the value to be from a discrete set
- // parse: input => 'output', // instead of the user input, return a differnt value
- // default: 'world', // default value if flag not passed
- // required: false, // make flag required (this is not common and you should probably use an argument instead)
- }),
-
- // flag with no value (-f, --force)
- force: flags.boolean({
- char: 'f',
-
- // by default boolean flags may also be reversed with `--no-` (in this case: `--no-force`)
- // the flag will be set to false if reversed
- // set this to false to disable this functionality
- // allowNo: false,
- }),
+ name: flags.string({char: 'n', description: 'name to print'}),
+ force: flags.boolean({char: 'f'}),
}
- static args = [
- {
- name: 'file', // name of arg to show in help and reference with args[name]
- required: false, // make the arg required with `required: true`
- description: 'file to output', // help description
- // hidden: true, // hide this flag from help
- // parse: input => 'output', // instead of the user input, return a differnt value
- // default: 'world', // default value if no arg input
- // options: ['a', 'b'], // only allow input to be from a discrete set
- },
- ]
-
- // this makes the parser not fail when it receives invalid arguments
- // set it to off if you need to accept variable arguments
- // static strict = false
+ static args = [{name: 'file'}]
- // entry point of command
async run() {
const {args, flags} = this.parse(<%- klass %>)
const name = flags.name || 'world'
this.log(`hello ${name} from ./src/<%- name %>.ts!`)
if (args.file && flags.force) {
- this.log(`you input ${args.file}`)
+ this.log(`you input --force and --file: ${args.file}`)
}
}
}

fix: readme improvements