@openuidev/cli

A command-line tool for scaffolding OpenUI apps, minting OpenUI Gateway API keys, generating system prompts and library specs from a component library, and deploying apps.

Installation

Run without installing:

pnpx @openuidev/cli@latest <command>

Or install globally:

pnpm add -g @openuidev/cli

Global options

Available on every command.

create

Scaffolds a generative UI agent with Next.js and your choice of agent framework. No account or API key is needed to scaffold; add the key afterwards with generate-api-key.

openui create [directory] [options]

Options

--example cannot be combined with --backend-framework. --immediate and --no-immediate cannot be used together.

Interactive and non-interactive runs

In a terminal, create prompts for anything you didn't pass: the project name, a backend framework or example, and Gateway sign-in. It then installs dependencies and starts the development server.

When nobody can answer prompts, create takes the defaults instead: langgraph and the name openui-agent (or openui-agent-2, -3, … if that directory exists). This happens when you pass --no-interactive, when there's no terminal attached (CI, scripts), or when a coding agent runs the CLI. In that mode it:

• installs dependencies but doesn't start the development server (pass --immediate to start it)
• skips Gateway sign-in and ends with the generate-api-key command to run next

An explicit --name that already exists is an error in non-interactive runs.

Pass . as the directory (openui create .) to scaffold into the current folder instead; it must be empty apart from editor or agent folders such as .git, .vscode or .claude, and the project is named after the folder.

Backend frameworks

OpenUI examples

Loaded from OpenUI examples. Pass --example <name> with any catalog folder name; it can't be combined with --backend-framework.

Examples

# Prompt for anything not passed
pnpx @openuidev/cli@latest create

# Pick a backend framework, or start from an example
pnpx @openuidev/cli@latest create --name my-app --backend-framework vercel-ai-sdk
pnpx @openuidev/cli@latest create --name my-app --example shadcn

# Never prompt, then add the key
pnpx @openuidev/cli@latest create --no-interactive --name my-app
cd my-app && pnpx @openuidev/cli@latest generate-api-key

deploy

Deploys an OpenUI project to Vercel.

openui deploy [dir] [options]

Arguments

Options

Any other flags, such as --prod, are passed through to Vercel. Unlinked projects are linked first. Build logs are hidden unless you pass --verbose; failures always print the end of the log.

# Preview deploy from the project directory
pnpx @openuidev/cli@latest deploy

# Production deploy
pnpx @openuidev/cli@latest deploy --prod --yes

# Deploy a specific directory without local env
pnpx @openuidev/cli@latest deploy ./my-app --skip-env

generate-api-key

Signs in with Thesys in the browser, mints an OpenUI Gateway API key, and writes it to an env file in the current project. It needs an interactive terminal; without one it exits with the command to run yourself.

openui generate-api-key [options]

Options

Examples

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

generate

Generates the system prompt and the serialized library spec from a file that exports a createLibrary() result. Use the spec with generateSystemPrompt in backend routes; the prompt file supports static or legacy integrations.

openui generate [entry] [options]

Arguments

Options

Without --export, the CLI uses an export named library, then the default export, then any export that is a library. Without --prompt-options, it uses an export named promptOptions, then options, then any export whose name ends with PromptOptions.

Examples

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

# Write the prompt and its .spec.json alongside it
pnpx @openuidev/cli@latest generate ./src/library.ts --out ./src/generated/system-prompt.txt

# Output only the spec or the JSON schema
pnpx @openuidev/cli@latest generate ./src/library.ts --spec
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

PromptOptions

Export a PromptOptions object next to your library to customize the generated system prompt.

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.

// 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."],
};

setup-agent

Adds OpenUI instructions for coding agents to an existing project. It appends the OpenUI skill to AGENTS.md, or creates the file. Running it again refreshes the OpenUI instructions and leaves the rest of the file alone. Projects made with create already have it.

openui setup-agent [directory]

directory defaults to the current folder.

pnpx @openuidev/cli@latest setup-agent

feedback

Sends anonymous feedback to the OpenUI team. It isn't linked to your account, device, or IP address, and it's sent even when telemetry is disabled. Don't include personal data, secrets, or code.

openui feedback [options] <message...>

Options

pnpx @openuidev/cli@latest feedback --category docs "The streaming guide doesn't cover partial components"

Coding agents

Coding agents should pass --agent-name with their stable, lowercase kebab-case product slug, such as codex, claude-code, cline, factory-droid, or pi. Don't pass a model version, user name, or session ID. Humans can omit it.

create never waits on a prompt when an agent runs it, whether or not --agent-name is passed: it takes its non-interactive defaults and prints any follow-up commands, such as generate-api-key, at the end. Its last line points the agent at the new project's README to get started.

Telemetry

The CLI sends usage analytics: which commands and flags are used, and bounded failure codes. Browser sign-in may link usage to your Thesys account ID. It never sends code, prompts, API keys, env values, project paths, or command output. Disable it with --no-telemetry or DO_NOT_TRACK=1.

See also