Skip to main content

ShellUI CLI

The ShellUI CLI is the command-line tool for developing and building ShellUI applications.

Installation​

See the Installation Guide for detailed installation instructions.

Commands​

shellui init [root]​

Create a shellui.config.ts boilerplate to get started quickly.

Usage:

shellui init
shellui init ./my-project
shellui init --force

Description:

  • Creates a minimal shellui.config.ts in the project root (or the given directory)
  • Includes port, title, layout, language, and sample navigation (Home + Settings)
  • Does not overwrite an existing config unless --force is used

Options:

  • root (optional): Directory where to create the config (default: current directory)
  • --force: Overwrite existing shellui.config.ts

Example:

# Create config in current directory
shellui init

# Create config in a subdirectory
shellui init ./my-app

# Overwrite existing config
shellui init --force

After running shellui init, add a static/ folder with favicon.svg, logo.svg, and icons/ (e.g. home.svg, settings.svg) to customize assets, then run shellui dev to begin development.

shellui start [root] / shellui dev [root]​

Start the ShellUI development server. dev is an alias for start.

Usage:

shellui start
shellui dev
shellui start ./my-project
shellui dev --host
shellui dev --app

Description:

  • Starts a Vite development server with hot module replacement
  • Automatically opens your browser (on first start)
  • Watches for configuration file changes and restarts automatically
  • Uses the port specified in your configuration (default: 3000)
  • With --app, starts a native desktop development environment (see Desktop app)

Options:

  • root (optional): Project root directory (default: current directory)
  • --host: Listen on 0.0.0.0 so the app can be accessed from other devices on your network (e.g. via your machine’s LAN IP)
  • --app: Start as a native desktop app. On first run, generates dist/app/ (desktop wrapper) and installs desktop build tools if needed.
  • --target <web|tauri>: Build target injected at compile time (default: web). Set to tauri for desktop-specific behavior (e.g. disable service worker). Automatically applied when using --app.

Example:

# Start server in current directory
shellui dev

# Start server in specific directory
shellui start ./my-app

# Allow access from network (e.g. from phone or another machine)
shellui dev --host

# Start desktop development (ShellUI server + native window)
shellui dev --app

shellui build [root]​

Build the ShellUI application for production.

Usage:

shellui build
shellui build ./my-project
shellui build --app
shellui build --app --bundles app,dmg

Description:

  • Builds your ShellUI application for production
  • Outputs optimized files to dist/web/
  • Minifies and optimizes assets
  • Creates a production-ready static site
  • With --app, builds a native desktop app (web assets to dist/web/, desktop wrapper and bundles under dist/app/)

Options:

  • root (optional): Project root directory (default: current directory)
  • --app: Build the desktop app. Generates dist/app/ on first run and installs desktop build tools if needed.
  • --bundles <targets>: Desktop bundle format(s) when using --app (comma-separated). Default: app (e.g. .app on macOS). Use app,dmg on macOS to also produce a .dmg installer. See Desktop app — Bundle targets.
  • --target <web|tauri>: Build target injected at compile time (default: web). Set to tauri for desktop builds. Automatically applied when using --app.

Example:

# Build in current directory
shellui build

# Build specific project
shellui build ./my-app

# Build native desktop app (.app on macOS, default)
shellui build --app

# Build desktop app + macOS DMG installer (for distribution)
npx shellui build --app --bundles app,dmg

Configuration​

ShellUI uses a TypeScript configuration file to customize your application. The CLI looks for shellui.config.ts in your project root.

Configuration File Location​

The CLI searches for configuration files in this order:

  1. The specified root directory (if provided)
  2. The current working directory

Configuration Options​

port (number, optional)​

Port number for the development server.

{
  "port": 4000
}

Default: 3000

title (string, optional)​

Application title displayed in the UI.

{
  "title": "My Application"
}

backend (object, optional)​

Backend communication settings used for auth/API integration. See Backend and Authentication.

{
  "backend": {
    "type": "supabase",
    "url": "http://localhost:54321"
  }
}

Default: undefined

Properties:

  • type ("shellui" | "supabase", required when backend is set): Backend provider.
  • url (string, required when backend is set): Base API URL.

Array of navigation items for the sidebar. See the Navigation Guide for complete documentation.

{
  "navigation": [
    {
      "label": "Home",
      "path": "home",
      "url": "http://localhost:4000/",
      "icon": "/icons/home.svg"
    }
  ]
}

Basic Navigation Item Properties:

  • label (string | LocalizedString, required): Display text for the navigation item
  • path (string, required): Unique path identifier
  • url (string, required): URL to navigate to when clicked
  • icon (string, optional): Path to SVG icon file (e.g., "/icons/home.svg")

For advanced navigation features like groups, localization, visibility control, and opening modes, see the Navigation Guide.

Example Configuration​

TypeScript (shellui.config.ts):

import type { ShellUIConfig } from '@shellui/core';

const config: ShellUIConfig = {
  port: 4000,
  title: 'My ShellUI App',
  backend: {
    type: 'supabase',
    url: 'http://localhost:54321',
  },
  navigation: [
    {
      label: 'Documentation',
      path: 'docs',
      url: 'https://docs.example.com/',
      icon: 'BookOpen',
    },
    {
      label: 'Dashboard',
      path: 'dashboard',
      url: 'http://localhost:4000/',
      icon: 'Layout',
    },
    {
      label: 'Settings',
      path: 'settings',
      url: 'https://app.example.com/settings',
      icon: 'Settings',
    },
  ],
};

export default config;

Configuration File Watching​

When you run shellui start, the CLI automatically watches your configuration file for changes. When you modify the configuration:

  1. The server detects the change
  2. Automatically restarts with the new configuration
  3. The browser will refresh with updated settings

This allows you to iterate on your configuration without manually restarting the server.

Project Structure​

When using the CLI, your project structure should look like:

my-project/
├── shellui.config.ts
├── package.json
├── static/                # Optional static assets (favicon, icons, fonts)
├── dist/                  # Build output (gitignored, generated locally)
│   ├── web/               # Web build (`shellui build`)
│   └── app/               # Desktop wrapper (`shellui dev --app` / `shellui build --app`)
└── node_modules/

Only source files are committed — dist/ is generated on each machine (shellui init adds dist/ to .gitignore).

Configuration Reference​

For detailed configuration options, see:

Tips​

  • TypeScript configuration gives you IDE support and type checking
  • The CLI automatically handles hot reloading during development
  • Configuration changes trigger automatic server restarts
  • Production builds are optimized and ready for deployment
  • Check the terminal output for server URLs and build status

Troubleshooting​

Command Not Found​

If you see command not found: shellui, ensure the CLI is installed:

npm install -g @shellui/cli

Or use npx:

npx shellui start

Configuration Not Found​

Ensure shellui.config.ts exists in your project root directory.

Port Already in Use​

Change the port in your configuration file:

{
  "port": 5000
}

TypeScript Config Not Loading​

Ensure TypeScript is installed if using shellui.config.ts:

npm install -D typescript