Piral CLI is a command-line tool that can also be used as a library. It should make common tasks such as building a pilet, scaffolding a pilet, or debugging a piral instance simple.
Internally, Piral CLI is build upon existing tools with connection points to their respective eco-systems.
For details on the available commands check out the documentation at Piral or on GitHub.
The Piral CLI can be extended with plugins.
Right now the following generic plugins exist:
- piral-cli-local-feed, provides the ability to start a local feed service
- piral-cli-dotenv, provides the ability to easily integrate environment variables
Also the following bundler plugin exists (bringing build/debug capabilities):
- piral-cli-parcel, provides an integration for Parcel (v1) as a bundler
- piral-cli-parcel2, provides an integration for Parcel (v2) as a bundler
- piral-cli-webpack, provides an integration for Webpack (v4) as a bundler
- piral-cli-webpack5, provides an integration for Webpack (v5) as a bundler
- piral-cli-esbuild, provides an integration for ES Build as a bundler
- piral-cli-rollup, provides an integration for Rollup as a bundler
- piral-cli-vite, provides an integration for Vite as a bundler
- piral-cli-xbuild, provides the possibility of using npm scripts for building and debugging
You'll find an updated list on NPM using the keyword piral-cli.
A plugin has to be an NPM module with a name that starts with piral-cli-
, e.g., piral-cli-local-feed
.
Recommendation: If your CLI plugin adds a new command, name your plugin accordingly, e.g., for a new command named foo-piral
create an NPM package called piral-cli-foo-piral
. The foo-piral
command can be invoked by the user in the command line via piral foo
or pb foo-piral
.
The NPM module needs to look as follows:
module.exports = function (cliApi) {
// your code
};
With the CLI API you can do things such as wrapping commands or adding new commands. For commands the yargs command definition is followed.
An example command for a pilet:
module.exports = function (cliApi) {
cliApi.withCommand({
name: 'dependencies-pilet',
alias: ['deps-pilet'],
description: 'Lists the dependencies of the current pilet.',
arguments: [],
flags(argv) {
return argv
.boolean('only-shared')
.describe('only-shared', 'Only outputs the declared shared dependencies.')
.default('only-shared', false)
.string('base')
.default('base', process.cwd())
.describe('base', 'Sets the base directory. By default the current directory is used.');
},
run(args) {
// your code here, where args.onlyShared refers to our custom argument
},
});
};
The resolution for plugins is as follows:
- Take the plugins from the local project (
piral-cli
must be installed/run locally) - Take the plugins from the global modules
Plugins are never loaded twice. Local versions have precedence.
Using a plugin you can also attach to the hooks of the pilet build/debug
and piral build/debug
commands.
module.exports = function (cliApi) {
cliApi.wrapCommand('debug-pilet', (args, run) => run({
...args,
hooks: {
afterBuild({ outFile, outDir }) {
console.log('Build done', outFile, outDir);
},
},
}));
};
In this case the afterBuild
hook of the pilet debug
command is set. You can do whatever else hook, too. Furthermore, you are not limited to a single command - you might want to wrap multiple here.
Piral is released using the MIT license. For more information see the license file.