feat(cli): scaffold selected backend framework

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

@@ -53,35 +53,46 @@ openui create [options]
 
 **Options**
 
-| Flag                        | Description                                                      |
-| --------------------------- | ---------------------------------------------------------------- |
-| `-n, --name <string>`       | Project name (interactive default: `openui-agent`)               |
-| `-t, --template <template>` | AI backend: `openui-cloud` (recommended) or `openui-self-hosted` |
-| `--api-key <key>`           | OpenUI Cloud API key; skips sign-in for the Cloud setup          |
-| `--auth <method>`           | Cloud 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`)      |
-
-When run interactively (default), the CLI prompts for any missing options, then asks whether to start the development server after installing dependencies with the detected package manager. The start prompt defaults to yes; answering no preserves the existing install-and-exit behavior and prints the `cd` and dev commands. For most prototypes and evaluations, start with **OpenUI Cloud, the recommended default**: hosted models, managed conversation history and streaming, built-in tools, and ready-to-use reports and presentations without operating the model, storage, or artifact infrastructure. Choose **self-hosted** when owning the OpenAI-compatible provider, AI route, and persistence is a requirement.
+| Flag                              | Description                                                      |
+| --------------------------------- | ---------------------------------------------------------------- |
+| `-n, --name <string>`             | Project name (interactive default: `openui-agent`)               |
+| `-t, --template <template>`       | AI backend: `openui-cloud` (recommended) or `openui-self-hosted` |
+| `--backend-framework <framework>` | Backend integration: `none`, `langgraph`, or `vercel-ai-sdk`     |
+| `--api-key <key>`                 | OpenUI Cloud API key; skips sign-in for the Cloud setup          |
+| `--auth <method>`                 | Cloud 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`)      |
+
+When run interactively (default), the CLI prompts for any missing options, including the backend framework, then asks whether to start the development server after installing dependencies with the detected package manager. The start prompt defaults to yes; answering no preserves the existing install-and-exit behavior and prints the `cd` and dev commands. For most prototypes and evaluations, start with **OpenUI Cloud, the recommended default**: hosted models, managed conversation history and streaming, built-in tools, and ready-to-use reports and presentations without operating the model, storage, or artifact infrastructure. Choose **self-hosted** when owning the OpenAI-compatible provider, AI route, and persistence is a requirement.
 
 In non-interactive mode, dependencies are installed without starting the long-running development server. Pass `--immediate` to install and start, `--no-immediate` to make the install-and-exit behavior explicit, or `--no-install` to scaffold only.
 
 **What it does**
 
-1. Resolves the project name and AI setup
+1. Resolves the project name, AI setup, and backend framework
 2. Copies the selected Next.js template into `<name>/`
 3. Rewrites `workspace:*` dependency versions to `latest`
 4. Writes the relevant `.env` values, including Thesys sign-in/API-key setup for OpenUI Cloud
 5. Optionally installs the [OpenUI agent skill](/docs/openui-lang/agent-skill) for AI coding assistants (e.g. Claude, Cursor, Copilot)
 6. Auto-detects your package manager (npm, pnpm, yarn, bun)
 7. Installs dependencies unless skipped, then optionally starts the development server in the generated directory
 
-The generated project includes a `generate:prompt` script that runs `openui generate` as part of `dev` and `build`.
+**Backend frameworks**
+
+| Value           | OpenUI Cloud route                                  | Self-hosted route                          |
+| --------------- | --------------------------------------------------- | ------------------------------------------ |
+| `none`          | Direct OpenAI SDK Responses proxy                   | Direct OpenAI SDK Chat Completions proxy   |
+| `langgraph`     | OpenAI SDK proxy + LangGraph app-tool execution     | LangGraph `StateGraph` using your provider |
+| `vercel-ai-sdk` | OpenAI SDK proxy + Vercel AI SDK app-tool execution | Vercel AI SDK `streamText()` route         |
+
+The CLI replaces `src/app/api/chat/route.ts` and adds the selected framework's dependencies. Self-hosted framework selections also switch `src/app/page.tsx` to the framework's frontend message format and stream adapter, so the route can return the native LangGraph or Vercel AI SDK stream. Every Cloud route keeps the OpenAI SDK pointed at OpenUI Cloud, preserving the raw Responses stream and managed conversation storage. Artifacts, web search, image search, and configured MCP tools still execute in Cloud; selecting LangGraph or Vercel AI SDK only changes how application-owned function tools are defined and executed on your server. Choose self-hosted to use your own model provider key.
+
+Both self-hosted framework routes include 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.
 
 **Agent skill**
 
@@ -100,6 +111,11 @@ 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-self-hosted --backend-framework langgraph
+pnpx @openuidev/cli@latest create --name my-app --template openui-self-hosted --backend-framework vercel-ai-sdk
+
 # Non-interactive
 pnpx @openuidev/cli@latest create --no-interactive --name my-app --template openui-cloud --auth skip
 
@@ -116,6 +132,11 @@ bunx @openuidev/cli@latest create
 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-self-hosted --backend-framework langgraph
+bunx @openuidev/cli@latest create --name my-app --template openui-self-hosted --backend-framework vercel-ai-sdk
+
 # Non-interactive
 bunx @openuidev/cli@latest create --no-interactive --name my-app --template openui-cloud --auth skip
 
@@ -132,6 +153,11 @@ yarn dlx @openuidev/cli@latest create
 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-self-hosted --backend-framework langgraph
+yarn dlx @openuidev/cli@latest create --name my-app --template openui-self-hosted --backend-framework vercel-ai-sdk
+
 # Non-interactive
 yarn dlx @openuidev/cli@latest create --no-interactive --name my-app --template openui-cloud --auth skip
 
@@ -148,6 +174,11 @@ npx @openuidev/cli@latest create
 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-self-hosted --backend-framework langgraph
+npx @openuidev/cli@latest create --name my-app --template openui-self-hosted --backend-framework vercel-ai-sdk
+
 # Non-interactive
 npx @openuidev/cli@latest create --no-interactive --name my-app --template openui-cloud --auth skip
 

packages/openui-cli/README.md

@@ -12,6 +12,7 @@ It currently supports two workflows:
 - 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
+- choosing the direct OpenAI SDK route, LangGraph, or Vercel AI SDK for either template
 - generating a system prompt or JSON Schema from a `createLibrary()` export
 
 ## Install
@@ -39,6 +40,15 @@ 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 `none`, which uses the OpenAI SDK):
+
+```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-self-hosted --backend-framework langgraph
+npx @openuidev/cli@latest create --template openui-self-hosted --backend-framework vercel-ai-sdk
+```
+
 Generate a prompt from a library file:
 
 ```bash
@@ -65,10 +75,11 @@ 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 — `none`, `langgraph`, or `vercel-ai-sdk`
 - `--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
+- `-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 template) OpenUI Cloud API key; skips sign-in
@@ -79,11 +90,13 @@ What it does:
 
 - prompts for the project name, defaulting to `openui-agent`, if you do not pass `--name`
 - prompts for the template if you do not pass `--template`
+- prompts for a backend framework after the template; non-interactive usage defaults to `none`
 - copies the bundled template into a new directory
 - rewrites monorepo-local dependencies (`workspace:`, `file:`, `catalog:`) in the generated `package.json` to `latest`
 - asks whether to start the development server after dependency installation (default: yes); answering no preserves the install-and-exit behavior
 - installs dependencies automatically using the detected package manager (unless `--no-install`)
 - in non-interactive mode, installs dependencies without starting the server unless overridden with `--immediate`
+- before an immediate start, requires `THESYS_API_KEY` for OpenUI Cloud or `OPENAI_API_KEY` for self-hosted to be available
 - optionally installs the OpenUI agent skill for AI coding assistants
 - writes a `.env` file tailored to the template (see below)
 
@@ -92,6 +105,18 @@ What it does:
 - **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.
 
+#### Backend frameworks
+
+| Value           | OpenUI Cloud route                                  | Self-hosted route                          |
+| --------------- | --------------------------------------------------- | ------------------------------------------ |
+| `none`          | Direct OpenAI SDK Responses proxy                   | Direct OpenAI SDK Chat Completions proxy   |
+| `langgraph`     | OpenAI SDK proxy + LangGraph app-tool execution     | LangGraph `StateGraph` using your provider |
+| `vercel-ai-sdk` | OpenAI SDK proxy + Vercel AI SDK app-tool execution | Vercel AI SDK `streamText()` route         |
+
+The CLI replaces `src/app/api/chat/route.ts` and adds the dependencies for the selected framework. Self-hosted framework selections also switch `src/app/page.tsx` to the matching frontend message format and stream adapter, allowing LangGraph and the Vercel AI SDK to use their native streaming protocols instead of emulating OpenAI Chat Completions. Every Cloud combination keeps the OpenAI SDK pointed at OpenUI Cloud, preserving the raw Responses stream and managed conversation storage. Artifacts, web search, image search, and configured MCP tools still execute in Cloud; selecting LangGraph or Vercel AI SDK only changes how application-owned function tools are defined and executed on your server. It does not configure a user-owned model provider. Choose `openui-self-hosted` when you want to bring your own provider.
+
+Every Cloud route includes `get_weather` as its example app-owned function tool. The LangGraph and Vercel AI SDK variants define and execute that tool through the selected framework while leaving Cloud-owned tools unchanged. The two self-hosted framework routes include the same weather example and run it through their native multi-step tool loops, making the selected backend directly testable after scaffolding.
+
 #### 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:
@@ -107,7 +132,12 @@ 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-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 --api-key tk_your_key
 openui create --name my-app --template openui-self-hosted
 openui create --name my-app --template openui-cloud --immediate