CLI Reference#
Warning
Project Neo is currently in Technical Preview. Features described in this section may change before general availability.
All commands are invoked as neo-ui <command>. Run neo-ui with no arguments to print the full command list.
neo-ui create bundle#
Scaffolds a complete bundle in a new directory. Must be run from the parent directory where you want the project folder created.
neo-ui create bundle
Prompts
Prompt |
Description |
|---|---|
Project name |
Confirms or collects the name. Accepted characters are letters, digits, hyphens, underscores, and dots. No spaces. |
Squirro API endpoint |
Your instance URL. Must start with |
Refresh token |
From My Account → API Access in your Squirro profile. |
Port confirmation |
If the default ports (3001, 5555) are in use, the CLI suggests alternatives. |
What gets created
Complete project directory with all configuration files.
src/manifest.tswith an empty dashboards array.src/dashboards/directory for your components..envwith your API credentials.All dependencies installed, including
@squirro/nextgen-coreand@squirro/neo-ui.
After creating the bundle, the CLI shows a Next steps panel with the commands to enter the project, start the dev server, build for production, and add a dashboard.
Tip
If credential verification fails due to a wrong URL or expired token, you can continue anyway and fix it later with neo-ui config.
neo-ui create dashboard#
Adds a new dashboard to an existing bundle. Must be run from within a project directory. You can pass the dashboard name and details as arguments, or run the command with no arguments to be prompted for each value. The CLI prompts only for values you do not supply.
neo-ui create dashboard # Prompt for every value
neo-ui create dashboard Analytics # Name as a positional argument
neo-ui create dashboard --name Analytics --route analytics --icon bar-chart-3
Arguments and flags
Argument or flag |
Default |
Description |
|---|---|---|
|
Prompted |
Dashboard name displayed in the sidebar. |
|
Kebab-case of name |
URL segment, for example |
|
|
Lucide icon name from lucide.dev/icons. Use the kebab-case name shown there. |
What gets created
src/dashboards/{ComponentName}.tsx: starter dashboard component.src/manifest.ts: new entry added to the dashboards array.src/main.tsx: import and development route added.
neo-ui remove dashboard#
Interactively removes a dashboard from the project. Must be run from within a project directory.
neo-ui remove dashboard
The CLI lists all dashboards found in src/manifest.ts and prompts you to select one. After confirmation, it:
Removes the entry from
src/manifest.ts.Removes the import and route from
src/main.tsx.Deletes the component file from
src/dashboards/.
Warning
This command permanently deletes the component file. Commit or back up your work before running it.
neo-ui dev#
Starts the local development environment. Must be run from within a project directory.
neo-ui dev
Two servers start in parallel:
Server |
Default port |
Role |
|---|---|---|
Dev proxy |
5555 |
Serves the pre-built Project Neo host, handles authentication, and proxies API requests. |
Bundle dev server |
3001 |
Builds and serves your bundle via Module Federation. |
Open http://localhost:5555 in your browser.
Flags
Flag |
Description |
|---|---|
|
Use a specific bundle dev server port. |
|
Use a specific dev proxy port. |
|
Save the resolved ports to |
Port conflicts: if a default or .env port is already in use, neo-ui dev automatically falls back to the next free port for the current run, prints a notice, and leaves .env unchanged. A port you request explicitly with --port or --proxy-port is never moved. If that port is busy, the command exits with an error so you can free it or choose another.
Live reload: the dev server watches your src/ directory and reloads the browser automatically when files change.
Stopping: press Ctrl+C to shut down both servers cleanly.
Tip
Keep http://localhost:3001/mf-manifest.json open in a second browser tab during development. If it returns JSON, your bundle server is running correctly.
neo-ui build#
Builds the bundle for production deployment. Must be run from within a project directory.
neo-ui build
Outputs optimized static files to dist/:
dist/
├── mf-manifest.json # Module Federation manifest (loaded by the host)
├── bundle-info.json # Build metadata used by neo-ui deploy
├── *.js # Bundled chunks
└── *.css # Styles
Deploy the entire dist/ folder to a static file server or CDN. For deployment details, see the Building and Deploying page.
neo-ui upgrade#
Upgrades @squirro/nextgen-core and @squirro/neo-ui to a published version, and migrates a project off the legacy nextgen CLI in the same step. Must be run from within a project directory.
neo-ui upgrade # Upgrade to the latest stable release
neo-ui upgrade --next # Upgrade to the latest pre-release
neo-ui upgrade 0.3.0 # Pin an exact version
neo-ui upgrade --dry-run # Preview the changes without writing
Flags and arguments
Flag or argument |
Description |
|---|---|
|
Upgrade to the latest pre-release channel instead of the latest stable release. |
|
Preview the changes without writing to the project. |
|
Pin an exact version to install, for example |
The command pins both packages in package.json to the target version and reinstalls dependencies. It also migrates a project that still uses the legacy nextgen CLI, updating the dependency name and the package.json scripts that call the old binary so they call neo-ui instead. The migration is idempotent. Running it again on an already-migrated project reports no changes.
Tip
The default upgrade targets the latest stable release. If your project tracks a pre-release line, pass --next. Preview first with neo-ui upgrade --next --dry-run.
After upgrading, run neo-ui build to rebuild with the new version, then neo-ui deploy to push the updated bundle.
neo-ui deploy#
Builds the bundle, validates version compatibility with the target instance, and uploads the bundle in one command. Must be run from within a project directory.
neo-ui deploy # Build, preflight, and upload
neo-ui deploy --no-build # Skip build, deploy the existing dist/
neo-ui deploy --dry-run # Preflight and list projects, no upload
neo-ui deploy --project <id> # Skip the interactive picker (for CI)
neo-ui deploy --force # Override an incompatible compatibility verdict
neo-ui deploy --json # Machine-readable receipt on stdout
Flags
Flag |
Description |
|---|---|
|
Skip the build step and deploy the existing |
|
Run preflight and list available projects without uploading. |
|
Skip the interactive picker and use a known project ID. |
|
Override an incompatible compatibility verdict. |
|
Emit a machine-readable receipt on stdout. |
The command builds the bundle unless --no-build is given, runs preflight checks, shows an interactive project picker, uploads the bundle, and activates it on the chosen project by setting frontend.ui-bundle. A version-compatibility gate blocks the deploy when the bundle is incompatible with the target instance. For details on the gate and remediation, see the Building and Deploying page.
Tip
Run neo-ui deploy --dry-run first to see the available projects and the compatibility verdict without uploading anything.
neo-ui catalog#
Serves the component catalog locally, which is the same interactive catalog hosted at neo-catalog.squirro.com. It documents every component and widget a bundle can import from @squirro/nextgen-core. The catalog ships with the installed @squirro/neo-ui package, so it works offline and matches your installed version. Run it from anywhere. No bundle directory is required.
neo-ui catalog # Serve at http://localhost:6007
neo-ui catalog --port 6100 # Use a custom port
For what the catalog contains and how to use it, see the Styling and Components page.
neo-ui doctor#
Diagnoses common bundle issues and prints a checklist, with a copy-paste fix for each item. Must be run from within a bundle directory.
neo-ui doctor # Diagnose
neo-ui doctor --fix # Diagnose, then auto-heal the safe issues
neo-ui doctor --json # Machine-readable output (for CI)
neo-ui doctor --offline # Skip the network token check
Flags
Flag |
Description |
|---|---|
|
Auto-heal the safe issues, such as removing a duplicate core package, installing a missing one, or recreating a missing type shim. Everything else, including a stale core package, prints the command to run. |
|
Print the results as machine-readable output. In this mode |
|
Skip the network token check. |
The command exits with a non-zero status only when a check fails, so neo-ui doctor --json is safe to gate a pipeline on. Warnings do not fail the pipeline.
neo-ui config#
Interactively edits the .env configuration. Must be run from within a project directory.
neo-ui config
Presents a menu for updating API credentials and port settings. For API credentials, the CLI validates the new token against the Squirro API before saving. If validation fails, you can save anyway and correct it later.
neo-ui info#
Displays a summary of the current project configuration and dashboards. Must be run from within a project directory.
neo-ui info
Example output:
┌──────────────────────────────────────────┐
│ Project Info │
│ │
│ Project: my-dashboards │
│ Version: 1.0.0 │
│ API: https://your-instance.example.com│
│ Token: abc...xyz │
│ Dashboards: 2 │
│ - Analytics /analytics │
│ - Reports /reports │
└──────────────────────────────────────────┘
The Token field shows the SQUIRRO_TOKEN value from your .env file, masked to the first and last three characters. Use it to confirm that a token is set and to identify which token is active when switching between projects. To validate the token against the API or replace it, run neo-ui config and select API credentials.
neo-ui translations init#
Scaffolds translation files for your bundle. Must be run from within a project directory. Designed to run once during initial setup.
neo-ui translations init
Creates the following files:
src/translations/en.json: English strings (also createsde,fr, andit).src/translations/use-translation.ts: typeduseExtTranslation()hook.
Also updates src/manifest.ts to include the translations configuration.
Note
This command fails if translations are already configured in the project.
For full details, see the Translations page.
neo-ui translations keys#
Lists all translation keys available in the Project Neo host application. Must be run from within a project directory.
neo-ui translations keys
To filter by keyword, use the --search flag:
neo-ui translations keys --search chat
Use this command to discover keys that your bundle can override. Keys are printed in namespace:dotted.path format, which is the same format used in your translation JSON files.
Example output:
chat:welcome.inputPlaceholder
chat:welcome.title
common:actions.save
common:actions.cancel
...
247 keys listed.
neo-ui translations add-locale#
Adds a new locale to your bundle, on top of the four built-in languages (en, de, fr, and it). Must be run from within a project directory, after neo-ui translations init.
neo-ui translations add-locale # Interactive prompts
neo-ui translations add-locale es # Specify the locale code
neo-ui translations add-locale pt-BR --label "Português (Brasil)"
Arguments
[code]The locale code, for example
esorpt-BR. Must match the patternxxorxx-YYand cannot be one of the four built-ins. Prompted for if omitted.--label <name>The display name shown in the host language selector, for example
Español. Defaults to the code if omitted.
The command copies src/translations/en.json to src/translations/<code>.json as your starting point to translate, and wires the locale into src/manifest.ts. Re-running the command for an already-configured locale makes no changes.
For full details, see the Translations page.