Added docs for writing new commands

core/cli/README.md

@@ -0,0 +1,88 @@
+# CLI Commands
+
+## Writing new commands
+
+Commands are classes which extend the base `Command` class (see [`command.js`](command.js)).
+
+The only required override is the `handle()` method, which defines the logic for the command:
+```javascript
+const Command = require('./command');
+
+module.exports = class REPL extends Command {
+    async handle(argv = {}) {
+        // this is where your logic is implemented
+    }
+};
+```
+
+### Arguments
+
+Optionally, you can override the `setup()` method, where you can define any command-line arguments and help text etc:
+```javascript
+    setup() {
+        this.help('A brief explanation of what your command does, shown when the --help flag is used');
+        // arguments are passed to sywac - see https://sywac.io/docs/
+        this.argument('--color', {type: 'string', defaultValue: 'yellow'});
+    }
+```
+
+Arguments specified in `setup()` are accessed from the `argv` object passed to the `handle()` method:
+```javascript
+async handle(argv = {}) {
+    this.log(`Your color is ${argv.color}`);
+}
+```
+
+### Output
+
+You can write console output using a number of helper methods:
+```javascript
+this.log('Writes a line to the console');
+```
+
+Available helpers are `log`, `ok`, `info`, `error`, `fatal`, `warn`, and `debug`.
+
+### Interactive input
+
+**Confirm an action** with:
+```javascript
+const confirm = await this.confirm('Are you sure you want to continue?');
+if (!confirm) {
+    // ...
+}
+```
+
+**Ask for user input** with:
+```javascript
+const fruit = await this.ask('Favorite fruit?');
+this.info(`You answered: ${fruit}`);
+```
+
+**Get masked input** with:
+```javascript
+const password = await this.secret('Password:');
+this.log(`Your password is: ${password}`);
+```
+
+### Progress bars
+
+You can show a progress bar to e.g. display progress through a long-running task.
+
+`this.progressBar()` returns an instance of a [cli-progress](https://github.com/npkgz/cli-progress) progress bar. You can add a status to the output by calling `.update({status: 'Your status message'})`, and the progress bar can be advanced by `.increment()`:
+
+```javascript
+const progressBar = this.progressBar(listOfTasks.length);
+for (const task in listOfTasks) {
+    progressBar.update({status: `Running ${task.name}`});
+    await task.run();
+    progressBar.increment();
+}
+```
+
+## Registering commands
+
+New commands need to be registered in `ghost.js` before they can be called.
+
+Commands are called by passing them to `command.run()` either as a class definition, or as the name of the file to be required in the `core/cli` directory.
+
+`command.run()` is a static method on the Command class that handles instantiating the command, resolving arguments, and calling the `handle` method. You can instantiate and call a command outside of this structure, but you'll need to resolve/provide the arguments (`argv` object) manually.