@openuidev/cli

A command-line tool for scaffolding OpenUI chat apps and generating system prompts, JSON schemas, or serialized library specs from library definitions.

Installation

Run without installing:

pnpx @openuidev/cli@latest <command>

Or install globally:

pnpm add -g @openuidev/cli

openui create

Scaffolds a new Next.js app pre-configured with OpenUI Chat.

openui create [options]

Options

When run interactively (default), the CLI prompts for any missing options. It asks you to choose your AI setup: OpenUI Cloud is the fastest setup with free hosted models, while OpenAI-compatible provider uses your own key and self-hosts the AI route in the generated app. Pass --no-interactive in CI or scripted environments to surface missing required flags as errors instead.

What it does

1. Resolves the project name and AI setup
2. Copies the selected Next.js template into <name>/
3. Rewrites workspace:* dependency versions to latest
4. Writes the relevant .env values, including Thesys sign-in/API-key setup for OpenUI Cloud
5. Optionally installs the OpenUI agent skill for AI coding assistants (e.g. Claude, Cursor, Copilot)
6. Auto-detects your package manager (npm, pnpm, yarn, bun)
7. Installs dependencies

The generated project includes a generate:prompt script that runs openui generate as part of dev and build.

Agent skill

When run interactively, openui create asks whether to install the OpenUI agent skill. The skill teaches AI coding assistants how to build with OpenUI Lang — covering component definitions, system prompts, the Renderer, and debugging.

Pass --skill or --no-skill to skip the prompt. In --no-interactive mode the skill is skipped unless --skill is explicitly passed.

Examples

# Interactive — prompts for project name, AI setup, env setup, and skill installation
pnpx @openuidev/cli@latest create

# Select an AI setup explicitly
pnpx @openuidev/cli@latest create --name my-app --template openui-cloud
pnpx @openuidev/cli@latest create --name my-app --template openui-self-hosted

# Non-interactive
pnpx @openuidev/cli@latest create --no-interactive --name my-app --template openui-cloud --auth skip

# Explicitly install or skip the agent skill
pnpx @openuidev/cli@latest create --name my-app --skill
pnpx @openuidev/cli@latest create --name my-app --no-skill

openui generate

Generates a system prompt or JSON schema from a file that exports a createLibrary() result.

openui generate [entry] [options]

Arguments

Options

Examples

# Print system prompt to stdout
pnpx @openuidev/cli@latest generate ./src/library.ts

# Write system prompt to a file
pnpx @openuidev/cli@latest generate ./src/library.ts --out ./src/generated/system-prompt.txt

# Output JSON schema instead
pnpx @openuidev/cli@latest generate ./src/library.ts --json-schema

# Explicit export names
pnpx @openuidev/cli@latest generate ./src/library.ts --export myLibrary --prompt-options myOptions

Export auto-detection

The CLI bundles the entry file with esbuild before evaluating it. CSS, SVG, image, and font imports are stubbed automatically.

If --export is not provided, the CLI searches the module's exports in this order:

1. An export named library
2. The default export
3. Any export whose value has both a .prompt() method and a .toJSONSchema() method

If --prompt-options is not provided, the CLI looks for:

1. An export named promptOptions
2. An export named options
3. Any export whose name ends with PromptOptions (case-insensitive)

A valid PromptOptions value has at least one of: examples (string array), additionalRules (string array), or preamble (string).

PromptOptions type

interface PromptOptions {
  preamble?: string;
  additionalRules?: string[];
  examples?: string[];
  toolExamples?: string[];
  editMode?: boolean;
  inlineMode?: boolean;
  /** Enable Query(), Mutation(), @Run, built-in functions. Default: true if tools provided. */
  toolCalls?: boolean;
  /** Enable $variables, @Set, @Reset, built-in functions. Default: true if toolCalls. */
  bindings?: boolean;
}

Built-in functions (@Count, @Filter, @Sort, @Each, etc.) are included in the prompt only when toolCalls or bindings is enabled. For static UI examples without data fetching, they are omitted to keep the prompt focused.

Pass this as a named export alongside your library to customise the generated system prompt without hard-coding it into createLibrary.

// src/library.ts
import { createLibrary } from "@openuidev/react-lang";
import type { PromptOptions } from "@openuidev/react-lang";

export const library = createLibrary({ components: [...] });

export const promptOptions: PromptOptions = {
  preamble: "You are a dashboard builder...",
  additionalRules: ["Always use compact variants for table cells."],
};

pnpx @openuidev/cli@latest generate ./src/library.ts --out src/generated/system-prompt.txt

openui generate-spec

Generates a serialized library spec as JSON — component signatures, component groups, and the library's JSON schema — from a file that exports a createLibrary() result.

openui generate-spec [entry] [options]

The spec is a handover artifact: the team that owns the component library generates it once and hands the JSON to whoever configures the model server — for example as the chatLibrary config value in OpenUI Cloud. The server rebuilds the system prompt, response validation, and sanitization from the spec, so the model can only be prompted with components the library actually registers.

Arguments

Options

Entry bundling and library detection work the same as openui generate. PromptOptions exports are not folded into the spec — the spec is pure library data; consumers apply prompt customisation separately when they build the system prompt.

Output

{
  // Optional root component the response must start with
  "root": "Page",
  // Pre-rendered signatures, for review and inspection
  "components": {
    "Metric": {
      "signature": "Metric(label: string, value: string, trend?: \"up\" | \"down\")",
      "description": "A single KPI stat"
    }
  },
  // Optional grouping, mirrored into the generated prompt
  "componentGroups": [{ "name": "Data display", "components": ["Metric"] }],
  // JSON schema of every registered component ($defs keyed by component name)
  "schema": {
    "$defs": {
      "Metric": { "type": "object", "description": "A single KPI stat", "properties": { /* … */ } }
    }
  }
}

Examples

# Print the spec to stdout
pnpx @openuidev/cli@latest generate-spec ./src/library.ts

# Write the handover file
pnpx @openuidev/cli@latest generate-spec ./src/library.ts --out ./library-spec.json

# Explicit export name
pnpx @openuidev/cli@latest generate-spec ./src/library.ts --export myLibrary

Coding-agent attribution

When a coding agent invokes any CLI command, it should pass --agent-name using its stable, lowercase kebab-case product slug. Examples include codex, claude-code, cline, factory-droid, and pi. Do not pass a model/version, user name, session ID, or another unique value. Humans can omit the option; its default is unknown.

Usage analytics include two independent properties: agent_name, declared through the option, and detected_agent_name, inferred best-effort from known product environment markers. Either value can be spoofed, inherited, missing, or ambiguous, so neither should be treated as an authentication or security signal. For create, analytics also include package_manager, the manager selected for dependency installation (npm, pnpm, yarn, or bun). Use --no-telemetry or DO_NOT_TRACK=1 to disable collection.

See also