Overview

The KOS UI CLI (kosui) is a command-line tool designed to streamline the development of KOS UI applications. It provides a comprehensive set of generators for creating various KOS components, models, projects, and more within Nx workspaces.

Installation & Usage

The CLI is available as @kosdev-code/kos-ui-cli and can be invoked using the kosui command.

Installation

It’s recommended to install the CLI globally for system-wide access:

npm install -g @kosdev-code/kos-ui-cli

Once installed globally, you can use the kosui command from any directory.

Basic Usage

kosui <generator> [options]

Global Options

• --no-cache – Disable cache
• --refresh – Clear cache and refresh
• --interactive, -i – Force interactive mode (ignore provided arguments)
• --help – Show help information

Help Commands

kosui help                    # Show all available generators
kosui <generator> --help      # Show generator-specific help

Quick Command Reference

Available Generators

1. Workspace Generator

Command: kosui workspace

Creates a new KOS UI workspace, which is a monorepo structure based on Nx that’s optimized for KOS UI development.

What is a KOS UI Workspace?

A KOS UI workspace is a specialized Nx monorepo that provides:

• Organized Project Structure – Separate projects for models, UI components, plugins, themes, and internationalization
• Optimized Build Configuration – Pre-configured build pipelines tailored for KOS UI applications
• Shared Dependencies – Efficient dependency management across all projects in the workspace
• Code Generation Support – Full integration with all KOS UI CLI generators
• Development Tooling – Pre-configured linting, testing, and formatting rules
• Scalability – Designed to grow from small applications to large enterprise systems

The workspace structure enables teams to:

• Share code and models across multiple KOS UI applications
• Maintain consistent coding standards and practices
• Build and deploy multiple related applications efficiently
• Leverage Nx’s powerful caching and incremental builds

Options:

• --workspaceName – Name of the workspace

Example:

kosui workspace --workspaceName my-workspace

Once created, all other generators should be run from within this workspace directory.

2. Model Generators

Models are the core data structures in KOS UI applications. They define the shape of your data, business logic, and how different parts of your application interact.

2.1 KOS Model

Command: kosui model

Creates a new KOS Model, which is the fundamental building block for data management in KOS UI applications.

Why Use This:

• Define strongly-typed data structures for your application
• Automatically generate TypeScript interfaces and validation
• Create reusable business logic that can be shared across components
• Enable data persistence and synchronization capabilities

Options:

• --modelName – Name of the model
• --modelProject – Target project for the model
• --container – Requires container model (boolean) – Use when this model needs a parent container
• --parentAware – Aware of parent container (boolean) – Enables access to parent model context
• --singleton – Is singleton (boolean) – Ensures only one instance exists in the application
• --dataServices – Create data services (boolean, default: true) – Generates CRUD operations and API integration
• --futureAware – Include Future-aware capabilities (none/minimal/complete) – Enables async operations with Java Future pattern
• --dryRun – Perform a dry run

Examples:

# Simple model
kosui model --modelName user --modelProject shared-models
# Model with container and data services
kosui model --modelName user-profile --modelProject shared-models --container --dataServices
# Singleton model with Future support
kosui model --modelName app-config --modelProject core-models --singleton --futureAware minimal

2.2 Add Future to Model

Command: kosui add-future

Enhances an existing KOS Model with Future support, enabling asynchronous operations that integrate with Java backend services.

Why Use This:

• Retrofit existing models with async capabilities without rewriting
• Enable non-blocking operations for better UI performance
• Integrate with Java Future-based backend APIs
• Add progress tracking and cancellation support to long-running operations

Future Types Explained:

• Minimal – External access only; suitable for simple async data fetching
• Complete – Internal + external access; full async operation support with progress tracking

Options:

• --modelName – Name of the existing model
• --futureType – Type of Future support (minimal/complete)
• --updateServices – Update/create services file with Future operations

Example:

# Add basic async support
kosui add-future --modelName user --futureType minimal
# Add full async support with service updates
kosui add-future --modelName report-generator --futureType complete --updateServices

2.3 Container Model

Command: kosui container

Creates a KOS Container Model, which is designed to hold and manage collections of other models.

Why Use This:

• Manage parent-child relationships between models
• Create hierarchical data structures (e.g., folders containing files)
• Enable bulk operations on collections of models
• Provide centralized state management for related models
• Implement tree-like or nested data structures

Options:

• --modelName – Name of the container model
• --modelProject – Target project

Example:

# Create a container for managing user groups
kosui container --modelName user-group --modelProject shared-models
# Create a folder container for document management
kosui container --modelName document-folder --modelProject content-models

2.4 Companion Model

Command: kosui model:companion

Creates a KOS Companion Model, which extends an existing model with additional functionality without modifying the original.

Why Use This:

• Add domain-specific features to base models
• Extend third-party or system models safely
• Implement the decorator pattern for models
• Keep concerns separated while maintaining relationships
• Add computed properties or methods to existing models

Options:

• --modelName – Name of the companion model
• --modelProject – Target project
• --companionParent – Parent model for the companion

Example:

# Add UI-specific behavior to a data model
kosui model:companion --modelName user-ui-companion --modelProject ui-models --companionParent user
# Extend a system model with custom analytics
kosui model:companion --modelName analytics-companion --modelProject analytics-models --companionParent system-event

2.5 Model React Context

Command: kosui context

Creates a React Context for a KOS Model, enabling efficient state sharing across component trees.

Why Use This:

• Share model state across multiple components without prop drilling
• Implement the Provider pattern for model data
• Enable global access to frequently-used models
• Optimize React re-renders with context-based state management
• Create boundaries for model scope in your application

Options:

• --modelName – Name of the model
• --modelProject – Target project

Example:

# Create context for user authentication model
kosui context --modelName auth-user --modelProject auth-models
# Create context for application settings
kosui context --modelName app-settings --modelProject core-models

2.6 Model React Hook

Command: kosui hook

Creates a React Hook for a KOS Model, providing a convenient API for components to interact with model data.

Why Use This:

• Simplify model usage in React components
• Encapsulate model subscription and lifecycle management
• Provide type-safe access to model properties and methods
• Enable reactive updates when model data changes
• Follow React best practices with custom hooks

Options:

• --modelName – Name of the model
• --modelProject – Target project

Example:

# Create hook for user profile model
kosui hook --modelName user-profile --modelProject user-models
# Create hook for shopping cart model
kosui hook --modelName shopping-cart --modelProject ecommerce-models

3. Component Generators

3.1 KOS React Component

Command: kosui component

Creates a new KOS React Component that is fully integrated with the KOS Model observability framework.

Why Use This:

• Automatic Optimization – Components only re-render when consumed model properties change
• Fine-grained Reactivity – The observability framework tracks exactly which model properties your component uses
• Performance by Default – No need for manual memoization or optimization
• Type-safe Integration – Full TypeScript support for model consumption
• Best Practices Built-in – Follows KOS UI patterns and conventions automatically

How It Works:
The generated component uses KOS’s observability system to:

1. Track which model properties are accessed during render
2. Subscribe only to changes in those specific properties
3. Trigger re-renders only when relevant data changes
4. Automatically clean up subscriptions when components unmount

Options:

• --componentName – Name of the component
• --componentProject – Target project

Example:

# Create a user profile component
kosui component --componentName UserProfile --componentProject user-ui
# Create a dashboard component
kosui component --componentName Dashboard --componentProject analytics-ui

The generated component will include:

• Proper model integration setup
• TypeScript interfaces
• Observability hooks
• Example of consuming model data efficiently

3.2 KOS Dispenser Developer Kit (DDK) Plugin Generators

The KOS UI CLI provides specialized generators for creating UI plugins as part of the KOS Dispenser Developer Kit (DDK). These plugins enable developers to extend NCUI applications with custom functionality through a robust plugin infrastructure.

Available Plugin Extension Points:

kosui plugin:cui – Consumer UI (CUI) Configuration

Creates a CUI setup page for configuration and management of Consumer UIs on a dispenser.

Use Case: When you need to add custom configuration options for managing different CUI instances on dispensers.

kosui plugin:cui --name MyCUIConfig --registrationProject my-ddk-plugin

kosui plugin:setup – NCUI Setup Step

Generates a new step for the NCUI setup wizard, allowing custom configuration during initial system setup.

Use Case: Add custom initialization or configuration steps to the dispenser setup process.

kosui plugin:setup --name CustomSetupStep --registrationProject my-ddk-plugin

kosui plugin:utility – NCUI Utility

Creates a new utility plugin that appears in the NCUI utilities section.

Use Case: Add custom tools or utilities for system management, diagnostics, or specialized operations.

kosui plugin:utility --name DiagnosticTool --registrationProject my-ddk-plugin

kosui plugin:setting – Settings Page

Adds a new settings page to the NCUI settings interface.

Use Case: Provide configuration options for your plugin or system features.

kosui plugin:setting --name AdvancedSettings --registrationProject my-ddk-plugin --group system

kosui plugin:nav – Navigation Routes

Adds generic navigation routes and associated content to the NCUI application.

Use Case: Create new sections or pages in the NCUI with custom navigation entries.

kosui plugin:nav --name ReportsSection --registrationProject my-ddk-plugin

kosui plugin:cp – Controlled Pour Plugin

Creates a Controlled Pour plugin for use with compatible Consumer UIs.

Use Case: Implement custom pour control logic or UI for specific dispensing scenarios.

kosui plugin:cp --name PrecisionPour --registrationProject my-ddk-plugin

How DDK Plugins Work:

• Plugins are dynamically loaded by host applications (like kos-ddk-app)
• Each plugin type has specific integration points in the NCUI
• The plugin infrastructure handles registration, loading, and lifecycle management
• Plugins can share models and services with the host application

Testing Your Plugins:
Each plugin generator automatically creates a Storybook test harness, allowing you to:

• Develop and test plugins in isolation from the host NCUI application
• Iterate quickly without needing a full dispenser environment
• Test different states and configurations
• Ensure your plugin works correctly before integration

To run the Storybook test harness:

npm run storybook

Note: The pluginComponent generator is available for basic plugin components, but the specific extension point generators above are recommended for DDK development.

4. API Type Generation

4.1 OpenAPI Type Generator

Command: kosui api:generate

Generates TypeScript type definitions and service wrappers from OpenAPI specifications for type-safe device API integration.

Why Use This:

• Eliminate manual interface creation for device APIs
• Get full TypeScript IntelliSense for all endpoints and parameters
• Automatically generate typed service functions with error-first tuple pattern
• Filter by app namespace to generate only what you need
• Support multiple API versions in the same project

Options:

• --project – Target project name (required)
• --host – API host URL (default: inherited from project.json or http://127.0.0.1:8081)
• --apps – Comma-separated app filters (e.g., ‘kos,dispense’)
• --output – Output path relative to sourceRoot (default: ‘utils’)
• --default-version – Default version for service exports
• --all-apps-version – Override all apps to use specific version
• --alias – Custom export aliases as JSON
• --app-version – Custom versions per app as JSON

Examples:

# Basic generation
kosui api:generate --project my-device-models
# Filter by specific apps
kosui api:generate --project my-models --host http://device.local:8081 --apps kos,dispense
# Multiple API versions
kosui api:generate --project my-models --app-version '{"kos":"v2","dispense":"v1"}'

Generated Files:

• utils/services/{app}/{version}/openapi.d.ts – TypeScript type definitions
• utils/services/{app}/{version}/service.ts – Typed service wrappers
• utils/openapi-index.ts – Aggregated type exports
• utils/services-index.ts – Aggregated service exports

Note: Core SDK services (kos, vfs, dispense, freestyle, handle, kosdev.ddk) are automatically excluded for third-party projects since they’re provided by published SDKs.

5. Project Generators

4.1 KOS UI App Project

Command: kosui project

Creates a new KOS UI application within your workspace. This generator is essential for building multi-UI architectures where different user interfaces serve different purposes or user types.

Why Use This:

• Multi-UI Architecture – Build separate UIs for different user experiences (e.g., NCUI for operators, CUI for consumers)
• Use Case Separation – Create distinct applications for different scenarios (e.g., Crew Serve vs Self Serve CUIs)
• Shared Resources – All UI apps in the workspace can share models, components, and services
• Independent Deployment – Each UI app can be built and deployed separately
• Consistent Foundation – All apps start with the same KOS UI architecture and best practices

Common Scenarios:

• NCUI + CUI Setup – Administrative interface alongside consumer-facing interface
• Multiple CUI Variants – Different consumer experiences for different contexts:
  • Crew Serve CUI – Optimized for operator-assisted dispensing
  • Self Serve CUI – Simplified interface for consumer self-service
  • Kiosk CUI – Touch-optimized for standalone kiosks
• Brand-Specific UIs – Different UI applications for different brands or customers

Options:

• --name – Name of the project

Example:

# Create an NCUI application
kosui project --name dispenser-ncui
# Create a crew-serve CUI
kosui project --name crew-serve-cui
# Create a self-serve CUI
kosui project --name self-serve-cui

Each generated project includes:

• Full React application setup
• KOS UI framework integration
• Routing and navigation
• Model integration capabilities
• Build and development scripts

4.2 Plugin Project

Command: kosui plugin

Creates a KOS Plugin Project that serves as a container for plugin components. Each plugin project can be independently packaged into a KOS artifact for deployment to plugin-aware host UI applications.

Why Use This:

• Independent Packaging – Each plugin project becomes a deployable KOS artifact
• Plugin Organization – Groups related plugin functionality together
• Deployment Flexibility – Deploy plugins separately from host applications
• Version Management – Version and update plugins independently
• Host UI Integration – Works seamlessly with the KOS UI Plugin infrastructure

How It Works:

• The plugin project acts as a target for generated plugin components (CUI, setup, utility, etc.)
• Once built, the project produces a KOS artifact that can be deployed
• Plugin-aware host UIs (like NCUI applications) use the KOS core plugin infrastructure to:
  • Discover available plugin artifacts
  • Load plugins dynamically
  • Present plugin functionality to users
• Multiple plugin projects can be deployed and consumed by a single host application

Common Use Cases:

• Feature Extensions – Add new capabilities to existing NCUI deployments
• Customer Customizations – Create customer-specific plugins without modifying core applications
• Modular Deployment – Deploy only the plugins needed for specific installations
• Third-party Integration – Package integrations as plugins

Options:

• --name – Name of the plugin project

Example:

# Create a plugin project for custom utilities
kosui plugin --name custom-utilities-plugin
# Create a plugin project for brand-specific features
kosui plugin --name brand-x-plugin
# Create a plugin project for integration features
kosui plugin --name payment-integration-plugin

After creating a plugin project, use the DDK plugin generators (plugin:cui, plugin:setup, etc.) to add functionality to it.

4.3 Theme Project

Command: kosui theme

Creates a KOS Theme Project that produces an artifact for overlaying custom theme configurations onto DDK applications. The DDK’s extensive design token system enables complete visual customization without modifying application code.

Why Use This:

• Brand Customization – Create unique visual experiences for different brands or customers
• White-labeling – Enable partners to apply their own branding to DDK applications
• Consistent Design Language – Maintain design consistency across all UI components
• Non-invasive Theming – Change appearance without touching application logic
• Multiple Theme Support – Deploy different themes for different contexts or customers

Design Token System:
The DDK uses a hierarchical design token system that can be customized at multiple levels:

1. Generic Tokens – Base-level tokens (colors, spacing, typography)
   • Primary colors, secondary colors, neutrals
   • Font families, sizes, weights
   • Spacing units, border radius values
2. Semantic Tokens – Purpose-driven tokens that reference generic tokens
   • Background colors (surface, overlay, etc.)
   • Text colors (primary, secondary, disabled)
   • Interactive states (hover, active, focus)
3. Component Tokens – Component-specific tokens for fine-grained control
   • Button backgrounds, borders, text
   • Card shadows, spacing
   • Navigation colors and states

Options:

• --name – Name of the theme project

Example:

# Create a theme for a specific brand
kosui theme --name coca-cola-theme
# Create a dark mode theme
kosui theme --name dark-mode-theme
# Create a high-contrast accessibility theme
kosui theme --name high-contrast-theme

The generated theme project includes:

• Default token definitions you can override
• Build system for packaging themes
• Preview capabilities to test your theme
• Documentation of all available tokens

4.4 Content Project

Command: kosui content

Creates a KOS Content Project for creating KAB (Kos Asset Bundle) generation projects. These projects are designed to bundle and deploy static content assets like images, videos, audio files, and other media resources.

Why Use This:

• Asset Management – Organize and deploy content assets efficiently
• KAB Generation – Creates projects optimized for Kos Asset Bundle (KAB) creation
• Static Content – Purpose-built for managing static content separate from application logic
• Build Pipeline – Includes optimized build targets for asset bundling and compression
• Independent Deployment – Deploy content bundles separately from applications

How It Works:

• Creates a project structure with an assets/ directory for content files
• Configures Vite with publicDir: "assets" for proper asset handling
• Includes KAB and zip build targets for asset bundling
• Generates projects in the packages/content/ directory
• Uses the NX React library generator as a foundation

Common Use Cases:

• Media Libraries – Bundle images, videos, and audio for applications
• Branding Assets – Package brand-specific imagery and media
• Localized Content – Create region-specific asset bundles
• Seasonal Content – Deploy temporary or seasonal assets
• White-label Assets – Different asset bundles for different partners

Options:

• --name – Name of the content project

Example:

# Create a content project for brand assets
kosui content --name brand-assets
# Create a content project for seasonal imagery
kosui content --name holiday-content
# Create a content project for product media
kosui content --name product-media

The generated project includes:

• assets/ directory with .gitkeep file for content placement
• Vite configuration with publicDir: "assets"
• KAB build target for asset bundle generation
• Zip build target for compression
• Standard build pipeline for processing assets

4.5 Splash Screen Project

Command: kosui project:splash

Creates a KOS Splash Screen Project with an optimized build pipeline that produces a KOS layer artifact for customizing device splash screens.

Why Use This:

• White-label Experiences – Enable partners and customers to display their own branding at device startup
• First Impressions – Customize the initial user experience when the device boots
• Brand Consistency – Ensure branding is present from the moment the device powers on
• Layer Architecture – Deploys as a KOS layer that overlays the default splash screen
• Simple Deployment – Package and deploy splash screens independently from applications

How It Works:

• The project includes an optimized build pipeline specifically for splash screen assets
• Builds into a KOS layer artifact that can be deployed to devices
• The layer system allows splash screen customization without modifying the base system
• Supports various image formats and resolutions for different display types

Common Use Cases:

• Brand-specific Deployments – Different splash screens for different customers
• Seasonal Updates – Change splash screens for promotions or seasons
• Multi-tenant Systems – Different splash screens based on location or operator
• Partner Branding – Allow partners to apply their branding to devices

Options:

• --name – Name of the splash screen project

Example:

# Create a splash screen for a specific brand
kosui project:splash --name starbucks-splash
# Create a seasonal splash screen
kosui project:splash --name holiday-splash
# Create a partner splash screen
kosui project:splash --name partner-splash

The generated project includes:

• Asset pipeline for image optimization
• Build configuration for KOS layer creation
• Templates for common splash screen layouts
• Guidelines for image dimensions and formats

5. Internationalization (i18n)

5.1 Localization Project

Command: kosui i18n

Creates a KOS Localization Project that generates translation bundles compatible with the KOS translation service. These projects live independently from UI applications, enabling flexible localization management.

Why Use This:

• Independent Translation Management – Add new languages without modifying UI applications
• Centralized Localization – Manage all translations in one place for multiple UI projects
• Dynamic Language Support – Deploy new locales without rebuilding applications
• Translation Service Integration – Works seamlessly with the KOS translation service
• Modular Deployment – Deploy only the language bundles needed for specific regions

How It Works:

• The i18n project creates translation bundles that are consumed by the KOS i18n framework
• Supports layered namespaces for organizing translations by feature or component
• Translation bundles can be deployed independently and loaded dynamically
• Multiple i18n projects can be combined to provide complete localization
• The KOS translation service automatically discovers and loads available bundles

Key Features:

• Namespace Organization – Group translations logically (e.g., common, errors, products)
• Inheritance Support – Base translations can be extended or overridden
• Fallback Chains – Automatic fallback to default language for missing translations
• Hot Reload – Update translations without restarting applications
• Format Support – Compatible with standard i18n formats (JSON, YAML)

Common Use Cases:

• Multi-region Deployments – Different language packs for different markets
• Partner Customization – Custom terminology for specific partners
• Gradual Rollout – Add new languages incrementally
• A/B Testing – Test different translations without code changes

Options:

• --name – Name of the i18n project

Example:

# Create a project for European languages
kosui i18n --name european-languages
# Create a project for Asian languages
kosui i18n --name asian-languages
# Create a project for custom partner terminology
kosui i18n --name partner-terminology

The generated project includes:

• Namespace structure for organizing translations
• Build pipeline for creating translation bundles
• Validation tools for checking translation completeness
• Integration with KOS translation service

5.2 i18n Namespace

Command: kosui i18n:namespace

Creates a KOS i18n Project Namespace.

Options:

• --project – Target project
• --locale – Locale code (e.g., ‘en’, ‘es’)

Example:

kosui i18n:namespace --project my-i18n --locale en

6. Development Commands

6.1 Development Server

Command: kosui dev

The kosui dev command provides a metadata-driven development workflow that automatically manages multiple dev servers based on configuration in .kos.json. It replaces hardcoded shell scripts with a unified, data-driven approach that scales effortlessly as you add more plugins.

Why Use This:

• No More Hardcoded Scripts – Eliminate workspace-specific shell scripts (like ddk-dev.sh)
• Automatic Port Management – No more manual port conflict resolution
• Scalable – Add unlimited plugins without script modifications
• Dual-Mode Support – Internal AND third-party development from one configuration
• Cross-Workspace Consistency – Same workflow across all KOS projects
• Selective Plugin Loading – Start only the plugins you need for testing

How It Works:

1. Configuration lives in .kos.json – Host apps and plugins are registered with ports, aliases, and metadata
2. Automatic port assignment – When you create a plugin, it auto-registers and gets a port from the host’s range
3. Two development modes:
   • Internal Mode: Starts host + plugins (for teams with full source access)
   • Third-Party Mode: Starts plugins only (connect to deployed devices via query params)

Options:

• --host – Which host application to start (e.g., --host ddk-app)
• --plugins – Comma-separated plugin aliases to start (e.g., --plugins beverage,pos)
• --disable – Comma-separated plugin aliases to disable (e.g., --disable old-plugin)
• --plugins-only – Start plugins only (third-party mode)
• -i, --interactive – Force interactive mode

Examples:

# Interactive mode - prompts for host and plugin selection
kosui dev
# Start specific host with all enabled plugins
kosui dev --host ddk-app
# Start with specific plugins only
kosui dev --host ddk-app --plugins beverage,pos
# Disable specific plugins
kosui dev --host ddk-app --disable old-plugin
# Third-party mode (plugins only, no host)
kosui dev --host ddk-app --plugins-only
# Verbose logging
VERBOSE_PLUGIN_DEV=true kosui dev --host ddk-app

Development Modes:

Internal Development Mode (Default)

• Starts host app + plugin dev servers
• Server-side plugin aggregation via webpack middleware
• Hot module reloading for all plugins
• Access at host port (e.g., http://localhost:4200)

Third-Party Development Mode (--plugins-only)

• Starts only plugin dev servers
• For developing plugins without host source code
• Connect deployed devices via query parameters
• Useful for external developers or testing against production

Plugin Selection:

# Start all enabled plugins (default)
kosui dev --host my-app
# Start specific plugins
kosui dev --host my-app --plugins plugin-a,plugin-b
# Disable specific plugins
kosui dev --host my-app --disable old-plugin
# Combine filters
kosui dev --host my-app --plugins a,b,c --disable b

npm Script Integration:

Add to your workspace package.json:

{
  "scripts": {
    "dev": "kosui dev",
    "dev:verbose": "VERBOSE_PLUGIN_DEV=true kosui dev"
  }
}

Logs and Process Management:

• Logs stored in /tmp/kos-dev-logs/ by default
• Each server gets its own log file
• Override with DEV_LOG_DIR environment variable
• Press Ctrl+C to stop all servers gracefully
• Automatic health checks before proceeding

For More Information:

• Full usage guide: packages/plugins/kos-nx-plugin/docs/dev-script-usage.md
• Schema reference: packages/plugins/kos-nx-plugin/docs/kos-json-schema.md
• Migration guide: packages/plugins/kos-nx-plugin/docs/migration-to-data-driven.md

6.2 Serve Target

Command: kosui serve

Runs the serve target for a specific project.

Options:

• --project – Project to serve

Example:

kosui serve --project my-ui

6.3 KAB Packaging

Command: kosui kab

Runs the KAB packaging target for a project.

Options:

• --project – Project to package

Example:

kosui kab --project my-plugin

7. Environment & Cache

7.1 Environment Variables

Command: kosui env

Discovers and populates environment variables for KOS Studio and associated build utilities. This generator should be run immediately after creating a new workspace.

Why Use This:

• Automatic Discovery – Locates KOS Studio installation and build tools on your system
• Build Configuration – Sets up paths for creating KOS artifacts (kabs, etc.)
• User-specific Setup – Creates configuration specific to your development environment
• Workspace Initialization – Essential first step after workspace creation

What It Does:

• Scans your system for KOS Studio installation
• Locates associated utilities and build tools
• Creates a .env.local file with discovered paths
• Sets up environment for artifact creation and deployment

Important Notes:

• The .env.local file is specific to your machine and should NOT be committed to source control
• Each developer needs to run this command on their machine
• Re-run if you update or relocate KOS Studio

When to Run:

1. Immediately after kosui workspace when setting up a new workspace
2. When setting up the workspace on a new machine
3. After updating or reinstalling KOS Studio

Example:

# After creating a new workspace
kosui workspace --workspaceName my-workspace
cd my-workspace
kosui env
# The command will output something like:
# ✓ Found KOS Studio at: /opt/kos/studio
# ✓ Found build utilities at: /opt/kos/tools
# ✓ Created .env.local with environment configuration

The generated .env.local file includes:

• KOS_INSTALL_PATH – Path to KOS Studio installation
• JAVA_CMD – Path to Java binary
• Other build-related environment variables

7.2 Clear Cache

Command: kosui cache:clear

Clears the generator context cache.

Example:

kosui cache:clear

7.3 Version Information

Command: kosui version

Displays version information for the KOS UI CLI and SDK packages.

Example:

kosui version

Advanced Features

Non-Interactive Mode

The CLI supports non-interactive mode where all required parameters can be passed as command-line arguments:

# Create a model with all options specified
kosui model --modelName user-profile --modelProject shared-models --container --singleton --dataServices

Interactive Mode

Force interactive mode even when arguments are provided:

kosui model --modelName user-profile -i

Dry Run

Test commands without making actual changes:

kosui model --modelName test-model --modelProject my-lib --dryRun

Cache Management

The CLI includes an intelligent caching system to improve performance, especially in large monorepos. The cache stores:

• Available projects and their configurations
• Model definitions and metadata
• Workspace structure information

This caching significantly speeds up generator execution by avoiding repeated file system scans and project analysis.

When to Use Cache Options

--no-cache – Disable cache for a single command

• Use when you’ve made changes to project structure that the cache might not reflect
• Helpful when debugging generator issues
• Ensures you’re working with the absolute latest project state

--refresh – Clear cache before running the command

• Use after adding new projects or models to your workspace
• Recommended after pulling changes that affect project structure
• Ensures a fresh scan of your workspace while still benefiting from caching for future runs

kosui cache:clear – Manually clear all cache

• Use when experiencing persistent issues with outdated information
• Helpful after major refactoring or restructuring
• Provides a clean slate for the caching system

Examples

# After adding a new project to your workspace
kosui model --refresh --modelName user --modelProject new-project
# When debugging or troubleshooting
kosui component --no-cache --componentName Header --componentProject my-app
# Complete cache reset
kosui cache:clear

Architecture

Technology Stack

• Node.js – Runtime environment
• Nx – Monorepo management and build system

Key Features

1. Command Line Interface
   • Intuitive command structure
   • Comprehensive help system
   • Support for both interactive and non-interactive modes
2. Generator System
   • Wide variety of code generators
   • Consistent patterns across all generators
   • Workspace-aware generation
3. Smart Defaults
   • Intelligent project detection
   • Sensible configuration defaults
   • Context-aware prompts
4. Performance
   • Built-in caching system
   • Optimized for large monorepos
   • Fast execution times

Best Practices

1. Always work within an Nx workspace – Most generators require an Nx workspace context
2. Use dry run for testing – Test complex operations with --dryRun first
3. Leverage non-interactive mode – Automate repetitive tasks with command-line arguments
4. Clear cache when needed – If experiencing issues, try --refresh or cache:clear
5. Follow naming conventions – Use consistent naming for models, components, and projects

Troubleshooting

Common Issues

1. “Not inside an Nx workspace” error
   • Ensure you’re in a valid Nx workspace directory
   • Only the workspace generator works outside of Nx context
2. Generator not found
   • Check available generators with kosui help
   • Ensure you’re using the correct generator name
3. Cache-related issues
   • Clear cache with kosui cache:clear
   • Use --no-cache flag for one-time bypass
4. Missing dependencies
   • Ensure all npm dependencies are installed
   • Check that @kosdev-code/kos-nx-plugin is available

Integration with Development Workflow

The KOS UI CLI integrates seamlessly with:

• Nx Console – Visual interface for Nx commands
• Git – All generated files follow Git-friendly patterns
• VS Code – Full IntelliSense support for generated code
• CI/CD – Scriptable for automation pipelines

Future Enhancements

Planned features for future releases:

• Additional generator templates
• Enhanced validation and error handling
• Integration with KOS Studio
• Custom generator creation support
• Performance optimizations