89 lines
2.8 KiB
Markdown
89 lines
2.8 KiB
Markdown
|
# 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.
|