brettz9
command-line-basics
Wraps the basic command-line functionality to your package.
It is probably easiest to see it in an example:
- Binary file
- The option definitions (this file defines the schema and format for the CLI arguments; note: it is not necessary to export the chalk templates assuming you even need to use them at all).
- The main app which receives the command line arguments ready for use.
Performs the following:
- Utilizes
update-notifierto notify the user of any updates of your package. - By default, will automatically add
--version/-vand--help/-hflags to the options defined in your targeted file'sdefinitions(processed bycommand-line-args) andsections[1].optionList(processed bycommand-line-usage). When your users call--help, these two flags will be shown there. When your users call--version, it will output the currentversionof yourpackage.json). - By default, will automatically add
headertosections[0]if not present (based on thenameinpackage.json). - All of
sectionswill be passed tocommand-line-usage.
Install
npm i -P command-line-basicsSimple usage
After adding your binary file to package.json, e.g.,
{
"bin": {
"myCliApp": "./bin/index.js"
}
}...and optionally making the script executable, as with
chmod 0755 ./bin/index.js, then add the following to that file:
#!/usr/bin/env node
import {cliBasics} from 'command-line-basics';
// Your main programmatic code
import mainScript from '../src/index.js';
// Point to a file with a `definitions` and `sections` export (or
// JSON properties)
const optionDefinitions = await cliBasics(
'./src/optionDefinitions.js'
);
if (!optionDefinitions) { // cliBasics handled
process.exit(0);
}
// Use `optionDefinitions` (which is just the result of running
// `command-line-args` on the `definitions` from your
// `optionDefinitions.js` file
mainScript(optionDefinitions);Advanced usage
Except for optionsPath, the example indicates the defaults:
import {dirname} from 'path'; // For `__dirname`
import {fileURLToPath} from 'url'; // For `__dirname`
import {cliBasics} from 'command-line-basics';
// For `__dirname`
const __dirname = dirname(fileURLToPath(import.meta.url));
const options = await cliBasics({
// Point to a file with a `definitions` and `sections` export (or
// JSON properties)
optionsPath: path.join(process.cwd(), './src/optionDefinitions.js'),
// `cwd` is an alternative to joining (for `optionsPath` and for an
// explicit `packageJsonPath`; has no effect on `package.json` if
// relying on the default)
cwd: __dirname,
async notifierCallback (notifier) {
// Do something with `notifier` instance: https://github.com/yeoman/update-notifier
const {
latest, current,
name,
type // `latest`, `major`, `minor`, `patch`, `prerelease`, `build`
} = await notifier.fetchInfo();
console.log('Versions', latest, current);
console.log('Package name', name);
console.log('Current update type', type);
},
options: {
packageJsonPath: path.join(process.cwd(), 'package.json'),
autoAddVersion: true,
autoAddHelp: true,
autoAddHeader: true,
autoAddOptionsHeader: true,
autoAddContent: true,
commandLineArgsOptions: {
// See https://github.com/75lb/command-line-args/blob/master/doc/API.md
},
updateNotifierOptions: {
// Options besides `pkg`
updateCheckInterval: 1000 * 60 * 60 * 24,
shouldNotifyInNpmScript: false,
distTag: 'latest' // https://docs.npmjs.com/adding-dist-tags-to-packages
},
// May also set this to `false` to avoid calling `notify` of
// `update-notifier`
updateNotifierNotifyOptions: {
defer: false, // Our default differs from that of `update-notifier` here
message: '',
isGlobal: defaultsToAutoDetectBoolean,
boxenOptions: {
// Also `dimBorder`, `float`, and `backgroundColor`
// See https://github.com/sindresorhus/boxen
padding: 1, margin: 1, align: 'center',
borderColor: 'yellow', borderStyle: 'round'
}
}
}
});
if (!options) { // cliBasics handled
process.exit(0);
}
// Use `definitions` (which is just the result of running `command-line-args`
// on the `definitions` from your `optionDefinitions.js` file)There is also exported an autoAdd method which takes the same arguments
and returns the (potentially help/version and header enhanced)
definitions and sections. It is also used internally by cliBasics.
See also
To-dos
- Utility for main files to create a file retrieval/writing function (for conversions)
- Auto-convert JSON Schema into option defintion structures with jsdoc (and
the converted JSON Schema) enhanced to add CLI properties,
e.g., any alias (
@cli-alias {file} f) and possibly itstypeLabel. Default should be deducible.