@openuidev/cli

A command-line tool for scaffolding OpenUI chat apps, minting OpenUI Cloud API key, 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, including the backend framework, 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, start, and open the app, or --no-install to scaffold only.

--immediate and --no-immediate are mutually exclusive; passing both exits with an error.

What it does

1. Resolves the project name, AI setup, and backend framework
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

Backend frameworks

The CLI applies the selected framework's final route/page files, dependencies, and deployment configuration over the base template. Both Vercel AI SDK variants are standard Next.js deployments with streamText(), toUIMessageStreamResponse(), and vercelAIAdapter(). Both LangGraph variants separate the Agent Server described by langgraph.json from the Next.js frontend/proxy. The proxy uses @openuidev/langchain, and the browser consumes its AG-UI stream with agUIAdapter(). Both Eve variants wrap Next.js with withEve() and talk to Eve's native /eve/v1/session* protocol from the browser; a small client adapter maps Eve events to AG-UI for agUIAdapter().

For Cloud LangGraph and Vercel AI SDK variants, the framework owns orchestration and application tool execution. OpenUI Cloud is attached as the Responses/Chat Completions model provider and conversation store. Reports, presentations, web search, image search, and configured MCP tools remain provider-executed Cloud tools. The Eve Cloud overlay uses Cloud as the Chat Completions provider and conversation store, without those provider-executed Cloud tools. For either LangGraph template, pnpm dev starts the local Agent Server and Next.js together. Deploy the Next.js frontend to Vercel and point LANGGRAPH_API_URL at wherever the Agent Server runs. Eve embeds in the Next.js process, so pnpm dev is enough for both Eve variants.

Every framework overlay includes a get_weather example backed by Open-Meteo. Ask “What’s the weather in Berlin?” to verify the selected framework’s native multi-step tool loop.

Conversation storage

Every OpenUI Cloud variant uses OpenUI Cloud as its only durable conversation and artifact store. The browser connects directly through useOpenuiCloudStorage() with a short-lived frontend token. For default, LangGraph, and Vercel AI SDK routes, the threadId sent to /api/chat is the Cloud conversation id, and each backend appends model turns to it with conversation: threadId and store: true. The Vercel AI SDK route does not create a second store. The Eve Cloud overlay keeps that Cloud thread store and maps each Cloud threadId to an Eve session cursor in the browser; it does not use /api/chat. The Cloud LangGraph relay creates and deletes a temporary Agent Server thread for each run; configure a separate LangGraph checkpointer only when graph state, interrupts, or resumable runs must persist independently.

The self-hosted variants do not configure durable storage. AgentInterface keeps messages in memory for the current page session; refreshing the page loses it. Default, Vercel AI SDK, and LangGraph send that history to /api/chat. The self-hosted LangGraph relay also creates and deletes a temporary Agent Server thread for each run. Eve maps follow-ups onto its session protocol for the page session only. Pass a storage implementation to AgentInterface and back it with your own database when persistence is required; add a LangGraph checkpointer only for graph-specific durable state.

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

# Select a backend framework explicitly
pnpx @openuidev/cli@latest create --name my-app --template openui-cloud --backend-framework langgraph
pnpx @openuidev/cli@latest create --name my-app --template openui-cloud --backend-framework vercel-ai-sdk
pnpx @openuidev/cli@latest create --name my-app --template openui-cloud --backend-framework vercel-eve
pnpx @openuidev/cli@latest create --name my-app --template openui-self-hosted --backend-framework langgraph
pnpx @openuidev/cli@latest create --name my-app --template openui-self-hosted --backend-framework vercel-ai-sdk
pnpx @openuidev/cli@latest create --name my-app --template openui-self-hosted --backend-framework vercel-eve

# 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-api-key

Signs in with Thesys in the browser, mints an OpenUI Cloud API key, and writes it to a project env file.

openui generate-api-key [options]

Options

Examples

pnpx @openuidev/cli@latest generate-api-key
pnpx @openuidev/cli@latest generate-api-key --file .env.local
pnpx @openuidev/cli@latest generate-api-key --file .env.local --key THESYS_API_KEY

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