Skip to content

The Open Standard for Generative UI

feat(cli): let agents and non-interactive shells run create without prompts (#1411)

AB60ab506ce3ed
diff --git a/.changeset/cli-agent-auth-skip.md b/.changeset/cli-agent-auth-skip.md
new file mode 100644
index 000000000..c93bc8085
--- /dev/null
+++ b/.changeset/cli-agent-auth-skip.md
@@ -0,0 +1,5 @@
+---
+"@openuidev/cli": patch
+---
+
+Stop `create` from hanging or failing when a coding agent or a non-interactive shell runs it. Agents are detected from `--agent-name` or, via `@vercel/detect-agent` plus a few extra markers, from the environment their harness sets. With nobody to answer prompts, a plain `create` now takes the defaults (OpenUI Cloud template, LangGraph, `openui-agent` or the next free name) instead of erroring on a missing template arg, skips Cloud sign-in, and ends with a `generate-api-key` hint that uses the invoking package manager.
diff --git a/.github/actions/cli-scaffold-e2e/action.yml b/.github/actions/cli-scaffold-e2e/action.yml
index 2a07760a2..8f3cc4ac6 100644
--- a/.github/actions/cli-scaffold-e2e/action.yml
+++ b/.github/actions/cli-scaffold-e2e/action.yml
@@ -2,9 +2,6 @@ name: CLI scaffold end to end
description: Scaffold a template with the packed CLI, then install and build the generated app.
inputs:
- template:
- description: Template key passed to `openui create --template`.
- required: true
backend-framework:
description: Overlay key passed to `openui create --backend-framework`.
required: false
@@ -94,9 +91,7 @@ runs:
npm exec --yes --package="${{ steps.cli-package.outputs.path }}" --
openui --no-telemetry create
--name generated-app
- --template ${{ inputs.template }}
--backend-framework ${{ inputs.backend-framework }}
- --api-key sk-test
--no-interactive
--no-skill
@@ -107,13 +102,12 @@ runs:
env:
OPENUI_DEBUG: "1"
OPENUI_SOURCE_DIR: ${{ github.workspace }}
+ THESYS_API_KEY: "sk-test"
run: >-
pnpm dlx "${{ steps.cli-package.outputs.path }}"
--no-telemetry create
--name generated-app
- --template ${{ inputs.template }}
--backend-framework ${{ inputs.backend-framework }}
- --api-key sk-test
--no-interactive
--no-skill
@@ -146,6 +140,5 @@ runs:
working-directory: ${{ runner.temp }}/cli-e2e/generated-app
run: ${{ inputs.package-manager }} run build
env:
- OPENAI_API_KEY: sk-test
THESYS_API_KEY: sk-test
DEMO_USER_ID: test-user
diff --git a/.github/workflows/cli-e2e.yml b/.github/workflows/cli-e2e.yml
index 621871988..9e3710698 100644
--- a/.github/workflows/cli-e2e.yml
+++ b/.github/workflows/cli-e2e.yml
@@ -54,15 +54,12 @@ jobs:
retention-days: 1
cli-e2e:
- name: ${{ matrix.template }} (${{ matrix.package-manager }}@${{ matrix.package-manager-version }}, ${{ matrix.os }}, Node ${{ matrix.node-version }})
+ name: langgraph (${{ matrix.package-manager }}@${{ matrix.package-manager-version }}, ${{ matrix.os }}, Node ${{ matrix.node-version }})
needs: package-cli
runs-on: ${{ matrix.os }}
strategy:
fail-fast: false
matrix:
- template:
- - openui-cloud
- - openui-self-hosted
configuration:
# Keep one npm and pnpm canary for the legacy Node.js line.
- ubuntu-node20-npm10
@@ -152,7 +149,6 @@ jobs:
- uses: ./.github/actions/cli-scaffold-e2e
with:
- template: ${{ matrix.template }}
backend-framework: langgraph
node-version: ${{ matrix.node-version }}
package-manager: ${{ matrix.package-manager }}
@@ -162,15 +158,12 @@ jobs:
# manager majors; overlays only change dependencies and app code, so one
# current Linux configuration per package manager is enough.
cli-e2e-overlays:
- name: ${{ matrix.template }} + ${{ matrix.overlay }} (${{ matrix.package-manager }}@11, ubuntu, Node 24)
+ name: ${{ matrix.overlay }} (${{ matrix.package-manager }}@11, ubuntu, Node 24)
needs: package-cli
runs-on: ubuntu-latest
strategy:
fail-fast: false
matrix:
- template:
- - openui-cloud
- - openui-self-hosted
overlay:
- vercel-ai-sdk
- vercel-eve
@@ -183,7 +176,6 @@ jobs:
- uses: ./.github/actions/cli-scaffold-e2e
with:
- template: ${{ matrix.template }}
backend-framework: ${{ matrix.overlay }}
node-version: 24
package-manager: ${{ matrix.package-manager }}
diff --git a/README.md b/README.md
index 2d56d711a..b609e3c75 100644
--- a/README.md
+++ b/README.md
@@ -54,9 +54,6 @@ At the center of OpenUI is **OpenUI Lang**: a compact, streaming-first language
```bash
npx @openuidev/cli@latest create --name genui-chat-app
-cd genui-chat-app
-echo "OPENAI_API_KEY=sk-your-key-here" > .env
-npm run dev
```
This is the fastest way to start with OpenUI. The scaffolded app gives you an end-to-end starting point with streaming, built-in UI, and OpenUI Lang support.
diff --git a/docs/app/(home)/cloud/gateway/IntegrateSection.tsx b/docs/app/(home)/cloud/gateway/IntegrateSection.tsx
index 2aeee830a..1028767f7 100644
--- a/docs/app/(home)/cloud/gateway/IntegrateSection.tsx
+++ b/docs/app/(home)/cloud/gateway/IntegrateSection.tsx
@@ -26,7 +26,7 @@ const GATEWAY_EXAMPLE = `const client = new OpenAI({
const response = await client.chat.completions.create({
model: "openai/gpt-5",
messages: [
- { role: "system", content: generatePrompt({ thesys: true }) },
+ { role: "system", content: generatePrompt({ cloud: true }) },
...messages,
],
});`;
diff --git a/docs/app/(home)/components/AgentPicker/AgentPicker.tsx b/docs/app/(home)/components/AgentPicker/AgentPicker.tsx
index 75b5cc70a..4a971d8fc 100644
--- a/docs/app/(home)/components/AgentPicker/AgentPicker.tsx
+++ b/docs/app/(home)/components/AgentPicker/AgentPicker.tsx
@@ -13,8 +13,11 @@ import styles from "./AgentPicker.module.css";
// on the dark page; marks with colour of their own keep it on both themes.
/* What each agent button puts on the clipboard. A prompt to paste into an
agent, not a shell command: it is copied verbatim, with nothing appended. */
-export const AGENT_SETUP_PROMPT =
- "Visit OpenUI.com/docs and set up my first Generative UI agent using the recommended OpenUI stack.";
+export const AGENT_SETUP_PROMPT = `Set up my first Generative UI agent using the recommended OpenUI stack. Docs: https://www.openui.com/docs/getting-started
+
+1. Scaffold: run \`npx @openuidev/cli@latest create\`. It runs without prompts, creates the project folder, and installs dependencies.
+2. Tell me if there are any steps required of me to complete.
+3. First message: start the app, open its local URL, send one message, and tell me what the server log actually returned.`;
export const AGENTS = [
{
diff --git a/docs/app/(home)/sections/CompatibilitySection/CompatibilityDiagram.module.css b/docs/app/(home)/sections/CompatibilitySection/CompatibilityDiagram.module.css
index ea8483261..18cd11b82 100644
--- a/docs/app/(home)/sections/CompatibilitySection/CompatibilityDiagram.module.css
+++ b/docs/app/(home)/sections/CompatibilitySection/CompatibilityDiagram.module.css
@@ -107,7 +107,7 @@
width: var(--centre);
}
-/* One element over all four rows, so its shadow falls on the bands either side
+/* One element over every row, so its shadow falls on the bands either side
and never on itself. Centred by the auto margins rather than a transform. */
.centre {
--stack-logo-size: 24px;
diff --git a/docs/app/(home)/sections/CompatibilitySection/CompatibilityDiagram.tsx b/docs/app/(home)/sections/CompatibilitySection/CompatibilityDiagram.tsx
index a313ae566..d001d993b 100644
--- a/docs/app/(home)/sections/CompatibilitySection/CompatibilityDiagram.tsx
+++ b/docs/app/(home)/sections/CompatibilitySection/CompatibilityDiagram.tsx
@@ -5,9 +5,9 @@ import { StackLayerRow } from "./StackLayerRow";
type StackGroup = { label: string; items: StackChipItem[] };
-/* Four rows of square cells, one per layer, their bands drifting inward in step
- * so the rows read as one grid rather than four strips. The centre of the grid
- * is a single column, drawn over all four rows, naming each layer.
+/* Rows of square cells, one per layer, their bands drifting inward in step
+ * so the rows read as one grid rather than separate strips. The centre of the grid
+ * is a single column, drawn over every row, naming each layer.
*/
export function CompatibilityDiagram({ groups }: { groups: StackGroup[] }) {
return (
diff --git a/docs/app/(home)/sections/CompatibilitySection/CompatibilitySection.tsx b/docs/app/(home)/sections/CompatibilitySection/CompatibilitySection.tsx
index c3636bb6c..7586b5262 100644
--- a/docs/app/(home)/sections/CompatibilitySection/CompatibilitySection.tsx
+++ b/docs/app/(home)/sections/CompatibilitySection/CompatibilitySection.tsx
@@ -10,64 +10,15 @@ interface StackRow {
items: StackChipItem[];
}
-/* The four compatibility groups, ordered the way the stack is drawn top to
- bottom: the model at the top, then the service that calls it, the library it
- renders with, and the client the user touches at the base. The diagram draws
+/* The three compatibility groups, ordered the way the stack is drawn top to
+ bottom: the agent backend at the top, then the library it renders with, and
+ the client the user touches at the base. The diagram draws
one StackLayerRow per group, in this order, and runs that group's own logos
past it.
Every entry needs a real mark. Anything with no logo to be found is left out
rather than stood in for by a related company's. */
const STACK_ROWS: StackRow[] = [
- {
- /* OpenAI, xAI and DeepSeek are local files: Simple Icons carries no OpenAI
- mark, and its "x" is the social network, not xAI. */
- label: "LLMs",
- items: [
- {
- name: "OpenAI",
- iconKind: "image",
- localSrc: "/brand-icons/openai.svg",
- iconColor: "000000",
- badgeClassName: `${stackChipStyles.badgeWhite} ${stackChipStyles.badgeWithBorder}`,
- },
- {
- name: "Anthropic",
- iconKind: "image",
- slug: "anthropic",
- iconColor: "ffffff",
- badgeClassName: stackChipStyles.badgeAnthropic,
- },
- {
- name: "Gemini",
- iconKind: "image",
- slug: "googlegemini",
- iconColor: "000000",
- badgeClassName: `${stackChipStyles.badgeWhite} ${stackChipStyles.badgeWithBorder}`,
- },
- {
- name: "DeepSeek",
- iconKind: "image",
- localSrc: "/brand-icons/deepseek.svg",
- iconColor: "ffffff",
- badgeClassName: stackChipStyles.badgeDeepSeek,
- },
- {
- name: "xAI",
- iconKind: "image",
- localSrc: "/brand-icons/xai.svg",
- iconColor: "ffffff",
- badgeClassName: stackChipStyles.badgeBlack,
- },
- {
- name: "Mistral",
- iconKind: "image",
- slug: "mistralai",
- iconColor: "ffffff",
- badgeClassName: stackChipStyles.badgeMistral,
- },
- ],
- },
{
/* Llama, LlamaIndex and Mastra are absent: no logo could be found for any of
them, and a row is better short than wrong. */
@@ -244,7 +195,7 @@ export function CompatibilitySection({ embedded = false }: { embedded?: boolean
puts this band's claim into crawlable body text. One clause per
row above it, in the same order. */}
<SectionHeader
- caption="Generative UI that renders in any client framework, uses any component library, and runs on any agent backend or model."
+ caption="Generative UI that renders in any client framework, uses any component library, and runs on any agent backend."
title="...and works with your stack."
titleId="favorite-stack-title"
/>
diff --git a/docs/app/(home)/sections/CompatibilitySection/StackCentreColumn.tsx b/docs/app/(home)/sections/CompatibilitySection/StackCentreColumn.tsx
index cfa95091c..dfc8ce243 100644
--- a/docs/app/(home)/sections/CompatibilitySection/StackCentreColumn.tsx
+++ b/docs/app/(home)/sections/CompatibilitySection/StackCentreColumn.tsx
@@ -8,7 +8,7 @@ import styles from "./CompatibilityDiagram.module.css";
* stacked, sitting over the drifting bands and lining up with their rows.
*
* One element rather than one per row, so the shadow it casts onto the bands is
- * a single shadow around a single box. Four stacked boxes each cast onto the
+ * a single shadow around a single box. Stacked boxes each cast onto the
* ones above and below them, which are the rest of this same column.
*/
@@ -69,7 +69,7 @@ export function StackCentreColumn({ layers }: { layers: Layer[] }) {
items={layer.items}
key={layer.label}
label={layer.label}
- /* Staggered, so the four titles do not all change logo together. */
+ /* Staggered, so the titles do not all change logo together. */
swapDelay={index * 550}
/>
))}
diff --git a/docs/app/(home)/sections/FaqSection/FaqSection.tsx b/docs/app/(home)/sections/FaqSection/FaqSection.tsx
index e85db7aba..0212641e3 100644
--- a/docs/app/(home)/sections/FaqSection/FaqSection.tsx
+++ b/docs/app/(home)/sections/FaqSection/FaqSection.tsx
@@ -15,8 +15,8 @@ export const FAQS: MarketingFaq[] = [
{
question: "What should I use to build a Generative UI app?",
answer: [
- "Start with OpenUI, the free and open-source framework for Generative UI.",
- "For production, we recommend adding OpenUI Gateway for reliability and OpenUI Observability for monitoring and product analytics.",
+ "Start with OpenUI and OpenUI Gateway. One command scaffolds a working app: npx @openuidev/cli@latest create.",
+ "Gateway gives you free models to build with, and repairs invalid output so broken UI doesn't reach users. The same setup carries into production.",
],
},
{
@@ -40,16 +40,7 @@ export const FAQS: MarketingFaq[] = [
{
question: "Is OpenUI free and open source?",
answer: [
- "Yes. OpenUI is fully open source and works with your own models, infrastructure, components, and design system.",
- "OpenUI Gateway and OpenUI Observability are managed services for teams running Generative UI in production.",
- ],
- },
- {
- question: "Do I need OpenUI Gateway to use OpenUI?",
- answer: [
- "No. You can call any supported LLM directly.",
- "For production applications, OpenUI Gateway adds validation and automatic corrections for generated UI, model routing, and provider fallbacks through an OpenAI-compatible API.",
- "Adopt it by changing your base URL and model configuration.",
+ "Yes. OpenUI is fully open source and works with your own components and design system.",
],
},
{
@@ -61,13 +52,6 @@ export const FAQS: MarketingFaq[] = [
"We recommend using both. Gateway makes generated UI more reliable. Observability shows what users experienced and whether it worked.",
],
},
- {
- question: "Can OpenUI work with my existing stack?",
- answer: [
- "Yes. OpenUI works with your existing LLMs, agent frameworks, design systems, and infrastructure.",
- "Bring your own OpenAI, Anthropic, or Google keys, use custom component libraries, and run OpenUI Gateway behind any OpenAI-compatible gateway, including Portkey.",
- ],
- },
{
question: "How is Thesys related to OpenUI?",
answer: [
diff --git a/docs/content/docs/agent/getting-started/quickstart.mdx b/docs/content/docs/agent/getting-started/quickstart.mdx
index fb91cf8ae..6612b8540 100644
--- a/docs/content/docs/agent/getting-started/quickstart.mdx
+++ b/docs/content/docs/agent/getting-started/quickstart.mdx
@@ -1,41 +1,31 @@
---
title: Quickstart
-description: Scaffold a streaming Agent Interface application connected to your model provider.
+description: Scaffold a streaming Agent Interface application with one command.
---
The OpenUI CLI can scaffold a Next.js agent application with Agent Interface, an OpenUI renderer, and a server route for model generation.
## 1. Create the application
-Run the command with the self-hosted template to connect your own OpenAI-compatible provider:
+Run the command:
```bash tab="pnpm" tab-group="pkg"
-pnpx @openuidev/cli@latest create --template openui-self-hosted
+pnpx @openuidev/cli@latest create
```
```bash tab="bun" tab-group="pkg"
-bunx @openuidev/cli@latest create --template openui-self-hosted
+bunx @openuidev/cli@latest create
```
```bash tab="yarn" tab-group="pkg"
-yarn dlx @openuidev/cli@latest create --template openui-self-hosted
+yarn dlx @openuidev/cli@latest create
```
```bash tab="npm" tab-group="pkg"
-npx @openuidev/cli@latest create --template openui-self-hosted
+npx @openuidev/cli@latest create
```
-## 2. Configure your provider key
-
-Enter your provider key when prompted, or add it to the generated environment file:
-
-```bash
-OPENAI_API_KEY=sk-your-key-here
-```
-
-The key stays in the generated server route. Browser code calls your application and never receives this server credential.
-
-## 3. Run
+## 2. Run
```bash tab="pnpm" tab-group="pkg"
pnpm dev
@@ -47,7 +37,7 @@ npm run dev
Open [http://localhost:3000](http://localhost:3000) and request an interface such as a comparison table or interactive form.
-## 4. Share a preview
+## 3. Share a preview
Deploy a Vercel preview from the project directory:
@@ -67,8 +57,6 @@ yarn dlx @openuidev/cli@latest deploy
npx @openuidev/cli@latest deploy
```
-Allowlisted keys from `.env`, such as `OPENAI_API_KEY`, are passed to the deployment.
-
## What to read next
- [Deploy with the CLI](/docs/api-reference/cli#deploy)
diff --git a/docs/content/docs/api-reference/cli.mdx b/docs/content/docs/api-reference/cli.mdx
index 8282e9e56..b3da89ab7 100644
--- a/docs/content/docs/api-reference/cli.mdx
+++ b/docs/content/docs/api-reference/cli.mdx
@@ -1,9 +1,9 @@
---
title: "@openuidev/cli"
-description: API reference for the OpenUI CLI to scaffold apps, mint Gateway API keys, and generate system prompts or library specs, and deploy projects.
+description: API reference for the OpenUI CLI to scaffold apps, mint Gateway API keys, generate system prompts or library specs, and deploy projects.
---
-A command-line tool for scaffolding OpenUI chat apps, minting OpenUI Gateway API key, and generating system prompts, JSON schemas, or serialized library specs from library definitions, and deploying those apps.
+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
@@ -43,9 +43,21 @@ yarn global add @openuidev/cli
npm install -g @openuidev/cli
```
+## Global options
+
+Available on every command.
+
+| Flag | Description |
+| --------------------- | ------------------------------------------------------------------------------------------------------------- |
+| `--agent-name <name>` | Coding agents: declare your product slug, e.g. `codex` or `claude-code` (see [Coding agents](#coding-agents)) |
+| `--verbose` | Stream full command logs |
+| `--no-telemetry` | Disable anonymous usage analytics (`DO_NOT_TRACK=1` also works) |
+| `-V, --version` | Print the CLI version |
+| `-h, --help` | Show help for a command |
+
## `create`
-Scaffolds a new Next.js app pre-configured with OpenUI Chat.
+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`](#generate-api-key).
```
openui create [options]
@@ -53,194 +65,101 @@ openui create [options]
**Options**
-| Flag | Description |
-| --------------------------------- | ---------------------------------------------------------------------------- |
-| `-n, --name <string>` | Project name (interactive default: `openui-agent`) |
-| `-t, --template <template>` | AI backend: `openui-cloud` (Gateway; recommended) or `openui-self-hosted` |
-| `--backend-framework <framework>` | Backend integration: `langgraph` (default), `vercel-ai-sdk`, or `vercel-eve` |
-| `-e, --example <example>` | Scaffold any example from the OpenUI Repository |
-| `--api-key <key>` | OpenUI Gateway API key; skips sign-in for the Gateway setup |
-| `--auth <method>` | Gateway auth method: `oauth` or `skip`; `manual` is deprecated |
-| `--skill` | Install the OpenUI agent skill for AI coding assistants |
-| `--no-skill` | Skip installing the OpenUI agent skill |
-| `--no-install` | Scaffold without running dependency installation |
-| `-i, --immediate` | Start the development server after installing dependencies |
-| `--no-immediate` | Install dependencies without starting the development server |
-| `--no-interactive` | Fail instead of prompting for missing input |
-| `--agent-name <name>` | Declare the invoking coding-agent slug (default: `unknown`) |
+| Flag | Description |
+| --------------------------------- | ------------------------------------------------------------------------------------------------------------------- |
+| `-n, --name <string>` | Project name (default: `openui-agent`) |
+| `--backend-framework <framework>` | Backend framework: `langgraph` (default), `vercel-ai-sdk`, or `vercel-eve` |
+| `-e, --example <example>` | Scaffold an [OpenUI example](https://github.com/thesysdev/openui/blob/main/examples) instead |
+| `--skill` / `--no-skill` | Install or skip the [OpenUI agent skill](/docs/mcp#install-via-the-skills-cli-recommended) for AI coding assistants |
+| `--no-install` | Scaffold without installing dependencies |
+| `-i, --immediate` | Start the development server after installing |
+| `--no-immediate` | Install dependencies without starting the development server |
+| `--no-interactive` | Never prompt; use defaults for anything not passed |
-When run interactively (default), the CLI prompts for any missing options, including the backend framework or an example, 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 Gateway, 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.
+`--example` cannot be combined with `--backend-framework`. `--immediate` and `--no-immediate` cannot be used together.
-`openui-cloud` remains the CLI template identifier for the Gateway-backed setup.
+**Interactive and non-interactive runs**
-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.
+In a terminal, `create` prompts for anything you didn't pass: the project name, a backend framework or example, Gateway sign-in, and the agent skill. It then installs dependencies and starts the development server.
-`--immediate` and `--no-immediate` are mutually exclusive; passing both exits with an error.
+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:
-**What it does**
+- 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
+- skips the agent skill unless you pass `--skill`
-1. Resolves the project name, picks a backend-framework overlay or an OpenUI example
-2. Copies the selected Next.js template or example into `<name>/`
-3. Rewrites `workspace:*` dependency versions to `latest`
-4. Writes the relevant `.env` values, including Thesys sign-in/API-key setup for OpenUI Gateway
-5. Optionally installs the [OpenUI agent skill](/docs/mcp#install-via-the-skills-cli-recommended) 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
+An explicit `--name` that already exists is an error in non-interactive runs.
**Backend frameworks**
-| Value | OpenUI Gateway route | Self-hosted route |
-| --------------- | ------------------------------------- | ---------------------------------- |
-| `langgraph` | LangGraph + Gateway Chat Completions | LangGraph + your provider |
-| `vercel-ai-sdk` | Vercel AI SDK Next.js agent + Gateway | Vercel AI SDK `streamText()` route |
-| `vercel-eve` | Vercel Eve agent + Gateway provider | Vercel Eve agent + your provider |
-
-LangGraph is the default backend and lives directly in both base templates. Vercel AI SDK and Eve apply overlays with their own route/page files, dependencies, and deployment configuration. Both LangGraph variants run the agent inside the Next.js `/api/chat` route and stream native LangGraph events to `langGraphAdapter()`. They do not require a separate Agent Server. Vercel AI SDK uses `streamText()` and `vercelAIAdapter()`. Eve wraps Next.js with `withEve()` and uses its native `/eve/v1/session*` protocol with `eveAdapter()`.
+| Value | Description |
+| --------------- | ------------------------------------------ |
+| `langgraph` | LangGraph agent |
+| `vercel-ai-sdk` | Vercel AI SDK agent |
+| `vercel-eve` | Eve agent rendered through Agent Interface |
-The framework owns orchestration and application tool execution. Gateway-backed templates use OpenUI Gateway as their Chat Completions model provider; self-hosted templates use the configured OpenAI-compatible provider. `pnpm dev` starts the app for every variant, including the embedded Eve server when selected.
-
-Every backend 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.
**OpenUI examples**
-Interactive `openui create` lists starter templates and featured [OpenUI examples](https://github.com/thesysdev/openui/blob/main/examples). `--example <name>` skips both menus. `--example` cannot be combined with `--template` or `--backend-framework`. Any other folder name in the catalog works the same way.
-
-**Conversation storage**
-
-The default Gateway-backed LangGraph template uses Gateway for durable conversation history. The browser reads history through `useOpenuiCloudStorage()` with a short-lived frontend token. The `threadId` sent to `/api/chat` is the Gateway conversation ID. After a successful turn, `storeLangGraphHistory()` saves the new user message, assistant messages, tool calls, and tool results together. Replayed history is excluded. The browser sends the full history back to the in-process graph on subsequent turns.
-
-The Gateway-backed Vercel AI SDK and Eve overlays include the Cloud storage reader, but do not currently write completed turns to that store. Add server-side persistence before relying on conversation history surviving a reload. Eve keeps a browser-side mapping from each Gateway `threadId` to an Eve session cursor for follow-ups.
-
-The self-hosted variants do not configure durable storage. `AgentInterface` keeps messages in memory for the current page session; refreshing the page loses them. LangGraph and Vercel AI SDK send that history to `/api/chat`. Eve maps follow-ups onto its session protocol. Pass a storage implementation to `AgentInterface` and back it with your own database when persistence is required; add a LangGraph checkpointer when graph state, interrupts, or resumable runs must persist independently.
-
-**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.
+Loaded from [OpenUI examples](https://github.com/thesysdev/openui/blob/main/examples). Pass `--example <name>` with any catalog folder name; it can't be combined with `--backend-framework`.
**Examples**
```bash tab="pnpm" tab-group="pkg"
-# Interactive — prompts for project name, AI setup, env setup, and skill installation
+# Prompt for anything not passed
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
-
-# Select an example
+# 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
-pnpx @openuidev/cli@latest create --name my-app --example mastra
-pnpx @openuidev/cli@latest create --name my-app --example vue
-
-# 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
+# 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
```
```bash tab="bun" tab-group="pkg"
-# Interactive — prompts for project name, AI setup, env setup, and skill installation
+# Prompt for anything not passed
bunx @openuidev/cli@latest create
-# Select an AI setup explicitly
-bunx @openuidev/cli@latest create --name my-app --template openui-cloud
-bunx @openuidev/cli@latest create --name my-app --template openui-self-hosted
-
-# Select a backend framework explicitly
-bunx @openuidev/cli@latest create --name my-app --template openui-cloud --backend-framework langgraph
-bunx @openuidev/cli@latest create --name my-app --template openui-cloud --backend-framework vercel-ai-sdk
-bunx @openuidev/cli@latest create --name my-app --template openui-cloud --backend-framework vercel-eve
-bunx @openuidev/cli@latest create --name my-app --template openui-self-hosted --backend-framework langgraph
-bunx @openuidev/cli@latest create --name my-app --template openui-self-hosted --backend-framework vercel-ai-sdk
-bunx @openuidev/cli@latest create --name my-app --template openui-self-hosted --backend-framework vercel-eve
-
-# Select an example
+# Pick a backend framework, or start from an example
+bunx @openuidev/cli@latest create --name my-app --backend-framework vercel-ai-sdk
bunx @openuidev/cli@latest create --name my-app --example shadcn
-bunx @openuidev/cli@latest create --name my-app --example mastra
-bunx @openuidev/cli@latest create --name my-app --example vue
-# Non-interactive
-bunx @openuidev/cli@latest create --no-interactive --name my-app --template openui-cloud --auth skip
-
-# Explicitly install or skip the agent skill
-bunx @openuidev/cli@latest create --name my-app --skill
-bunx @openuidev/cli@latest create --name my-app --no-skill
+# Never prompt, then add the key
+bunx @openuidev/cli@latest create --no-interactive --name my-app
+cd my-app && bunx @openuidev/cli@latest generate-api-key
```
```bash tab="yarn" tab-group="pkg"
-# Interactive — prompts for project name, AI setup, env setup, and skill installation
+# Prompt for anything not passed
yarn dlx @openuidev/cli@latest create
-# Select an AI setup explicitly
-yarn dlx @openuidev/cli@latest create --name my-app --template openui-cloud
-yarn dlx @openuidev/cli@latest create --name my-app --template openui-self-hosted
-
-# Select a backend framework explicitly
-yarn dlx @openuidev/cli@latest create --name my-app --template openui-cloud --backend-framework langgraph
-yarn dlx @openuidev/cli@latest create --name my-app --template openui-cloud --backend-framework vercel-ai-sdk
-yarn dlx @openuidev/cli@latest create --name my-app --template openui-cloud --backend-framework vercel-eve
-yarn dlx @openuidev/cli@latest create --name my-app --template openui-self-hosted --backend-framework langgraph
-yarn dlx @openuidev/cli@latest create --name my-app --template openui-self-hosted --backend-framework vercel-ai-sdk
-yarn dlx @openuidev/cli@latest create --name my-app --template openui-self-hosted --backend-framework vercel-eve
-
-# Select an example
+# Pick a backend framework, or start from an example
+yarn dlx @openuidev/cli@latest create --name my-app --backend-framework vercel-ai-sdk
yarn dlx @openuidev/cli@latest create --name my-app --example shadcn
-yarn dlx @openuidev/cli@latest create --name my-app --example mastra
-yarn dlx @openuidev/cli@latest create --name my-app --example vue
-
-# Non-interactive
-yarn dlx @openuidev/cli@latest create --no-interactive --name my-app --template openui-cloud --auth skip
-# Explicitly install or skip the agent skill
-yarn dlx @openuidev/cli@latest create --name my-app --skill
-yarn dlx @openuidev/cli@latest create --name my-app --no-skill
+# Never prompt, then add the key
+yarn dlx @openuidev/cli@latest create --no-interactive --name my-app
+cd my-app && yarn dlx @openuidev/cli@latest generate-api-key
```
```bash tab="npm" tab-group="pkg"
-# Interactive — prompts for project name, AI setup, env setup, and skill installation
+# Prompt for anything not passed
npx @openuidev/cli@latest create
-# Select an AI setup explicitly
-npx @openuidev/cli@latest create --name my-app --template openui-cloud
-npx @openuidev/cli@latest create --name my-app --template openui-self-hosted
-
-# Select a backend framework explicitly
-npx @openuidev/cli@latest create --name my-app --template openui-cloud --backend-framework langgraph
-npx @openuidev/cli@latest create --name my-app --template openui-cloud --backend-framework vercel-ai-sdk
-npx @openuidev/cli@latest create --name my-app --template openui-cloud --backend-framework vercel-eve
-npx @openuidev/cli@latest create --name my-app --template openui-self-hosted --backend-framework langgraph
-npx @openuidev/cli@latest create --name my-app --template openui-self-hosted --backend-framework vercel-ai-sdk
-npx @openuidev/cli@latest create --name my-app --template openui-self-hosted --backend-framework vercel-eve
-
-# Select an example
+# Pick a backend framework, or start from an example
+npx @openuidev/cli@latest create --name my-app --backend-framework vercel-ai-sdk
npx @openuidev/cli@latest create --name my-app --example shadcn
-npx @openuidev/cli@latest create --name my-app --example mastra
-npx @openuidev/cli@latest create --name my-app --example vue
-# Non-interactive
-npx @openuidev/cli@latest create --no-interactive --name my-app --template openui-cloud --auth skip
-
-# Explicitly install or skip the agent skill
-npx @openuidev/cli@latest create --name my-app --skill
-npx @openuidev/cli@latest create --name my-app --no-skill
+# Never prompt, then add the key
+npx @openuidev/cli@latest create --no-interactive --name my-app
+cd my-app && npx @openuidev/cli@latest generate-api-key
```
## `deploy`
-Deploys an OpenUI project. The default supported platform is **Vercel**.
+Deploys an OpenUI project to Vercel.
```
openui deploy [dir] [options]
@@ -254,16 +173,13 @@ openui deploy [dir] [options]
**Options**
-| Flag | Description |
-| ------------------ | ----------------------------------------------------------------------------- |
-| `-y, --yes` | Skip confirmation prompts (also saves missing env keys to the Vercel project) |
-| `--skip-env` | Do not pass or save local `.env` / `.env.local` values |
-| `--no-interactive` | Skip prompts (implies `--yes`) |
-| `--verbose` | Stream full Vercel build logs (hidden by default; failures print a log tail) |
-
-Extra flags after `deploy` are forwarded as-is to the target deployment platform, which validates them. `--skip-env` is OpenUI-specific so it does not collide with the target platform's env specific args.
+| Flag | Description |
+| ------------------ | ------------------------------------------------------------------------- |
+| `-y, --yes` | Skip confirmation prompts and save missing env keys to the Vercel project |
+| `--skip-env` | Don't pass or save local `.env` / `.env.local` values |
+| `--no-interactive` | Skip prompts (implies `--yes`) |
-Unlinked projects are linked to the platform first. Allowlisted keys from `.env` / `.env.local` that are missing on different deployment environments can be saved to the project (auto-accepted with `--yes`). Build logs are quiet by default; use `--verbose` to stream them.
+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.
```bash tab="pnpm" tab-group="pkg"
# Preview deploy from the project directory
@@ -272,7 +188,7 @@ pnpx @openuidev/cli@latest deploy
# Production deploy
pnpx @openuidev/cli@latest deploy --prod --yes
-# Deploy a specific directory without forwarding local env
+# Deploy a specific directory without local env
pnpx @openuidev/cli@latest deploy ./my-app --skip-env
```
@@ -283,7 +199,7 @@ bunx @openuidev/cli@latest deploy
# Production deploy
bunx @openuidev/cli@latest deploy --prod --yes
-# Deploy a specific directory without forwarding local env
+# Deploy a specific directory without local env
bunx @openuidev/cli@latest deploy ./my-app --skip-env
```
@@ -294,7 +210,7 @@ yarn dlx @openuidev/cli@latest deploy
# Production deploy
yarn dlx @openuidev/cli@latest deploy --prod --yes
-# Deploy a specific directory without forwarding local env
+# Deploy a specific directory without local env
yarn dlx @openuidev/cli@latest deploy ./my-app --skip-env
```
@@ -305,13 +221,13 @@ npx @openuidev/cli@latest deploy
# Production deploy
npx @openuidev/cli@latest deploy --prod --yes
-# Deploy a specific directory without forwarding local env
+# Deploy a specific directory without local env
npx @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 a project env file.
+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]
@@ -319,41 +235,37 @@ openui generate-api-key [options]
**Options**
-| Flag | Description |
-| --------------------- | -------------------------------------------------------------------------------------------------- |
-| `-f, --file <path>` | Env file to write (default: `.env`) |
-| `-k, --key <name>` | Environment variable name (default: `THESYS_API_KEY`) |
-| `-n, --name <string>` | Name of the minted key in the Thesys console (default: `package.json` name, or the directory name) |
+| Flag | Description |
+| --------------------- | ----------------------------------------------------------------------------------------------- |
+| `-f, --file <path>` | Env file to write (default: `.env`) |
+| `-k, --key <name>` | Environment variable name (default: `THESYS_API_KEY`) |
+| `-n, --name <string>` | Name of the key in the Thesys console (default: the `package.json` name, or the directory name) |
**Examples**
```bash tab="pnpm" tab-group="pkg"
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
```
```bash tab="bun" tab-group="pkg"
bunx @openuidev/cli@latest generate-api-key
bunx @openuidev/cli@latest generate-api-key --file .env.local
-bunx @openuidev/cli@latest generate-api-key --file .env.local --key THESYS_API_KEY
```
```bash tab="yarn" tab-group="pkg"
yarn dlx @openuidev/cli@latest generate-api-key
yarn dlx @openuidev/cli@latest generate-api-key --file .env.local
-yarn dlx @openuidev/cli@latest generate-api-key --file .env.local --key THESYS_API_KEY
```
```bash tab="npm" tab-group="pkg"
npx @openuidev/cli@latest generate-api-key
npx @openuidev/cli@latest generate-api-key --file .env.local
-npx @openuidev/cli@latest generate-api-key --file .env.local --key THESYS_API_KEY
```
## `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.
+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]
@@ -372,100 +284,77 @@ openui generate [entry] [options]
| `-o, --out <file>` | Write the prompt to `<file>`; the spec uses the same basename with a `.spec.json` extension |
| `--json-schema` | Output only the JSON schema; it is not the input to `generateSystemPrompt` |
| `--spec` | Output only the serialized library spec |
-| `--export <name>` | Name of the export to use (auto-detected by default) |
-| `--prompt-options <name>` | Name of the `PromptOptions` export to use (auto-detected by default) |
-| `--no-interactive` | Fail instead of prompting for missing `entry` |
-| `--agent-name <name>` | Declare the invoking coding-agent slug (default: `unknown`) |
+| `--export <name>` | Name of the library export to use |
+| `--prompt-options <name>` | Name of the `PromptOptions` export to use |
+| `--no-interactive` | Fail instead of prompting for a missing `entry` |
+
+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**
```bash tab="pnpm" tab-group="pkg"
-# Print system prompt to stdout
+# Print the system prompt to stdout
pnpx @openuidev/cli@latest generate ./src/library.ts
-# Write both artifacts; use the sibling .spec.json file with generateSystemPrompt
+# Write the prompt and its .spec.json alongside it
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
+# 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
```
```bash tab="bun" tab-group="pkg"
-# Print system prompt to stdout
+# Print the system prompt to stdout
bunx @openuidev/cli@latest generate ./src/library.ts
-# Write both artifacts; use the sibling .spec.json file with generateSystemPrompt
+# Write the prompt and its .spec.json alongside it
bunx @openuidev/cli@latest generate ./src/library.ts --out ./src/generated/system-prompt.txt
-# Output JSON schema for external tooling (not generateSystemPrompt)
-bunx @openuidev/cli@latest generate ./src/library.ts --json-schema
-
-# Output only the spec file
+# Output only the spec or the JSON schema
bunx @openuidev/cli@latest generate ./src/library.ts --spec
+bunx @openuidev/cli@latest generate ./src/library.ts --json-schema
# Explicit export names
bunx @openuidev/cli@latest generate ./src/library.ts --export myLibrary --prompt-options myOptions
```
```bash tab="yarn" tab-group="pkg"
-# Print system prompt to stdout
+# Print the system prompt to stdout
yarn dlx @openuidev/cli@latest generate ./src/library.ts
-# Write both artifacts; use the sibling .spec.json file with generateSystemPrompt
+# Write the prompt and its .spec.json alongside it
yarn dlx @openuidev/cli@latest generate ./src/library.ts --out ./src/generated/system-prompt.txt
-# Output JSON schema for external tooling (not generateSystemPrompt)
-yarn dlx @openuidev/cli@latest generate ./src/library.ts --json-schema
-
-# Output only the spec file
+# Output only the spec or the JSON schema
yarn dlx @openuidev/cli@latest generate ./src/library.ts --spec
+yarn dlx @openuidev/cli@latest generate ./src/library.ts --json-schema
# Explicit export names
yarn dlx @openuidev/cli@latest generate ./src/library.ts --export myLibrary --prompt-options myOptions
```
```bash tab="npm" tab-group="pkg"
-# Print system prompt to stdout
+# Print the system prompt to stdout
npx @openuidev/cli@latest generate ./src/library.ts
-# Write both artifacts; use the sibling .spec.json file with generateSystemPrompt
+# Write the prompt and its .spec.json alongside it
npx @openuidev/cli@latest generate ./src/library.ts --out ./src/generated/system-prompt.txt
-# Output JSON schema for external tooling (not generateSystemPrompt)
-npx @openuidev/cli@latest generate ./src/library.ts --json-schema
-
-# Output only the spec file
+# Output only the spec or the JSON schema
npx @openuidev/cli@latest generate ./src/library.ts --spec
+npx @openuidev/cli@latest generate ./src/library.ts --json-schema
# Explicit export names
npx @openuidev/cli@latest generate ./src/library.ts --export myLibrary --prompt-options myOptions
```
-### Export auto-detection
+### `PromptOptions`
-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
+Export a `PromptOptions` object next to your library to customize the generated system prompt.
```ts
interface PromptOptions {
@@ -482,9 +371,7 @@ interface PromptOptions {
}
```
-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`.
+Built-in functions (`@Count`, `@Filter`, `@Sort`, `@Each`, etc.) are included in the prompt only when `toolCalls` or `bindings` is enabled.
```ts
// src/library.ts
@@ -499,54 +386,50 @@ export const promptOptions: PromptOptions = {
};
```
+## `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**
+
+| Flag | Description |
+| --------------------------- | ------------------------------------ |
+| `-c, --category <category>` | `bug`, `feature`, `docs`, or `other` |
+
```bash tab="pnpm" tab-group="pkg"
-pnpx @openuidev/cli@latest generate ./src/library.ts --out src/generated/system-prompt.txt
+pnpx @openuidev/cli@latest feedback --category docs "The streaming guide doesn't cover partial components"
```
```bash tab="bun" tab-group="pkg"
-bunx @openuidev/cli@latest generate ./src/library.ts --out src/generated/system-prompt.txt
+bunx @openuidev/cli@latest feedback --category docs "The streaming guide doesn't cover partial components"
```
```bash tab="yarn" tab-group="pkg"
-yarn dlx @openuidev/cli@latest generate ./src/library.ts --out src/generated/system-prompt.txt
+yarn dlx @openuidev/cli@latest feedback --category docs "The streaming guide doesn't cover partial components"
```
```bash tab="npm" tab-group="pkg"
-npx @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. For `deploy`, analytics include the target (currently `vercel`), production vs preview, whether
-local env was passed (true/false), CLI resolution source, and process status — not env
-values, project paths, or command output.
-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; Gateway-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.
+npx @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](#create) and prints any follow-up commands, such as `generate-api-key`, at the end.
+
+## 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
<Cards>
<Card title="@openuidev/react-lang" href="/docs/api-reference/react-lang">
- `createLibrary`, `PromptOptions`, and the `Library` interface that `openui generate` read.
+ `createLibrary`, `PromptOptions`, and the `Library` interface that `openui generate` reads.
</Card>
</Cards>
-
-The backend framework picker shows examples marked `featured: true`
-in `examples/examples.json`, in catalog order. Select “More OpenUI Examples →” for the
-complete catalog, or pass any catalog name through `--example`.
diff --git a/docs/content/docs/build-agents/ui-generation.mdx b/docs/content/docs/build-agents/ui-generation.mdx
index c24f3b6fd..7adbd2ebd 100644
--- a/docs/content/docs/build-agents/ui-generation.mdx
+++ b/docs/content/docs/build-agents/ui-generation.mdx
@@ -60,41 +60,19 @@ npx @openuidev/cli@latest generate src/lib/openui.tsx --spec --out src/lib/openu
The specification lists each component and its props. Regenerate it whenever the library changes, for example in a `prebuild` script.
-## 4. Generate the system prompt
+## 4. Call the model
-`generateSystemPrompt` turns the specification into the instructions the agent needs to write OpenUI Lang. It produces one of two forms, depending on where the model request goes:
+`generateSystemPrompt` turns the specification into the instructions the agent needs to write OpenUI Lang. Send them as the system prompt and route the request through OpenUI Gateway, which corrects invalid OpenUI Lang as it streams and falls back to another provider when one is unavailable.
-```ts title="server.ts" tab="OpenUI Gateway (recommended)" tab-group="call-model"
+```ts title="server.ts"
+import OpenAI from "openai";
import { generateSystemPrompt, type LibrarySpec } from "@openuidev/lang-core";
import library from "./lib/openui.spec.json";
-// A compact configuration block. Gateway expands it into the full prompt.
const openuiInstructions = generateSystemPrompt({
cloud: true,
library: library as LibrarySpec,
});
-```
-
-```ts title="server.ts" tab="Your own provider" tab-group="call-model"
-import { generateSystemPrompt, type LibrarySpec } from "@openuidev/lang-core";
-import library from "./lib/openui.spec.json";
-
-// The complete prompt, ready to send to any model.
-const openuiInstructions = generateSystemPrompt({
- library: library as LibrarySpec,
-});
-```
-
-With `cloud: true`, Gateway assembles the prompt on its side and keeps it up to date with the language. Without it, the full prompt is generated locally and works with any provider.
-
-Pass `openuiInstructions` through the agent framework's system-instruction option. If the agent already has a system prompt, append the OpenUI instructions after it.
-
-## 5. Call the model
-
-Route model requests through Gateway to correct invalid OpenUI Lang as it streams and fall back to another provider when one is unavailable. To keep your own provider, repair the output with [Autofix](/docs/autofix) instead.
-
-```ts title="server.ts" tab="OpenUI Gateway (recommended)" tab-group="call-model"
-import OpenAI from "openai";
const gateway = new OpenAI({
apiKey: process.env.THESYS_API_KEY,
@@ -108,24 +86,9 @@ const completion = await gateway.chat.completions.create({
});
```
-```ts title="server.ts" tab="Your own provider" tab-group="call-model"
-import OpenAI from "openai";
-import { createAutofix } from "@openuidev/server/openai";
-
-const model = new OpenAI();
-const autofix = createAutofix({ apiKey: process.env.THESYS_API_KEY!, library });
-
-const source = await model.chat.completions.create({
- model: "gpt-5",
- messages: [{ role: "system", content: openuiInstructions }, ...messages],
- stream: true,
-});
-
-// Autofix adds the library itself, so pass only the conversation.
-const response = autofix.completions.stream({ stream: source, messages }).toResponse();
-```
+If the agent already has a system prompt, append the OpenUI instructions after it.
-Both options use a `THESYS_API_KEY`. Create one and write it to `.env` with:
+Generate an API key and write it to `.env` with:
```bash
npx @openuidev/cli@latest generate-api-key
@@ -133,7 +96,7 @@ npx @openuidev/cli@latest generate-api-key
Gateway is OpenAI-compatible, so agent frameworks that accept an OpenAI client or base URL can use it without other changes. See the [Gateway documentation](/docs/gateway) for supported models and APIs.
-## 6. Stream the response to the chat UI
+## 5. Stream the response to the chat UI
The agent's response is now OpenUI Lang text instead of Markdown. If the agent framework already streams text to its chat UI, keep that transport: nothing about it changes.
diff --git a/docs/content/docs/getting-started.mdx b/docs/content/docs/getting-started.mdx
index 06e010e9c..c5712cf9c 100644
--- a/docs/content/docs/getting-started.mdx
+++ b/docs/content/docs/getting-started.mdx
@@ -13,7 +13,7 @@ You need Node.js 20 or later. Run:
npx @openuidev/cli@latest create
```
-The interactive setup asks how to connect to a model and which agent framework to use, then creates the project, installs its dependencies, and can start the development server for you. See the [CLI reference](/docs/api-reference/cli) for templates, framework options, and deploying a preview.
+The setup asks which agent framework to use, then creates the project, installs its dependencies, and can start the development server for you. See the [CLI reference](/docs/api-reference/cli) for framework options and deploying a preview.
## End-to-end integration
@@ -51,7 +51,7 @@ The generated specification describes the available components and their propert
Generate the system prompt from the library specification and send it with the user's message.
-```ts title="server.ts" tab="OpenUI Gateway (recommended)" tab-group="call-model"
+```ts title="server.ts"
import OpenAI from "openai";
import { generateSystemPrompt } from "@openuidev/lang-core";
import library from "./lib/openui.spec.json";
@@ -71,37 +71,13 @@ const completion = await gateway.chat.completions.create({
});
```
-```ts title="server.ts" tab="OpenAI" tab-group="call-model"
-import OpenAI from "openai";
-import { generateSystemPrompt } from "@openuidev/lang-core";
-import { createAutofix } from "@openuidev/server/openai";
-import library from "./lib/openui.spec.json";
-
-const model = new OpenAI();
-const autofix = createAutofix({ apiKey: process.env.THESYS_API_KEY!, library });
-
-const messages = [{ role: "user" as const, content: "Compare quarterly revenue by region." }];
-
-const source = await model.chat.completions.create({
- model: "gpt-5",
- messages: [{ role: "system", content: generateSystemPrompt({ library }) }, ...messages],
- stream: true,
-});
-
-// Autofix adds the library itself, so pass only the conversation.
-// Return this from your API route as a server-sent events response.
-const response = autofix.completions.stream({ stream: source, messages }).toResponse();
-```
-
-Both examples use a `THESYS_API_KEY`. Run the command below to sign in with Thesys, create a key, and write it to your `.env` file. Keep the key on the server and never expose it to browser code.
+Generate an API key and write it to `.env` with the command below. Keep the key on the server and never expose it to browser code.
```bash
npx @openuidev/cli@latest generate-api-key
```
-The OpenAI example uses [Autofix](/docs/autofix) to repair invalid OpenUI Lang against your library before it reaches your application. Gateway does this for you as the response streams.
-
-You can also use Anthropic, Gemini, or any other LLM provider. Send the generated system prompt with your provider's SDK.
+Gateway repairs invalid OpenUI Lang as the response streams.
### 4. Render the UI
diff --git a/docs/content/docs/openui-lang/quickstart.mdx b/docs/content/docs/openui-lang/quickstart.mdx
index 459371d1e..9453d9ea5 100644
--- a/docs/content/docs/openui-lang/quickstart.mdx
+++ b/docs/content/docs/openui-lang/quickstart.mdx
@@ -14,14 +14,12 @@ The Gateway-backed starter already includes streaming chat, conversation history
search, image search, reports, presentations, and an example function tool.
You will keep those features and add one tool and one component.
-You need Node.js 20 or later and a Thesys account.
+You need Node.js 20 or later.
## 1. Create the app
```bash
-npx @openuidev/cli@latest create \
- --name recipe-remix \
- --template openui-cloud
+npx @openuidev/cli@latest create --name recipe-remix
```
Follow the prompts. The CLI signs you in, creates the project, installs its
diff --git a/docs/lib/demo-credits.ts b/docs/lib/demo-credits.ts
index 39075c1a4..db2699aa3 100644
--- a/docs/lib/demo-credits.ts
+++ b/docs/lib/demo-credits.ts
@@ -4,9 +4,9 @@ export const DEMO_CREDITS_EXHAUSTED_MESSAGE =
"We're recharging the hosted demo credits. Until then, please download the repo and run it locally to see the live demo.";
export const DEMO_CREDITS_LOCAL_COMMANDS = [
- "pnpm dlx @openuidev/cli@latest create --name openui-demo --template openui-self-hosted --no-interactive",
+ "pnpm dlx @openuidev/cli@latest create --name openui-demo --no-interactive",
"cd openui-demo",
- "# Configure OPENAI_API_KEY in .env.local",
+ "pnpm dlx @openuidev/cli@latest generate-api-key",
"pnpm dev",
] as const;
diff --git a/packages/openui-cli/README.md b/packages/openui-cli/README.md
index 0a008a113..62aefdaaa 100644
--- a/packages/openui-cli/README.md
+++ b/packages/openui-cli/README.md
@@ -1,24 +1,12 @@
# @openuidev/cli
-Command-line tools for starting OpenUI projects, minting OpenUI Cloud API keys, and generating model instructions from component libraries, and deploying apps to Vercel.
+Command-line tools for starting OpenUI projects, minting OpenUI Cloud API keys, generating model instructions from component libraries, and deploying apps to Vercel.
[![npm](https://img.shields.io/npm/v/@openuidev/cli)](https://www.npmjs.com/package/@openuidev/cli)
[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://github.com/thesysdev/openui/blob/main/LICENSE)
**Links:** [CLI docs](https://openui.com/docs/api-reference/cli) | [GitHub repo](https://github.com/thesysdev/openui)
-It currently supports:
-
-- scaffolding a new OpenUI app from one of two templates:
- - **OpenUI Cloud (recommended)** — hosted models with managed conversations, streaming, built-in tools, and ready-to-use report and presentation artifacts
- - **Self-hosted** — bring an OpenAI-compatible model key and own the AI route and persistence
-- using the default LangGraph backend or choosing Vercel AI SDK or Vercel Eve for either template
-- scaffolding an example from [OpenUI Examples](https://github.com/thesysdev/openui/blob/main/examples)
-- minting an OpenUI Cloud API key into an existing project's env file
-- sending anonymous feedback to the OpenUI team
-- generating a system prompt or JSON Schema from a `createLibrary()` export
-- deploying a project with `openui deploy`
-
## Install
Run the CLI with your package manager of choice:
@@ -27,67 +15,37 @@ Run the CLI with your package manager of choice:
npx @openuidev/cli@latest --help
pnpm dlx @openuidev/cli@latest --help
bunx @openuidev/cli@latest --help
+yarn dlx @openuidev/cli@latest --help
```
-## Quick Start
-
-Create a new app (you'll be prompted to pick a template):
+## Quick start
```bash
+# Create an app (prompts for anything you don't pass)
npx @openuidev/cli@latest create
-```
-
-Skip the prompt and pick a template directly:
-
-```bash
-npx @openuidev/cli@latest create --template openui-cloud
-npx @openuidev/cli@latest create --template openui-self-hosted
-```
-
-Choose a backend framework directly (the default is `langgraph`):
-
-```bash
-npx @openuidev/cli@latest create --template openui-cloud --backend-framework langgraph
-npx @openuidev/cli@latest create --template openui-cloud --backend-framework vercel-ai-sdk
-npx @openuidev/cli@latest create --template openui-cloud --backend-framework vercel-eve
-npx @openuidev/cli@latest create --template openui-self-hosted --backend-framework langgraph
-npx @openuidev/cli@latest create --template openui-self-hosted --backend-framework vercel-ai-sdk
-npx @openuidev/cli@latest create --template openui-self-hosted --backend-framework vercel-eve
-npx @openuidev/cli@latest create --example shadcn
-npx @openuidev/cli@latest create --example mastra
-```
-Mint an OpenUI Cloud API key into the current project's `.env`:
-
-```bash
+# Mint an OpenUI Cloud API key into the current project's .env
npx @openuidev/cli@latest generate-api-key
-npx @openuidev/cli@latest generate-api-key --file .env.local --key THESYS_API_KEY
-```
-Generate a prompt from a library file:
-
-```bash
+# Generate a system prompt from a component library
npx @openuidev/cli@latest generate ./src/library.ts
-```
-Generate JSON Schema instead:
-
-```bash
-npx @openuidev/cli@latest generate ./src/library.ts --json-schema
+# Deploy the current project to Vercel
+npx @openuidev/cli@latest deploy
```
-Deploy the current project:
+## Global options
-```bash
-npx @openuidev/cli@latest deploy
-npx @openuidev/cli@latest deploy --prod
-```
+- `--agent-name <name>`: Coding agents: declare your product slug, e.g. `codex` or `claude-code` (see [Coding agents](#coding-agents))
+- `--verbose`: Stream full command logs
+- `--no-telemetry`: Disable usage analytics (`DO_NOT_TRACK=1` also works)
+- `-V, --version`: Print the CLI version
## Commands
### `openui create`
-Scaffolds a new Next.js agent app from the recommended managed **OpenUI Cloud** template or the **self-hosted** template.
+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 `openui generate-api-key`.
```bash
openui create [options]
@@ -95,113 +53,40 @@ openui create [options]
Options:
-- `-n, --name <string>`: Project name (interactive default: `openui-agent`)
-- `-t, --template <template>`: AI backend — `openui-cloud` (managed) or `openui-self-hosted` (bring your provider)
-- `--backend-framework <framework>`: API route implementation — `langgraph` (default), `vercel-ai-sdk`, or `vercel-eve`
-- `-e, --example <example>`: Scaffold any example from `examples/examples.json`
-- `--skill`: Install the OpenUI agent skill for AI coding assistants
-- `--no-skill`: Skip installing the OpenUI agent skill
-- `--no-install`: Scaffold without running the package install
-- `-i, --immediate`: Start the development server after installing dependencies; the CLI refuses to start when the template's required API key is unavailable
-- `--no-immediate`: Install dependencies without starting the development server
-- `--no-interactive`: Fail instead of prompting for missing required input
-- `--api-key <key>`: (cloud templates and examples) OpenUI Cloud API key; skips sign-in
-- `--auth <method>`: (cloud templates and examples) How to obtain the key — `oauth` or `skip`; `manual` remains available for backward compatibility but is deprecated
-- `--agent-name <name>`: Declare the invoking coding agent as a lowercase kebab-case product slug (default: `unknown`)
+- `-n, --name <string>`: Project name (default: `openui-agent`)
+- `--backend-framework <framework>`: `langgraph` (default), `vercel-ai-sdk`, or `vercel-eve`
+- `-e, --example <example>`: Scaffold an OpenUI example instead (see below)
+- `--skill` / `--no-skill`: Install or skip the OpenUI agent skill for AI coding assistants
+- `--no-install`: Scaffold without installing dependencies
+- `-i, --immediate` / `--no-immediate`: Start, or don't start, the development server after installing
+- `--no-interactive`: Never prompt; use defaults for anything not passed
-`--immediate` and `--no-immediate` are mutually exclusive; passing both exits with an error.
+Backend frameworks:
-What it does:
+| Value | Description |
+| --------------- | ------------------------------------------ |
+| `langgraph` | LangGraph agent |
+| `vercel-ai-sdk` | Vercel AI SDK agent |
+| `vercel-eve` | Eve agent rendered through Agent Interface |
-- prompts for the project name, defaulting to `openui-agent`, if you do not pass `--name`
-- uses the `openui-cloud` template when you do not pass `--template` (interactive runs no longer ask; `--template openui-self-hosted` still works)
-- prompts for a backend framework or example after the template; non-interactive usage defaults to `langgraph`
-- copies the bundled template or example into a new directory
-- rewrites monorepo-local dependencies (`workspace:`, `file:`, `catalog:`) in the generated `package.json` to `latest`
-- installs dependencies automatically using the detected package manager (unless `--no-install`)
-- in interactive sessions, starts the development server and opens its local URL in the default browser; pass `--no-immediate` to install and exit instead
-- in non-interactive sessions, installs and exits unless `--immediate` is passed
-- optionally installs the OpenUI agent skill for AI coding assistants
-- writes a `.env` file tailored to the template (see below)
+Examples are loaded from [OpenUI Examples](https://github.com/thesysdev/openui/blob/main/examples). Pass `--example <name>` with any catalog folder name; it can't be combined with `--backend-framework`.
-#### Choose a backend
+In a terminal, `create` prompts for anything you didn't pass, installs dependencies, and starts the development server.
-- **OpenUI Cloud (recommended default)** — start here for prototypes and evaluations. You get hosted models, managed conversation history and streaming, built-in tools, and ready-to-use report and presentation artifacts without operating the model, storage, or artifact infrastructure.
-- **Self-hosted** — choose this when owning the OpenAI-compatible provider integration, AI route, and persistence is a requirement. It is not offered as an interactive choice; request it with `--template openui-self-hosted`.
-
-#### Backend frameworks
-
-Framework choices are loaded from the template catalog. LangGraph is the default; the SDK-only `default` option has been removed. Current templates ship:
-
-| Value | OpenUI Cloud route | Self-hosted route |
-| --------------- | -------------------------------------------- | ---------------------------------- |
-| `langgraph` | LangGraph + Cloud provider | LangGraph + your provider |
-| `vercel-ai-sdk` | Vercel AI SDK Next.js agent + Cloud provider | Vercel AI SDK `streamText()` route |
-| `vercel-eve` | Vercel Eve agent + Cloud provider | Vercel Eve agent + your provider |
-
-Each base template is a complete LangGraph app. The CLI copies it directly for LangGraph, or applies an overlay for Vercel AI SDK or Eve. LangGraph and Vercel AI SDK use Chat Completions; their native streams are decoded by the matching browser adapters.
-
-In Cloud framework variants, the selected framework owns agent orchestration and application tools such as `get_weather`. OpenUI Cloud supplies the Chat Completions model provider. These starters do not attach Responses-only provider tools. Choose `openui-self-hosted` to supply your own model provider.
-
-The Cloud graph needs `THESYS_API_KEY`; the self-hosted graph needs the selected provider credentials such as `OPENAI_API_KEY`.
-
-Every framework overlay includes `get_weather` as its example app-owned function tool. Ask “What’s the weather in Berlin?” to exercise the selected backend’s native tool loop.
-
-#### OpenUI examples
-
-Interactive `openui create` offers featured [OpenUI examples](https://github.com/thesysdev/openui/blob/main/examples). Pass `--example <name>` to skip the menus. `--example` cannot be combined with `--template` or `--backend-framework`.
-
-```bash
-openui create --example shadcn
-openui create --name my-mastra-app --example mastra
-openui create --example vue
-```
-
-Examples whose primary key is `THESYS_API_KEY` offer the same browser sign-in and key generation as Cloud templates. Use `--api-key <key>` to supply a key or `--auth skip` to configure it later. Other provider keys still use the existing paste prompt.
-
-The example catalog uses `env: { "file": "backend/.env", "key": "THESYS_API_KEY" }`. The `file` is a relative `.env` or `.env.local` path (default: `.env`); `key` is the primary API key to prompt for. FastAPI and React Native write the key to `backend/.env`; Supabase uses `.env.local`. Other variables in the example's env file are preserved.
-
-#### Conversation storage
-
-Cloud conversations are created and read by the browser through `useOpenuiCloudStorage()` with a short-lived frontend token. The LangGraph `afterAgent` middleware calls `storeLangGraphHistory` once after success to save the complete new turn: user message, assistant messages, tool calls, and tool results. Failed or stopped runs are not persisted. LangGraph and Vercel AI SDK routes receive the full message history on each request and use stateless Chat Completions. Add a LangGraph checkpointer only for graph-specific durable state, interrupts, or resumable runs.
-
-The self-hosted variants do not configure durable storage. `AgentInterface` keeps the conversation in memory for the current page session and sends that history to `/api/chat`; refreshing the page loses it. 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.
-
-#### Template-specific `.env`
-
-- **OpenUI Cloud** — obtains an OpenUI Cloud API key and writes `THESYS_API_KEY` plus `DEMO_USER_ID=demo-user` to `.env`. The key is resolved by, in order:
- - `--api-key <key>` if provided
- - the `--auth` method, otherwise an interactive prompt offering:
- - `oauth` — sign in with Thesys in the browser and mint a key for your org
- - `skip` — leave `THESYS_API_KEY` empty and add it later (get one at <https://console.thesys.dev/keys>)
- - `--auth manual` is deprecated but remains available for backward compatibility; use `--api-key` for scripted setup instead
- - in non-interactive mode without `--api-key`, the cloud template fails because a key is required
-- **Self-hosted** — prompts for your OpenAI-compatible provider API key and writes `OPENAI_API_KEY` to `.env` (interactive mode only). Leave blank to skip.
+When nobody can answer prompts (`--no-interactive`, no terminal attached, or a coding agent running the CLI), it takes the defaults instead: `langgraph` and `openui-agent` (or the next free `openui-agent-<n>`). It installs dependencies without starting the server, skips Cloud sign-in, and ends with the `generate-api-key` command to run next. An explicit `--name` that already exists is an error.
Examples:
```bash
openui create
-openui create --name my-app --template openui-self-hosted
-openui create --name my-app --template openui-self-hosted --backend-framework langgraph
-openui create --name my-app --template openui-self-hosted --backend-framework vercel-ai-sdk
-openui create --name my-app --template openui-self-hosted --backend-framework vercel-eve
-openui create --name my-app --template openui-cloud --auth oauth
-openui create --name my-app --template openui-cloud --backend-framework langgraph --auth oauth
-openui create --name my-app --template openui-cloud --backend-framework vercel-ai-sdk --auth oauth
-openui create --name my-app --template openui-cloud --backend-framework vercel-eve --auth oauth
-openui create --name my-shadcn-app --example shadcn
-openui create --name my-app --template openui-cloud --api-key tk_your_key
-openui create --name my-app --template openui-self-hosted
-openui create --name my-app --template openui-cloud --immediate
-openui create --name my-app --template openui-cloud --no-immediate
-openui create --name my-app --no-skill --no-install
-openui create --no-interactive --name my-app --template openui-cloud --api-key tk_your_key
+openui create --name my-app --backend-framework vercel-ai-sdk
+openui create --name my-app --example shadcn
+openui create --no-interactive --name my-app
```
### `openui deploy`
-Deploys an OpenUI project. The default platform supported is **Vercel**.
+Deploys an OpenUI project to Vercel.
```bash
openui deploy [dir] [options]
@@ -213,25 +98,21 @@ Arguments:
Options:
-- `-y, --yes`: Skip confirmation prompts (also saves missing env keys to the Vercel project)
-- `--skip-env`: Do not pass or save local `.env` / `.env.local` values
+- `-y, --yes`: Skip confirmation prompts and save missing env keys to the Vercel project
+- `--skip-env`: Don't pass or save local `.env` / `.env.local` values
- `--no-interactive`: Skip prompts (implies `--yes`)
-- `--verbose`: Stream full Vercel build logs (hidden by default; failure still prints a log tail)
-
-Extra flags after `deploy` are forwarded as-is to the target deployment platform, which validates them. `--skip-env` is OpenUI-specific so it does not collide with the target platform's env specific args.
-Unlinked projects are linked to the platform first. Allowlisted keys from `.env` / `.env.local` that are missing on different deployment environments can be saved to the project (auto-accepted with `--yes`). Build logs are quiet by default; use `--verbose` to stream them.
+Any other flags, such as `--prod`, are passed through to Vercel. Unlinked projects are linked first.
```bash
openui deploy
-openui deploy ./my-app
openui deploy ./my-app --prod
openui deploy --skip-env -- --force
```
### `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.
+Signs in with Thesys in the browser, mints an OpenUI Cloud 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.
```bash
openui generate-api-key [options]
@@ -240,41 +121,17 @@ openui generate-api-key [options]
Options:
- `-f, --file <path>`: Env file to write (default: `.env`)
-- `-k, --key <name>`: Environment variable name (default: `THESYS_API_KEY`; letters, digits, and underscores)
-- `-n, --name <string>`: Name of the minted key in the Thesys console (default: `package.json` name, or the current directory name)
-
-Examples:
+- `-k, --key <name>`: Environment variable name (default: `THESYS_API_KEY`)
+- `-n, --name <string>`: Name of the key in the Thesys console (default: the `package.json` name, or the directory name)
```bash
openui generate-api-key
openui generate-api-key --file .env.local
-openui generate-api-key --file .env.local --key THESYS_API_KEY
-```
-
-### `openui feedback`
-
-Sends anonymous feedback about OpenUI to the OpenUI team.
-
-```bash
-openui feedback [options] <message...>
-```
-
-Options:
-
-- `-c, --category <category>`: `bug`, `feature`, `docs`, or `other`
-
-Feedback is anonymous: 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.
-
-Examples:
-
-```bash
-openui feedback "The streaming docs don't explain how to handle partial components"
-openui --agent-name codex feedback --category bug "Renderer throws when a streamed component closes before its props"
```
### `openui generate`
-Generates a system prompt and serialized library spec from a file that exports a `createLibrary()` result. Use the spec with `generateSystemPrompt` in backend routes; the prompt file remains available for static or legacy integrations.
+Generates a system prompt and serialized library spec from a file that exports a `createLibrary()` result. Use the spec with `generateSystemPrompt` in backend routes.
```bash
openui generate [options] [entry]
@@ -286,91 +143,47 @@ Arguments:
Options:
-- `-o, --out <file>`: Write the prompt to a file and the spec alongside it with the extension replaced by `.spec.json`
-- `--json-schema`: Output only JSON Schema instead of the prompt and spec
+- `-o, --out <file>`: Write the prompt to a file, with the spec alongside it as `.spec.json`
+- `--json-schema`: Output only the JSON Schema
- `--spec`: Output only the serialized library spec
-- `--export <name>`: Use a specific export name instead of auto-detecting the library export
-- `--prompt-options <name>`: Use a specific `PromptOptions` export name (auto-detected by default)
+- `--export <name>`: Library export to use (default: `library`, then `default`, then any library export)
+- `--prompt-options <name>`: `PromptOptions` export to use (default: `promptOptions`, then `options`, then any export ending in `PromptOptions`)
- `--no-interactive`: Fail instead of prompting for a missing `entry`
-- `--agent-name <name>`: Declare the invoking coding agent as a lowercase kebab-case product slug (default: `unknown`)
-
-What it does:
-
-- prompts for the entry file path if you do not pass one
-- bundles the entry with `esbuild` before evaluating it in Node
-- supports both TypeScript and JavaScript entry files
-- stubs common asset imports such as CSS, SVG, images, and fonts during bundling
-- auto-detects the exported library by checking `library`, `default`, and then all exports
-- auto-detects a `PromptOptions` export (with `examples`, `additionalRules`, or `preamble`) and passes it to `library.prompt()`
-
-Examples:
```bash
openui generate ./src/library.ts
-openui generate ./src/library.ts --json-schema
+openui generate ./src/library.ts --out ./src/generated/system-prompt.txt
openui generate ./src/library.ts --spec
-openui generate ./src/library.ts --export library
-openui generate ./src/library.ts --out ./artifacts/system-prompt.txt
-openui generate ./src/library.ts --prompt-options myPromptOptions
-openui generate --no-interactive ./src/library.ts
+openui generate ./src/library.ts --json-schema
+openui generate ./src/library.ts --export myLibrary --prompt-options myPromptOptions
```
-## How `generate` resolves exports
-
-`openui generate` expects the target module to export a library object with `prompt()`, `toSpec()`, and `toJSONSchema()` methods.
-
-If `--export` is not provided, it looks for exports in this order:
-
-1. `library`
-2. `default`
-3. any other export that matches the expected library shape
-
-### PromptOptions auto-detection
-
-If `--prompt-options` is not provided, the CLI looks for a `PromptOptions` export in this order:
-
-1. `promptOptions`
-2. `options`
-3. any export whose name ends with `PromptOptions` (case-insensitive)
-
-A valid `PromptOptions` object has at least one of: `examples` (string array), `additionalRules` (string array), or `preamble` (string).
-
-## Local Development
+### `openui feedback`
-Build the CLI locally:
+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.
```bash
-pnpm run build
+openui feedback [options] <message...>
```
-Run the built CLI:
+Options:
+
+- `-c, --category <category>`: `bug`, `feature`, `docs`, or `other`
```bash
-node dist/index.js --help
-node dist/index.js create --help
-node dist/index.js deploy --help
-node dist/index.js generate-api-key --help
-node dist/index.js generate --help
+openui feedback "The streaming docs don't explain how to handle partial components"
+openui --agent-name codex feedback --category bug "Renderer throws when a streamed component closes before its props"
```
-## Telemetry
-
-The CLI sends usage analytics; OAuth sign-ins may link usage to your OIDC account ID. It does not send code, prompts, API keys, email, or personal names.
+## Coding agents
-When a coding agent invokes the CLI, it should pass `--agent-name` using its stable, lowercase kebab-case product slug—for example, `codex`, `claude-code`, `cline`, `factory-droid`, or `pi`. Do not pass a model/version, user name, session ID, or other unique value. Humans can omit the flag; it defaults to `unknown`.
+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.
-Telemetry includes both `agent_name` (the CLI declaration) and `detected_agent_name` (best-effort environment detection). Either can be spoofed, inherited, missing, or ambiguous; neither is an authentication signal. Every invocation gets an ephemeral, unpersisted `cli_run_id` so its events can be correlated. Failure events include bounded `failure_stage`, `error_class`, and `error_code` values, never 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. For `create`, telemetry also includes `package_manager`, the immediate-start selection, and best-effort dev-command start and result events. Dev-command events contain status, duration, exit code, and signal—not project paths, command output, code, or environment values. For `deploy`, telemetry includes the target (currently `vercel`), production vs preview, whether the Vercel CLI was logged in, whether local env was passed, CLI resolution source, and process status; not env values, project paths, or command output. Disable telemetry with `--no-telemetry` or `DO_NOT_TRACK=1`.
+`create` never waits on a prompt when an agent runs it, whether or not `--agent-name` is passed. It takes the non-interactive defaults and prints any follow-up commands at the end.
-```bash
-openui create --no-telemetry
-```
-
-## Notes
+## Telemetry
-- interactive prompts can be cancelled without creating output
-- `create` fetches `templates/templates.json` and the selected template from GitHub (`thesysdev/openui@main`)
-- `generate` exits with a non-zero code if the file is missing or no valid library export is found
-- `deploy` exits with a non-zero code if the directory has no `package.json` or the Vercel CLI fails
+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`.
## Documentation
@@ -381,7 +194,3 @@ openui create --no-telemetry
## License
[MIT](https://github.com/thesysdev/openui/blob/main/LICENSE)
-
-The backend framework picker shows examples marked `featured: true`
-in `examples/examples.json`, in catalog order. Select “More OpenUI Examples →” for the
-complete catalog, or pass any catalog name through `--example`.
diff --git a/packages/openui-cli/package.json b/packages/openui-cli/package.json
index 7f196611c..917e3e8eb 100644
--- a/packages/openui-cli/package.json
+++ b/packages/openui-cli/package.json
@@ -51,6 +51,7 @@
"dependencies": {
"@inquirer/core": "^11.1.5",
"@inquirer/prompts": "^8.3.0",
+ "@vercel/detect-agent": "1.2.6",
"commander": "^14.0.3",
"cross-spawn": "^7.0.6",
"dotenv": "^17.2.2",
diff --git a/packages/openui-cli/src/commands/create/command.ts b/packages/openui-cli/src/commands/create/command.ts
index 42d0c8379..8c8501b85 100644
--- a/packages/openui-cli/src/commands/create/command.ts
+++ b/packages/openui-cli/src/commands/create/command.ts
@@ -1,6 +1,5 @@
import { Command } from "commander";
-import { normalizeAuth } from "../../lib/auth/mint";
import { context } from "../../lib/context";
import { rejectConflictingScaffoldSelectors } from "./lib/examples-catalog";
import { printCreateHelp } from "./lib/help";
@@ -10,17 +9,16 @@ import { runCreateApp } from "./run";
export const createCommand = new Command("create")
.description(
- "Scaffold a Next.js agent app with the recommended OpenUI Cloud backend or your own provider",
+ "Scaffold a generative UI agent with Next.js and your choice of agent framework.\n" +
+ "No account or API key is needed to scaffold. Add the key afterwards:\n" +
+ " openui generate-api-key",
)
- .option("-n, --name <string>", "Project name (interactive default: openui-agent)")
- .option("-t, --template <template>", "AI backend to use (default: openui-cloud)")
+ .option("-n, --name <string>", "Project name (default: openui-agent)")
.option("--backend-framework <framework>", "Backend framework to use (default: langgraph)")
.option("-e, --example <example>", "Create from an example in examples/examples.json")
- .option("--api-key <key>", "OpenUI Cloud API key (cloud templates and examples; skips sign-in)")
- .option("--auth <method>", "Cloud auth method: oauth | skip (manual is deprecated)")
.option("--skill", "Install the OpenUI agent skill for AI coding assistants")
.option("--no-skill", "Skip installing the OpenUI agent skill")
- .option("--no-interactive", "Fail with error if required args are missing")
+ .option("--no-interactive", "Never prompt; use defaults for anything not passed")
.option("--no-install", "Scaffold without running the package install")
.option("-i, --immediate", "Start the development server after installing dependencies")
.option("--no-immediate", "Install dependencies without starting the development server")
@@ -29,11 +27,8 @@ export const createCommand = new Command("create")
.action(
async (options: {
name?: string;
- template?: string;
backendFramework?: string;
example?: string;
- apiKey?: string;
- auth?: string;
skill?: boolean;
interactive: boolean;
install: boolean;
@@ -49,19 +44,14 @@ export const createCommand = new Command("create")
rejectConflictingScaffoldSelectors({
example: options.example,
backendFramework: options.backendFramework,
- template: options.template,
});
await runCreateApp(
{
name: options.name,
- template: options.template,
backendFramework: options.backendFramework,
example: options.example,
- apiKey: options.apiKey,
- auth: normalizeAuth(options.auth),
skill: options.skill,
- noInteractive: !options.interactive,
noInstall: !options.install,
immediate: options.immediate,
},
diff --git a/packages/openui-cli/src/commands/create/lib/create-example.ts b/packages/openui-cli/src/commands/create/lib/create-example.ts
index c48c740db..ef626ff3f 100644
--- a/packages/openui-cli/src/commands/create/lib/create-example.ts
+++ b/packages/openui-cli/src/commands/create/lib/create-example.ts
@@ -7,6 +7,7 @@ import type { CreateAppOptions, EnvResult } from "./create-types";
import { resolveCloudEnv, writeEnvVar } from "./env";
import type { ExampleProject } from "./examples-catalog";
import { installRequestedSkill, shouldInstallSkill } from "./install-skill";
+import { missingCloudKeyNote } from "./messages";
import {
exampleDevCommand,
exampleLayout,
@@ -19,6 +20,7 @@ import type { CreateTelemetryClient } from "./telemetry";
export async function runCreateExample(params: {
options: CreateAppOptions;
interactive: boolean;
+ agent?: string;
packageManager: ReturnType<typeof resolveInstallPackageManager>;
t0: number;
name: string;
@@ -27,8 +29,18 @@ export async function runCreateExample(params: {
tel: CreateTelemetryClient;
verbose: boolean;
}): Promise<void> {
- const { options, interactive, packageManager, t0, name, targetDir, example, tel, verbose } =
- params;
+ const {
+ options,
+ interactive,
+ agent,
+ packageManager,
+ t0,
+ name,
+ targetDir,
+ example,
+ tel,
+ verbose,
+ } = params;
tel.registerContext({ example: example.name, project_category: "example" });
tel.trackExampleSelected({
@@ -37,7 +49,7 @@ export async function runCreateExample(params: {
});
tel.trackEnvResolutionStarted({ example: example.name });
- const envResult = await resolveExampleEnv(example, name, options, interactive, tel);
+ const envResult = await resolveExampleEnv(example, name, options, interactive, agent, tel);
const installSkill = await shouldInstallSkill(options.skill, false);
tel.trackSkillInstalled({ skill_installed: installSkill });
@@ -132,12 +144,7 @@ export async function runCreateExample(params: {
auth_succeeded: envResult.authSucceeded,
dependency_installed: false,
});
- const envKey = example.env.key;
- const envNote = envKey
- ? envResult.envWritten
- ? `✅ ${example.env.file} updated with ${envKey}.`
- : `Add ${envKey}=… to ${example.env.file} (see the example README).`
- : `Add your API keys to ${example.env.file} (see the example README).`;
+ const envNote = exampleEnvNote(example.env, envResult.envWritten, name, packageManager.dlxCmd);
const skillMessage = skillInstalled
? "The OpenUI agent skill was installed.\nAI coding assistants will use it to help you build with OpenUI.\n"
: "";
@@ -161,6 +168,7 @@ async function resolveExampleEnv(
name: string,
options: CreateAppOptions,
interactive: boolean,
+ agent: string | undefined,
tel: CreateTelemetryClient,
): Promise<EnvResult & { envKeyValue?: string }> {
if (!example.env.key) {
@@ -172,6 +180,7 @@ async function resolveExampleEnv(
name,
{ ...options, envFile: example.env.file },
interactive,
+ agent,
tel,
);
return { ...result, envKeyValue: result.envVars?.[example.env.key] || undefined };
@@ -202,6 +211,18 @@ async function promptForProviderKey(envKey: string): Promise<string | null> {
}
}
+function exampleEnvNote(
+ env: ExampleProject["env"],
+ envWritten: boolean,
+ name: string,
+ dlxCmd: string,
+): string {
+ if (!env.key) return `Add your API keys to ${env.file} (see the example README).`;
+ if (envWritten) return `✅ ${env.file} updated with ${env.key}.`;
+ if (env.key === "THESYS_API_KEY") return missingCloudKeyNote(name, dlxCmd, env.file);
+ return `Add ${env.key}=… to ${env.file} (see the example README).`;
+}
+
function posixJoin(...parts: string[]): string {
return parts.filter((part) => part && part !== ".").join("/");
}
diff --git a/packages/openui-cli/src/commands/create/lib/create-types.ts b/packages/openui-cli/src/commands/create/lib/create-types.ts
index ff73a790d..b4efd131c 100644
--- a/packages/openui-cli/src/commands/create/lib/create-types.ts
+++ b/packages/openui-cli/src/commands/create/lib/create-types.ts
@@ -1,4 +1,4 @@
-import type { CloudAuthMethod, ResolvedAuthMethod } from "../../../lib/auth/mint";
+import type { ResolvedAuthMethod } from "../../../lib/auth/mint";
/** Template `key` from `templates/templates.json`. */
export type TemplateName = string;
@@ -7,16 +7,12 @@ export type OverlayName = string;
export interface CreateAppOptions {
name?: string;
- template?: TemplateName;
backendFramework?: OverlayName;
example?: string;
skill?: boolean;
- noInteractive?: boolean;
noInstall?: boolean;
immediate?: boolean;
- apiKey?: string;
envFile?: string;
- auth?: CloudAuthMethod;
}
export type AiSetup = "openui_cloud" | "openai_compatible_provider";
diff --git a/packages/openui-cli/src/commands/create/lib/env.ts b/packages/openui-cli/src/commands/create/lib/env.ts
index 87896a3b3..a69e4ce0b 100644
--- a/packages/openui-cli/src/commands/create/lib/env.ts
+++ b/packages/openui-cli/src/commands/create/lib/env.ts
@@ -4,7 +4,7 @@ import * as path from "node:path";
import { resolveCloudApiKey, THESYS_KEYS_URL } from "../../../lib/auth/mint";
import { DEFAULT_ENV_FILE, upsertEnvVar } from "../../../lib/env";
import { CliCancelledError, cliErrorProperties } from "../../../lib/errors";
-import type { CreateAppOptions, EnvResult, TemplateName } from "./create-types";
+import type { CreateAppOptions, EnvResult } from "./create-types";
import type { CreateTelemetryClient } from "./telemetry";
export function buildAppId(name: string): string {
@@ -15,10 +15,6 @@ export function buildAppId(name: string): string {
return `${slug}-${Math.random().toString(36).slice(2, 8)}`;
}
-export function requiredApiKeyEnv(template: TemplateName): "THESYS_API_KEY" | "OPENAI_API_KEY" {
- return template === "openui-cloud" ? "THESYS_API_KEY" : "OPENAI_API_KEY";
-}
-
export function writeEnvVar(filePath: string, name: string, value: string): void {
upsertEnvVar(filePath, name, value);
}
@@ -46,65 +42,24 @@ export async function writeEnv(
}
}
-async function promptForProviderKey(): Promise<string | null> {
- try {
- const { input } = await import("@inquirer/prompts");
- const apiKey = (
- await input({
- message: "Enter your OpenAI-compatible provider API key (leave blank to skip):",
- })
- ).trim();
- return apiKey || null;
- } catch (error) {
- const { ExitPromptError } = await import("@inquirer/core");
- if (error instanceof ExitPromptError) {
- throw new CliCancelledError("environment_resolution");
- }
- throw error;
- }
-}
-
-export async function resolveChatEnv(interactive: boolean): Promise<EnvResult> {
- const apiKey = interactive ? await promptForProviderKey() : null;
-
- // Always write a file, so the scaffold has a .env to edit rather than one the
- // user must know to create. Without a key the entries stay commented out: an
- // empty `OPENAI_API_KEY=` would shadow a key already exported in the shell.
- if (apiKey) {
- return { envWritten: true, envVars: { OPENAI_API_KEY: apiKey } };
- }
-
- return {
- // False without a key, so the immediate dev-server gate and the
- // "add your API key" message still apply even though .env now exists.
- envWritten: false,
- envStub: [
- "# Your OpenAI-compatible provider key. Uncomment and fill it in.",
- "# OPENAI_API_KEY=sk-your-key-here",
- "# Optional:",
- "# OPENAI_MODEL=gpt-5.2",
- "# OPENAI_BASE_URL=https://api.openai.com/v1",
- "",
- ].join("\n"),
- };
-}
-
export async function resolveCloudEnv(
name: string,
options: CreateAppOptions,
interactive: boolean,
+ agent: string | undefined,
tel: CreateTelemetryClient,
): Promise<EnvResult> {
const envFile = options.envFile ?? DEFAULT_ENV_FILE;
+ if (!interactive) {
+ console.info(
+ `${agent ? "Coding agent detected" : "Non-interactive run"} — skipping OpenUI Cloud sign-in.`,
+ );
+ }
let apiKey: string | null = null;
let authMethod: EnvResult["authMethod"];
try {
- tel.trackCloudAuthStarted({
- auth_method: options.auth ?? (options.apiKey ? "apikey-flag" : undefined),
- });
+ tel.trackCloudAuthStarted();
const resolved = await resolveCloudApiKey({
- apiKey: options.apiKey,
- auth: options.auth,
projectName: name,
envFile,
interactive,
@@ -119,7 +74,6 @@ export async function resolveCloudEnv(
} catch (err) {
if (err instanceof CliCancelledError) {
tel.trackCloudAuthCancelled({
- auth_method: options.auth ?? (options.apiKey ? "apikey-flag" : undefined),
auth_succeeded: false,
...cliErrorProperties(err),
});
@@ -132,7 +86,6 @@ export async function resolveCloudEnv(
error_code: "AUTH_FAILED",
});
tel.trackCloudAuthFailed({
- auth_method: options.auth ?? (options.apiKey ? "apikey-flag" : undefined),
auth_succeeded: false,
...properties,
});
diff --git a/packages/openui-cli/src/commands/create/lib/examples-catalog.ts b/packages/openui-cli/src/commands/create/lib/examples-catalog.ts
index 84d6be357..2df3ac788 100644
--- a/packages/openui-cli/src/commands/create/lib/examples-catalog.ts
+++ b/packages/openui-cli/src/commands/create/lib/examples-catalog.ts
@@ -193,7 +193,6 @@ export function findExample(name: string, examples: ExampleProject[]): ExamplePr
export function rejectConflictingScaffoldSelectors(opts: {
example?: string;
backendFramework?: string;
- template?: string;
}): void {
if (opts.example && opts.backendFramework) {
throw new CreateError(
@@ -203,14 +202,6 @@ export function rejectConflictingScaffoldSelectors(opts: {
"CONFLICTING_SCAFFOLD_SELECTORS",
);
}
- if (opts.example && opts.template) {
- throw new CreateError(
- "bad_args",
- "Cannot use --example with --template. Choose one scaffold selector.",
- "invalid_input",
- "CONFLICTING_SCAFFOLD_SELECTORS",
- );
- }
}
function categoryLabel(key: string): string {
diff --git a/packages/openui-cli/src/commands/create/lib/help.ts b/packages/openui-cli/src/commands/create/lib/help.ts
index be7124032..ab269fdd3 100644
--- a/packages/openui-cli/src/commands/create/lib/help.ts
+++ b/packages/openui-cli/src/commands/create/lib/help.ts
@@ -8,31 +8,18 @@ import {
type HelpEntry = { key: string; description: string };
-const FALLBACK_TEMPLATES: HelpEntry[] = [
- {
- key: "openui-cloud",
- description:
- "Recommended default for prototypes and evaluations. Hosted models, managed conversation history, built-in tools, and ready-to-use reports and presentations.",
- },
- {
- key: "openui-self-hosted",
- description:
- "Choose when owning the OpenAI-compatible provider, AI route, and persistence is a requirement. Available only via --template; interactive runs default to openui-cloud.",
- },
-];
-
const FALLBACK_FRAMEWORKS: HelpEntry[] = [
{
key: "langgraph",
- description: "Default. Bootstraps a LangGraph agent with the selected model backend.",
+ description: "Default. Bootstraps a LangGraph agent.",
},
{
key: "vercel-ai-sdk",
- description: "Scaffolds a Vercel AI SDK agent with the selected model backend.",
+ description: "Scaffolds a Vercel AI SDK agent.",
},
{
key: "vercel-eve",
- description: "Scaffolds a Vercel Eve agent with the selected model backend.",
+ description: "Scaffolds a Vercel Eve agent.",
},
];
@@ -56,15 +43,6 @@ async function loadCreateHelpText(): Promise<string> {
const sections: string[] = [];
try {
const templates = await loadTemplatesCatalog();
- sections.push(
- formatSection(
- "Templates:",
- templates.map((template) => ({
- key: template.key,
- description: template.description,
- })),
- ),
- );
sections.push(
formatSection(
"Backend frameworks:",
@@ -75,7 +53,6 @@ async function loadCreateHelpText(): Promise<string> {
),
);
} catch {
- sections.push(formatSection("Templates:", FALLBACK_TEMPLATES));
sections.push(formatSection("Backend frameworks:", FALLBACK_FRAMEWORKS));
sections.push(" Live catalog could not be fetched.");
}
diff --git a/packages/openui-cli/src/commands/create/lib/messages.ts b/packages/openui-cli/src/commands/create/lib/messages.ts
index c64d4bacd..766c9345d 100644
--- a/packages/openui-cli/src/commands/create/lib/messages.ts
+++ b/packages/openui-cli/src/commands/create/lib/messages.ts
@@ -1,13 +1,29 @@
import { THESYS_KEYS_URL } from "../../../lib/auth/mint";
-import type { TemplateName } from "./create-types";
+import { DEFAULT_ENV_FILE } from "../../../lib/env";
+
+export function missingCloudKeyNote(
+ projectDir: string,
+ dlxCmd: string,
+ envFile = DEFAULT_ENV_FILE,
+): string {
+ const fileArg = envFile === DEFAULT_ENV_FILE ? "" : ` --file ${envFile}`;
+ return [
+ `[!] No OpenUI Cloud API key added. Sign in and write one to ${envFile} with:`,
+ `> cd ${projectDir}`,
+ `> ${dlxCmd} @openuidev/cli@latest generate-api-key${fileArg}`,
+ `(or create one at ${THESYS_KEYS_URL} and set THESYS_API_KEY yourself)`,
+ ].join("\n");
+}
export function getStartedMessage(o: {
name: string;
devCmd: string;
- template: TemplateName;
+ dlxCmd: string;
backendGettingStarted?: string;
skillInstalled: boolean;
envWritten: boolean;
+ /** A key is in `.env` or already exported in the shell. */
+ apiKeyAvailable: boolean;
startDev: boolean;
installCmd: string;
dependencyInstalled: boolean;
@@ -16,26 +32,33 @@ export function getStartedMessage(o: {
? "The OpenUI agent skill was installed.\nAI coding assistants will use it to help you build with OpenUI.\n"
: "";
- const envNote =
- o.template === "openui-cloud"
- ? o.envWritten
- ? "✅ .env created with your OpenUI Cloud API key + base URL."
- : `[!] .env created without a key. Add THESYS_API_KEY=… (get one at ${THESYS_KEYS_URL}).`
- : o.envWritten
- ? "✅ .env created with your API key."
- : "Add your API key to .env:\nOPENAI_API_KEY=sk-your-key-here";
-
- const nextStep = o.startDev
- ? `Starting the development server in "${o.name}"...\n\n> ${o.devCmd} run dev`
+ const envNote = o.envWritten ? "✅ .env created with your OpenUI Cloud API key + base URL." : "";
+
+ // Without a key the app can't answer yet, so the key step replaces the usual
+ // next steps and goes last, where it's read.
+ const nextStep = !o.apiKeyAvailable
+ ? ""
+ : o.startDev
+ ? `Starting the development server in "${o.name}"...\n\n> ${o.devCmd} run dev`
+ : [
+ `> cd ${o.name}`,
+ ...(o.dependencyInstalled ? [] : [`> ${o.installCmd}`]),
+ `> ${o.devCmd} run dev`,
+ ].join("\n");
+
+ const keyStep = o.apiKeyAvailable
+ ? ""
: [
+ "Next, add your OpenUI API key. This signs you in and writes THESYS_API_KEY to .env:",
+ "",
`> cd ${o.name}`,
...(o.dependencyInstalled ? [] : [`> ${o.installCmd}`]),
+ `> ${o.dlxCmd} @openuidev/cli@latest generate-api-key`,
`> ${o.devCmd} run dev`,
].join("\n");
- const deployHint = "Share a preview:\n> npx @openuidev/cli@latest deploy";
- const feedbackHint =
- 'Found a bug or have an idea?\n> npx @openuidev/cli@latest feedback "<message>"';
+ const deployHint = `Share a preview:\n> ${o.dlxCmd} @openuidev/cli@latest deploy`;
+ const feedbackHint = `Found a bug or have an idea?\n> ${o.dlxCmd} @openuidev/cli@latest feedback "<message>"`;
const frameworkNote = o.backendGettingStarted?.replaceAll("{{packageManager}}", o.devCmd) ?? "";
@@ -47,6 +70,7 @@ export function getStartedMessage(o: {
nextStep,
deployHint,
feedbackHint,
+ keyStep,
]
.filter(Boolean)
.join("\n\n")}\n`;
diff --git a/packages/openui-cli/src/commands/create/lib/resolve.ts b/packages/openui-cli/src/commands/create/lib/resolve.ts
index c5d8a615b..a27af2f11 100644
--- a/packages/openui-cli/src/commands/create/lib/resolve.ts
+++ b/packages/openui-cli/src/commands/create/lib/resolve.ts
@@ -10,7 +10,7 @@ import {
rejectConflictingScaffoldSelectors,
type ExampleProject,
} from "./examples-catalog";
-import { resolveAvailableTarget } from "./target-dir";
+import { firstAvailableName, resolveAvailableTarget } from "./target-dir";
import type { CreateTelemetryClient } from "./telemetry";
import {
DEFAULT_TEMPLATE_KEY,
@@ -21,6 +21,8 @@ import {
type CatalogTemplate,
} from "./templates-catalog";
+const DEFAULT_PROJECT_NAME = "openui-agent";
+
export function rejectConflictingImmediateFlags(args: string[]): void {
const separatorIndex = args.indexOf("--");
const optionArgs = separatorIndex === -1 ? args : args.slice(0, separatorIndex);
@@ -39,29 +41,13 @@ export type CreateCatalog = {
export async function loadCreateCatalog(params: {
example?: string;
- template?: TemplateName;
backendFramework?: OverlayName;
interactive: boolean;
onRetry?: (info: RetryAttemptInfo) => void;
}): Promise<CreateCatalog> {
- const { example, template: requestedTemplate, backendFramework, interactive, onRetry } = params;
-
- rejectConflictingScaffoldSelectors({
- example,
- backendFramework,
- template: requestedTemplate,
- });
-
- // Interactive runs always scaffold the Cloud backend; openui-self-hosted stays
- // available, but only when requested explicitly with --template.
- if (!interactive && !example && !requestedTemplate) {
- throw new CreateError(
- "args_resolution",
- "Missing required argument --template",
- "invalid_input",
- "MISSING_REQUIRED_ARG",
- );
- }
+ const { example, backendFramework, interactive, onRetry } = params;
+
+ rejectConflictingScaffoldSelectors({ example, backendFramework });
if (example) {
const examples = await loadExamplesCatalog({ onRetry });
@@ -74,7 +60,7 @@ export async function loadCreateCatalog(params: {
loadTemplatesCatalog({ onRetry }),
loadExamplesCatalog({ onRetry }),
]);
- const template = requestedTemplate ?? DEFAULT_TEMPLATE_KEY;
+ const template = DEFAULT_TEMPLATE_KEY;
const templateEntry = findCatalogTemplate(catalog, template);
if (backendFramework) {
findCatalogOverlay(templateEntry, backendFramework);
@@ -83,7 +69,7 @@ export async function loadCreateCatalog(params: {
}
const catalog = await loadTemplatesCatalog({ onRetry });
- const template = requestedTemplate ?? DEFAULT_TEMPLATE_KEY;
+ const template = DEFAULT_TEMPLATE_KEY;
const templateEntry = findCatalogTemplate(catalog, template);
if (backendFramework) {
findCatalogOverlay(templateEntry, backendFramework);
@@ -96,12 +82,15 @@ export async function resolveProjectIdentity(
interactive: boolean,
tel: CreateTelemetryClient,
): Promise<{ name: string; targetDir: string }> {
+ if (!requestedName && !interactive) {
+ return resolveAvailableTarget(firstAvailableName(DEFAULT_PROJECT_NAME), interactive, tel);
+ }
const nameArgs = await resolveArgs(
{
name: requestedName
? { value: requestedName }
: {
- prompt: { type: "input", message: "Project name?", default: "openui-agent" },
+ prompt: { type: "input", message: "Project name?", default: DEFAULT_PROJECT_NAME },
required: true,
},
},
@@ -204,8 +193,6 @@ export async function resolveCreateSelection(params: {
}
}
-const isInteractiveTerminal = () => Boolean(process.stdin.isTTY && process.stdout.isTTY);
-
export function resolveImmediate(
immediate: boolean | undefined,
noInstall: boolean | undefined,
@@ -225,7 +212,7 @@ export function resolveImmediate(
source: "flag",
};
}
- if (!interactive || !isInteractiveTerminal()) {
+ if (!interactive) {
return {
immediate: false,
installDependencies: true,
diff --git a/packages/openui-cli/src/commands/create/lib/target-dir.ts b/packages/openui-cli/src/commands/create/lib/target-dir.ts
index 03d7ccb75..2db85eeb3 100644
--- a/packages/openui-cli/src/commands/create/lib/target-dir.ts
+++ b/packages/openui-cli/src/commands/create/lib/target-dir.ts
@@ -19,6 +19,11 @@ function suggestAvailableName(name: string): string {
return `${base}-${suffix}`;
}
+/** `name` if that directory is free, otherwise the next free `<name>-<n>`. */
+export function firstAvailableName(name: string): string {
+ return fs.existsSync(path.resolve(process.cwd(), name)) ? suggestAvailableName(name) : name;
+}
+
/** Resolve a project directory that does not exist yet */
export async function resolveAvailableTarget(
requestedName: string,
@@ -41,7 +46,6 @@ export async function resolveAvailableTarget(
// instead of throwing, so without this the TARGET_EXISTS signal that used
// to reach analytics via cli_create_failed would disappear for them.
tel.trackTargetExists({
- interactive,
attempt: retries + 1,
exhausted,
error_code: "TARGET_EXISTS",
diff --git a/packages/openui-cli/src/commands/create/lib/telemetry.ts b/packages/openui-cli/src/commands/create/lib/telemetry.ts
index b023c802b..c88b40ecf 100644
--- a/packages/openui-cli/src/commands/create/lib/telemetry.ts
+++ b/packages/openui-cli/src/commands/create/lib/telemetry.ts
@@ -63,13 +63,9 @@ export class CreateTelemetryClient extends Telemetry {
}
trackStarted(props: {
- interactive: boolean;
has_name_arg: boolean;
- has_template_arg: boolean;
has_backend_framework_arg: boolean;
has_example_arg: boolean;
- has_api_key_arg: boolean;
- has_auth_arg: boolean;
no_install: boolean;
immediate_arg: boolean | undefined;
}) {
@@ -160,11 +156,8 @@ export class CreateTelemetryClient extends Telemetry {
this.capture("cli_dev_command_failed", props);
}
- trackCloudAuthStarted(props: { auth_method?: string }) {
- this.capture("cli_cloud_auth_started", {
- ...createFunnelProps("cloud_auth_started"),
- ...props,
- });
+ trackCloudAuthStarted() {
+ this.capture("cli_cloud_auth_started", createFunnelProps("cloud_auth_started"));
}
trackCloudAuthMethod(props: { auth_method: string; auth_succeeded: boolean }) {
@@ -257,12 +250,7 @@ export class CreateTelemetryClient extends Telemetry {
this.capture("cli_target_name_retried", props);
}
- trackTargetExists(props: {
- interactive: boolean;
- attempt: number;
- exhausted: boolean;
- error_code: string;
- }) {
+ trackTargetExists(props: { attempt: number; exhausted: boolean; error_code: string }) {
this.capture("cli_target_exists", props);
}
}
diff --git a/packages/openui-cli/src/commands/create/run.ts b/packages/openui-cli/src/commands/create/run.ts
index 398030db7..68c2588c3 100644
--- a/packages/openui-cli/src/commands/create/run.ts
+++ b/packages/openui-cli/src/commands/create/run.ts
@@ -10,13 +10,7 @@ import { withSpinner } from "../../lib/spinner";
import { runCreateExample } from "./lib/create-example";
import type { CreateAppOptions } from "./lib/create-types";
import { runDevCommand } from "./lib/dev-server";
-import {
- buildAppId,
- requiredApiKeyEnv,
- resolveChatEnv,
- resolveCloudEnv,
- writeEnv,
-} from "./lib/env";
+import { buildAppId, resolveCloudEnv, writeEnv } from "./lib/env";
import { installProjectDependencies, resolveInstallInvocation } from "./lib/install";
import { installRequestedSkill, shouldInstallSkill } from "./lib/install-skill";
import { getStartedMessage } from "./lib/messages";
@@ -32,18 +26,15 @@ import { findCatalogOverlay } from "./lib/templates-catalog";
export async function runCreateApp(options: CreateAppOptions, ctx: CliContext): Promise<void> {
const tel = new CreateTelemetryClient(ctx.telemetry);
- const interactive = !options.noInteractive;
+ const interactive = ctx.canPrompt;
+ const agent = ctx.activeAgent;
const packageManager = resolveInstallPackageManager();
const t0 = Date.now();
- tel.registerContext({ interactive, package_manager: packageManager.name });
+ tel.registerContext({ package_manager: packageManager.name });
tel.trackStarted({
- interactive,
has_name_arg: Boolean(options.name),
- has_template_arg: Boolean(options.template),
has_backend_framework_arg: Boolean(options.backendFramework),
has_example_arg: Boolean(options.example),
- has_api_key_arg: Boolean(options.apiKey),
- has_auth_arg: Boolean(options.auth),
no_install: Boolean(options.noInstall),
immediate_arg: options.immediate,
});
@@ -52,7 +43,6 @@ export async function runCreateApp(options: CreateAppOptions, ctx: CliContext):
const sourceRetryReporter = tel.reportNetworkRetry("source_checkout");
const catalog = await loadCreateCatalog({
example: options.example,
- template: options.template,
backendFramework: options.backendFramework,
interactive,
onRetry: sourceRetryReporter,
@@ -70,6 +60,7 @@ export async function runCreateApp(options: CreateAppOptions, ctx: CliContext):
await runCreateExample({
options,
interactive,
+ agent,
packageManager,
t0,
name,
@@ -86,9 +77,9 @@ export async function runCreateApp(options: CreateAppOptions, ctx: CliContext):
if (!template || !templateEntry) {
throw new CreateError(
"args_resolution",
- "Missing required argument --template",
- "invalid_input",
- "MISSING_REQUIRED_ARG",
+ "The OpenUI Cloud template is missing from the template catalog.",
+ "network",
+ "TEMPLATE_NOT_FOUND",
);
}
@@ -108,16 +99,13 @@ export async function runCreateApp(options: CreateAppOptions, ctx: CliContext):
});
tel.trackEnvResolutionStarted({ template, ai_setup: aiSetup });
- const envResult =
- template === "openui-self-hosted"
- ? await resolveChatEnv(interactive)
- : await resolveCloudEnv(name, options, interactive, tel);
+ const envResult = await resolveCloudEnv(name, options, interactive, agent, tel);
const installSkill = await shouldInstallSkill(options.skill, interactive);
tel.trackSkillInstalled({ skill_installed: installSkill });
const immediateResolution = resolveImmediate(options.immediate, options.noInstall, interactive);
- const apiKeyEnv = requiredApiKeyEnv(template);
+ const apiKeyEnv = "THESYS_API_KEY";
const apiKeyAvailable = envResult.envWritten || Boolean(process.env[apiKeyEnv]?.trim());
const devStartBlockedByMissingApiKey = immediateResolution.immediate && !apiKeyAvailable;
tel.trackImmediateSelected({
@@ -140,11 +128,7 @@ export async function runCreateApp(options: CreateAppOptions, ctx: CliContext):
packageManager: packageManager.name,
backendFramework,
});
- await writeEnv(
- targetDir,
- envResult,
- template === "openui-cloud" ? buildAppId(name) : undefined,
- );
+ await writeEnv(targetDir, envResult, buildAppId(name));
} catch (err) {
const properties = cliErrorProperties(err, {
failure_stage: "scaffold",
@@ -220,10 +204,11 @@ export async function runCreateApp(options: CreateAppOptions, ctx: CliContext):
getStartedMessage({
name,
devCmd,
- template,
+ dlxCmd: packageManager.dlxCmd,
backendGettingStarted: overlay?.manifest.gettingStarted,
skillInstalled,
envWritten: envResult.envWritten,
+ apiKeyAvailable,
startDev,
installCmd,
dependencyInstalled,
diff --git a/packages/openui-cli/src/commands/generate-api-key/run.ts b/packages/openui-cli/src/commands/generate-api-key/run.ts
index e790cfb7b..670aea96f 100644
--- a/packages/openui-cli/src/commands/generate-api-key/run.ts
+++ b/packages/openui-cli/src/commands/generate-api-key/run.ts
@@ -1,9 +1,10 @@
import * as fs from "node:fs";
import * as path from "node:path";
-import { assertValidApiKeyName, mintCloudApiKey } from "../../lib/auth/mint";
+import { assertValidApiKeyName, CloudAuthError, mintCloudApiKey } from "../../lib/auth/mint";
import { AuthTelemetryClient } from "../../lib/auth/telemetry";
import type { CliContext } from "../../lib/context";
+import { resolveInstallPackageManager } from "../../lib/detect-package-manager";
import { assertValidEnvVarName, DEFAULT_ENV_FILE, upsertEnvVar } from "../../lib/env";
import { GenerateApiKeyTelemetryClient } from "./lib/telemetry";
@@ -47,6 +48,19 @@ export async function runGenerateApiKey(
env_key: envKey,
});
+ // The sign-in happens in a browser and needs a person at the terminal;
+ // without one this would wait on a callback that never arrives.
+ if (!ctx.detectedInteractive) {
+ const { dlxCmd } = resolveInstallPackageManager();
+ const fileArg = file === DEFAULT_ENV_FILE ? "" : ` --file ${file}`;
+ throw new CloudAuthError(
+ "method_resolution",
+ "INTERACTIVE_REQUIRED",
+ "generate-api-key signs you in through a browser, so it needs an interactive shell. " +
+ `Run this command yourself in a terminal:\n\n> ${dlxCmd} @openuidev/cli@latest generate-api-key${fileArg}`,
+ );
+ }
+
const apiKey = await mintCloudApiKey(projectName, authTel);
const filePath = path.resolve(ctx.cwd, file);
diff --git a/packages/openui-cli/src/lib/auth/mint.ts b/packages/openui-cli/src/lib/auth/mint.ts
index 7b0ab2846..5e5901b47 100644
--- a/packages/openui-cli/src/lib/auth/mint.ts
+++ b/packages/openui-cli/src/lib/auth/mint.ts
@@ -23,21 +23,10 @@ export function assertValidApiKeyName(name: string): void {
}
}
-export type CloudAuthMethod = "oauth" | "manual" | "skip";
-
-export function normalizeAuth(a?: string): CloudAuthMethod | undefined {
- if (!a) return undefined;
- const v = a.toLowerCase();
- if (v === "oauth" || v === "manual" || v === "skip") return v;
- throw new CreateError(
- "args_resolution",
- `unknown --auth "${a}". Use: oauth | skip (manual is deprecated).`,
- "invalid_input",
- "INVALID_AUTH",
- );
-}
-/** How the cloud key was obtained (for telemetry) — auth method + the `--api-key` flag case. */
-export type ResolvedAuthMethod = CloudAuthMethod | "apikey-flag";
+export type CloudAuthMethod = "oauth" | "skip";
+
+/** How the cloud key was obtained (for telemetry). */
+export type ResolvedAuthMethod = CloudAuthMethod;
type CloudAuthFailureStage =
| "method_resolution"
@@ -169,61 +158,36 @@ export async function mintCloudApiKey(
}
/**
- * Resolve a cloud API key by the chosen method: an explicitly provided key, a
- * browser OAuth mint, the deprecated manual paste, or skip (null → leave the
+ * Resolve a cloud API key: a browser OAuth mint, or skip (null → leave the
* .env slot empty).
*/
export async function resolveCloudApiKey(opts: {
- apiKey?: string;
- auth?: CloudAuthMethod;
projectName: string;
envFile?: string;
interactive: boolean;
tel: AuthTelemetryClient;
}): Promise<{ key: string | null; method: ResolvedAuthMethod }> {
- const provided = opts.apiKey?.trim();
- if (provided) return { key: provided, method: "apikey-flag" };
-
- let method = opts.auth;
- if (!method) {
- if (!opts.interactive) {
- throw new CloudAuthError(
- "method_resolution",
- "AUTH_REQUIRED",
- `An API key is required in non-interactive mode. Pass --api-key <key> ` +
- `(get one at ${THESYS_KEYS_URL}).`,
- );
- }
- const { select } = await import("@inquirer/prompts");
- method = await cloudAuthPrompt(
- "method_resolution",
- "AUTH_METHOD_PROMPT_FAILED",
- () =>
- select({
- message: "Connect to OpenUI Cloud:",
- choices: [
- { name: "Sign in with Thesys (opens a browser, mints a key)", value: "oauth" },
- {
- name: `Skip — add THESYS_API_KEY to ${opts.envFile ?? ".env"} later`,
- value: "skip",
- },
- ],
- }) as Promise<CloudAuthMethod>,
- );
- }
+ // Nobody is there to sign in: leave the .env slot empty and let the
+ // closing message point at `generate-api-key`.
+ if (!opts.interactive) return { key: null, method: "skip" };
+ const { select } = await import("@inquirer/prompts");
+ const method = await cloudAuthPrompt(
+ "method_resolution",
+ "AUTH_METHOD_PROMPT_FAILED",
+ () =>
+ select({
+ message: "Connect to OpenUI Cloud:",
+ choices: [
+ { name: "Sign in with Thesys (opens a browser, mints a key)", value: "oauth" },
+ {
+ name: `Skip — add THESYS_API_KEY to ${opts.envFile ?? ".env"} later`,
+ value: "skip",
+ },
+ ],
+ }) as Promise<CloudAuthMethod>,
+ );
if (method === "skip") return { key: null, method: "skip" };
- if (method === "manual") {
- console.warn(
- "[!] --auth manual is deprecated. Use browser sign-in or pass --api-key for scripted setup.",
- );
- const { password } = await import("@inquirer/prompts");
- const key = await cloudAuthPrompt("manual_key_prompt", "MANUAL_KEY_PROMPT_FAILED", () =>
- password({ message: "Paste your OpenUI Cloud API key:", mask: true }),
- );
- return { key: key.trim() || null, method: "manual" };
- }
-
return { key: await mintCloudApiKey(opts.projectName, opts.tel), method: "oauth" };
}
diff --git a/packages/openui-cli/src/lib/context.ts b/packages/openui-cli/src/lib/context.ts
index 02eb89aa0..6536b1d76 100644
--- a/packages/openui-cli/src/lib/context.ts
+++ b/packages/openui-cli/src/lib/context.ts
@@ -1,3 +1,4 @@
+import { detectAgent, UNKNOWN_AGENT_NAME } from "./detect-agent";
import { telemetry, type Telemetry } from "./telemetry";
export type CliContext = {
@@ -6,8 +7,21 @@ export type CliContext = {
telemetry: Telemetry;
verbose: boolean;
cliVersion?: string;
+ readonly agent?: string;
+ readonly detectedAgentName?: string;
+ /** `--no-interactive` as passed (false when given); undefined for commands without the flag. */
+ readonly interactive?: boolean;
+ readonly detectedInteractive: boolean;
+ readonly activeAgent?: string;
+ readonly canPrompt: boolean;
+ initialize(
+ this: CliContext,
+ passed: { verbose: boolean; agent?: string; interactive?: boolean },
+ ): Promise<void>;
};
+const isInteractiveTerminal = () => Boolean(process.stdin.isTTY && process.stdout.isTTY);
+
export const context: CliContext = {
get cwd() {
return process.cwd();
@@ -18,4 +32,22 @@ export const context: CliContext = {
telemetry,
verbose: false,
cliVersion: undefined,
+ detectedInteractive: false,
+ canPrompt: false,
+ async initialize(passed) {
+ const agent = passed.agent === UNKNOWN_AGENT_NAME ? undefined : passed.agent;
+ const detectedAgentName = await detectAgent();
+ const detectedInteractive = isInteractiveTerminal();
+ const activeAgent = agent ?? detectedAgentName;
+ const verbose = passed.verbose;
+ Object.assign(this, {
+ agent,
+ verbose,
+ detectedAgentName,
+ interactive: passed.interactive,
+ detectedInteractive,
+ activeAgent,
+ canPrompt: passed.interactive !== false && detectedInteractive && !activeAgent,
+ } satisfies Partial<CliContext>);
+ },
};
diff --git a/packages/openui-cli/src/lib/detect-agent.ts b/packages/openui-cli/src/lib/detect-agent.ts
index edb74e5b9..8b23f8c39 100644
--- a/packages/openui-cli/src/lib/detect-agent.ts
+++ b/packages/openui-cli/src/lib/detect-agent.ts
@@ -1,34 +1,42 @@
+import { determineAgent } from "@vercel/detect-agent";
+
import { isTruthyEnv } from "./env";
export const UNKNOWN_AGENT_NAME = "unknown";
-export type DetectedAgentName =
- | "claude-code"
- | "cline"
- | "codex"
- | "factory-droid"
- | "pi"
- | "ambiguous"
- | typeof UNKNOWN_AGENT_NAME;
-
const isPresent = (value?: string) => Boolean(value?.trim());
+// Keeps names stable in telemetry where @vercel/detect-agent differs from ours.
+const RENAMED: Record<string, string> = { claude: "claude-code" };
+
+/** `claude` → `claude-code`, and raw `AI_AGENT` values like `claude-code_2-1-295_agent` → `claude-code`. */
+function normalizeAgentName(name: string): string {
+ const slug = (
+ name
+ .trim()
+ .toLowerCase()
+ .split(/[_@\s]/)[0] ?? ""
+ ).replace(/[^a-z0-9-]/g, "");
+ return RENAMED[slug] ?? (slug || "other");
+}
+
+/** Markers @vercel/detect-agent doesn't check. */
+function detectUncoveredAgent(env: NodeJS.ProcessEnv): string | undefined {
+ if (env["CLAUDE_CODE_CHILD_SESSION"] === "1") return "claude-code";
+ if (isTruthyEnv(env["CLINE_ACTIVE"])) return "cline";
+ if (isPresent(env["FACTORY_PROJECT_DIR"])) return "factory-droid";
+ if (isTruthyEnv(env["PI_CODING_AGENT"])) return "pi";
+ return undefined;
+}
+
/**
* Best-effort detection from environment markers set by coding-agent products.
* These markers are not an authentication boundary: callers can spoof or inherit them.
*/
-export function detectAgent(env: NodeJS.ProcessEnv = process.env): DetectedAgentName {
- const matches = new Set<Exclude<DetectedAgentName, "ambiguous" | "unknown">>();
-
- if (env["CLAUDE_CODE_CHILD_SESSION"] === "1" || env["CLAUDECODE"] === "1") {
- matches.add("claude-code");
- }
- if (isPresent(env["CODEX_THREAD_ID"])) matches.add("codex");
- if (isTruthyEnv(env["CLINE_ACTIVE"])) matches.add("cline");
- if (isPresent(env["FACTORY_PROJECT_DIR"])) matches.add("factory-droid");
- if (isTruthyEnv(env["PI_CODING_AGENT"])) matches.add("pi");
-
- if (matches.size === 0) return UNKNOWN_AGENT_NAME;
- if (matches.size > 1) return "ambiguous";
- return [...matches][0] ?? UNKNOWN_AGENT_NAME;
+export async function detectAgent(
+ env: NodeJS.ProcessEnv = process.env,
+): Promise<string | undefined> {
+ const result = await determineAgent().catch(() => undefined);
+ if (result?.isAgent) return normalizeAgentName(result.agent.name);
+ return detectUncoveredAgent(env);
}
diff --git a/packages/openui-cli/src/lib/detect-package-manager.ts b/packages/openui-cli/src/lib/detect-package-manager.ts
index 222f91c7b..b9ad76edb 100644
--- a/packages/openui-cli/src/lib/detect-package-manager.ts
+++ b/packages/openui-cli/src/lib/detect-package-manager.ts
@@ -5,6 +5,7 @@ export interface PackageManager {
installCmd: string;
installArgs: string[];
runCmd: string;
+ dlxCmd: string;
}
const PACKAGE_MANAGERS: Record<PackageManagerName, PackageManager> = {
@@ -13,24 +14,28 @@ const PACKAGE_MANAGERS: Record<PackageManagerName, PackageManager> = {
installCmd: "pnpm install",
installArgs: ["install"],
runCmd: "pnpm",
+ dlxCmd: "pnpm dlx",
},
yarn: {
name: "yarn",
installCmd: "yarn",
installArgs: [],
runCmd: "yarn",
+ dlxCmd: "yarn dlx",
},
bun: {
name: "bun",
installCmd: "bun install",
installArgs: ["install"],
runCmd: "bun",
+ dlxCmd: "bunx",
},
npm: {
name: "npm",
installCmd: "npm ci --prefer-offline --no-audit --no-fund --progress=false",
installArgs: ["ci", "--prefer-offline", "--no-audit", "--no-fund", "--progress=false"],
runCmd: "npm",
+ dlxCmd: "npx",
},
};
@@ -45,7 +50,10 @@ function detectInvokingPackageManager(): PackageManagerName | null {
export function resolveInstallPackageManager(): PackageManager {
const invoking = detectInvokingPackageManager();
- return PACKAGE_MANAGERS[invoking ?? "npm"];
+ const pm = PACKAGE_MANAGERS[invoking ?? "npm"];
+ // Yarn 1 has no `dlx`; npx is what its users run instead.
+ const yarnClassic = (process.env["npm_config_user_agent"] ?? "").startsWith("yarn/1.");
+ return yarnClassic ? { ...pm, dlxCmd: "npx" } : pm;
}
/** Run a published CLI through npm's Node-compatible executor. */
diff --git a/packages/openui-cli/src/lib/telemetry.ts b/packages/openui-cli/src/lib/telemetry.ts
index 49c6b6866..e25c90e15 100644
--- a/packages/openui-cli/src/lib/telemetry.ts
+++ b/packages/openui-cli/src/lib/telemetry.ts
@@ -17,7 +17,6 @@ const isCi = () => {
const e = process.env;
return isTruthyEnv(e["CI"]) || !!e["GITHUB_ACTIONS"] || !!e["GITLAB_CI"] || !!e["BUILDKITE"];
};
-const isInteractiveTerminal = () => Boolean(process.stdin.isTTY && process.stdout.isTTY);
const debugLogPostHogFailure = (stage: string, error: unknown) => {
if (!isTelemetryDebug()) return;
const message = error instanceof Error ? error.message : String(error);
@@ -73,7 +72,12 @@ export class Telemetry {
};
}
- init(opts: { cliVersion: string; flagEnabled: boolean }) {
+ init(opts: {
+ cliVersion: string;
+ flagEnabled: boolean;
+ detectedInteractive: boolean;
+ detectedAgentName: string;
+ }) {
const optedOut =
isTruthyEnv(process.env["DO_NOT_TRACK"]) ||
isTruthyEnv(process.env["OPENUI_TELEMETRY_DISABLED"]) ||
@@ -81,7 +85,6 @@ export class Telemetry {
if (optedOut) return; // enabled stays false → all capture() are no-ops
const state = loadOrCreateState();
this.session.distinctId = state.distinctId;
- const interactiveTerminal = isInteractiveTerminal();
this.session.superProps = {
cli_version: opts.cliVersion,
os: process.platform,
@@ -91,7 +94,8 @@ export class Telemetry {
ci: isCi(),
stdin_is_tty: Boolean(process.stdin.isTTY),
stdout_is_tty: Boolean(process.stdout.isTTY),
- is_interactive_terminal: interactiveTerminal,
+ is_interactive_terminal: opts.detectedInteractive,
+ detected_agent_name: opts.detectedAgentName,
};
try {
this.session.client = createPostHogClient();
@@ -127,7 +131,9 @@ export class Telemetry {
registerRun(props: {
agent_name: string;
- detected_agent_name: string;
+ can_prompt: boolean;
+ /** false when `--no-interactive` is passed; only sent for commands that have the flag. */
+ interactive?: boolean;
cli_run_id: string;
command: string;
}) {
diff --git a/packages/openui-cli/src/program.ts b/packages/openui-cli/src/program.ts
index 3c0d47c3b..7fd118644 100644
--- a/packages/openui-cli/src/program.ts
+++ b/packages/openui-cli/src/program.ts
@@ -7,7 +7,7 @@ import { Command } from "commander";
import { commands } from "./commands";
import { CreateTelemetryClient } from "./commands/create/lib/telemetry";
import { context as ctx } from "./lib/context";
-import { detectAgent, UNKNOWN_AGENT_NAME } from "./lib/detect-agent";
+import { UNKNOWN_AGENT_NAME } from "./lib/detect-agent";
import { CliCancelledError, cliErrorProperties, CreateError } from "./lib/errors";
let activeCommand = "unknown";
@@ -33,18 +33,28 @@ function buildProgram(): Command {
program.configureHelp({ showGlobalOptions: true });
program.addHelpText("after", '\nFound a bug or have an idea? Run: openui feedback "<message>"');
- program.hook("preAction", (_thisCommand, actionCommand) => {
+ program.hook("preAction", async (_thisCommand, actionCommand) => {
activeCommand = actionCommand.name();
const globalOptions = program.opts<{
agentName: string;
telemetry?: boolean;
verbose?: boolean;
}>();
- ctx.verbose = Boolean(globalOptions.verbose || actionCommand.optsWithGlobals()["verbose"]);
- ctx.telemetry.init({ cliVersion, flagEnabled: globalOptions.telemetry !== false });
+ await ctx.initialize({
+ agent: globalOptions.agentName,
+ interactive: actionCommand.opts()["interactive"] as boolean | undefined,
+ verbose: Boolean(globalOptions.verbose || actionCommand.optsWithGlobals()["verbose"]),
+ });
+ ctx.telemetry.init({
+ cliVersion,
+ flagEnabled: globalOptions.telemetry !== false,
+ detectedInteractive: ctx.detectedInteractive,
+ detectedAgentName: ctx.detectedAgentName ?? UNKNOWN_AGENT_NAME,
+ });
ctx.telemetry.registerRun({
agent_name: globalOptions.agentName,
- detected_agent_name: detectAgent(),
+ can_prompt: ctx.canPrompt,
+ ...(ctx.interactive === undefined ? {} : { interactive: ctx.interactive }),
cli_run_id: randomUUID(),
command: actionCommand.name(),
});
diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml
index 366067680..796e1cd26 100644
--- a/pnpm-lock.yaml
+++ b/pnpm-lock.yaml
@@ -528,6 +528,9 @@ importers:
'@inquirer/prompts':
specifier: ^8.3.0
version: 8.5.2(@types/[email protected])
+ '@vercel/detect-agent':
+ specifier: 1.2.6
+ version: 1.2.6
commander:
specifier: ^14.0.3
version: 14.0.3
@@ -5769,6 +5772,10 @@ packages:
'@upsetjs/[email protected]':
resolution: {integrity: sha512-WbBhLrooyePuQ1VZxrJjtLvTc4NVfpOyKx0sKqioq9bX1C1m7Jgykkn8gLrtwumBioXIqam8DLxp88Adbue6Hw==}
+ '@vercel/[email protected]':
+ resolution: {integrity: sha512-MpsC5alyelZCSI93gX12Sjd29LFJUNn0auiJ3YZ0fAcmeT7HvaM+GFpoNhrgJuZGSEXysRRUcew9hPqITwKZMg==}
+ engines: {node: '>=14'}
+
'@vercel/[email protected]':
resolution: {integrity: sha512-UycprH3T6n3jH0k44NHMa7pnFHGu/N05MjojYr+Mc6I7obkoLIJujSWwin1pCvdy/eOxrI/l3uDLQsmcrOb4ug==}
engines: {node: '>= 20'}
@@ -15891,6 +15898,8 @@ snapshots:
d3-selection: 3.0.0
d3-transition: 3.0.1([email protected])
+ '@vercel/[email protected]': {}
+
'@vercel/[email protected]': {}
diff --git a/templates/README.md b/templates/README.md
index 76097a58e..67ce385c4 100644
--- a/templates/README.md
+++ b/templates/README.md
@@ -2,10 +2,10 @@
Starter apps for `openui create`. `templates.json` is the catalog file.
-| Directory | `--template` |
-| --------------------- | ------------------------------------ |
-| `openui-cloud/` | `openui-cloud` (interactive default) |
-| `openui-self-hosted/` | `openui-self-hosted` |
+| Templates |
+| ------------------------------------ |
+| `openui-cloud` (interactive default) |
+| `openui-self-hosted` |
Base directories are complete LangGraph apps using Chat Completions.
The CLI copies them directly for the default backend; other frameworks use overlays.
diff --git a/templates/templates.json b/templates/templates.json
index 69afce6f2..e9f3f535d 100644
--- a/templates/templates.json
+++ b/templates/templates.json
@@ -8,12 +8,12 @@
{
"name": "LangGraph (default)",
"key": "langgraph",
- "description": "LangGraph agent with the selected model backend"
+ "description": "LangGraph agent"
},
{
"name": "Vercel AI SDK",
"key": "vercel-ai-sdk",
- "description": "Vercel AI SDK agent with the selected model backend"
+ "description": "Vercel AI SDK agent"
},
{
"name": "Vercel Eve",
@@ -25,17 +25,17 @@
{
"name": "OpenUI Self-hosted",
"key": "openui-self-hosted",
- "description": "Bring your own OpenAI-compatible provider, AI route, and persistence. Available only via --template.",
+ "description": "Bring your own OpenAI-compatible provider, AI route, and persistence.",
"overlays": [
{
"name": "LangGraph (default)",
"key": "langgraph",
- "description": "LangGraph agent with the selected model backend"
+ "description": "LangGraph agent"
},
{
"name": "Vercel AI SDK",
"key": "vercel-ai-sdk",
- "description": "Vercel AI SDK agent with the selected model backend"
+ "description": "Vercel AI SDK agent"
},
{
"name": "Vercel Eve",