Skip to content

feat(cli): scaffold selected backend framework #785

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
vishxrad wants to merge 1 commit into
base: main
Choose a base branch
from
Open

feat(cli): scaffold selected backend framework #785

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
51 changes: 36 additions & 15 deletions docs/content/docs/api-reference/cli.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -53,31 +53,40 @@ openui create [options]

**Options**

| Flag | Description |
| --------------------------- | ----------------------------------------------------------- |
| `-n, --name <string>` | Project name (directory to create) |
| `-t, --template <template>` | AI setup/template: `openui-cloud` or `openui-self-hosted` |
| `--api-key <key>` | OpenUI Cloud API key; skips sign-in for the Cloud setup |
| `--auth <method>` | Cloud auth method: `oauth`, `manual`, or `skip` |
| `--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 |
| `--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. It asks you to choose your AI setup: **OpenUI Cloud** is the fastest setup with free hosted models, while **OpenAI-compatible provider** uses your own key and self-hosts the AI route in the generated app. Pass `--no-interactive` in CI or scripted environments to surface missing required flags as errors instead.
| Flag | Description |
| --------------------------------- | ----------------------------------------------------------- |
| `-n, --name <string>` | Project name (directory to create) |
| `-t, --template <template>` | AI setup/template: `openui-cloud` or `openui-self-hosted` |
| `--backend-framework <framework>` | Self-hosted backend: `none`, `langgraph`, or `vercel` |
| `--api-key <key>` | OpenUI Cloud API key; skips sign-in for the Cloud setup |
| `--auth <method>` | Cloud auth method: `oauth`, `manual`, or `skip` |
| `--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 |
| `--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. It asks you to choose your AI setup: **OpenUI Cloud** is the fastest setup with free hosted models, while **self-hosted** uses your own key and runs the AI route in the generated app. Self-hosted then offers the **OpenAI SDK** (default), **LangGraph**, or **Vercel AI SDK**. Cloud skips this prompt because it provides the managed backend. Pass `--no-interactive` in CI or scripted environments to surface missing required flags as errors instead; self-hosted defaults to `none` when the flag is omitted.

**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

The generated project includes a `generate:prompt` script that runs `openui generate` as part of `dev` and `build`.
**Self-hosted backends**

| Value | Generated backend |
| ----------- | ------------------------------------ |
| `none` | The default OpenAI SDK chat route |
| `langgraph` | A LangGraph `StateGraph` route |
| `vercel` | A Vercel AI SDK `streamText()` route |

All three choices share the same frontend. The CLI replaces only `src/app/api/chat/route.ts` and the backend dependencies; every route emits the OpenAI-compatible NDJSON stream consumed by that frontend. Passing `langgraph` or `vercel` without `--template` selects `openui-self-hosted`. Combining either with `openui-cloud` is an error because Cloud already supplies the backend.

**Agent skill**

Expand All @@ -95,6 +104,9 @@ pnpx @openuidev/cli@latest create
pnpx @openuidev/cli@latest create --name my-app --template openui-cloud
pnpx @openuidev/cli@latest create --name my-app --template openui-self-hosted

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

# Non-interactive
pnpx @openuidev/cli@latest create --no-interactive --name my-app --template openui-cloud --auth skip

Expand All @@ -111,6 +123,9 @@ 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-self-hosted --backend-framework langgraph

# Non-interactive
bunx @openuidev/cli@latest create --no-interactive --name my-app --template openui-cloud --auth skip

Expand All @@ -127,6 +142,9 @@ 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-self-hosted --backend-framework langgraph

# Non-interactive
yarn dlx @openuidev/cli@latest create --no-interactive --name my-app --template openui-cloud --auth skip

Expand All @@ -143,6 +161,9 @@ 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-self-hosted --backend-framework langgraph

# Non-interactive
npx @openuidev/cli@latest create --no-interactive --name my-app --template openui-cloud --auth skip

Expand Down
30 changes: 27 additions & 3 deletions packages/openui-cli/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -10,7 +10,7 @@ Command-line tools for starting OpenUI projects and generating model instruction
It currently supports two workflows:

- scaffolding a new OpenUI app from one of two templates:
- **OpenUI Chat** — a Next.js app where you bring your own model key (OpenAI)
- **Self-hosted** — a Next.js app where you bring your own model key and choose the OpenAI SDK, LangGraph, or Vercel AI SDK backend
- **OpenUI Cloud** — a Next.js app backed by OpenUI Cloud for managed conversations, artifacts, and streaming
- generating a system prompt or JSON Schema from a `createLibrary()` export

Expand Down Expand Up @@ -39,6 +39,13 @@ npx @openuidev/cli@latest create --template openui-self-hosted
npx @openuidev/cli@latest create --template openui-cloud
```

Choose a self-hosted backend directly (the default is `none`, which uses the OpenAI SDK):

```bash
npx @openuidev/cli@latest create --template openui-self-hosted --backend-framework langgraph
npx @openuidev/cli@latest create --template openui-self-hosted --backend-framework vercel
```

Generate a prompt from a library file:

```bash
Expand All @@ -55,7 +62,7 @@ npx @openuidev/cli@latest generate ./src/library.ts --json-schema

### `openui create`

Scaffolds a new Next.js app from the **OpenUI Chat** or **OpenUI Cloud** template.
Scaffolds a new Next.js app using **OpenUI Cloud** or a **self-hosted** backend.

```bash
openui create [options]
Expand All @@ -65,6 +72,7 @@ Options:

- `-n, --name <string>`: Project name
- `-t, --template <template>`: Template to scaffold — `openui-self-hosted` or `openui-cloud`
- `--backend-framework <framework>`: Self-hosted backend — `none`, `langgraph`, or `vercel`
- `--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
Expand All @@ -77,15 +85,29 @@ What it does:

- prompts for the project name if you do not pass `--name`
- prompts for the template if you do not pass `--template`
- prompts for a backend framework after you choose self-hosted; non-interactive usage defaults to `none`
- skips the backend prompt for OpenUI Cloud because Cloud provides the managed backend
- copies the bundled template 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`)
- optionally installs the OpenUI agent skill for AI coding assistants
- writes a `.env` file tailored to the template (see below)

#### Self-hosted backends

| Value | Generated backend |
| ----------- | ------------------------------------ |
| `none` | The default OpenAI SDK chat route |
| `langgraph` | A LangGraph `StateGraph` route |
| `vercel` | A Vercel AI SDK `streamText()` route |

The frontend is shared by all three choices. The CLI replaces only `src/app/api/chat/route.ts` and the backend dependencies; each route emits the OpenAI-compatible NDJSON stream expected by the shared frontend.

Passing `langgraph` or `vercel` without `--template` selects `openui-self-hosted`. OpenUI Cloud cannot be combined with either because it already supplies the backend.

#### Template-specific `.env`

- **OpenUI Chat** — prompts for your OpenAI API key and writes `OPENAI_API_KEY` to `.env` (interactive mode only). Leave blank to skip.
- **Self-hosted** — prompts for your OpenAI API key and writes `OPENAI_API_KEY` to `.env` (interactive mode only). Leave blank to skip.
- **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:
Expand All @@ -99,6 +121,8 @@ 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
openui create --name my-app --template openui-cloud --auth oauth
openui create --name my-app --template openui-cloud --api-key tk_your_key
openui create --name my-app --no-skill --no-install
Expand Down
2 changes: 1 addition & 1 deletion packages/openui-cli/package.json
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
{
"name": "@openuidev/cli",
"version": "0.1.7",
"version": "0.1.8",
"description": "CLI for OpenUI — scaffold generative UI chat apps and generate LLM system prompts from component libraries",
"bin": {
"openui": "dist/index.js"
Expand Down
Loading
Loading