Skip to content

The Open Standard for Generative UI

feat(cli): add Cloud sign-in and configurable env files for examples (#1336)

ABadc023433e0e
diff --git a/.changeset/example-cloud-auth.md b/.changeset/example-cloud-auth.md
new file mode 100644
index 000000000..b8aeba8a8
--- /dev/null
+++ b/.changeset/example-cloud-auth.md
@@ -0,0 +1,5 @@
+---
+"@openuidev/cli": patch
+---
+
+Offer browser sign-in and API key generation when scaffolding OpenUI examples. Read the primary key and destination from the example catalog's nested `env` object, including backend `.env` files and `.env.local`, and preserve other environment settings.
diff --git a/docs/components/showcase/examples.tsx b/docs/components/showcase/examples.tsx
index 32a4aa7ba..a6e19b7f7 100644
--- a/docs/components/showcase/examples.tsx
+++ b/docs/components/showcase/examples.tsx
@@ -52,7 +52,7 @@ export function RepoExamples() {
<h4 className={styles.cardTitle}>{example.title}</h4>
<p className={styles.cardDescription}>{example.description}</p>
<div className={styles.cardLinks}>
- <RunLocally title={example.title} name={example.name} envKey={example.envKey} />
+ <RunLocally title={example.title} name={example.name} env={example.env} />
<CardLink label="Source" href={example.sourceUrl} external />
{example.guideUrl ? (
<Link className={styles.cardLink} href={example.guideUrl}>
diff --git a/docs/components/showcase/run-locally.tsx b/docs/components/showcase/run-locally.tsx
index 435bdd3c4..7030ff2a8 100644
--- a/docs/components/showcase/run-locally.tsx
+++ b/docs/components/showcase/run-locally.tsx
@@ -9,11 +9,11 @@ import styles from "./showcase.module.css";
type RunLocallyProps = {
title: string;
name: string;
- envKey?: string;
+ env?: { file: string; key?: string };
};
/** Shows the exact `openui create` command for an example and what it will ask for. */
-export function RunLocally({ title, name, envKey }: RunLocallyProps) {
+export function RunLocally({ title, name, env }: RunLocallyProps) {
const command = `npx @openuidev/cli@latest create --example ${name}`;
const [copied, onCopy] = useCopyButton(() => navigator.clipboard.writeText(command));
@@ -45,10 +45,10 @@ export function RunLocally({ title, name, envKey }: RunLocallyProps) {
</button>
</div>
<p className={styles.runNote}>
- {envKey ? (
+ {env?.key ? (
<>
- The CLI copies the example into a new folder and asks for your <code>{envKey}</code>,
- which it saves to <code>.env</code>.
+ The CLI copies the example into a new folder and asks for your <code>{env.key}</code>,
+ which it saves to <code>{env.file}</code>.
</>
) : (
<>
diff --git a/docs/lib/examples-catalog.ts b/docs/lib/examples-catalog.ts
index 2c6edc1d9..a497dd1bd 100644
--- a/docs/lib/examples-catalog.ts
+++ b/docs/lib/examples-catalog.ts
@@ -28,8 +28,8 @@ export type RepoExample = {
category: ExampleCategoryId;
sourceUrl: string;
guideUrl?: string;
- /** The key the CLI asks for while scaffolding. Omitted when the example needs several. */
- envKey?: string;
+ /** Environment setup used by the CLI while scaffolding. */
+ env?: { file: string; key?: string };
};
export const REPO_EXAMPLES: RepoExample[] = catalog.examples.map((example) => {
@@ -42,7 +42,7 @@ export const REPO_EXAMPLES: RepoExample[] = catalog.examples.map((example) => {
category,
sourceUrl: `${EXAMPLES_REPO_URL}/${example.path}`,
guideUrl: EXAMPLE_GUIDES[example.path],
- envKey: example.envKey,
+ env: example.env,
};
});
diff --git a/examples/examples.json b/examples/examples.json
index eac950c14..679f69600 100644
--- a/examples/examples.json
+++ b/examples/examples.json
@@ -4,106 +4,157 @@
"title": "Google ADK",
"description": "A Google ADK TypeScript agent streaming OpenUI Lang to a Next.js client.",
"path": "agent-frameworks/google-adk",
- "envKey": "THESYS_API_KEY"
+ "env": {
+ "file": ".env",
+ "key": "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",
- "envKey": "THESYS_API_KEY"
+ "env": {
+ "file": ".env",
+ "key": "THESYS_API_KEY"
+ }
},
{
"title": "Mastra",
"description": "A Mastra agent connected to OpenUI through AG-UI.",
"path": "agent-frameworks/mastra",
- "envKey": "THESYS_API_KEY",
+ "env": {
+ "file": ".env",
+ "key": "THESYS_API_KEY"
+ },
"featured": true
},
{
"title": "Vercel AI SDK",
"description": "AgentInterface over a Vercel AI SDK streamText backend.",
"path": "agent-frameworks/vercel-ai-sdk",
- "envKey": "THESYS_API_KEY"
+ "env": {
+ "file": ".env",
+ "key": "THESYS_API_KEY"
+ }
},
{
"title": "Vercel Eve",
"description": "An Eve agent rendered through Agent Interface.",
"path": "agent-frameworks/vercel-eve",
- "envKey": "THESYS_API_KEY"
+ "env": {
+ "file": ".env",
+ "key": "THESYS_API_KEY"
+ }
},
{
"title": "Angular",
"description": "An NG-ZORRO X chat interface rendering OpenUI Cloud responses with the Angular runtime.",
"path": "app-frameworks/angular",
- "envKey": "THESYS_API_KEY"
+ "env": {
+ "file": ".env",
+ "key": "THESYS_API_KEY"
+ }
},
{
"title": "FastAPI",
"description": "A Python FastAPI streaming backend with a React OpenUI client.",
"path": "app-frameworks/fastapi",
- "envKey": "THESYS_API_KEY"
+ "env": {
+ "file": "backend/.env",
+ "key": "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",
- "envKey": "THESYS_API_KEY"
+ "env": {
+ "file": "backend/.env",
+ "key": "THESYS_API_KEY"
+ }
},
{
"title": "Svelte",
"description": "OpenUI Lang parsing and rendering in SvelteKit.",
"path": "app-frameworks/svelte",
- "envKey": "THESYS_API_KEY"
+ "env": {
+ "file": ".env",
+ "key": "THESYS_API_KEY"
+ }
},
{
"title": "Vue",
"description": "OpenUI Lang parsing and rendering in Nuxt and Vue.",
"path": "app-frameworks/vue",
- "envKey": "THESYS_API_KEY"
+ "env": {
+ "file": ".env",
+ "key": "THESYS_API_KEY"
+ }
},
{
"title": "Conversational analytics",
"description": "Explore real Formula 1 lap times with OpenUI Gateway, streamed charts, and visible database tool calls.",
"path": "cookbooks/conversational-analytics",
- "envKey": "THESYS_API_KEY"
+ "env": {
+ "file": ".env",
+ "key": "THESYS_API_KEY"
+ }
},
{
"title": "Document comparison",
"description": "Compare NVIDIA, AMD, and Intel annual reports with retrieved, page-cited evidence, charts, and a customized Agent Interface.",
"path": "cookbooks/document-comparison",
- "envKey": "THESYS_API_KEY"
+ "env": {
+ "file": ".env",
+ "key": "THESYS_API_KEY"
+ }
},
{
"title": "Booking assistant",
"description": "Find stays anywhere with prefilled, validated forms, live hotel prices from trivago's MCP server, and a summary before booking.",
"path": "cookbooks/booking-assistant",
- "envKey": "THESYS_API_KEY"
+ "env": {
+ "file": ".env",
+ "key": "THESYS_API_KEY"
+ }
},
{
"title": "Material UI",
"description": "A broad Material UI component library for generated interfaces.",
"path": "design-systems/material-ui",
- "envKey": "THESYS_API_KEY",
+ "env": {
+ "file": ".env",
+ "key": "THESYS_API_KEY"
+ },
"featured": true
},
{
"title": "ShadCN",
"description": "A broad shadcn/ui component library for generated interfaces.",
"path": "design-systems/shadcn",
- "envKey": "THESYS_API_KEY",
+ "env": {
+ "file": ".env",
+ "key": "THESYS_API_KEY"
+ },
"featured": true
},
{
"title": "Grok Build",
"description": "Grok Build coding sessions rendered with OpenUI Cloud.",
"path": "harnesses/grok-build",
- "envKey": "XAI_API_KEY"
+ "env": {
+ "file": ".env",
+ "key": "XAI_API_KEY"
+ }
},
{
"title": "Pi Harness",
"description": "A Pi coding-agent session on OpenUI Cloud.",
"path": "harnesses/pi",
- "envKey": "THESYS_API_KEY",
+ "env": {
+ "file": ".env",
+ "key": "THESYS_API_KEY"
+ },
"featured": true
},
{
@@ -115,25 +166,37 @@
"title": "Handsontable",
"description": "Generated spreadsheet interfaces backed by Handsontable.",
"path": "miscellaneous/handsontable",
- "envKey": "THESYS_API_KEY"
+ "env": {
+ "file": ".env",
+ "key": "THESYS_API_KEY"
+ }
},
{
"title": "HTML artifact",
"description": "Sandboxed HTML artifacts as an OpenUI capability.",
"path": "miscellaneous/html-artifact",
- "envKey": "THESYS_API_KEY"
+ "env": {
+ "file": ".env",
+ "key": "THESYS_API_KEY"
+ }
},
{
"title": "React Email",
"description": "Generating and previewing emails with the OpenUI React Email library.",
"path": "miscellaneous/react-email",
- "envKey": "THESYS_API_KEY"
+ "env": {
+ "file": ".env",
+ "key": "THESYS_API_KEY"
+ }
},
{
"title": "Supabase",
"description": "Persisted OpenUI conversations and threads with Supabase.",
"path": "miscellaneous/supabase",
- "envKey": "THESYS_API_KEY"
+ "env": {
+ "file": ".env.local",
+ "key": "THESYS_API_KEY"
+ }
}
]
}
diff --git a/packages/openui-cli/README.md b/packages/openui-cli/README.md
index 3df1ac1d6..0a008a113 100644
--- a/packages/openui-cli/README.md
+++ b/packages/openui-cli/README.md
@@ -105,8 +105,8 @@ Options:
- `-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
-- `--auth <method>`: (cloud template) How to obtain the key — `oauth` or `skip`; `manual` remains available for backward compatibility but is deprecated
+- `--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`)
`--immediate` and `--no-immediate` are mutually exclusive; passing both exits with an error.
@@ -157,6 +157,10 @@ 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.
diff --git a/packages/openui-cli/src/commands/create/command.ts b/packages/openui-cli/src/commands/create/command.ts
index 72de95da4..42d0c8379 100644
--- a/packages/openui-cli/src/commands/create/command.ts
+++ b/packages/openui-cli/src/commands/create/command.ts
@@ -16,7 +16,7 @@ export const createCommand = new Command("create")
.option("-t, --template <template>", "AI backend to use (default: openui-cloud)")
.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 template; skips sign-in)")
+ .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")
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 15c21196f..c48c740db 100644
--- a/packages/openui-cli/src/commands/create/lib/create-example.ts
+++ b/packages/openui-cli/src/commands/create/lib/create-example.ts
@@ -4,7 +4,7 @@ import { resolveInstallPackageManager } from "../../../lib/detect-package-manage
import { CliCancelledError, cliErrorProperties, CreateError } from "../../../lib/errors";
import { withSpinner } from "../../../lib/spinner";
import type { CreateAppOptions, EnvResult } from "./create-types";
-import { writeEnvVar } from "./env";
+import { resolveCloudEnv, writeEnvVar } from "./env";
import type { ExampleProject } from "./examples-catalog";
import { installRequestedSkill, shouldInstallSkill } from "./install-skill";
import {
@@ -37,7 +37,7 @@ export async function runCreateExample(params: {
});
tel.trackEnvResolutionStarted({ example: example.name });
- const envResult = await resolveExampleEnv(example, interactive);
+ const envResult = await resolveExampleEnv(example, name, options, interactive, tel);
const installSkill = await shouldInstallSkill(options.skill, false);
tel.trackSkillInstalled({ skill_installed: installSkill });
@@ -83,8 +83,8 @@ export async function runCreateExample(params: {
tel.trackScaffoldSucceeded({ example: example.name });
try {
- if (envResult.envKeyValue && example.envKey) {
- writeEnvVar(path.join(targetDir, example.envFile), example.envKey, envResult.envKeyValue);
+ if (envResult.envKeyValue && example.env.key) {
+ writeEnvVar(path.join(targetDir, example.env.file), example.env.key, envResult.envKeyValue);
}
} catch (err) {
const properties = cliErrorProperties(err, {
@@ -102,6 +102,8 @@ export async function runCreateExample(params: {
tel.trackEnvResolved({
example: example.name,
env_written: envResult.envWritten,
+ auth_method: envResult.authMethod,
+ auth_succeeded: envResult.authSucceeded,
});
layout ??= exampleLayout(targetDir);
@@ -126,14 +128,16 @@ export async function runCreateExample(params: {
duration_ms: Date.now() - t0,
skill_installed: skillInstalled,
env_written: envResult.envWritten,
+ auth_method: envResult.authMethod,
+ auth_succeeded: envResult.authSucceeded,
dependency_installed: false,
});
- const envKey = example.envKey;
+ const envKey = example.env.key;
const envNote = envKey
? envResult.envWritten
- ? `✅ ${example.envFile} updated with ${envKey}.`
- : `Add ${envKey}=… to ${example.envFile} (see the example README).`
- : `Add your API keys to ${example.envFile} (see the example README).`;
+ ? `✅ ${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 skillMessage = skillInstalled
? "The OpenUI agent skill was installed.\nAI coding assistants will use it to help you build with OpenUI.\n"
: "";
@@ -154,13 +158,26 @@ export async function runCreateExample(params: {
async function resolveExampleEnv(
example: ExampleProject,
+ name: string,
+ options: CreateAppOptions,
interactive: boolean,
+ tel: CreateTelemetryClient,
): Promise<EnvResult & { envKeyValue?: string }> {
- if (!example.envKey) {
+ if (!example.env.key) {
return { envWritten: false };
}
- const apiKey = interactive ? await promptForProviderKey(example.envKey) : null;
+ if (example.env.key === "THESYS_API_KEY") {
+ const result = await resolveCloudEnv(
+ name,
+ { ...options, envFile: example.env.file },
+ interactive,
+ tel,
+ );
+ return { ...result, envKeyValue: result.envVars?.[example.env.key] || undefined };
+ }
+
+ const apiKey = interactive ? await promptForProviderKey(example.env.key) : null;
return {
envWritten: apiKey != null,
envKeyValue: apiKey ?? undefined,
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 732d1d811..ff73a790d 100644
--- a/packages/openui-cli/src/commands/create/lib/create-types.ts
+++ b/packages/openui-cli/src/commands/create/lib/create-types.ts
@@ -15,6 +15,7 @@ export interface CreateAppOptions {
noInstall?: boolean;
immediate?: boolean;
apiKey?: string;
+ envFile?: string;
auth?: CloudAuthMethod;
}
diff --git a/packages/openui-cli/src/commands/create/lib/env.ts b/packages/openui-cli/src/commands/create/lib/env.ts
index c5ef33bc3..87896a3b3 100644
--- a/packages/openui-cli/src/commands/create/lib/env.ts
+++ b/packages/openui-cli/src/commands/create/lib/env.ts
@@ -95,6 +95,7 @@ export async function resolveCloudEnv(
interactive: boolean,
tel: CreateTelemetryClient,
): Promise<EnvResult> {
+ const envFile = options.envFile ?? DEFAULT_ENV_FILE;
let apiKey: string | null = null;
let authMethod: EnvResult["authMethod"];
try {
@@ -105,6 +106,7 @@ export async function resolveCloudEnv(
apiKey: options.apiKey,
auth: options.auth,
projectName: name,
+ envFile,
interactive,
tel: tel.authClient(),
});
@@ -135,7 +137,7 @@ export async function resolveCloudEnv(
...properties,
});
console.error(`\n[!] Could not obtain an API key: ${msg}`);
- console.error(` Add THESYS_API_KEY to .env later (keys: ${THESYS_KEYS_URL}).\n`);
+ console.error(` Add THESYS_API_KEY to ${envFile} later (keys: ${THESYS_KEYS_URL}).\n`);
}
return {
envWritten: apiKey != null,
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 e5d51a407..37d63eaa3 100644
--- a/packages/openui-cli/src/commands/create/lib/examples-catalog.ts
+++ b/packages/openui-cli/src/commands/create/lib/examples-catalog.ts
@@ -12,9 +12,12 @@ export type ExampleProject = {
description: string;
/** Path inside the OpenUI repo, e.g. `examples/app-frameworks/vue`. */
path: string;
- envFile: ".env";
- /** Primary env var to prompt for. Omit when the example needs several keys. */
- envKey?: string;
+ env: {
+ /** Environment file relative to the example root. */
+ file: string;
+ /** Primary env var to prompt for. Omit when the example needs several keys. */
+ key?: string;
+ };
/** Show this example in the curated interactive picker. */
featured?: boolean;
};
@@ -28,7 +31,7 @@ function parseCatalogEntry(item: unknown): ExampleProject {
title?: unknown;
description?: unknown;
path?: unknown;
- envKey?: unknown;
+ env?: unknown;
featured?: unknown;
};
if (
@@ -48,19 +51,29 @@ function parseCatalogEntry(item: unknown): ExampleProject {
if (!name) {
throw catalogError(`${EXAMPLES_CATALOG_PATH} has an example with an empty path.`);
}
- if (entry.envKey !== undefined) {
- if (typeof entry.envKey !== "string" || !/^[A-Za-z_][A-Za-z0-9_]*$/.test(entry.envKey)) {
- throw catalogError(`${EXAMPLES_CATALOG_PATH} example "${name}" has an invalid envKey.`);
+ if (
+ entry.env !== undefined &&
+ (typeof entry.env !== "object" || entry.env === null || Array.isArray(entry.env))
+ ) {
+ throw catalogError(`${EXAMPLES_CATALOG_PATH} example "${name}" has an invalid env.`);
+ }
+ const env = (entry.env ?? {}) as { file?: unknown; key?: unknown };
+ if (env.key !== undefined) {
+ if (typeof env.key !== "string" || !/^[A-Za-z_][A-Za-z0-9_]*$/.test(env.key)) {
+ throw catalogError(`${EXAMPLES_CATALOG_PATH} example "${name}" has an invalid env.key.`);
}
}
+ const file = env.file ?? ".env";
+ if (typeof file !== "string" || !/^(?:[A-Za-z0-9_-]+\/)*\.env(?:\.local)?$/.test(file)) {
+ throw catalogError(`${EXAMPLES_CATALOG_PATH} example "${name}" has an invalid env.file.`);
+ }
return {
name,
label: entry.title,
description: entry.description,
path: relative.startsWith("examples/") ? relative : `examples/${relative}`,
- envFile: ".env",
+ env: { file, key: typeof env.key === "string" ? env.key : undefined },
featured: entry.featured === true,
- envKey: typeof entry.envKey === "string" ? entry.envKey : undefined,
};
}
diff --git a/packages/openui-cli/src/lib/auth/mint.ts b/packages/openui-cli/src/lib/auth/mint.ts
index 9ea89ee8b..7b0ab2846 100644
--- a/packages/openui-cli/src/lib/auth/mint.ts
+++ b/packages/openui-cli/src/lib/auth/mint.ts
@@ -177,6 +177,7 @@ export async function resolveCloudApiKey(opts: {
apiKey?: string;
auth?: CloudAuthMethod;
projectName: string;
+ envFile?: string;
interactive: boolean;
tel: AuthTelemetryClient;
}): Promise<{ key: string | null; method: ResolvedAuthMethod }> {
@@ -202,7 +203,10 @@ export async function resolveCloudApiKey(opts: {
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 .env later", value: "skip" },
+ {
+ name: `Skip — add THESYS_API_KEY to ${opts.envFile ?? ".env"} later`,
+ value: "skip",
+ },
],
}) as Promise<CloudAuthMethod>,
);