Boreal UI CLI
Use the Boreal UI command line tool to configure an existing React or Next.js project with the package dependency, global styles, ThemeProvider, and default style config.
Run it anywhere
Run @boreal-ui/cli directly with npx, or install it as a dev dependency when you want the boreal-ui and create-boreal-ui bins available locally.
Preview first
Use --dry-run or --check to inspect the planned file edits before the CLI writes to the project.
Framework aware
The CLI detects React or Next.js from dependencies and common entry files, or accepts an explicit --framework.
Common Commands
Start with a dry run, then apply the generated edits when the plan looks right.
npx @boreal-ui/cli@latest init --framework react --dry-run
npx @boreal-ui/cli@latest init --framework react --yes --installnpx @boreal-ui/cli@latest init --framework next --recommended-globals --dry-run
npx @boreal-ui/cli@latest init --framework next --recommended-globals --yesnpx @boreal-ui/cli@latest init ./apps/admin --framework next --package-manager pnpmCommands
| Default setup | npx @boreal-ui/cli@latest init |
|---|---|
| Explicit init | npx @boreal-ui/cli@latest init |
| Setup alias | npx @boreal-ui/cli@latest setup |
| Create alias | npx --package @boreal-ui/cli@latest create-boreal-ui |
| Help | npx @boreal-ui/cli@latest --help |
Options
| --cwd, --project, --dir <path> | Choose the project directory to configure. |
|---|---|
| --framework <react|next> | Skip detection and choose the React or Next.js setup path. |
| --dry-run, --check | Print the planned edits without writing files. |
| --install / --no-install | Run or skip the dependency install after edits are applied. |
| --package-manager <name> | Use npm, pnpm, or yarn for dependency installation. |
| --recommended-globals | Apply the Boreal-safe Next.js globals.css baseline without prompting. |
| --no-recommended-globals | Skip the recommended Next.js globals.css prompt and edit. |
| --yes, -y | Accept recommended edits without interactive prompts. |
What the CLI Changes
- Runs against an existing React or Next.js project.
- Requires a package.json in the target directory.
- Adds the selected scoped Boreal UI package to dependencies when it is missing.
- Imports the correct globals.css entry for the detected framework.
- Wraps the app with ThemeProvider and sets default style config.
- Can show planned edits first with --dry-run or --check.
Next.js globals baseline
Next starter projects often include a universal margin and padding reset. --recommended-globals replaces that with a safer box-sizing baseline so Boreal component spacing remains intact.
- Sets html box-sizing to border-box.
- Inherits box sizing for elements and pseudo-elements.
- Keeps body margin at zero without wiping every element.
Recommended Flow
For teams, keep the first run reviewable and repeatable.
npx @boreal-ui/cli@latest init --framework next --recommended-globals --dry-run
npx @boreal-ui/cli@latest init --framework next --recommended-globals --yes
npm install- package.json
- src/main.tsx
- src/app/layout.tsx
- src/app/boreal-provider.tsx
- src/app/globals.css
Exit cleanly with help and version
Use npx @boreal-ui/cli@latest --help for usage details and npx @boreal-ui/cli@latest --version to print the installed package version.
- Unknown options fail with a helpful message.
- Invalid framework values must be react or next.
- Invalid package managers must be npm, pnpm, or yarn.