Generate New Application

The TelemetryOS CLI (@telemetryos/cli) is the recommended way to create new applications. It scaffolds a complete, production-ready application with modern tooling, best practices, and local development capabilities in seconds.

Why Use the CLI?

Speed and Efficiency

• Scaffold in seconds - Complete application structure with one command
• Zero configuration - Pre-configured build tools, TypeScript, and hot reload
• Best practices built-in - Follows TelemetryOS application patterns and conventions
• Instant feedback - Local development server simulates the platform environment

Developer Experience

• Modern stack - React, TypeScript, Vite for fast development and builds
• Type safety - Full TypeScript definitions for the SDK
• Hot module reload - See changes instantly without page refresh
• Familiar tools - Uses standard npm/yarn workflows you already know

Production Ready

• Proper structure - Mount points, configuration, and component organization
• SDK integration - Pre-configured with @telemetryos/sdk
• Development server - Test locally before deploying to devices
• Git ready - Initialized repository with sensible .gitignore

Installation

Install the CLI globally to use across all projects:

npm install -g @telemetryos/cli

Or use locally in a specific project:

npm install --save-dev @telemetryos/cli

Or use npx without installation:

npx @telemetryos/cli init my-app

Quick Start

Application Generation

The CLI generates complete application structures with one command:

tos init my-weather-app

Application generation creates:

• Project directory my-weather-app/ with complete structure
• React + TypeScript + Vite application scaffold
• telemetry.config.json with pre-configured mount points
• Render and settings components with example implementations
• Automatic dependency installation
• Git repository initialization

Development Server

The CLI development server provides local testing capabilities:

cd my-weather-app
tos serve

The development server:

• Reads telemetry.config.json for configuration
• Starts Vite development server
• Provides TelemetryOS platform simulation
• Opens development UI in browser
• Enables hot module replacement

Application Structure

CLI-generated applications include pre-configured components:

Render Component (src/render/)

• Main UI that displays on devices
• React + TypeScript setup
• SDK pre-configured and imported
• Example storage usage patterns

Settings Component (src/settings/)

• Configuration interface for Studio
• React form components
• Connected to instance storage
• Example settings implementation

Configuration (telemetry.config.json)

• Mount points pre-configured
• Development server settings
• Application metadata

Local Testing

The development server simulates the TelemetryOS environment:

• Storage API with persistence
• Message passing between components
• SDK method implementations
• Settings ↔ Render communication

Applications are accessible at http://localhost:5173 (or configured port).

Deployment

After local development, applications deploy to TelemetryOS:

• Code pushes to GitHub repository
• Application registration in Studio connects GitHub repository
• TelemetryOS builds and packages applications automatically
• Applications add to playlists and deploy to devices

CLI Commands

tos init

Create a new application from template.

tos init <app-name> [options]

Examples:

# Create with default template (React + TypeScript + Vite)
tos init my-app

# Specify custom template
tos init my-app --template react-basic

# Use current directory
tos init .

Options:

• --template <name> - Choose template (default: vite-react-typescript)
• --skip-install - Skip npm install step
• --skip-git - Skip git initialization

What's Created:

my-app/
├── src/
│   ├── render/           # Main display component
│   │   ├── index.tsx
│   │   └── App.tsx
│   ├── settings/         # Configuration UI
│   │   ├── index.tsx
│   │   └── Settings.tsx
│   └── shared/           # Shared code/types
├── public/               # Static assets
├── telemetry.config.json # TelemetryOS configuration
├── vite.config.ts        # Build configuration
├── tsconfig.json         # TypeScript config
├── package.json          # Dependencies
└── .gitignore            # Git ignore rules

tos serve

Start local development server with hot reload.

tos serve [options]

Examples:

# Start with defaults from telemetry.config.json
tos serve

# Override port
tos serve --port 3000

# Enable verbose logging
tos serve --verbose

Options:

• --port <number> - Override development server port
• --verbose - Enable detailed logging
• --no-open - Don't automatically open browser

What It Does:

1. Reads telemetry.config.json for configuration
2. Executes devServer.runCommand (e.g., vite --port 3000)
3. Provides TelemetryOS SDK environment simulation
4. Watches for file changes and hot reloads
5. Serves render and settings components
6. Simulates storage API with local persistence

Development UI:

The server provides a host interface at http://localhost:5173 showing:

• Render component preview
• Settings component preview
• Storage inspector
• Message logs
• SDK method calls

Project Structure

The CLI generates a well-organized project structure:

Source Files

src/render/ - Display Component

import { configure, store } from '@telemetryos/sdk';

configure('my-app');

// Subscribe to settings changes
store().instance.subscribe('config', (config) => {
  updateDisplay(config);
});

src/settings/ - Configuration Component

import { configure, store } from '@telemetryos/sdk';

configure('my-app');

// Save configuration
async function saveSettings(config) {
  await store().instance.set('config', config);
}

Configuration Files

telemetry.config.json - Platform Configuration

{
  "name": "my-app",
  "version": "1.0.0",
  "mountPoints": {
    "render": "/render",
    "settings": "/settings"
  },
  "devServer": {
    "runCommand": "vite --port 3000",
    "url": "http://localhost:3000"
  }
}

vite.config.ts - Build Configuration

import { defineConfig } from 'vite';
import react from '@vitejs/plugin-react';

export default defineConfig({
  plugins: [react()],
  build: {
    rollupOptions: {
      input: {
        render: '/render/index.html',
        settings: '/settings/index.html'
      }
    }
  }
});

Development Workflow

Project Initialization

CLI initialization creates complete project structures:

tos init weather-dashboard
cd weather-dashboard

Local Development

The development server enables rapid iteration:

tos serve

Changes to src/render/ or src/settings/ appear instantly through hot module replacement.

Storage Communication

Storage API enables component communication:

Settings Component:

await store().instance.set('city', 'New York');

Render Component:

store().instance.subscribe('city', (city) => {
  console.log('City changed:', city);
});

Dependency Management

Standard npm workflows add dependencies:

npm install axios
npm install @types/node --save-dev

Production Builds

Build commands generate deployment-ready output:

npm run build

Build output writes to dist/ directory for deployment.

Repository Setup

Git workflows prepare code for deployment:

git add .
git commit -m "Initial commit"
git remote add origin https://github.com/username/weather-dashboard.git
git push -u origin main

Studio Registration

Application registration connects GitHub repositories to TelemetryOS for automated deployment.

Benefits Over Manual Setup

Templates

The CLI supports multiple templates for different use cases:

vite-react-typescript (Default)

• React (latest stable) with TypeScript
• Vite for fast builds
• Hot module replacement
• Full type safety

react-basic

• React with JavaScript
• Simpler for beginners
• No TypeScript complexity
• Still uses Vite

vanilla-typescript

• No framework
• Pure TypeScript
• Minimal dependencies
• Direct DOM manipulation

vanilla-javascript

• No framework or TypeScript
• HTML/CSS/JS only
• Smallest bundle size
• Maximum simplicity

Use a template:

tos init my-app --template react-basic

Common Patterns

Worker Implementation

Workers provide background processing capabilities:

Worker File Creation:

// src/worker/index.ts
import { configure, store } from '@telemetryos/sdk';

configure('my-app');

// Background task
setInterval(async () => {
  const data = await fetchExternalData();
  await store().instance.set('data', data);
}, 60000);

Configuration Update:

{
  "mountPoints": {
    "render": "/render",
    "settings": "/settings",
    "background": "/worker"
  }
}

Vite configuration updates enable worker builds.

Container Integration

Containers provide backend service capabilities:

Container Configuration:

{
  "containers": [
    {
      "name": "api-server",
      "image": "myapp/api:latest",
      "port": 3000
    }
  ]
}

Render components access container services:

const data = await fetch('http://api-server:3000/data').then(r => r.json());

Troubleshooting

Port Conflicts

Port conflicts resolve through configuration or CLI flags:

Configuration Update:

{
  "devServer": {
    "url": "http://localhost:3001"
  }
}

CLI Override:

tos serve --port 3001

SDK Configuration Issues

SDK initialization requires configure() calls in all components:

import { configure } from '@telemetryos/sdk';
configure('my-app-name');

Both render and settings components must call configure() before SDK usage.

Hot Reload Issues

Hot reload requires matching Vite port and configuration:

{
  "devServer": {
    "runCommand": "vite --port 3000",
    "url": "http://localhost:3000"
  }
}

Port mismatches prevent hot reload functionality.

Build Failures

Build failures resolve through dependency reinstallation:

rm -rf node_modules package-lock.json
npm install

Dependency corruption causes build errors; clean reinstallation restores functionality.

Next Steps

After generating your application with the CLI:

1. Defining Application - Connect your code to TelemetryOS Studio
2. Local Development - Advanced development server usage
3. Storage Methods - Learn data persistence patterns
4. Mount Points - Understand application architecture
5. GitHub Integration - Set up CI/CD deployment

Learn More

• SDK Method Reference - Complete SDK method reference
• Quick Start Guide - Detailed tutorial
• Code Examples - Working code samples
• Local Development - Development server details