Client CLI

The Client CLI (@yuuvis/client-cli) is a command-line tool for scaffolding, generating, and maintaining client projects. It automates the repetitive setup work that comes with Angular-based shell development — from creating a fully configured client project in a single command, to generating apps and widgets with the correct structure and wiring, to applying patches that keep existing projects aligned with the latest conventions.

The CLI is the recommended starting point for any new yuuvis shell client project.

Installation

Install the CLI globally so the yuv command is available in any project:

npm install -g @yuuvis/client-cli

Verify the installation:

yuv --help

To update the CLI, always install the latest version within the major that matches your Angular version:

# Angular 19 project
npm install -g @yuuvis/client-cli@19

# Angular 18 project
npm install -g @yuuvis/client-cli@18

Note

The CLI version is synchronized with Angular. Use CLI v19 for Angular 19 projects and @yuuvis/client-shell v2+. See Version Compatibility for the full matrix.

Best Practice

Always use the latest available version within the major that matches your Angular project.

Run npm install -g @yuuvis/client-cli@19 regularly to pick up the latest patches and schematic improvements. Jumping to a higher major (e.g., from v18 to v19) requires a full Angular upgrade first.

Commands

All commands follow the structure yuv <command> [subcommand] <argument> [options]. Most commands support short aliases for faster use in the terminal.

yuv new — Create a client project

Creates a new yuuvis client project with all required dependencies, build scripts, and configuration pre-wired.

yuv new <project-name> [options]

If --shell-version is not provided, the CLI prompts interactively.

Options

Option	Type	Description
--shell-version	string	Shell version to install (default: latest)
--skip-git	boolean	Skip initializing a git repository
--skip-install	boolean	Skip running npm install
--skip-tests	boolean	Skip generating spec.ts test files

Example

yuv new my-client
yuv new my-client --shell-version 2.6.0 --skip-tests

What gets generated

• Angular standalone application with SCSS
• All yuuvis shell libraries pre-installed (@yuuvis/client-core, @yuuvis/client-shell-core, @yuuvis/client-framework, @yuuvis/client-shell, @yuuvis/material)
• Monaco editor and the media viewer assets configured
• npm scripts for i18n, component metadata extraction, and shell updates
• Git repository initialized

yuv generate — Generate code

Generates Angular code artifacts within an existing client workspace. Use yuv generate app to scaffold a new app with all required wiring, or yuv generate widget to add a widget component to an existing app.

yuv generate app

Generates a new app within the client workspace — including the UI component, routing, and an extension layer that registers services with the shell.

yuv generate app <name> [options]
yuv g a <name> [options]         # short alias

If --app-id, --route, --prefix, --app-header, or --hide-from-nav are not provided, the CLI prompts interactively.

Options

Option	Type	Description
--app-id	string	Unique app identifier in reverse-domain notation (e.g. com.example.myapp)
--route	string	Route path under which the app is registered in the client
--prefix	string	Selector prefix for generated components (default: lib)
--app-header	boolean	Use the shell’s app header layout
--hide-from-nav	boolean	Hide the app icon from the navigation bar
--skip-extension	boolean	Skip generating the extension layer

Example

yuv generate app @mycompany/document-viewer --app-id com.mycompany.docviewer
yuv g a @mycompany/document-viewer --app-id com.mycompany.docviewer --skip-extension

What gets generated

• Angular library structure under projects/
• App manifest (yuv-manifest.json) with id, title, and UI configuration
• UI component with routing
• Extension layer with service registration (unless --skip-extension)
• Path mappings added to tsconfig.json
• App routes registered in app.routes.ts
• Extension registered in app.config.ts

Best Practice

Use scoped package names for apps (e.g. @mycompany/my-app) to avoid naming conflicts, and define app IDs in reverse-domain notation (e.g. com.mycompany.myapp) to ensure uniqueness across projects.

yuv generate widget

Generates a widget component for use in the widget grid framework.

yuv generate widget <name> [options]
yuv g w <name> [options]         # short alias

Options

Option	Type	Description
--generate-setup-component / --gsc	boolean	Also generate a setup component for widget configuration UI
--path	string	Path where the widget component should be created
--project	string	Target project (auto-detected from current directory if omitted)
--prefix	string	Selector prefix for the generated component

Example

yuv generate widget my-chart
yuv g w my-chart --gsc              # include setup component
yuv g w widgets/my-chart --gsc      # place in specific path

Note

Use --gsc whenever the widget requires user-configurable settings. The setup component provides the configuration UI that appears when a user adds the widget to a dashboard.

yuv add app — Add an existing app

Integrates a published app package from npm into the current client project. The CLI reads the app’s yuv-manifest.json, registers its routes and extensions automatically, and installs the package as a dependency.

yuv add app <package-name>
yuv a a <package-name>        # short alias

Example

yuv add app @vendor/document-viewer
yuv add app @vendor/document-viewer@2.1.0

What happens

• Package is fetched from the npm registry
• yuv-manifest.json is read from the package to determine routes and extensions
• App routes are registered in app.routes.ts
• Extensions are registered in app.config.ts
• Package is installed via npm

Best Practice

Always pin a specific version when adding external apps to production clients (e.g. @vendor/document-viewer@2.1.0) to ensure reproducible builds.

yuv add language — Add a language

Adds a new language to the client project. The command updates package.json and the main configuration so that the full project is aware of the new language from that point on.

yuv add language <locale> [options]
yuv a l <locale> [options]     # short alias

Arguments

Argument	Description
locale	ISO 639-1 language code (lowercase letters and hyphens only, e.g. es, fr, pt-br)

Options

Option	Type	Description
--label	string	Display name of the language written in that language itself (e.g. Español, Français). Defaults to the locale code if omitted.

Example

yuv add language es --label Español
yuv add language fr --label Français

What happens

• Creates i18n-external/<locale>.json with an empty object {} — only if the file does not yet exist.
• Adds the new locale to the --lang= argument of the i18n:extract script in package.json.
• Adds a new language entry to core.languages in src/assets/_yuuvis/config/main.json.

After the command completes, run the following to populate translation keys and merge all sources:

npm run i18n:extract && npm run i18n:collect

i18n:extract writes empty-valued keys for the new locale into every local src/assets/i18n/ folder. i18n:collect then picks up the external library translations for the new locale and merges everything into the final src/assets/_yuuvis/i18n/<locale>.json runtime file.

Caution

After running i18n:collect, the new language file at src/assets/_yuuvis/i18n/<locale>.json will contain all keys, but translation values will be empty strings wherever a translation does not yet exist. Fill in the missing translations before enabling the language in production.

yuv patch — Manage patches

Patches are targeted updates that extend or migrate existing client projects. They add missing configuration, scripts, or files that were introduced in newer shell versions or that a project may not yet have. Each patch checks its own preconditions before running and will not apply if it has already been applied or is not relevant for the current project.

yuv patch list

Lists all available patches with their ID, name, and description.

yuv patch list
yuv patch list <id>     # show details for a specific patch
yuv p l                 # short alias

Example output

┌───────┬───────────────────┬──────────────────────────────────────────────────┐
│ ID    │ Name              │ Description                                      │
├───────┼───────────────────┼──────────────────────────────────────────────────┤
│ p0001 │ component-data    │ Adds a script for extracting component metadata  │
│ p0002 │ mv2-migration     │ Updates angular.json for media-viewer v2.0.0+    │
│ p0003 │ build-docker      │ Adds Dockerfile and nginx config for Docker      │
└───────┴───────────────────┴──────────────────────────────────────────────────┘

yuv patch apply

Applies a specific patch to the current client project. The CLI checks whether the patch is applicable before executing — it will not apply a patch that has already been applied or whose preconditions are not met.

yuv patch apply <patchId>
yuv p a <patchId>         # short alias

Example

yuv patch apply p0001

Generated Build Scripts

yuv new adds several npm scripts to package.json that cover common maintenance tasks:

Script	When it runs	Description
prestart	Before npm start	Collects i18n translations before starting the dev server
prebuild	Before npm run build	Extracts client version and component metadata before every build
i18n:collect	Manual	Collects translation strings from all source files into the i18n assets
i18n:extract	Manual	Extracts translation keys for localization workflows
update:shell	Manual	Updates all yuuvis shell library dependencies to a specified version

Example: updating the shell

npm run update:shell -- 2.6.0

Typical Workflows

Set up a new client project

yuv new my-client
cd my-client
npm start

Create and develop a new app

# Generate the app scaffold
yuv generate app @mycompany/my-app --app-id com.mycompany.myapp

# Develop in the app library
# projects/mycompany/my-app/...

# Build and test
npm run build
npm test

Integrate a published app from npm

yuv add app @vendor/document-viewer@2.1.0
npm start    # app is registered and available immediately

Add a new language

yuv add language es --label Español
npm run i18n:extract && npm run i18n:collect
# Translate empty values in src/assets/_yuuvis/i18n/es.json

Keep a project up to date

# Update shell libraries to a new version
npm run update:shell -- 2.6.0

# Check for applicable patches
yuv patch list

# Apply a patch
yuv patch apply p0001

Best Practices

Follow these conventions to keep client projects maintainable and portable across teams.

Best Practices

• When generating an app, use scoped package names (e.g. @mycompany/my-app) and reverse-domain app IDs (e.g. com.mycompany.myapp) to prevent naming conflicts across projects and teams.
• When adding external apps with yuv add app, always pin a specific version (e.g. @vendor/app@2.1.0) to ensure reproducible builds and avoid unexpected breaking changes.
• Run yuv patch list after updating the shell version to check whether any patches need to be applied. Patches are incremental — apply them in order when multiple are available.
• Use --gsc when generating widgets that require user configuration. Adding a setup component later requires manual wiring; generating it upfront is significantly easier.
• When adding a language with yuv add language, always provide --label with the display name written in the language itself (e.g. --label Español). This label is shown in the language selector UI.
• Keep the CLI up to date by installing the latest version within the major that matches your Angular version (e.g., npm install -g @yuuvis/client-cli@19 for Angular 19 projects).

Version Compatibility

The CLI follows a synchronized versioning strategy with Angular. Each major CLI version supports the corresponding Angular version and a specific major version of @yuuvis/client-shell.

CLI version	Angular version	@yuuvis/client-shell
v18	Angular 18	v1.x
v19	Angular 19	v2.x

Install the CLI version that matches both your Angular version and the required shell version.