# CLI Reference > **Warning** > > Project Neo is currently in [Technical Preview](../../../a-z/squirro-glossary.md#term-Technical-Preview). Features described in this section may change before general availability. All commands are invoked as `neo-ui `. 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 ` 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. ```bash 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/neo-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. ```bash 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 | | --- | --- | --- | | `` 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](https://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. ```bash 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 ` | Select the dashboard by its route segment. | | `--id ` | Select the dashboard by its manifest ID. | | `--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. ```bash 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 ` | Use a specific bundle dev server port. | | `--proxy-port ` | 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. ```bash 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: ` 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/`: ```text 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](build-and-deploy.md#neo-extensions-build-and-deploy) page. ## neo-ui upgrade Upgrades `@squirro/neo-core` and `@squirro/neo-ui` to a published version, and migrates a project off the legacy `nextgen` CLI and the pre-rename `@squirro/nextgen-core` package in the same step. Must be run from within a project directory. ```bash neo-ui upgrade # Upgrade to the latest stable release neo-ui upgrade --next # Upgrade to the latest pre-release neo-ui upgrade 3.17.1 # Pin an exact core 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. | | `` | Pin an exact core version to install, for example `3.17.1`. | 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 or the pre-rename `@squirro/nextgen-core` package, renaming the dependencies and rewriting every reference to the old core package: imports, the CSS `@import` and `@source` lines, the `extends` entries in `biome.json` and `tsconfig.json`, `rsbuild.config.ts`, `CLAUDE.md`, and the `NEXTGEN_CORE_VERSION` define, which becomes `NEO_CORE_VERSION`. It also rewrites the `package.json` scripts that call the old binary so they call `neo-ui` instead, and refreshes the Claude Code skills under `.claude/skills/` from the newly installed core package. The migration is idempotent. Running it again on an already-migrated project reports no changes. If `npm install` fails, `package.json` is restored to its previous state. Until the migration has run, `neo-ui dev`, `neo-ui build`, and `neo-ui translations keys` refuse to run in a bundle that has only `@squirro/nextgen-core` installed, so the two packages cannot be mixed by accident. For the full walkthrough, see the [Migrating from nextgen to neo-ui](migrating-from-nextgen.md#neo-extensions-migrating) page. > **Important** > > The command refuses to run while a project or user `.npmrc` still maps the `@squirro` scope to `npm.pkg.github.com`, because every lookup would be answered by the old registry. Run `neo-ui doctor --fix` to remove that line from the project `.npmrc`, and delete it from `~/.npmrc` yourself. > **Tip** > > The default upgrade targets the latest stable release. If your project tracks a pre-release line, pass `--next`. Otherwise the command may resolve an older stable release and offer to downgrade. 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. ```bash 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 # 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 ` | 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](build-and-deploy.md#neo-extensions-build-and-deploy) 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](#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. ```bash 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 `, 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](https://neo-catalog.squirro.com). It documents every component and widget a bundle can import from `@squirro/neo-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. ```bash 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](styling-and-components.md#neo-extensions-styling) 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. ```bash 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: removing a duplicate core package, installing a missing one, recreating a missing type shim, and deleting a stale GitHub Packages registry line from the project `.npmrc`. 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. | **Checks** The command reports on the `.env` file and its credentials, a stale GitHub Packages registry line in the project or user `.npmrc`, whether `@squirro/neo-core` is installed, its version drift and any duplicate copies, the version alignment between the core package and the CLI, React 19 or later, the `src/env.d.ts` type shim, and the validity of the refresh token. 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. ```bash 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. ```bash neo-ui info ``` Example output: ```text ┌──────────────────────────────────────────┐ │ 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. ```bash 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 creating and managing groups, see the [Managing User Groups](../../ui/user-groups.md#ui-user-groups) 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. ```bash 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](translations.md#neo-extensions-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. ```bash neo-ui translations keys ``` To filter by keyword, use the `--search` flag: ```bash 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: ```text 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`. ```bash 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 ` 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/.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](translations.md#neo-extensions-translations) page.