Getting Started – KOS CLI Installation and Workspace Setup

What You’ll Accomplish

Install the KOS CLI, create your first workspace, and run the default application connected to a KOS device.

Prerequisites

Before starting, ensure you have:

  • Node.js 20 or higher installed (node --version to check)
  • KOS Studio installed and running
  • A KOS device or simulator available and accessible

You don’t need deep knowledge of these tools—just have them installed and running.

Step 1: Install the KOS CLI

The KOS CLI is your primary tool for creating workspaces and generating code.

npm install -g @kosdev-code/kosui-cli

Why: Installing globally lets you run kosui commands from any directory.

[Screenshot: Terminal showing npm install output with successful installation message]

Verify it’s installed:

kosui --help

You should see a list of available commands like workspace, model, component, etc.

[Screenshot: Terminal showing kosui –help output with list of generators]

Tip: Any kosui command can be run with the -i or --interactive flag to launch an interactive session with prompts:

kosui workspace -i

This is helpful when you’re not sure what arguments a command needs or want to see all available options.

Step 2: Create Your Workspace

Create a new KOS workspace:

kosui workspace --name my-first-kos-app

Why: This generates a complete project structure with build tools, TypeScript configuration, and example projects already set up.

[Screenshot: Terminal showing workspace creation progress with Nx workspace generation messages]

The CLI creates:

  • An Nx monorepo structure
  • A UI application project
  • A models library project
  • Build and development scripts
  • TypeScript and linting configuration

Navigate into your new workspace:

cd my-first-kos-app

Step 3: Explore the Workspace Structure

Look at what was created:

ls -la

[Screenshot: Terminal showing directory listing with apps/, libs/, node_modules/, package.json, etc.]

Your workspace contains:

apps/my-first-kos-app-ui/ – The main UI application

  • src/app/ – Application components and registration
  • src/main.ts – Application entry point
  • webpack.config.ts – Build configuration

libs/my-first-kos-app-models/ – Model library

  • src/models/ – Where your models will live
  • src/index.ts – Public API exports

Root configuration files:

  • package.json – Dependencies and scripts
  • nx.json – Nx workspace configuration
  • tsconfig.base.json – TypeScript settings

[Screenshot: VS Code file explorer showing the workspace structure with apps/ and libs/ folders expanded to show the subfolders mentioned above]

Step 4: Configure Studio Environment

The kosui env command discovers your KOS Studio installation and sets up environment variables:

kosui env

Why: This automatically finds your Studio installation and Java paths, creating a .env.local file with the correct paths.

[Screenshot: Terminal showing kosui env output with discovered Studio and Java paths]

This creates .env.local at the workspace root:

cat .env.local

You should see:

#  Path to the Java binary
JAVA_CMD='/path/to/java'
#  Path to the kos installation
KOS_INSTALL_PATH='/path/to/KOS-Studio'

[Screenshot: Terminal showing cat .env.local output with the environment variables]

Step 5: Install Dependencies

Install the project dependencies:

npm install

Why: This downloads all the KOS SDK packages, React, build tools, and other dependencies your workspace needs.

[Screenshot: Terminal showing npm install progress and completion]

This may take a few minutes on first run.

Step 6: Start the Development Server

Start your application:

npx nx serve my-first-kos-app-ui

Why: The development server compiles your TypeScript code, bundles your application, and serves it with hot reload—changes you make will automatically appear in the browser.

[Screenshot: Terminal showing Webpack compilation progress and “webpack compiled successfully” message with the localhost:4200 URL]

The build process:

  1. Compiles TypeScript to JavaScript
  2. Bundles your application code
  3. Starts a local web server
  4. Watches for file changes

Step 7: Open Your Application

Open Chrome and navigate to:

http://localhost:4200?host=http://localhost:8081/#

Why: The host query parameter tells your app where to find the KOS device. Adjust localhost:8081 if your device uses a different address or port.

[Screenshot: Browser showing the default KOS application interface with the KOS logo and basic UI]

You should see the default KOS application interface.

Step 8: Open Developer Tools

Press F12 (or right-click and select “Inspect”) to open Chrome DevTools.

[Screenshot: Chrome DevTools docked at bottom of browser window]

Click the Console tab.

Why: The console shows log messages from your application, including KOS framework initialization and model lifecycle events.

[Screenshot: Chrome DevTools Console tab showing KOS framework initialization logs]

You should see messages indicating the KOS application has started and connected to the device.

Understanding the Architecture

Your new workspace follows KOS patterns:

Separation of concerns:

  • UI code lives in apps/ – presentation and user interaction
  • Model code lives in libs/ – business logic and device communication
  • Models are independent of UI and can be reused across multiple apps

NX monorepo:

  • Multiple projects in one repository
  • Shared dependencies and build configuration
  • Efficient builds that only rebuild what changed

Development workflow:

  • Hot reload during development
  • TypeScript for type safety
  • Webpack for bundling and optimization

What’s Running Now

The default application includes:

  • KOS framework initialization
  • Connection to your device via the host parameter
  • Basic UI structure with header and content area
  • Development tools integration

This gives you a working foundation to start adding your own models and UI components.

Next Steps

Now that you have a working workspace, you’re ready to:

  1. Create your first model – Learn the model lifecycle and see it execute
  2. Understand project architecture – Explore how apps and libs work together
  3. Add device communication – Connect models to real device APIs
  4. Build UI components – Create interfaces that display model data

Troubleshooting

npm install fails:

  • Ensure Node.js 20+ is installed: node --version
  • Clear npm cache: npm cache clean --force
  • Delete package-lock.json and try again

kosui env doesn’t find Studio:

  • Verify KOS Studio is installed
  • Check that Studio is in a standard installation location
  • Manually create .env.local with correct paths

Dev server won’t start:

  • Check if port 4200 is already in use
  • Try a different port: npx nx serve my-first-kos-app-ui --port=4300
  • Look for error messages in the terminal

App won’t connect to device:

  • Verify your device is running and accessible
  • Check the host query parameter in the URL matches your device address
  • Look for connection errors in the Network tab
  • Ensure no firewall is blocking the connection

Build errors:

  • Check the Problems panel in VS Code for TypeScript errors
  • Ensure all dependencies installed correctly
  • Try deleting node_modules and running npm install again

What You Learned

  • How to install the KOS CLI globally
  • How to create a KOS workspace with kosui workspace
  • How to configure Studio environment variables with kosui env
  • The structure of a KOS workspace (apps, libs, configuration)
  • How to start the development server with NX
  • How to connect your app to a KOS device using the host parameter
  • How to use Chrome DevTools to monitor your application

You now have a complete development environment ready for building KOS applications.

Next: Create your first model and watch it initialize through the console.
on