# piral-cli

> The standard CLI for creating and building a Piral instance or a Pilet.

Latest version **1.12.4** (published 2026-09-11) · MIT license · 0 weekly downloads

## Install

```sh
npm install piral-cli
pnpm add piral-cli
yarn add piral-cli
bun add piral-cli
```

Provides the commands `pb`, `pilet`, `piral`.

## Health

**Score 70/100 (B)** — status: active.

Positive: has types; no vulnerabilities; has provenance; recently updated; high maintenance score; high quality score.

Warnings: low downloads; no esm support.

## Facts

| | |
|---|---|
| Version | 1.12.4 |
| Published | 2026-09-11 |
| First published | 2019-02-15 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | bundled |
| Module format | CommonJS |
| Node | >=18.17 |
| Dependencies | 5 |
| Unpacked size | 4.4 MB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| Provenance | attested (GitHub Actions) |
| GitHub stars | 1932 |
| Author | smapiot |
| Maintainers | florianrappl, manuel.roemer, lschoett |
| Keywords | portal, modules, microfrontend, base, functional |

## Links

- npm: https://www.npmjs.com/package/piral-cli
- Repository: https://github.com/smapiot/piral
- Homepage: https://piral.io
- Issues: https://github.com/smapiot/piral/issues
- Funding: https://github.com/sponsors/smapiot
- npm.io page: https://npm.io/package/piral-cli

## Dependencies (5)

- [dets](https://npm.io/package/dets.md) ^1
- [kras](https://npm.io/package/kras.md) ^1.0.1
- [open](https://npm.io/package/open.md) ^10
- [typescript](https://npm.io/package/typescript.md) ^5
- [css-conflict-inspector](https://npm.io/package/css-conflict-inspector.md) ^0.3

## Alternatives

- [flatbuffers](https://npm.io/package/flatbuffers.md) — 6.0M weekly downloads
- [jwt-simple](https://npm.io/package/jwt-simple.md) — 259.5K weekly downloads
- [@exodus/patch-broken-hermes-typed-arrays](https://npm.io/package/@exodus/patch-broken-hermes-typed-arrays.md) — 28.5K weekly downloads
- [@native-to-anchor/buffer-layout](https://npm.io/package/@native-to-anchor/buffer-layout.md) — 12.2K weekly downloads
- [binary-parser-encoder](https://npm.io/package/binary-parser-encoder.md) — 5.3K weekly downloads

## Recent versions

- 1.12.4 (latest) — 2026-09-11
- 1.12.4-beta.fb90a9c (next) — 2026-10-21
- 0.15.0-alpha.4409 (canary) — 2022-07-07
- 1.12.4-beta.b76e5ae — 2026-10-21
- 1.12.4-beta.5c7192f — 2026-10-17
- 1.12.4-beta.ef95646 — 2026-10-17
- 1.12.4-beta.cf72637 — 2026-10-17
- 1.12.4-beta.0bc4ce7 — 2026-10-17
- 1.12.4-beta.92532b1 — 2026-10-16
- 1.12.4-beta.4f77727 — 2026-10-04
- 1.12.4-beta.6cb8b4e — 2026-10-04
- 1.12.4-beta.dc8413a — 2026-10-04
- 1.12.4-beta.d019a51 — 2026-09-29
- 1.12.4-beta.80d7277 — 2026-09-29
- 1.12.4-beta.6c244e5 — 2026-09-09
- … 1239 more at https://npm.io/package/piral-cli/versions

## README

[![Piral Logo](https://github.com/smapiot/piral/raw/main/docs/assets/logo.png)](https://piral.io)

# [Piral CLI](https://piral.io) · [![GitHub License](https://img.shields.io/badge/license-MIT-blue.svg)](https://github.com/smapiot/piral/blob/main/LICENSE) [![npm version](https://img.shields.io/npm/v/piral-cli.svg?style=flat)](https://www.npmjs.com/package/piral-cli) [![tested with vitest](https://img.shields.io/badge/tested_with-vitest-99424f.svg)](https://vitest.dev/) [![Community Chat](https://img.shields.io/discord/1222632475449229352)](https://discord.gg/kKJ2FZmK8t)

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.

## Documentation

For details on the available commands check out the [documentation at Piral](https://docs.piral.io) or [on GitHub](https://github.com/smapiot/piral/tree/main/docs/commands).

## Plugins

The Piral CLI can be extended with plugins.

### Available Plugins

Right now the following generic plugins exist:

- [**piral-cli-local-feed**](https://github.com/FlorianRappl/piral-cli-local-feed), provides the ability to start a local feed service
- [**piral-cli-dotenv**](https://github.com/FlorianRappl/piral-cli-dotenv), provides the ability to easily integrate environment variables

Also the following bundler plugin exists (bringing build/debug capabilities):

- [**piral-cli-parcel**](https://github.com/smapiot/piral-cli-parcel), provides an integration for Parcel (v1) as a bundler
- [**piral-cli-parcel2**](https://github.com/smapiot/piral-cli-parcel2), provides an integration for Parcel (v2) as a bundler
- [**piral-cli-webpack**](https://github.com/smapiot/piral-cli-webpack), provides an integration for Webpack (v4) as a bundler
- [**piral-cli-webpack5**](https://github.com/smapiot/piral), provides an integration for Webpack (v5) as a bundler
- [**piral-cli-esbuild**](https://github.com/smapiot/piral-cli-esbuild), provides an integration for ES Build as a bundler
- [**piral-cli-rollup**](https://github.com/smapiot/piral-cli-rollup), provides an integration for Rollup as a bundler
- [**piral-cli-vite**](https://github.com/smapiot/piral-cli-vite), provides an integration for Vite as a bundler
- [**piral-cli-xbuild**](https://github.com/smapiot/piral-cli-xbuild), provides the possibility of using npm scripts for building and debugging

You'll find an updated list [on NPM](https://www.npmjs.com/search?q=keywords%3Apiral-cli) using the keyword **piral-cli**.

### Building a Plugin

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:

```js
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:

```js
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:

1. Take the plugins from the local project (`piral-cli` must be installed/run locally)
2. 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.

```js
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.

## License

Piral is released using the MIT license. For more information see the [license file](./LICENSE).

---
_Source: https://npm.io/package/piral-cli · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._