CLI Reference

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, or neo-ui --version (short form -v) to print the installed CLI version. The version is written to standard output as plain text, without the CLI banner, so it is safe to read from a script.

Non-Interactive Use#

The commands that ask questions are create bundle, create dashboard, remove dashboard, config, translations add-locale, and upgrade when it needs confirmation for a downgrade. Each one checks for an attached terminal before it prompts, and in a session without one, such as a CI job, it exits with an error naming the flags or environment variables to pass instead.

neo-ui deploy is the exception. Without a terminal and without --project, it uploads the bundle but does not activate it, and reports that you have to set the frontend.ui-bundle project configuration yourself. Pass --project <id> to upload and activate in a single step.

neo-ui deploy, neo-ui projects, neo-ui groups, and neo-ui doctor accept --json. In that mode the CLI omits the banner and writes machine-readable output to standard output, including when the command fails. Parse that output instead of the human-readable progress messages.

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 `https://` or `http://`.
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.ts with an empty dashboards array.
src/dashboards/ directory for your components.
.env with your API credentials.
All dependencies installed, including @squirro/nextgen-core and @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
`<name>` or `--name`	Prompted	Dashboard name displayed in the sidebar.
`--route`	Kebab-case of name	URL segment, for example `analytics`.
`--icon`	`layout-dashboard`	Lucide icon name from lucide.dev/icons. Use the kebab-case name shown there.
`--groups`	Visible to everyone	Comma-separated list of user groups allowed to see the dashboard, written to the `allowedGroups` field of the manifest entry. To list the groups on your instance, run `neo-ui groups`.

Pass --name, --route, and --icon together to create a dashboard in a session without a terminal. The name is the only value with no default, so omitting it in such a session is reported as an error.

Unless --groups is given, a terminal session with valid instance credentials in .env also asks which groups may see the dashboard. Select none to leave the dashboard visible to everyone. Values passed with --groups are checked against the instance before the dashboard is created. A value that matches no group produces a warning and the dashboard is still created, because the token in use may not see every group.

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#

Removes a dashboard from the project. Must be run from within a project directory. Run it with no arguments to select the dashboard from a list, or name the dashboard with a selector flag.

neo-ui remove dashboard                        # Select from a list, then confirm
neo-ui remove dashboard --route analytics      # Select by route, then confirm
neo-ui remove dashboard --route analytics -y   # Select by route, no confirmation

Flags

Flag	Description
`--route <route>`	Select the dashboard by its route segment.
`--id <id>`	Select the dashboard by its manifest ID.
`--name <name>`	Select the dashboard by its display title.
`--yes`, `-y`	Skip the confirmation prompt.

When several selector flags are given, the dashboard has to match all of them. If no dashboard matches, the command reports the unmatched selector and makes no changes.

Without a terminal, you have to pass both a selector and --yes. Otherwise the command exits with an error, so that no file is ever deleted without an explicit instruction.

The list is built from the dashboards found in src/manifest.ts. Once the dashboard is selected and the removal is confirmed, the command:

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
`--port <n>`	Use a specific bundle dev server port.
`--proxy-port <n>`	Use a specific dev proxy port.
`--persist`	Save the resolved ports to `.env` for next time.

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#

Checks the project, then builds the bundle for production deployment. Must be run from within a project directory.

neo-ui build               # Run the preflight checks, then build
neo-ui build --no-verify   # Build without the preflight checks

Preflight checks

The preflight runs before the build and stops it when a blocking check fails. The blocking checks cover hardcoded secrets, access tokens embedded in URLs, stray CSS imports, biome lint errors, and TypeScript type errors.

The remaining findings are reported as warnings and do not stop the build. Those cover practices worth a second look rather than a hard failure, such as sample data left in the bundle or @squirro packages installed from a local path. Each finding names the file, the line, and the suggested fix.

To keep a false positive from blocking the build, add a // neo-guard-ignore: <reason> comment to the reported line. The comment is honored by the content checks, but not by biome, the TypeScript compiler, or the check for locally installed @squirro packages.

Use --no-verify for fast local iteration only. It skips the preflight and prints a warning that the bundle is unverified. The flag exists on neo-ui build alone. neo-ui deploy always runs the preflight and rejects the flag, so a bundle that skipped the checks is still verified before it reaches an instance.

After the checks pass, the command 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
`--next`	Upgrade to the latest pre-release channel instead of the latest stable release.
`--dry-run`	Preview the changes without writing to the project.
`<version>`	Pin an exact version to install, for example `0.3.0`.

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
`--no-build`	Skip the build step and deploy the existing `dist/`.
`--dry-run`	Run preflight and list available projects without uploading.
`--project <id>`	Skip the interactive picker and use a known project ID.
`--force`	Override an incompatible compatibility verdict.
`--json`	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.

The preflight covers the credentials, the host version, the bundle size, and the version-compatibility verdict, and it repeats the content checks described under neo-ui build. Those checks cannot be skipped on a deploy. The --no-verify flag of neo-ui build is rejected here, and @squirro packages installed from a local path block the deploy instead of only warning, because a bundle built against local packages must not reach an instance.

Once the deploy finishes, the command prints a receipt with the bundle name and version, the instance, the project, the compatibility verdict, and any non-blocking preflight warnings. The same receipt is appended to a deploys.log file in the project directory.

With --json, the receipt is written to standard output as a single object. When the deploy fails, the command writes a structured error object instead, with a timestamp field, an error field, and the instance and tenant fields once those are resolved. Every exit is therefore machine-readable.

Tip

Run neo-ui deploy --dry-run first to see the available projects and the compatibility verdict without uploading anything.

neo-ui projects#

Lists the projects on the Squirro instance configured in .env, using the SQUIRRO_API_URL and SQUIRRO_TOKEN values. Read-only. Must be run from within a project directory.

neo-ui projects          # Readable list of project titles and IDs
neo-ui projects --json   # Machine-readable output on stdout

With --json, the command writes an object with the instance, tenant, and projects fields, where each project has an id and a title.

Use this command to obtain the project ID for neo-ui deploy --project <id>, which activates a bundle without the interactive picker.

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
`--fix`	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.
`--json`	Print the results as machine-readable output. In this mode `--fix` is ignored and the command is report-only.
`--offline`	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 groups#

Lists the user groups of the Squirro instance configured in .env, with the name and ID of each group. Read-only. Must be run from within a project directory.

neo-ui groups          # Group names and IDs, sorted by name
neo-ui groups --json   # Machine-readable output on stdout

With --json, the command writes an array of objects, each with a name and an id field.

Use the output to set the allowedGroups field of a dashboard in src/manifest.ts, or to pass --groups to neo-ui create dashboard, without guessing a group name.

The listed groups are the ones defined for the whole instance in the Server space, not the roles a user holds in a project. For more information about groups, roles, and permissions, see the Squirro Roles & Permissions page.

The command needs administrator or project owner credentials. With any other token, the request for the group list is refused and the command reports the error.

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 creates de, fr, and it).
src/translations/use-translation.ts: typed useExtTranslation() 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 es or pt-BR. Must match the pattern xx or xx-YY and 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.

CLI Reference

Contents

CLI Reference#

Non-Interactive Use#

neo-ui create bundle#

neo-ui create dashboard#

neo-ui remove dashboard#

neo-ui dev#

neo-ui build#

neo-ui upgrade#

neo-ui deploy#

neo-ui projects#

neo-ui catalog#

neo-ui doctor#

neo-ui config#

neo-ui info#

neo-ui groups#

neo-ui translations init#

neo-ui translations keys#

neo-ui translations add-locale#