Skip to content

The Open Standard for Generative UI

Highlight OpenUI Cloud benefits in CLI (#834)

Zahle Khan5c510558eb63
diff --git a/docs/content/docs/agent/getting-started/quickstart.mdx b/docs/content/docs/agent/getting-started/quickstart.mdx
index 7fb8f396e..ca3cd778e 100644
--- a/docs/content/docs/agent/getting-started/quickstart.mdx
+++ b/docs/content/docs/agent/getting-started/quickstart.mdx
@@ -7,10 +7,12 @@ The CLI scaffolds a complete Next.js app: a streaming chat with a sidebar, threa
## 1. Create
-Run the create command and answer the prompts. One prompt 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.
+Run the create command and answer the prompts. One prompt asks you to choose your agent backend:
+For most prototypes and evaluations, start with **OpenUI Cloud, the recommended
+default**: hosted models plus managed conversation history, streaming, built-in
+tools, and ready-to-use reports and presentations. You can ship without operating
+the model, storage, or artifact infrastructure. Choose **self-hosted** when owning
+the OpenAI-compatible provider, AI route, and persistence is a requirement.
```bash tab="pnpm" tab-group="pkg"
pnpx @openuidev/cli@latest create
diff --git a/docs/content/docs/api-reference/cli.mdx b/docs/content/docs/api-reference/cli.mdx
index d5ba4c163..27c4c8917 100644
--- a/docs/content/docs/api-reference/cli.mdx
+++ b/docs/content/docs/api-reference/cli.mdx
@@ -53,19 +53,19 @@ 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 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`, `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. 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. Pass `--no-interactive` in CI or scripted environments to surface missing required flags as errors instead.
**What it does**
diff --git a/packages/openui-cli/README.md b/packages/openui-cli/README.md
index 3fa1afed6..2fa7b4304 100644
--- a/packages/openui-cli/README.md
+++ b/packages/openui-cli/README.md
@@ -10,8 +10,8 @@ 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)
- - **OpenUI Cloud** — a Next.js app backed by OpenUI Cloud for managed conversations, artifacts, and streaming
+ - **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
- generating a system prompt or JSON Schema from a `createLibrary()` export
## Install
@@ -35,8 +35,8 @@ npx @openuidev/cli@latest create
Skip the prompt and pick a template directly:
```bash
-npx @openuidev/cli@latest create --template openui-self-hosted
npx @openuidev/cli@latest create --template openui-cloud
+npx @openuidev/cli@latest create --template openui-self-hosted
```
Generate a prompt from a library file:
@@ -55,7 +55,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 agent app from the recommended managed **OpenUI Cloud** template or the **self-hosted** template.
```bash
openui create [options]
@@ -64,7 +64,7 @@ openui create [options]
Options:
- `-n, --name <string>`: Project name
-- `-t, --template <template>`: Template to scaffold — `openui-self-hosted` or `openui-cloud`
+- `-t, --template <template>`: AI backend — `openui-cloud` (managed) or `openui-self-hosted` (bring your provider)
- `--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
@@ -83,9 +83,13 @@ What it does:
- optionally installs the OpenUI agent skill for AI coding assistants
- writes a `.env` file tailored to the template (see below)
+#### Choose a backend
+
+- **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.
+
#### 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.
- **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:
@@ -93,14 +97,15 @@ What it does:
- `manual` — paste an existing key
- `skip` — leave `THESYS_API_KEY` empty and add it later (get one at <https://console.thesys.dev/keys>)
- 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.
Examples:
```bash
openui create
-openui create --name my-app --template openui-self-hosted
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 --template openui-self-hosted
openui create --name my-app --no-skill --no-install
openui create --no-interactive --name my-app --template openui-cloud --api-key tk_your_key
```
diff --git a/packages/openui-cli/src/commands/create-app.ts b/packages/openui-cli/src/commands/create-app.ts
index e4914f45f..cdcfc481b 100644
--- a/packages/openui-cli/src/commands/create-app.ts
+++ b/packages/openui-cli/src/commands/create-app.ts
@@ -124,15 +124,15 @@ export async function runCreateApp(options: CreateAppOptions): Promise<void> {
: {
prompt: {
type: "select",
- message: "Choose your AI setup",
+ message: "Choose your agent backend (OpenUI Cloud is recommended for most apps)",
choices: [
{
value: "openui-cloud",
- name: "OpenUI Cloud — fastest setup with free hosted models (recommended)",
+ name: "OpenUI Cloud — managed models, history, tools & artifacts (recommended)",
},
{
value: "openui-self-hosted",
- name: "OpenAI-compatible provider — use your own key and self-host the AI route",
+ name: "Self-hosted — choose when you need to own the provider, AI route & persistence",
},
],
},
diff --git a/packages/openui-cli/src/index.ts b/packages/openui-cli/src/index.ts
index 813696898..2537ccc87 100644
--- a/packages/openui-cli/src/index.ts
+++ b/packages/openui-cli/src/index.ts
@@ -43,15 +43,32 @@ program.hook("preAction", (_thisCommand, actionCommand) => {
program
.command("create")
- .description("Scaffold a new Next.js app with OpenUI Cloud or your provider")
+ .description(
+ "Scaffold a Next.js agent app with the recommended OpenUI Cloud backend or your own provider",
+ )
.option("-n, --name <string>", "Project name")
- .option("-t, --template <template>", "AI setup: openui-cloud | openui-self-hosted")
+ .option(
+ "-t, --template <template>",
+ "AI backend: openui-cloud (recommended default) | openui-self-hosted (infrastructure control)",
+ )
.option("--api-key <key>", "OpenUI Cloud API key (cloud template; skips sign-in)")
.option("--auth <method>", "Cloud auth method: oauth | manual | skip")
.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-install", "Scaffold without running the package install")
+ .addHelpText(
+ "after",
+ `
+Templates:
+ openui-cloud Recommended default for prototypes and evaluations.
+ Hosted models, managed conversation history, built-in tools,
+ and ready-to-use reports and presentations. No model, storage,
+ or artifact infrastructure to operate.
+ openui-self-hosted Choose when owning the OpenAI-compatible provider, AI route,
+ and persistence is a requirement.
+`,
+ )
.action(
async (options: {
name?: string;