Add featured examples to CLI

docs/content/docs/api-reference/cli.mdx

@@ -58,6 +58,7 @@ openui create [options]
 | `-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: `default`, `langgraph`, `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                       |
@@ -68,7 +69,7 @@ openui create [options]
 | `--no-interactive`                | Fail instead of prompting for missing input                                   |
 | `--agent-name <name>`             | Declare the invoking coding-agent slug (default: `unknown`)                   |
 
-When run interactively (default), the CLI prompts for any missing options, including the backend framework, then asks whether to start the development server after installing dependencies with the detected package manager. The start prompt defaults to yes; answering no preserves the existing install-and-exit behavior and prints the `cd` and dev commands. For most prototypes and evaluations, start with **OpenUI 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.
+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.
 
 `openui-cloud` remains the CLI template identifier for the Gateway-backed setup.
 
@@ -78,8 +79,8 @@ In non-interactive mode, dependencies are installed without starting the long-ru
 
 **What it does**
 
-1. Resolves the project name, AI setup, and backend framework
-2. Copies the selected Next.js template into `<name>/`
+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)
@@ -101,6 +102,10 @@ For Gateway-backed LangGraph and Vercel AI SDK variants, the framework owns orch
 
 Every framework overlay includes a `get_weather` example backed by Open-Meteo. Ask “What’s the weather in Berlin?” to verify the selected framework’s native multi-step tool loop.
 
+**OpenUI examples**
+
+Interactive `openui create` lists starter templates, and option to create an app from listed [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**
 
 Every Gateway-backed variant uses Gateway as its durable conversation and artifact store. The browser connects directly through `useOpenuiCloudStorage()` with a short-lived frontend token. For default, LangGraph, and Vercel AI SDK routes, the `threadId` sent to `/api/chat` is the Gateway conversation ID, and each backend appends model turns to it with `conversation: threadId` and `store: true`. The Vercel AI SDK route does not create a second store. The Eve Gateway overlay keeps that Gateway thread store and maps each Gateway `threadId` to an Eve session cursor in the browser; it does not use `/api/chat`. The Gateway-backed LangGraph relay creates and deletes a temporary Agent Server thread for each run; configure a separate LangGraph checkpointer only when graph state, interrupts, or resumable runs must persist independently.
@@ -132,6 +137,11 @@ pnpx @openuidev/cli@latest create --name my-app --template openui-self-hosted --
 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
+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
 
@@ -156,6 +166,11 @@ bunx @openuidev/cli@latest create --name my-app --template openui-self-hosted --
 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
+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
 
@@ -180,6 +195,11 @@ yarn dlx @openuidev/cli@latest create --name my-app --template openui-self-hoste
 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
+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
 
@@ -204,6 +224,11 @@ npx @openuidev/cli@latest create --name my-app --template openui-self-hosted --b
 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
+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
 

examples/examples.json

@@ -4,103 +4,103 @@
       "title": "Google ADK",
       "description": "A Google ADK TypeScript agent streaming OpenUI Lang to a Next.js client.",
       "path": "agent-frameworks/google-adk",
-      "featured": false
+      "envKey": "THESYS_API_KEY"
     },
     {
       "title": "LangGraph Platform",
       "description": "A DeepAgents graph on LangGraph Platform, streamed to OpenUI through the LangChain adapter.",
       "path": "agent-frameworks/langgraph-platform",
-      "featured": false
+      "envKey": "THESYS_API_KEY"
     },
     {
       "title": "Mastra",
       "description": "A Mastra agent connected to OpenUI through AG-UI.",
       "path": "agent-frameworks/mastra",
-      "featured": true
+      "envKey": "THESYS_API_KEY"
     },
     {
       "title": "Vercel AI SDK",
       "description": "AgentInterface over a Vercel AI SDK streamText backend.",
       "path": "agent-frameworks/vercel-ai-sdk",
-      "featured": false
+      "envKey": "THESYS_API_KEY"
     },
     {
       "title": "Vercel Eve",
       "description": "An Eve agent rendered through Agent Interface.",
       "path": "agent-frameworks/vercel-eve",
-      "featured": false
+      "envKey": "THESYS_API_KEY"
     },
     {
       "title": "FastAPI",
       "description": "A Python FastAPI streaming backend with a React OpenUI client.",
       "path": "app-frameworks/fastapi",
-      "featured": true
+      "envKey": "THESYS_API_KEY"
     },
     {
       "title": "React Native",
       "description": "An Expo client rendering native OpenUI components from a Next.js backend stream.",
       "path": "app-frameworks/react-native",
-      "featured": true
+      "envKey": "THESYS_API_KEY"
     },
     {
       "title": "Svelte",
       "description": "OpenUI Lang parsing and rendering in SvelteKit.",
       "path": "app-frameworks/svelte",
-      "featured": false
+      "envKey": "THESYS_API_KEY"
     },
     {
       "title": "Vue",
       "description": "OpenUI Lang parsing and rendering in Nuxt and Vue.",
       "path": "app-frameworks/vue",
-      "featured": false
+      "envKey": "THESYS_API_KEY"
     },
     {
       "title": "Material UI",
       "description": "A broad Material UI component library for generated interfaces.",
       "path": "design-systems/material-ui",
-      "featured": false
+      "envKey": "THESYS_API_KEY"
     },
     {
       "title": "shadcn/ui",
       "description": "A broad shadcn/ui component library for generated interfaces.",
       "path": "design-systems/shadcn",
-      "featured": true
+      "envKey": "THESYS_API_KEY"
     },
     {
       "title": "Grok Build",
       "description": "Grok Build coding sessions rendered with OpenUI Cloud.",
       "path": "harnesses/grok-build",
-      "featured": false
+      "envKey": "XAI_API_KEY"
     },
     {
       "title": "Pi",
       "description": "A Pi coding-agent session on OpenUI Cloud.",
       "path": "harnesses/pi",
-      "featured": false
+      "envKey": "THESYS_API_KEY"
     },
     {
       "title": "Handsontable",
       "description": "Generated spreadsheet interfaces backed by Handsontable.",
       "path": "miscellaneous/handsontable",
-      "featured": false
+      "envKey": "THESYS_API_KEY"
     },
     {
       "title": "HTML artifact",
       "description": "Sandboxed HTML artifacts as an OpenUI capability.",
       "path": "miscellaneous/html-artifact",
-      "featured": false
+      "envKey": "THESYS_API_KEY"
     },
     {
       "title": "React Email",
       "description": "Generating and previewing emails with the OpenUI React Email library.",
       "path": "miscellaneous/react-email",
-      "featured": false
+      "envKey": "THESYS_API_KEY"
     },
     {
       "title": "Supabase",
       "description": "Persisted OpenUI conversations and threads with Supabase.",
       "path": "miscellaneous/supabase",
-      "featured": false
+      "envKey": "THESYS_API_KEY"
     }
   ]
 }

packages/openui-cli/README.md

@@ -13,6 +13,7 @@ It currently supports:
   - **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
 - keeping the default minimal SDK route or adding a LangGraph, Vercel AI SDK, or Vercel Eve backend to 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
 - generating a system prompt or JSON Schema from a `createLibrary()` export
 
@@ -41,7 +42,7 @@ 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 `default`, the template's minimal SDK route):
+Choose a backend framework or example directly:
 
 ```bash
 npx @openuidev/cli@latest create --template openui-cloud --backend-framework langgraph
@@ -50,6 +51,8 @@ npx @openuidev/cli@latest create --template openui-cloud --backend-framework ver
 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`:
@@ -84,8 +87,9 @@ 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 — `default`, `langgraph`, `vercel-ai-sdk`, or `vercel-eve`
+- `-t, --template <template>`: AI backend `key` from `templates/templates.json` — interactive default `openui-cloud`
+- `--backend-framework <framework>`: Overlay `key` from that template's `overlays` list (plus `default` for the base template)
+- `-e, --example <example>`: Scaffold any example
 - `--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
@@ -102,8 +106,8 @@ What it does:
 
 - 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 after the template; non-interactive usage defaults to `default`
-- copies the bundled template into a new directory
+- prompts for a backend framework or example after the template; non-interactive usage defaults to `default`
+- 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
@@ -135,6 +139,16 @@ The Cloud graph needs `THESYS_API_KEY`; the self-hosted graph needs the selected
 
 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 to scaffold [OpenUI Examples from Github](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 --no-immediate
+openui create --example vue
+```
+
 #### Conversation storage
 
 Every OpenUI Cloud variant uses OpenUI Cloud as its only durable conversation and artifact store. The browser connects directly through `useOpenuiCloudStorage()` with a short-lived frontend token, and `/api/chat` appends each turn to the same Cloud conversation with `conversation: threadId` and `store: true`. Vercel does not add a second store. Configure a LangGraph checkpointer separately only when the graph itself needs durable state, interrupts, or resumable runs.
@@ -164,6 +178,7 @@ 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

packages/openui-cli/src/auth/mint.ts

@@ -198,6 +198,14 @@ export async function resolveCloudApiKey(opts: {
   if (method === "skip") return { key: null, method: "skip" };
 
   if (method === "manual") {
+    if (!opts.interactive) {
+      throw new CloudAuthError(
+        "manual_key_prompt",
+        "AUTH_REQUIRED",
+        `An API key is required in non-interactive mode. Pass --api-key <key> ` +
+          `(get one at ${THESYS_KEYS_URL}).`,
+      );
+    }
     console.warn(
       "[!] --auth manual is deprecated. Use browser sign-in or pass --api-key for scripted setup.",
     );