A sample project setup showcasing the ability to extend the base functionality of the and-cli package for project-specific needs.
.
├── modules # Modules are shared functions to be imported & called by commands
│ └── dotnet-version.js # A custom module that prints dotnet sdk version information
├── package.json
├── package-lock.json
├── plugin-cli.js # Main entrypoint of the CLI program
├── plugin-cli-dotnet.js # A custom implementation of the dotnet command
├── plugin-cli-example.js # An empty example command
└── README.md
The plugin feature is available from v1.2.0 and later. The alias feature is available from v1.3.1 and later. Prior to v2.0.0 modules were lowercase-first and "default" imports. Check the git history for examples if still using versions < v2.0.0.
In order to run this demo locally, you will need to:
- Clone this repository
git clone https://github.com/AndcultureCode/AndcultureCode.Cli.PluginExample- Install dependencies
cd AndcultureCode.Cli.PluginExample
npm install- Run the plugin cli
$ ./plugin-cli.jsClick to see code sample
#!/usr/bin/env node
// -----------------------------------------------------------------------------------------
// #region Imports
// -----------------------------------------------------------------------------------------
const { CommandRegistry, program } = require("and-cli");
// #endregion Imports
// -----------------------------------------------------------------------------------------
// #region Entrypoint
// -----------------------------------------------------------------------------------------
// Register all of the base commands from the and-cli with this application
CommandRegistry.registerAllBase();
program.parse(process.argv);
// #endregion EntrypointClick to see CLI output
Usage: plugin-cli [options] [command]
andculture cli
Options:
-V, --version output the version number
-h, --help display help for command
Commands:
copy Copy files and/or directories
deploy Deploy various application types
dotnet Run various dotnet commands for the project
dotnet-test Run various dotnet test runner commands for the project
github Commands for interacting with AndcultureCode github resources
install Collection of commands related to installation and configuration of the and-cli
migration Run commands to manage Entity Framework migrations
nuget Manages publishing of nuget dotnet core projects
webpack Run various webpack commands for the project
webpack-test Run various webpack test commands for the project
help [command] display help for commandClick to see code sample
#!/usr/bin/env node
// -----------------------------------------------------------------------------------------
// #region Imports
// -----------------------------------------------------------------------------------------
const { CommandRegistry, program } = require("and-cli");
// #endregion Imports
// -----------------------------------------------------------------------------------------
// #region Entrypoint
// -----------------------------------------------------------------------------------------
// Register a single base command from the and-cli with this application
CommandRegistry.registerBase("dotnet");
program.parse(process.argv);
// #endregion EntrypointClick to see CLI output
Usage: plugin-cli [options] [command]
andculture cli
Options:
-V, --version output the version number
-h, --help display help for command
Commands:
dotnet Run various dotnet commands for the project
help [command] display help for commandClick to see code sample
#!/usr/bin/env node
// -----------------------------------------------------------------------------------------
// #region Imports
// -----------------------------------------------------------------------------------------
const { CommandRegistry, program } = require("and-cli");
// #endregion Imports
// -----------------------------------------------------------------------------------------
// #region Entrypoint
// -----------------------------------------------------------------------------------------
// Register all of the base commands from the and-cli with this application
CommandRegistry.registerAllBase();
// Register a custom command in the current project (filename must match <cli-name>-<command-name>.js)
// ie, this command maps up to `plugin-cli-example.js`
CommandRegistry.register(
{
command: "example",
description: "Some example command",
},
);
program.parse(process.argv);
// #endregion EntrypointClick to see CLI output
Usage: plugin-cli [options] [command]
andculture cli
Options:
-V, --version output the version number
-h, --help display help for command
Commands:
copy Copy files and/or directories
deploy Deploy various application types
dotnet Run various dotnet commands for the project
dotnet-test Run various dotnet test runner commands for the project
example Some example command
github Commands for interacting with AndcultureCode github resources
install Collection of commands related to installation and configuration of the and-cli
migration Run commands to manage Entity Framework migrations
nuget Manages publishing of nuget dotnet core projects
webpack Run various webpack commands for the project
webpack-test Run various webpack test commands for the project
help [command] display help for commandImporting the base CLI, registering all of the base commands, adding aliases through the command registry
Click to see code sample
#!/usr/bin/env node
// -----------------------------------------------------------------------------------------
// #region Imports
// -----------------------------------------------------------------------------------------
const { CommandRegistry, program } = require("and-cli");
// #endregion Imports
// -----------------------------------------------------------------------------------------
// #region Entrypoint
// -----------------------------------------------------------------------------------------
// Register all of the base commands from the and-cli with this application
CommandRegistry.registerAllBase();
// Register an alias for the dotnet command and the dotnet command with specific options
CommandRegistry
.registerAlias({
command: "d",
description: "dotnet",
})
.registerAlias({
command: "dcRb",
description: "dotnet -cRb",
});
// Call CommandRegistry.parseWithAliases() instead of program.parse() to ensure aliases are handled
// before attempting to parse regular commands.
CommandRegistry.parseWithAliases();
// #endregion Entrypointd will be displayed in the help menu and map to the dotnet command when run, while dcRb maps to dotnet -cRb.
Click to see CLI output
Usage: plugin-cli [options] [command]
Sandbox project to showcase extending functionality of and-cli
Options:
-V, --version output the version number
-h, --help display help for command
Commands:
copy Copy files and/or directories
d (alias) dotnet
dcRb (alias) dotnet -cRb
deploy Deploy various application types
dotnet Some custom version of the dotnet command
dotnet-test Run various dotnet test runner commands for the project
example Some example command
github Commands for interacting with AndcultureCode github resources
install Collection of commands related to installation and configuration of the and-cli
migration Run commands to manage Entity Framework migrations
nuget Manages publishing of nuget dotnet core projects
webpack Run various webpack commands for the project
webpack-test Run various webpack test commands for the project
help [command] display help for commandClick to see code sample
#!/usr/bin/env node
// -----------------------------------------------------------------------------------------
// #region Imports
// -----------------------------------------------------------------------------------------
const { CommandRegistry, program } = require("and-cli");
// #endregion Imports
// -----------------------------------------------------------------------------------------
// #region Entrypoint
// -----------------------------------------------------------------------------------------
// Register a custom command in the current project (filename must match <cli-name>-<command-name>.js)
// ie, this command maps up to `plugin-cli-example.js`
CommandRegistry.register(
{
command: "example",
description: "Some example command",
},
);
// Aliases will be loaded from the local package.json file under an 'and-cli' > 'aliases' section.
CommandRegistry.registerAliasesFromConfig();
// Call CommandRegistry.parseWithAliases() instead of program.parse() to ensure aliases are handled
// before attempting to parse regular commands.
CommandRegistry.parseWithAliases();
// #endregion EntrypointThe package.json would have entries in it like this:
"and-cli": {
"aliases": {
"ex": "example"
}
},ex will be displayed in the help menu and map to the example command when run.
Click to see CLI output
Usage: plugin-cli [options] [command]
Sandbox project to showcase extending functionality of and-cli
Options:
-V, --version output the version number
-h, --help display help for command
Commands:
ex (alias) example
example Some example command
help [command] display help for commandAs of right now, consumers are unable to add additional options/flags to a base command that is exported from the and-cli. I think that would require some way to run a 'pre-parse' hook to tack on additional options before parsing arguments and running the command body, or possibly a larger refactor of the way we are registering commands in the base CLI. There is a documented issue (that is still being updated/vetted) on the commander.js repo for discussion around pre/post hooks.
If the proposed option makes sense to live in the base CLI, open up an issue in the and-cli repo and the team will discuss if it is a direction we want to go in.
Otherwise, the only workaround is to add a new command. Post-fixing the command to denote it is the custom to this project/extended cli might be a good idea (such as dotnet-local or dotnet-ext).
To override a base command with one that you've implemented yourself, each register*Command function has an overrideIfRegistered flag that needs to be set to true. This will ensure that you are intentionally attempting to replace the command(s) that have already been registered.
// ... imports, entrypoint, etc.
// Register a single base command from the and-cli with this application
CommandRegistry.registerBase("dotnet");
// Override the 'dotnet' command from and-cli with our own custom version
CommandRegistry.register(
{
command: "dotnet",
description: "Some custom version of the dotnet command",
},
true
);Under the hood, this is just checking to see if a command of the same name has already been added, and removing it before registering the new one. You could remove this command manually, in which case the overrideIfRegistered flag is not necessary:
// ... imports, entrypoint, etc.
// Register all of the base commands from the and-cli with this application
CommandRegistry.registerAllBase();
// Remove just the base 'dotnet' command
CommandRegistry.removeCommand("dotnet");
// Add our custom version of the 'dotnet' command now that there's no name conflict
CommandRegistry.register(
{
command: "dotnet",
description: "Some custom version of the dotnet command",
}
);As of v1.5.0, your CLI project can be installed globally using the same install command that the base and-cli provides.
- Add/update the bin name for your entrypoint file in
package.json
"bin": {
"plugin-cli": "plugin-cli.js"
},Note: While not required for the executable to run, it is probably a good idea to ensure the bin name is the same as your package name, ie:
"name": "plugin-cli",This will allow you to easily identify your globally installed CLI.
- Run the
installcommand. Ensure you've properly registered at least the baseinstallcommand in your project.
./plugin-cli.js install- You can then change to another directory and run it directly by the bin name.
cd ~/some/other/directory
plugin-cli dotnet -cRbThanks goes to these wonderful people (emoji key):
 Brandon Scott 💻 📖 |
 Joshua Hughes 👀 |
 Scott Savage 👀 |
 Jim Stevenson 👀 |
This project follows the all-contributors specification. Contributions of any kind welcome!