grok-studio 0.1.0 → 0.1.2

package/README.md

@@ -1,117 +1,50 @@
 # Grok Studio
 
-Self-hosted Grok generation workspace for local/LAN use. The app keeps xAI credentials on the server, lets the browser upload or paste an image, optionally prepares a video-ready first frame, then generates and stores video outputs on disk.
+Self-hosted Grok image-to-video studio. Your xAI credentials stay on the server; turn an image into video from a web UI or the CLI, with outputs stored on disk. Built for local / LAN use.
 
-## Product Model
-
-The UI is organized around generated outputs, active work, and source-scoped lineage.
-
-- **Left rail**: `+` creates a new source image. Active Jobs appears above the output gallery when queued or running work exists; it is global and not tied to the currently selected source. Outputs are typed as `Frame` or `Video`; status text is only for exceptional or in-progress states.
-- **Result Graph**: the center canvas shows lineage for the current source. Nodes are concrete artifacts/runs:
-  - `Source` is the root image.
-  - each Prep run creates a separate `Frame` node.
-  - each Video run creates a separate `Video` node.
-- **Inspector**: the right panel is the only place for details and actions. Select a node to inspect it, download video output, rerun, prepare another frame, or animate the selected frame.
-
-Lineage is data-driven:
-
-- Source-linked video jobs attach only when `inputFrame.source === "source"` and the job's `clientSourceId` matches the current source.
-- Frame-linked video jobs attach only when `inputFrame.source === "prep"` and `preparedImageId` matches a frame in the current graph.
-- UI cache must not decide graph edges. If lineage fields are missing, do not guess by recent history.
-
-## Run
+## Install & run
 
 ```bash
-vp install
-cp .env.example .env
-vpr build
-vpr start
+npx grok-studio
 ```
 
-For normal local use:
-
-```bash
-vpr launch
-```
-
-`launch` builds the app, checks xAI auth, opens the browser login flow when no token exists, then starts the web app. Open <http://127.0.0.1:8787>.
-
-## LAN Access
-
-For local-network access, set:
-
-```dotenv
-HOST=0.0.0.0
-ACCESS_TOKEN=
-```
-
-Then restart the service and open `http://<mac-lan-ip>:8787` or `http://<mac-local-hostname>.local:8787` from another device on the same LAN.
-
-`ACCESS_TOKEN` can be left empty for trusted local/LAN use. Set it before exposing the app outside a trusted network.
+That's it. First run opens the xAI browser login if needed, then serves on <http://127.0.0.1:8787>. (`npm i -g grok-studio` also works.)
 
-## Configuration
-
-- `HOST` / `PORT` control where the server binds.
-- `ACCESS_TOKEN` optionally protects browser/API access outside loopback.
-- `WORKSPACE_DIR` stores `images/`, `videos/`, `jobs/`, and `prepared-images/`.
-- `XAI_AUTH_MODE=oauth` reads `XAI_OAUTH_TOKEN_FILE`, refreshes it when needed, and `vpr launch` can bootstrap it interactively.
-- `XAI_AUTH_MODE=api_key` uses `XAI_API_KEY`.
-- `XAI_VIDEO_MODEL` controls image-to-video generation.
-- `XAI_IMAGE_MODEL` controls first-frame image editing.
-- `DEFAULT_DURATION_SECONDS` supports up to 15 seconds.
-- `MAX_VARIATIONS` limits sequential variations per video job.
-
-The app binds to `127.0.0.1` by default. Use `HOST=0.0.0.0` only for LAN/tunnel exposure.
-
-## Grok Login Test
-
-To test the xAI/Grok browser login without touching the token file used by the running service:
-
-```bash
-vpr login
-```
-
-The command opens the xAI authorization page, waits for the local callback, saves the token state to a test path, and verifies it with the API. If xAI shows a fallback code instead of redirecting, paste that code into the terminal prompt.
-
-Useful variants:
+## CLI
 
 ```bash
-vpr login --check
-vpr login --print-url-only
-vpr login --live --force
+grok-studio serve [--open]   # start the web app (default command)
+grok-studio gen --image a.png --prompt "slow head turn" \
+  [--prep --duration 6 --resolution 720p --aspect 9:16 --count 2 --out clip.mp4]
+grok-studio login            # xAI OAuth login (browser)
+grok-studio status           # config + xAI auth + server health
 ```
 
-`vpr login` is Vite+'s shorthand for `vp run login`. Vite+ built-in top-level commands such as `vp build` and `vp test` cannot be extended by this project, so custom project commands use `vp run <task>` / `vpr <task>`.
+`gen` is headless: image →(optional `--prep` first frame)→ video, no UI; result paths print to stdout.
 
-By default, login writes to `~/.grok-video-web/login-test/xai-oauth.json` so repeated login-flow tests do not disturb the live service token. Use `--live --force` only when intentionally repairing `XAI_OAUTH_TOKEN_FILE`. `--print-url-only` is only for smoke-checking that the OAuth authorization URL can be built; it exits immediately, so do not use that URL to complete a real login.
+## Web UI
 
-## Quality Loop
+- **Left rail** — `+` adds a source image; **Active Jobs** lists running work globally; **Outputs** is a gallery of every `Frame` / `Video`.
+- **Result Graph** (center) — every node is one concrete run: `Source` → `Frame` (each prep) → `Video` (each run). Forks are sibling nodes. Lineage is derived purely from data (`inputFrame.preparedImageId` / `clientSourceId`), never guessed from history.
+- **Inspector** (right) — the only place to view a result, download, rerun, prep, or animate the selected node.
 
-Vite+ (`vp`/`vpr`) owns build, lint/format/type checks, and tests:
+## Configure (`.env`)
 
-```bash
-vpr fmt
-vpr fmt:check
-vpr lint
-vpr lint:fix
-vpr check
-vp test
-vpr build
-vpr smoke
+```dotenv
+HOST=127.0.0.1                 # 0.0.0.0 for LAN access
+PORT=8787
+ACCESS_TOKEN=                  # set to gate non-loopback access (empty = open on loopback/LAN)
+WORKSPACE_DIR=./workspace      # holds images/ videos/ jobs/ prepared-images/
+XAI_AUTH_MODE=oauth            # or: api_key (+ XAI_API_KEY)
+XAI_VIDEO_MODEL=grok-imagine-video
+XAI_IMAGE_MODEL=grok-imagine-image-quality
 ```
 
-Quality gates include:
-
-- React-specific lint rules for hooks, effect dependencies, JSX keys, nested components, unsafe JSX, and button types.
-- Type-aware linting and TypeScript checks.
-- Architecture guardrails in `tests/architecture.test.ts` to keep the main app shell thin, limit local React state in `App.tsx`, split stylesheet ownership, and keep server route files focused.
-- Browser smoke coverage in `scripts/smoke.mjs`, including paste input, image lightbox, video-card scroll behavior, and legacy history not restoring unrelated Prep outputs.
-
-## Local Service
-
-If installed as the local launchd service, restart it after building:
+## Develop
 
 ```bash
-launchctl kickstart -k gui/$(id -u)/com.pengx17.grok-video-web
-curl -fsS http://127.0.0.1:8787/health
+vp install
+vpr check && vp test && vpr build && vpr smoke
 ```
+
+Quality gates: React/a11y lint, type checks, an architecture-size test (`tests/architecture.test.ts`), and a Playwright smoke (`scripts/smoke.mjs`).

package/dist/server/cli.js

@@ -1,14 +1,15 @@
 #!/usr/bin/env node
 import fs from "node:fs";
+import { Command } from "commander";
 import path from "node:path";
 import process$1 from "node:process";
 import { config } from "dotenv";
 import { z } from "zod";
 import { setTimeout as setTimeout$1 } from "node:timers/promises";
 import crypto from "node:crypto";
-import http from "node:http";
-import readline from "node:readline/promises";
 import { execFile } from "node:child_process";
+import http from "node:http";
+import * as clack from "@clack/prompts";
 import { fileURLToPath } from "node:url";
 import express from "express";
 import multer from "multer";
@@ -1000,21 +1001,16 @@ function formatError(error) {
 }
 //#endregion
 //#region src/server/gen.ts
-async function runGenCli(argv) {
-	const args = parseArgs$1(argv);
-	if (!args.image) {
-		printHelp$2();
-		throw new Error("--image <path> is required.");
-	}
-	if (!fs.existsSync(args.image)) throw new Error(`Image not found: ${args.image}`);
+async function runGenCli(opts) {
+	if (!fs.existsSync(opts.image)) throw new Error(`Image not found: ${opts.image}`);
 	const config = loadConfig();
 	try {
 		await resolveXaiAuth(config);
 	} catch (error) {
 		throw new Error(`xAI auth not ready (${error instanceof Error ? error.message : String(error)}). Run: grok-studio login`);
 	}
-	let imagePath = path.resolve(args.image);
-	if (args.prep) {
+	let imagePath = path.resolve(opts.image);
+	if (opts.prep) {
 		process.stderr.write("preparing first frame…\n");
 		imagePath = (await generateGrokImageEdit({
 			config,
@@ -1024,11 +1020,11 @@ async function runGenCli(argv) {
 		})).localPath;
 		process.stderr.write(`prepared frame: ${imagePath}\n`);
 	}
-	const overrides = { prompt: args.prompt ?? "" };
-	if (args.duration !== void 0) overrides.durationSeconds = args.duration;
-	if (args.resolution) overrides.resolution = args.resolution;
-	if (args.aspect) overrides.aspectRatio = args.aspect;
-	if (args.count !== void 0) overrides.count = args.count;
+	const overrides = { prompt: opts.prompt ?? "" };
+	if (opts.duration !== void 0) overrides.durationSeconds = opts.duration;
+	if (opts.resolution) overrides.resolution = opts.resolution;
+	if (opts.aspect) overrides.aspectRatio = opts.aspect;
+	if (opts.count !== void 0) overrides.count = opts.count;
 	const options = normalizeGenerationOptions(overrides, defaultGenerationOptions(config.defaults), config.defaults.maxVariations);
 	const stamp = (/* @__PURE__ */ new Date()).toISOString().replace(/[:.]/g, "-");
 	const outputs = [];
@@ -1042,7 +1038,7 @@ async function runGenCli(argv) {
 			jobId: `gen_${stamp}_${take}`,
 			onStatus: (status) => process.stderr.write(`  take ${take}: ${status}\n`)
 		});
-		outputs.push(resolveOutput(result.localPath, args.out, take, options.count));
+		outputs.push(resolveOutput(result.localPath, opts.out, take, options.count));
 	}
 	for (const file of outputs) console.log(file);
 }
@@ -1052,59 +1048,6 @@ function resolveOutput(localPath, out, take, count) {
 	fs.copyFileSync(localPath, path.resolve(target));
 	return path.resolve(target);
 }
-function parseArgs$1(values) {
-	const parsed = { prep: false };
-	for (let index = 0; index < values.length; index += 1) {
-		const value = values[index];
-		if (value === "--help" || value === "-h") {
-			printHelp$2();
-			process.exit(0);
-		}
-		if (value === "--prep") {
-			parsed.prep = true;
-			continue;
-		}
-		const next = values[index + 1];
-		const requireNext = () => {
-			if (!next || next.startsWith("--")) throw new Error(`${value} requires a value.`);
-			index += 1;
-			return next;
-		};
-		if (value === "--image") parsed.image = requireNext();
-		else if (value === "--prompt") parsed.prompt = requireNext();
-		else if (value === "--out") parsed.out = requireNext();
-		else if (value === "--resolution") parsed.resolution = requireNext();
-		else if (value === "--aspect") parsed.aspect = requireNext();
-		else if (value === "--duration") parsed.duration = parsePositiveInt(requireNext(), value);
-		else if (value === "--count") parsed.count = parsePositiveInt(requireNext(), value);
-		else throw new Error(`Unknown argument: ${value}`);
-	}
-	return parsed;
-}
-function parsePositiveInt(value, flag) {
-	const parsed = Number(value);
-	if (!Number.isInteger(parsed) || parsed <= 0) throw new Error(`${flag} requires a positive integer.`);
-	return parsed;
-}
-function printHelp$2() {
-	console.log(`Usage: grok-studio gen --image <path> [options]
-
-Headlessly turn an image into a video (no UI).
-
-Options:
-  --image <path>        Source image (required).
-  --prompt <text>       Motion prompt.
-  --prep                Run a first-frame prep pass before the video.
-  --duration <seconds>  Clip length. Default from config.
-  --resolution <res>    e.g. 720p / 1080p.
-  --aspect <ratio>      e.g. source / 9:16 / 16:9 / 1:1.
-  --count <n>           Number of takes. Default 1.
-  --out <path>          Write the result here (count>1 appends -N). Default: workspace path.
-
-Example:
-  grok-studio gen --image portrait.png --prompt "slow head turn" --duration 6 --out clip.mp4
-`);
-}
 //#endregion
 //#region src/server/oauth-login.ts
 var DISCOVERY_URL = `https://auth.x.ai/.well-known/openid-configuration`;
@@ -1128,18 +1071,15 @@ async function runXaiOauthLogin(options) {
 		nonce
 	});
 	try {
-		console.log("Open this URL to authorize Grok Studio with xAI:");
-		console.log(authorizeUrl);
-		console.log();
+		clack.note(authorizeUrl, "Authorize Grok Studio with xAI");
 		if (options.printUrlOnly) return;
-		console.log(`Waiting for callback on ${redirectUri}`);
-		console.log("If xAI shows a fallback code, paste that code here and press Return.");
 		if (!options.noBrowser) openBrowser$1(authorizeUrl);
-		const callback = await waitForCallbackOrFallbackInput({
+		const callback = await awaitAuthorization({
 			server,
 			timeoutMs: (options.timeoutSeconds ?? 600) * 1e3,
 			redirectUri,
-			expectedState: state
+			expectedState: state,
+			noBrowser: Boolean(options.noBrowser)
 		});
 		if (callback.error) throw new Error(`xAI authorization failed: ${callback.error_description ?? callback.error}`);
 		if (callback.state !== state) throw new Error("xAI authorization failed: state mismatch.");
@@ -1170,7 +1110,7 @@ async function runXaiOauthLogin(options) {
 			last_refresh: (/* @__PURE__ */ new Date()).toISOString(),
 			source: "grok-video-web-oauth-login"
 		});
-		console.log(`xAI OAuth login successful. Token state saved to ${options.outputPath}`);
+		clack.log.success(`xAI OAuth login successful. Token saved to ${options.outputPath}`);
 	} finally {
 		await closeServer(server.server);
 	}
@@ -1266,24 +1206,25 @@ async function waitForCallback(serverState, timeoutMs) {
 	}
 	throw new Error("Timed out waiting for xAI OAuth callback.");
 }
-async function waitForCallbackOrFallbackInput(input) {
-	const rl = readline.createInterface({
-		input: process$1.stdin,
-		output: process$1.stdout
-	});
+async function awaitAuthorization(input) {
+	if (input.noBrowser) return pasteFallback(input.redirectUri, input.expectedState);
+	const spinner = clack.spinner();
+	spinner.start("Waiting for browser login…");
 	try {
-		return await Promise.race([waitForCallback(input.server, input.timeoutMs), waitForFallbackInput(rl, {
-			redirectUri: input.redirectUri,
-			expectedState: input.expectedState
-		})]);
-	} finally {
-		rl.close();
+		const result = await waitForCallback(input.server, input.timeoutMs);
+		spinner.stop("Authorized in browser.");
+		return result;
+	} catch {
+		spinner.stop("No browser callback received.");
+		return pasteFallback(input.redirectUri, input.expectedState);
 	}
 }
-async function waitForFallbackInput(rl, input) {
+async function pasteFallback(redirectUri, expectedState) {
 	while (true) {
-		const parsed = parseCallbackInput(await rl.question(`Paste the full ${input.redirectUri} callback URL or xAI fallback code: `), input.expectedState);
-		if (parsed) return parsed;
+		const value = await clack.text({ message: `Paste the ${redirectUri} callback URL or the xAI fallback code` });
+		if (clack.isCancel(value)) throw new Error("Login cancelled.");
+		const parsed = parseCallbackInput(String(value), expectedState);
+		if (parsed?.code || parsed?.error) return parsed;
 	}
 }
 function parseCallbackInput(value, expectedState) {
@@ -1337,11 +1278,10 @@ function writeJson0600(filePath, value) {
 //#endregion
 //#region src/server/login.ts
 var DEFAULT_TEST_TOKEN_FILE = "~/.grok-video-web/login-test/xai-oauth.json";
-async function runLoginCli(argv) {
-	const args = parseArgs(argv);
+async function runLoginCli(opts) {
 	const config = loadConfig();
 	if (config.xai.authMode !== "oauth") throw new Error("Grok login flow only applies when XAI_AUTH_MODE=oauth.");
-	const outputPath = path.resolve(expandHome(args.output ?? (args.live ? config.xai.oauthTokenFile : DEFAULT_TEST_TOKEN_FILE)));
+	const outputPath = path.resolve(expandHome(opts.output ?? (opts.live ? config.xai.oauthTokenFile : DEFAULT_TEST_TOKEN_FILE)));
 	const authConfig = {
 		...config,
 		xai: {
@@ -1349,115 +1289,26 @@ async function runLoginCli(argv) {
 			oauthTokenFile: outputPath
 		}
 	};
-	if (args.check) {
+	if (opts.check) {
 		const auth = await resolveXaiAuth(authConfig);
 		console.log(`xAI OAuth ready: ${outputPath}`);
 		console.log(`Auth mode: ${auth.label}`);
 		console.log(`Base URL: ${auth.baseUrl}`);
 		return;
 	}
-	if (fs.existsSync(outputPath) && !args.force && !args.printUrlOnly && (args.live || args.output)) {
-		console.error(`Refusing to overwrite existing token state: ${outputPath}`);
-		console.error("Pass --force to refresh this token file. The default test token path can be overwritten without --force.");
-		process.exit(1);
-	}
+	if (fs.existsSync(outputPath) && !opts.force && !opts.printUrlOnly && (opts.live || opts.output)) throw new Error(`Refusing to overwrite existing token state: ${outputPath}. Pass --force to refresh it.`);
 	await runXaiOauthLogin({
 		outputPath,
-		noBrowser: args.noBrowser,
-		port: args.port,
-		timeoutSeconds: args.timeoutSeconds,
-		printUrlOnly: args.printUrlOnly
+		noBrowser: opts.browser === false,
+		port: opts.port,
+		timeoutSeconds: opts.timeout,
+		printUrlOnly: opts.printUrlOnly
 	});
-	if (!args.printUrlOnly) {
+	if (!opts.printUrlOnly) {
 		await resolveXaiAuth(authConfig);
 		console.log("xAI OAuth token verified with the API.");
 	}
 }
-function parseArgs(values) {
-	const parsed = {
-		live: false,
-		force: false,
-		noBrowser: false,
-		check: false,
-		printUrlOnly: false
-	};
-	for (let index = 0; index < values.length; index += 1) {
-		const value = values[index];
-		if (value === "--") continue;
-		if (value === "--help" || value === "-h") {
-			printHelp$1();
-			process.exit(0);
-		}
-		if (value === "--force") {
-			parsed.force = true;
-			continue;
-		}
-		if (value === "--live") {
-			parsed.live = true;
-			continue;
-		}
-		if (value === "--no-browser") {
-			parsed.noBrowser = true;
-			continue;
-		}
-		if (value === "--check") {
-			parsed.check = true;
-			continue;
-		}
-		if (value === "--print-url-only") {
-			parsed.printUrlOnly = true;
-			parsed.noBrowser = true;
-			continue;
-		}
-		if (value === "--output") {
-			parsed.output = requireValue(values, index, value);
-			index += 1;
-			continue;
-		}
-		if (value === "--port") {
-			parsed.port = parseInteger(requireValue(values, index, value), value);
-			index += 1;
-			continue;
-		}
-		if (value === "--timeout") {
-			parsed.timeoutSeconds = parseInteger(requireValue(values, index, value), value);
-			index += 1;
-			continue;
-		}
-		throw new Error(`Unknown argument: ${value}`);
-	}
-	return parsed;
-}
-function printHelp$1() {
-	console.log(`Usage: grok-studio login [options]
-
-Options:
-  --live                Write to XAI_OAUTH_TOKEN_FILE instead of the safe test token file.
-  --output <path>       Token state file to write. Defaults to ~/.grok-video-web/login-test/xai-oauth.json.
-  --force               Allow replacing an existing explicit or live token state file.
-  --check               Verify the selected token file without opening login.
-  --no-browser          Print the auth URL and wait instead of opening a browser.
-  --print-url-only      Print a disposable auth URL for smoke testing, then exit.
-  --port <number>       Local callback port. Default: 56121.
-  --timeout <seconds>   Login wait timeout. Default: 600.
-
-Safe test example:
-  grok-studio login
-
-Live token repair:
-  grok-studio login --live --force
-`);
-}
-function requireValue(values, index, flag) {
-	const next = values[index + 1];
-	if (!next || next.startsWith("--")) throw new Error(`${flag} requires a value.`);
-	return next;
-}
-function parseInteger(value, flag) {
-	const parsed = Number(value);
-	if (!Number.isInteger(parsed) || parsed <= 0) throw new Error(`${flag} requires a positive integer.`);
-	return parsed;
-}
 function expandHome(value) {
 	if (value === "~") return process.env.HOME ?? process.cwd();
 	if (value.startsWith("~/")) return path.join(process.env.HOME ?? process.cwd(), value.slice(2));
@@ -1832,14 +1683,15 @@ function cleanOptionalString(value) {
 //#endregion
 //#region src/server/serve.ts
 async function startServer(options = {}) {
+	clack.intro("Grok Studio");
 	const config = loadConfig();
 	await ensureAuthReady(config);
 	const { app } = createServer(config);
 	app.listen(config.port, config.host, () => {
-		const url = `http://${config.host}:${config.port}`;
-		console.log(`Grok Studio is running: ${url}`);
-		if (config.accessToken) console.log("ACCESS_TOKEN is configured; enter the value from .env in the browser gate.");
-		else console.log("ACCESS_TOKEN is not set; API access is open to whoever can reach this host.");
+		const url = `http://${config.host === "0.0.0.0" || config.host === "::" ? "127.0.0.1" : config.host}:${config.port}`;
+		const access = config.accessToken ? "Access: token required (set in .env)" : "Access: open — no ACCESS_TOKEN set";
+		clack.note(`${url}\n${access}`, "Running");
+		clack.outro("Press Ctrl+C to stop.");
 		if (options.open) openBrowser(url);
 	});
 }
@@ -1850,13 +1702,11 @@ async function ensureAuthReady(config) {
 	}
 	try {
 		await resolveXaiAuth(config);
-		console.log(`xAI OAuth ready: ${config.xai.oauthTokenFile}`);
+		clack.log.success(`xAI OAuth ready (${config.xai.oauthTokenFile})`);
 		return;
 	} catch (error) {
-		if (fs.existsSync(config.xai.oauthTokenFile)) {
-			console.warn(`xAI OAuth token check failed: ${error instanceof Error ? error.message : String(error)}`);
-			console.warn("Starting OAuth login to repair the token state.");
-		} else console.log(`No xAI OAuth token found at ${config.xai.oauthTokenFile}. Starting login.`);
+		if (fs.existsSync(config.xai.oauthTokenFile)) clack.log.warn(`xAI token check failed: ${error instanceof Error ? error.message : String(error)} — re-running login.`);
+		else clack.log.info("No xAI token found — starting login.");
 	}
 	await runXaiOauthLogin({ outputPath: config.xai.oauthTokenFile });
 	await resolveXaiAuth(config);
@@ -1868,35 +1718,22 @@ function openBrowser(url) {
 }
 //#endregion
 //#region src/server/cli.ts
-var [command, ...rest] = process.argv.slice(2);
+var program = new Command();
+program.name("grok-studio").description("Self-hosted Grok image-to-video studio (web app + CLI).").version(readVersion(), "-v, --version");
+program.command("serve", { isDefault: true }).description("Start the web app (ensures xAI auth, then serves HTTP).").option("--open", "open the browser after starting").action(async (opts) => {
+	await startServer({ open: Boolean(opts.open) });
+});
+program.command("login").description("Run the xAI OAuth login.").option("--live", "write to the live token file instead of the safe test path").option("--output <path>", "token state file to write").option("--force", "allow replacing an existing token file").option("--check", "verify the selected token file without logging in").option("--no-browser", "print the auth URL and wait instead of opening a browser").option("--print-url-only", "print a disposable auth URL, then exit").option("--port <number>", "local callback port", Number).option("--timeout <seconds>", "login wait timeout", Number).action(async (opts) => {
+	await runLoginCli(opts);
+});
+program.command("gen").description("Headlessly turn an image into a video (no UI).").requiredOption("--image <path>", "source image").option("--prompt <text>", "motion prompt").option("--prep", "run a first-frame prep pass before the video").option("--duration <seconds>", "clip length", Number).option("--resolution <res>", "e.g. 720p / 1080p").option("--aspect <ratio>", "e.g. source / 9:16 / 16:9 / 1:1").option("--count <n>", "number of takes", Number).option("--out <path>", "write the result here (count>1 appends -N)").action(async (opts) => {
+	await runGenCli(opts);
+});
+program.command("status").description("Print config, xAI auth, and server health.").action(async () => {
+	await runStatus();
+});
 try {
-	switch (command) {
-		case void 0:
-		case "serve":
-			await startServer({ open: rest.includes("--open") });
-			break;
-		case "login":
-			await runLoginCli(rest);
-			break;
-		case "gen":
-			await runGenCli(rest);
-			break;
-		case "status":
-			await runStatus();
-			break;
-		case "-v":
-		case "--version":
-			console.log(readVersion());
-			break;
-		case "-h":
-		case "--help":
-			printHelp();
-			break;
-		default:
-			console.error(`Unknown command: ${command}\n`);
-			printHelp();
-			process.exit(1);
-	}
+	await program.parseAsync(process.argv);
 } catch (error) {
 	console.error(`Error: ${error instanceof Error ? error.message : String(error)}`);
 	process.exit(1);
@@ -1930,20 +1767,5 @@ function readVersion() {
 		return "0.0.0";
 	}
 }
-function printHelp() {
-	console.log(`Grok Studio — self-hosted image-to-video studio
-
-Usage: grok-studio <command> [options]
-
-Commands:
-  serve            Start the web app (default). Ensures xAI auth, then serves HTTP.
-                     --open   open the browser after starting
-  login [options]  Run the xAI OAuth login (see: grok-studio login --help)
-  gen [options]    Headlessly turn an image into a video (see: grok-studio gen --help)
-  status           Print config, xAI auth, and server health
-  --version, -v    Print the version
-  --help, -h       Print this help
-`);
-}
 //#endregion
 export {};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "grok-studio",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "private": false,
   "description": "Self-hosted Grok image-to-video studio (web app + CLI).",
   "bin": {
@@ -35,7 +35,9 @@
     "prepack": "vp run build"
   },
   "dependencies": {
+    "@clack/prompts": "^1.5.0",
     "@xyflow/react": "^12.11.0",
+    "commander": "^15.0.0",
     "dotenv": "^17.2.3",
     "express": "^5.2.1",
     "lucide-react": "^0.561.0",