{"id":17874,"library":"piral-cli","title":"Piral CLI","description":"Piral CLI (Command Line Interface) is the essential toolkit for developing microfrontends within the Piral framework. It empowers developers to scaffold new Piral instances (the host shell application) and individual Pilets (the microfrontend modules), and to manage their lifecycle including building, debugging, and deploying. The current stable version is 1.10.3, with a release cadence that includes frequent patch and minor updates to incorporate bug fixes, dependency upgrades, and enhance compatibility with evolving frontend frameworks like Angular and React. Its key differentiators include a bundler-agnostic architecture supporting popular tools such as Webpack, Vite, and Esbuild, strong TypeScript integration, and comprehensive features for orchestrating independently deployable microfrontends, including shared dependencies and dynamic runtime updates.","status":"active","version":"1.10.3","language":"javascript","source_language":"en","source_url":"https://github.com/smapiot/piral","tags":["javascript","portal","modules","microfrontend","base","functional","typescript"],"install":[{"cmd":"npm install piral-cli","lang":"bash","label":"npm"},{"cmd":"yarn add piral-cli","lang":"bash","label":"yarn"},{"cmd":"pnpm add piral-cli","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"While primarily a CLI tool, `run` allows programmatic execution of Piral CLI commands within Node.js scripts. This is useful for CI/CD or custom automation.","wrong":"import run from 'piral-cli';","symbol":"run","correct":"import { run } from 'piral-cli';\n// or require for CJS\nconst { run } = require('piral-cli');"},{"note":"This type is primarily used when developing custom plugins for the Piral CLI (packages starting with `piral-cli-`).","wrong":"import { CliPlugin } from 'piral-cli';","symbol":"CliPlugin","correct":"import type { CliPlugin } from 'piral-cli';"},{"note":"The `cliApi` object is passed as an argument to the exported function of a Piral CLI plugin, providing methods to extend or wrap CLI commands. It's not a direct import from `piral-cli` itself.","wrong":"import { cliApi } from 'piral-cli';","symbol":"cliApi","correct":"// In a Piral CLI plugin (e.g., piral-cli-my-plugin/index.js):\nmodule.exports = function (cliApi) { /* ... */ };"}],"quickstart":{"code":"# Install Piral CLI globally (recommended for convenience, or use npx)\nnpm install -g piral-cli\n\n# Or use npx for local execution:\n# npx piral new my-piral-app --framework react --install\nnpx piral new my-piral-app --framework react --install\ncd my-piral-app\nnpx piral debug\n\n# In a new terminal, scaffold a new pilet (microfrontend)\nnpx pilet new my-pilet --source my-piral-app@1.0.0 --install\ncd my-pilet\nnpx pilet debug","lang":"typescript","description":"Demonstrates how to create a new Piral instance (host application) and a Pilet (microfrontend), then run them in debug mode."},"warnings":[{"fix":"Upgrade Node.js to version 18.17 or higher. We recommend using `nvm` to manage Node.js versions.","message":"The Node.js engine requirement for `piral-cli` is `>=18.17`. Using older Node.js versions will result in an error and prevent the CLI from running.","severity":"breaking","affected_versions":"<1.8.0 (likely)"},{"fix":"Refer to the `piral-ng` documentation and release notes for the exact `piral-cli` version compatibility with your Angular project's version. Update `piral-cli` and `piral-ng` in tandem.","message":"Compatibility with specific Angular versions and features (e.g., standalone components, lazy component loaders, input signals) in the `piral-ng` plugin often requires specific `piral-cli` and `piral-ng` versions. Discrepancies can lead to build or runtime errors.","severity":"gotcha","affected_versions":">=1.8.5"},{"fix":"Review and update any custom error handling or event listeners that access the `container` property of the `unhandled-error` event arguments.","message":"The `container` property was removed from the event arguments for the `unhandled-error` event. Code relying on this property will break.","severity":"breaking","affected_versions":">=1.9.0"},{"fix":"Ensure `piral-cli` is updated to at least version 1.8.2 or later to benefit from fixes to Windows command-line parsing.","message":"Earlier versions of `piral-cli` (prior to v1.8.2) had issues with command-line argument parsing on Windows, which could lead to unexpected behavior or incorrect command execution.","severity":"gotcha","affected_versions":"<1.8.2"}],"env_vars":null,"last_verified":"2026-04-23T00:00:00.000Z","next_check":"2026-07-22T00:00:00.000Z","problems":[{"fix":"Install globally: `npm install -g piral-cli`, or use `npx` to run commands: `npx piral [command]`.","cause":"`piral-cli` is not installed globally or `npx` is not used within the project context, or `PATH` is misconfigured.","error":"'piral' is not recognized as an internal or external command, operable program or batch file."},{"fix":"Upgrade Node.js to version 18.17 or higher. Use `nvm install 18` and `nvm use 18` (or your preferred version manager).","cause":"The installed Node.js version is older than the minimum required by `piral-cli`.","error":"Error: Minimum Node.js version not met. Expected >=18.17.0, got X.Y.Z"},{"fix":"Check the `piral-ng` documentation and changelog for known issues and required `piral-cli` versions for your Angular version. Ensure consistent `@angular/core` versions across your Piral instance and pilets.","cause":"This error often indicates an issue with Angular's Ivy compilation related to module boundaries or standalone component usage, which can arise from `piral-ng` plugin incompatibilities with specific Angular project configurations.","error":"Angular Compilation Error: NG04002"}],"ecosystem":"npm","meta_description":null,"install_score":null,"install_tag":null,"quickstart_score":null,"quickstart_tag":null}