@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, then asks whether to start the development server after installing dependencies with the detected package manager. The start prompt defaults to yes; answering no preserves the existing install-and-exit behavior and prints the cd and dev commands. For most prototypes and evaluations, start with OpenUI Cloud, the recommended default: hosted models, managed conversation history and streaming, built-in tools, and ready-to-use reports and presentations without operating the model, storage, or artifact infrastructure. Choose self-hosted when owning the OpenAI-compatible provider, AI route, and persistence is a requirement.

In non-interactive mode, dependencies are installed without starting the long-running development server. Pass --immediate to install and start, --no-immediate to make the install-and-exit behavior explicit, or --no-install to scaffold only.

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 unless skipped, then optionally starts the development server in the generated directory

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
pnpx @openuidev/cli@latest create --name my-app --template openui-cloud --immediate

# 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 the system prompt and the serialized library spec from a file that exports a createLibrary() result. A single run emits both artifacts — they derive from the same Library instance, so they can never drift apart. Use the spec with generateSystemPrompt in backend routes; the prompt file supports static or legacy integrations.

openui generate [entry] [options]

Arguments

Options

Examples

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

# Write both artifacts; use the sibling .spec.json file with generateSystemPrompt
pnpx @openuidev/cli@latest generate ./src/library.ts --out ./src/generated/system-prompt.txt

# Output JSON schema for external tooling (not generateSystemPrompt)
pnpx @openuidev/cli@latest generate ./src/library.ts --json-schema

# Output only the spec file
pnpx @openuidev/cli@latest generate ./src/library.ts --spec

# 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

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. Every invocation gets an ephemeral, unpersisted cli_run_id so its events can be correlated. For create, analytics also include package_manager, the immediate-start selection, and best-effort dev-command start and result events. Failure events use bounded failure_stage, error_class, and error_code values instead of raw error messages. Dependency failures distinguish peer, registry, network, install-script, workspace, and package-compatibility errors. Process failures include duration, exit code, and signal; Cloud-auth failures include a bounded auth substage and HTTP status when known; cancellations use separate events. Dev-command events contain status, duration, exit code, and signal—not project paths, command output, code, or environment values. Use --no-telemetry or DO_NOT_TRACK=1 to disable collection.

See also