blodemd 0.0.15 → 0.2.0

package/README.md

@@ -9,7 +9,7 @@
 - **One-command deploy:** Push your entire docs folder to Blode.md with `blodemd push`.
 - **Scaffold in seconds:** Generate a ready-to-edit docs folder with `blodemd new`.
 - **Config validation:** Catch `docs.json` errors before deploying.
-- **Zero keys:** Sign in once with GitHub in your browser — the CLI handles the rest.
+- **Zero keys locally:** Sign in once with GitHub in your browser — no keys for local deploys. CI uses a project deploy key.
 
 ## Install
 
@@ -41,6 +41,30 @@ blodemd dev
 blodemd push
 ```
 
+## Deploy from CI
+
+The [GitHub App](#auto-deploy-without-the-cli) is the recommended zero-config path. To run the deploy yourself from GitHub Actions, use a project deploy key stored in the `BLODEMD_API_KEY` secret:
+
+```yaml
+name: Deploy docs
+on:
+  push:
+    branches: [main]
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v5
+      - uses: actions/setup-node@v5
+        with:
+          node-version: 24
+      - run: npx blodemd@latest push --project your-project-slug
+        env:
+          BLODEMD_API_KEY: ${{ secrets.BLODEMD_API_KEY }}
+```
+
+Create a deploy key in the dashboard under **Settings → Deploy keys**, or copy the `bmd_...` key that `blodemd push` prints the first time it auto-creates a project. Deploy keys are project-scoped and deploy-only — store them as CI secrets, never commit them.
+
 ## Commands
 
 ```bash
@@ -57,6 +81,7 @@ blodemd dev [dir]         Start the local docs preview server
 
 ```
 --project <slug>    Project slug (env: BLODEMD_PROJECT)
+--api-key <token>   API key (env: BLODEMD_API_KEY)
 --api-url <url>     API URL (env: BLODEMD_API_URL)
 --branch <name>     Git branch (env: BLODEMD_BRANCH)
 --message <msg>     Deploy message (env: BLODEMD_COMMIT_MESSAGE)

package/dist/cli.mjs

@@ -1,5 +1,4 @@
 #!/usr/bin/env node
-import { createRequire } from "node:module";
 import { Command, InvalidArgumentError } from "commander";
 import { confirm, intro, isCancel, log, select, spinner, text } from "@clack/prompts";
 import chalk from "chalk";
@@ -20,6 +19,7 @@ import { watch } from "chokidar";
 import { readFileSync } from "node:fs";
 //#region src/constants.ts
 const CLI_NAME = "blodemd";
+const BLODE_API_KEY_ENV = "BLODEMD_API_KEY";
 const BLODE_PROJECT_ENV = "BLODEMD_PROJECT";
 const OAUTH_CLIENT_ID = "6b5f9860-fe96-4a83-b1ad-266260523c91";
 const DEFAULT_OAUTH_CALLBACK_PORT = 8787;
@@ -55,6 +55,7 @@ const toCliError = (error) => {
 	if (error instanceof Error) {
 		if (error instanceof TypeError && error.message.includes("fetch")) return new CliError("Cannot connect to Blode.md API.", EXIT_CODES.NETWORK, "Check your internet connection and API URL configuration.");
 		if (error.name === "TimeoutError" || error.name === "AbortError") return new CliError("Request timed out.", EXIT_CODES.NETWORK, "The API may be unavailable. Try again later.");
+		if (/\b401\b/.test(error.message)) return new CliError(error.message, EXIT_CODES.AUTH_REQUIRED, "Check your API key or run \"blodemd login\".");
 		return new CliError(error.message, EXIT_CODES.ERROR);
 	}
 	return new CliError("Unknown error", EXIT_CODES.ERROR);
@@ -1220,6 +1221,67 @@ const registerAnalyticsCommand = (program) => {
 	});
 };
 //#endregion
+//#region src/output.ts
+const isInteractive = (json = false) => !json && Boolean(process.stdout.isTTY) && !process.env.CI;
+const writeLine = (message) => {
+	process.stderr.write(`${message}\n`);
+};
+const createReporter = ({ json = false } = {}) => {
+	const interactive = isInteractive(json);
+	if (!interactive) return {
+		info: writeLine,
+		interactive,
+		json: (payload) => {
+			process.stdout.write(`${JSON.stringify(payload)}\n`);
+		},
+		step: writeLine,
+		stop: (message) => {
+			if (message) writeLine(message);
+		},
+		success: writeLine,
+		warn: writeLine
+	};
+	const s = spinner();
+	let active = false;
+	return {
+		info(message) {
+			if (active) {
+				s.stop();
+				active = false;
+			}
+			log.info(message);
+		},
+		interactive,
+		json() {},
+		step(message) {
+			if (active) s.message(message);
+			else {
+				s.start(message);
+				active = true;
+			}
+		},
+		stop(message) {
+			if (active) {
+				s.stop(message);
+				active = false;
+			}
+		},
+		success(message) {
+			if (active) {
+				s.stop(message);
+				active = false;
+			} else log.success(message);
+		},
+		warn(message) {
+			if (active) {
+				s.stop();
+				active = false;
+			}
+			log.warn(message);
+		}
+	};
+};
+//#endregion
 //#region src/scaffold.ts
 const SCAFFOLD_TEMPLATES = ["minimal", "starter"];
 const DEFAULT_SCAFFOLD_DIRECTORY = "docs";
@@ -1617,11 +1679,16 @@ const collectFiles = async (root, directory = root) => {
 	}
 	return files.toSorted((left, right) => left.localeCompare(right));
 };
-const reportCommandError = (prefix, error) => {
+const reportCommandError = (prefix, error, options) => {
 	const cliError = toCliError(error);
-	log.error(`${prefix}: ${cliError.message}`);
-	if (cliError.hint) log.info(cliError.hint);
-	log.info("Failed");
+	if (isInteractive(options?.json)) {
+		log.error(`${prefix}: ${cliError.message}`);
+		if (cliError.hint) log.info(cliError.hint);
+		log.info("Failed");
+	} else {
+		process.stderr.write(`${prefix}: ${cliError.message}\n`);
+		if (cliError.hint) process.stderr.write(`${cliError.hint}\n`);
+	}
 	process.exitCode = cliError.exitCode;
 };
 const parseScaffoldTemplate = (value) => {
@@ -1827,6 +1894,7 @@ const registerAuthCommands = (program) => {
 			const resolved = await resolveAuthToken();
 			if (!resolved) {
 				log.warn("Not logged in. Run \"blodemd login\" to authenticate.");
+				process.exitCode = EXIT_CODES.AUTH_REQUIRED;
 				return;
 			}
 			const status = resolveTokenStatus(resolved);
@@ -1904,51 +1972,7 @@ const DEV_READY_TIMEOUT_MS = 45e3;
 const DEV_PORT_SCAN_LIMIT = 10;
 const DEV_SHUTDOWN_TIMEOUT_MS = 5e3;
 const LOCALHOST = "127.0.0.1";
-const RUNTIME_EXCLUDE_DIRS = new Set([
-	".next",
-	".turbo",
-	"node_modules"
-]);
-const STANDALONE_RUNTIME_MAX_AGE_MS = 1440 * 60 * 1e3;
-const STANDALONE_RUNTIME_PREFIX = "standalone-runtime-";
-const TURBOPACK_ARGS = ["dev", "--turbopack"];
-const fileExists = async (filePath) => {
-	try {
-		await fs.access(filePath);
-		return true;
-	} catch {
-		return false;
-	}
-};
-const resolveCommonAncestor = (pathsToCompare) => {
-	const [firstPath, ...restPaths] = pathsToCompare;
-	if (!firstPath) return path.sep;
-	const first = path.resolve(firstPath);
-	const { root } = path.parse(first);
-	const firstSegments = first.slice(root.length).split(path.sep).filter(Boolean);
-	const sharedSegments = [];
-	for (const [index, segment] of firstSegments.entries()) {
-		if (!restPaths.every((candidatePath) => {
-			const candidate = path.resolve(candidatePath);
-			if (path.parse(candidate).root !== root) return false;
-			return candidate.slice(root.length).split(path.sep).filter(Boolean)[index] === segment;
-		})) break;
-		sharedSegments.push(segment);
-	}
-	return path.join(root, ...sharedSegments);
-};
-const cleanupStandaloneRuntimeRoots = async (configDir, maxAgeMs = STANDALONE_RUNTIME_MAX_AGE_MS) => {
-	const cutoff = Date.now() - maxAgeMs;
-	const entries = await fs.readdir(configDir, { withFileTypes: true });
-	await Promise.all(entries.filter((entry) => entry.isDirectory() && entry.name.startsWith(STANDALONE_RUNTIME_PREFIX)).map(async (entry) => {
-		const entryPath = path.join(configDir, entry.name);
-		if ((await fs.stat(entryPath)).mtimeMs >= cutoff) return;
-		await fs.rm(entryPath, {
-			force: true,
-			recursive: true
-		});
-	}));
-};
+const DEV_PACKAGE_NAME = "blodemd-dev";
 const probePortAvailability = async (port) => {
 	const server = createServer$1();
 	const listening = (async () => {
@@ -2001,122 +2025,33 @@ const shutdownChildProcess = async (child, timeoutMs = DEV_SHUTDOWN_TIMEOUT_MS)
 		clearTimeout(timer);
 	});
 };
-/**
-* Derive the CLI npm package root from the running script path.
-* The CLI entry point is at `<pkg-root>/dist/cli.mjs`.
-*/
-const resolveCliPackageRoot = (cliFilePath) => path.dirname(path.dirname(cliFilePath));
-const copyStandaloneTree = async (sourceDir, targetDir) => {
-	await fs.cp(sourceDir, targetDir, {
-		filter: (source) => {
-			const relative = path.relative(sourceDir, source);
-			if (!relative) return true;
-			const topSegment = relative.split(path.sep)[0] ?? "";
-			return !RUNTIME_EXCLUDE_DIRS.has(topSegment);
-		},
-		recursive: true
-	});
-};
-const isStandaloneCliInstall = async (cliPackageRoot) => {
+const fileExists = async (filePath) => {
 	try {
-		return (await fs.realpath(cliPackageRoot)).split(path.sep).includes("node_modules");
+		await fs.access(filePath);
+		return true;
 	} catch {
-		return cliPackageRoot.split(path.sep).includes("node_modules");
+		return false;
 	}
 };
-const createStandaloneRuntimeRoot = async (configDir = CONFIG_DIR) => {
-	await fs.mkdir(configDir, { recursive: true });
-	await cleanupStandaloneRuntimeRoots(configDir);
-	return await fs.mkdtemp(path.join(configDir, STANDALONE_RUNTIME_PREFIX));
-};
 /**
-* Locate the `node_modules` directory that actually contains the CLI's
-* transitive dependencies. Package managers like npm/yarn-classic (and
-* `npx` caches) hoist shared deps above the package directory, so
-* `<cliPackageRoot>/node_modules` may not exist or may not contain `next`.
-* Resolve `next/package.json` and use the directory that owns it.
+* Derive the CLI npm package root from the running script path.
+* The CLI entry point is at `<pkg-root>/dist/cli.mjs`.
 */
-const resolveRuntimeNodeModules = async (cliPackageRoot) => {
-	const localNodeModules = path.join(cliPackageRoot, "node_modules");
-	if (await fileExists(path.join(localNodeModules, "next", "package.json"))) return localNodeModules;
-	const nextPkgPath = createRequire(path.join(cliPackageRoot, "package.json")).resolve("next/package.json");
-	return path.dirname(path.dirname(nextPkgPath));
-};
-const materializeStandaloneRuntime = async (cliPackageRoot) => {
-	const runtimeRoot = await createStandaloneRuntimeRoot();
-	try {
-		for (const dir of [
-			"dev-server",
-			"docs",
-			"packages"
-		]) await copyStandaloneTree(path.join(cliPackageRoot, dir), path.join(runtimeRoot, dir));
-		const runtimeNodeModules = await resolveRuntimeNodeModules(cliPackageRoot);
-		await fs.symlink(runtimeNodeModules, path.join(runtimeRoot, "node_modules"), process.platform === "win32" ? "junction" : "dir");
-		const linkTarget = path.join(runtimeRoot, "packages", "@repo");
-		for (const consumer of [
-			"dev-server",
-			"docs",
-			"packages"
-		]) {
-			await fs.mkdir(path.join(runtimeRoot, consumer, "node_modules"), { recursive: true });
-			await fs.symlink(linkTarget, path.join(runtimeRoot, consumer, "node_modules", "@repo"), process.platform === "win32" ? "junction" : "dir");
-		}
-		await fs.writeFile(path.join(runtimeRoot, "dev-server", "package.json"), `${JSON.stringify({
-			dependencies: {
-				next: "16.2.1",
-				react: "^19.2.0",
-				"react-dom": "^19.2.0"
-			},
-			devDependencies: {
-				"@types/node": "^24.12.2",
-				"@types/react": "19.2.14",
-				"@types/react-dom": "19.2.3",
-				typescript: "6.0.2"
-			},
-			name: "blodemd-dev-server",
-			private: true,
-			type: "module"
-		}, null, 2)}\n`);
-		return {
-			devServerDir: path.join(runtimeRoot, "dev-server"),
-			runtimeRoot
-		};
-	} catch (error) {
-		await fs.rm(runtimeRoot, {
-			force: true,
-			recursive: true
-		});
-		throw error;
-	}
-};
+const resolveCliPackageRoot = (cliFilePath) => path.dirname(path.dirname(cliFilePath));
 /**
-* Check if a shipped dev-server exists alongside an installed CLI package.
-* We only use standalone mode when the package root lives under `node_modules`.
+* Read the CLI's own version so the delegated `blodemd-dev` invocation is
+* pinned to the exact matching release (they version together via changesets).
 */
-const findStandaloneDevServer = async (cliPackageRoot) => {
-	const devServerDir = path.join(cliPackageRoot, "dev-server");
-	if (!await fileExists(path.join(devServerDir, "next.config.js"))) return null;
-	if (!await isStandaloneCliInstall(cliPackageRoot)) return null;
-	try {
-		createRequire(path.join(cliPackageRoot, "package.json")).resolve("next/package.json");
-	} catch {
-		return null;
-	}
-	const runtime = await materializeStandaloneRuntime(cliPackageRoot);
-	return {
-		devServerDir: runtime.devServerDir,
-		mode: "standalone",
-		nextPackageRoot: cliPackageRoot,
-		runtimeRoot: runtime.runtimeRoot
-	};
+const readCliPackageVersion = async (cliFilePath) => {
+	const packageJsonPath = path.join(resolveCliPackageRoot(cliFilePath), "package.json");
+	const raw = await fs.readFile(packageJsonPath, "utf8");
+	return JSON.parse(raw).version ?? "0.0.0";
 };
 /**
-* Resolve the `next` CLI binary from the blodemd package's own dependencies.
+* Walk up from the running CLI looking for the blodemd monorepo checkout.
+* Returns the repo root when found (development mode), otherwise `null`
+* (installed mode, which delegates to `blodemd-dev`).
 */
-const resolveNextBin = (cliPackageRoot) => {
-	const nextPkgPath = createRequire(path.join(cliPackageRoot, "package.json")).resolve("next/package.json");
-	return path.join(path.dirname(nextPkgPath), "dist", "bin", "next");
-};
 const findMonorepoRoot = async (start) => {
 	let current = start;
 	while (true) {
@@ -2124,35 +2059,50 @@ const findMonorepoRoot = async (start) => {
 		if (await fileExists(packageJsonPath)) {
 			const raw = await fs.readFile(packageJsonPath, "utf8");
 			const workspaces = JSON.parse(raw).workspaces ?? [];
-			if (workspaces.includes("apps/*") && workspaces.includes("packages/*")) return current;
+			const hasWorkspaces = workspaces.includes("apps/*") && workspaces.includes("packages/*");
+			const hasDevServer = await fileExists(path.join(current, "apps", "dev-server", "next.config.js"));
+			if (hasWorkspaces && hasDevServer) return current;
 		}
 		const parent = path.dirname(current);
 		if (parent === current) break;
 		current = parent;
 	}
-	throw new CliError("Could not locate the blodemd dev server.", EXIT_CODES.ERROR, "Make sure blodemd is installed correctly (npm i blodemd).");
+	return null;
 };
 const resolveDevServer = async (cliFilePath) => {
-	const standalone = await findStandaloneDevServer(resolveCliPackageRoot(cliFilePath));
-	if (standalone) return standalone;
-	return {
+	const repoRoot = await findMonorepoRoot(path.dirname(cliFilePath));
+	if (repoRoot) return {
 		mode: "monorepo",
-		repoRoot: await findMonorepoRoot(path.dirname(cliFilePath))
+		repoRoot
+	};
+	return {
+		devPackageVersion: await readCliPackageVersion(cliFilePath),
+		mode: "delegated"
 	};
 };
 const buildDevServerLaunch = (server, { root, port }) => {
-	if (server.mode === "standalone") return {
-		args: [resolveNextBin(server.nextPackageRoot), ...TURBOPACK_ARGS],
-		command: process.execPath,
-		cwd: server.devServerDir,
-		env: {
-			...process.env,
-			BLODEMD_PACKAGES_DIR: path.join(server.runtimeRoot, "packages"),
-			BLODEMD_TURBOPACK_ROOT: resolveCommonAncestor([server.nextPackageRoot, server.runtimeRoot]),
-			DOCS_ROOT: root,
-			PORT: String(port)
-		}
-	};
+	if (server.mode === "delegated") {
+		const npxCommand = process.platform === "win32" ? "npx.cmd" : "npx";
+		return {
+			args: [
+				"-y",
+				`${DEV_PACKAGE_NAME}@${server.devPackageVersion}`,
+				"dev",
+				"--port",
+				String(port),
+				"--dir",
+				root,
+				"--no-open"
+			],
+			command: npxCommand,
+			cwd: process.cwd(),
+			env: {
+				...process.env,
+				DOCS_ROOT: root,
+				PORT: String(port)
+			}
+		};
+	}
 	return {
 		args: [
 			"run",
@@ -2198,7 +2148,6 @@ const defaultDevCommandDependencies = {
 	getLog: log,
 	getOpen: open,
 	parsePortValue: parsePort,
-	removeDirectory: fs.rm,
 	resolveDevPortValue: resolveDevPort,
 	resolveDocsRootValue: resolveDocsRoot,
 	resolveServer: resolveDevServer,
@@ -2233,10 +2182,6 @@ const devCommand = async ({ dir, openBrowser, port: portValue }, dependencies =
 				watcher = null;
 			}
 			await dependencies.shutdownChild(child);
-			if (server.mode === "standalone") await dependencies.removeDirectory(server.runtimeRoot, {
-				force: true,
-				recursive: true
-			});
 		};
 		process.once("SIGINT", closeAll);
 		process.once("SIGTERM", closeAll);
@@ -2513,6 +2458,31 @@ const registerNewCommand = (program) => {
 	});
 };
 //#endregion
+//#region src/commands/projects.ts
+const registerProjectsCommand = (program) => {
+	program.command("projects").description("List your projects").option("--api-url <url>", "API URL (env: BLODEMD_API_URL)").option("--json", "output machine-readable JSON (implies non-interactive)").action(async (options) => {
+		const reporter = createReporter({ json: options.json });
+		if (reporter.interactive) intro(chalk.bold("blodemd projects"));
+		try {
+			const resolved = await resolveAuthToken();
+			if (!resolved?.token) throw new CliError("Run \"blodemd login\" to list your projects. API keys cannot list projects.", EXIT_CODES.AUTH_REQUIRED, "Run \"blodemd login\" to authenticate.");
+			const apiUrl = options.apiUrl ?? process.env["BLODEMD_API_URL"] ?? "https://api.blode.md";
+			const projects = await requestJson(new URL("/projects", apiUrl).toString(), { headers: { Authorization: `Bearer ${resolved.token}` } }, "Failed to list projects");
+			reporter.json(projects);
+			if (projects.length === 0) {
+				reporter.info("No projects yet.");
+				return;
+			}
+			for (const project of projects) {
+				const label = project.name ? `${chalk.cyan(project.slug)} — ${project.name}` : chalk.cyan(project.slug);
+				reporter.info(label);
+			}
+		} catch (error) {
+			reportCommandError("Projects failed", error, { json: options.json });
+		}
+	});
+};
+//#endregion
 //#region src/upload.ts
 const TEXT_CONTENT_TYPES = {
 	".css": "text/css; charset=utf-8",
@@ -2560,10 +2530,10 @@ const resolveAuthHeaders = async (apiKeyOption) => {
 	const apiKey = (apiKeyOption ?? process.env["BLODEMD_API_KEY"])?.trim();
 	if (apiKey) return {
 		canAutoCreate: false,
-		headers: { "x-admin-token": apiKey }
+		headers: { Authorization: `Bearer ${apiKey}` }
 	};
 	const resolved = await resolveAuthToken();
-	if (!resolved?.token) throw new Error("Not logged in. Run \"blodemd login\" to authenticate, pass --api-key, or set BLODEMD_API_KEY.");
+	if (!resolved?.token) throw new Error("Not logged in. Run \"blodemd login\" to authenticate, pass --api-key, or set BLODEMD_API_KEY (see https://blode.md/docs/deployment/ci).");
 	return {
 		canAutoCreate: true,
 		headers: { Authorization: `Bearer ${resolved.token}` }
@@ -2604,8 +2574,9 @@ const resolvePushConfig = async (config, options) => {
 		usedLegacyNameFallback
 	};
 };
-const autoCreateProject = async (project, projectDisplayName, apiUrl, headers, canAutoCreate) => {
+const autoCreateProject = async (project, projectDisplayName, apiUrl, headers, canAutoCreate, reporter) => {
 	if (!canAutoCreate) throw new Error(`Project "${project}" not found. Create it at blode.md or login with "blodemd login" to auto-create.`);
+	if (!reporter.interactive) throw new Error(`Project "${project}" not found. Create it in the dashboard or run \`blodemd push\` in an interactive terminal to auto-create it.`);
 	const shouldCreate = await confirm({ message: `Project "${project}" doesn't exist. Create it?` });
 	if (isCancel(shouldCreate) || !shouldCreate) return false;
 	const createResult = await requestJson(new URL("/projects", apiUrl).toString(), {
@@ -2616,12 +2587,18 @@ const autoCreateProject = async (project, projectDisplayName, apiUrl, headers, c
 		headers,
 		method: "POST"
 	}, "Failed to create project");
-	log.success(`Project ${chalk.cyan(createResult.slug)} created`);
+	reporter.success(`Project ${chalk.cyan(createResult.slug)} created`);
+	const keyResult = await requestJson(new URL(`/projects/${createResult.id}/keys`, apiUrl).toString(), {
+		body: JSON.stringify({ name: "CI deploy key" }),
+		headers,
+		method: "POST"
+	}, "Failed to create deploy key");
+	reporter.info(`Deploy key created (save this — shown once, use as ${BLODE_API_KEY_ENV} in CI): ${chalk.cyan(keyResult.key)}`);
 	return true;
 };
 const MAX_BATCH_BYTES = 4 * 1024 * 1024;
-const uploadFiles = async (files, root, apiPath, deploymentId, headers, s) => {
-	s.start(`Uploading ${files.length} files`);
+const uploadFiles = async (files, root, apiPath, deploymentId, headers, reporter) => {
+	reporter.step(`Uploading ${files.length} files`);
 	let uploaded = 0;
 	for await (const batch of createUploadBatches({
 		files,
@@ -2634,26 +2611,26 @@ const uploadFiles = async (files, root, apiPath, deploymentId, headers, s) => {
 			method: "POST"
 		}, "Failed to upload files");
 		uploaded += batch.length;
-		s.message(`Uploading files (${uploaded}/${files.length})`);
+		reporter.step(`Uploading files (${uploaded}/${files.length})`);
 	}
-	s.stop(`Uploaded ${chalk.cyan(String(files.length))} files`);
+	reporter.success(`Uploaded ${chalk.cyan(String(files.length))} files`);
 };
 const registerPushCommand = (program) => {
-	program.command("push").description("Deploy docs").argument("[dir]", "docs directory").option("--project <slug>", "project slug (env: BLODEMD_PROJECT)").option("--api-key <token>", "API key (env: BLODEMD_API_KEY)").option("--api-url <url>", "API URL (env: BLODEMD_API_URL)").option("--branch <name>", "git branch (env: BLODEMD_BRANCH)").option("--message <msg>", "deploy message (env: BLODEMD_COMMIT_MESSAGE)").action(async (dir, options) => {
-		intro(chalk.bold("blodemd push"));
-		const s = spinner();
+	program.command("push").description("Deploy docs").argument("[dir]", "docs directory").option("--project <slug>", "project slug (env: BLODEMD_PROJECT)").option("--api-key <token>", "API key (env: BLODEMD_API_KEY)").option("--api-url <url>", "API URL (env: BLODEMD_API_URL)").option("--branch <name>", "git branch (env: BLODEMD_BRANCH)").option("--message <msg>", "deploy message (env: BLODEMD_COMMIT_MESSAGE)").option("--json", "output machine-readable JSON (implies non-interactive)").action(async (dir, options) => {
+		const reporter = createReporter({ json: options.json });
+		if (reporter.interactive) intro(chalk.bold("blodemd push"));
 		try {
 			const root = await resolveDocsRoot(dir);
-			s.start("Validating configuration");
+			reporter.step("Validating configuration");
 			const { config, warnings } = await loadValidatedSiteConfig(root);
-			s.stop("Configuration valid");
-			for (const warning of warnings) log.warn(warning);
+			reporter.success("Configuration valid");
+			for (const warning of warnings) reporter.warn(warning);
 			const { project, projectDisplayName, apiUrl, authHeaders, canAutoCreate, branch, commitMessage, usedLegacyNameFallback } = await resolvePushConfig(config, options);
-			if (usedLegacyNameFallback) log.warn(LEGACY_PROJECT_NAME_FALLBACK_WARNING);
-			s.start("Collecting files");
+			if (usedLegacyNameFallback) reporter.warn(LEGACY_PROJECT_NAME_FALLBACK_WARNING);
+			reporter.step("Collecting files");
 			const files = await collectFiles(root);
 			if (files.length === 0) throw new Error("No files found to deploy.");
-			s.stop(`Found ${chalk.cyan(String(files.length))} files`);
+			reporter.success(`Found ${chalk.cyan(String(files.length))} files`);
 			const headers = {
 				...authHeaders,
 				"Content-Type": "application/json"
@@ -2663,7 +2640,7 @@ const registerPushCommand = (program) => {
 				branch,
 				commitMessage
 			});
-			s.start("Creating deployment");
+			reporter.step("Creating deployment");
 			let deployment;
 			try {
 				deployment = await requestJson(apiPath(""), {
@@ -2673,34 +2650,39 @@ const registerPushCommand = (program) => {
 				}, "Failed to create deployment");
 			} catch (error) {
 				if (!(error instanceof Error ? error.message : "").includes("404")) throw error;
-				s.stop("Project not found");
-				if (!await autoCreateProject(project, projectDisplayName, apiUrl, headers, canAutoCreate)) {
-					log.info("Cancelled");
+				reporter.stop("Project not found");
+				if (!await autoCreateProject(project, projectDisplayName, apiUrl, headers, canAutoCreate, reporter)) {
+					reporter.info("Cancelled");
 					return;
 				}
-				s.start("Creating deployment");
+				reporter.step("Creating deployment");
 				deployment = await requestJson(apiPath(""), {
 					body: createDeploymentBody,
 					headers,
 					method: "POST"
 				}, "Failed to create deployment");
 			}
-			s.stop(`Deployment ${chalk.cyan(deployment.id)} created`);
-			await uploadFiles(files, root, apiPath, deployment.id, headers, s);
-			s.start("Finalizing deployment");
+			reporter.success(`Deployment ${chalk.cyan(deployment.id)} created`);
+			await uploadFiles(files, root, apiPath, deployment.id, headers, reporter);
+			reporter.step("Finalizing deployment");
 			const finalized = await requestJson(apiPath(`/${deployment.id}/finalize`), {
 				body: JSON.stringify({ promote: true }),
 				headers,
 				method: "POST"
 			}, "Failed to finalize deployment");
-			s.stop("Deployment finalized");
-			log.success(`Published ${chalk.cyan(finalized.id)}`);
-			if (finalized.manifestUrl) log.info(`Manifest: ${finalized.manifestUrl}`);
-			if (typeof finalized.fileCount === "number") log.info(`Files: ${finalized.fileCount}`);
-			log.info("Done");
+			reporter.success("Deployment finalized");
+			reporter.success(`Published ${chalk.cyan(finalized.id)}`);
+			if (finalized.manifestUrl) reporter.info(`Manifest: ${finalized.manifestUrl}`);
+			if (typeof finalized.fileCount === "number") reporter.info(`Files: ${finalized.fileCount}`);
+			reporter.info("Done");
+			reporter.json({
+				deploymentId: finalized.id,
+				fileCount: finalized.fileCount ?? files.length,
+				manifestUrl: finalized.manifestUrl ?? null
+			});
 		} catch (error) {
-			s.stop("Failed");
-			reportCommandError("Push failed", error);
+			reporter.stop("Failed");
+			reportCommandError("Push failed", error, { json: options.json });
 		}
 	});
 };
@@ -2708,15 +2690,24 @@ const registerPushCommand = (program) => {
 //#region src/commands/validate.ts
 const CONFIG_FILE = "docs.json";
 const registerValidateCommand = (program) => {
-	program.command("validate").description("Validate docs.json").argument("[dir]", "docs directory").action(async (dir) => {
-		intro(chalk.bold("blodemd validate"));
+	program.command("validate").description("Validate docs.json").argument("[dir]", "docs directory").option("--json", "output machine-readable JSON (implies non-interactive)").action(async (dir, options) => {
+		const reporter = createReporter({ json: options.json });
+		if (reporter.interactive) intro(chalk.bold("blodemd validate"));
 		try {
 			const { warnings } = await loadValidatedSiteConfig(await resolveDocsRoot(dir));
-			for (const warning of warnings) log.warn(warning);
-			log.success(`${chalk.cyan(CONFIG_FILE)} is valid.`);
-			log.info("Done");
+			for (const warning of warnings) reporter.warn(warning);
+			reporter.success(`${chalk.cyan(CONFIG_FILE)} is valid.`);
+			reporter.info("Done");
+			reporter.json({
+				valid: true,
+				warnings
+			});
 		} catch (error) {
-			reportCommandError("Validation failed", error);
+			if (options.json && error instanceof CliError && error.exitCode === EXIT_CODES.VALIDATION) reporter.json({
+				errors: error.message.split("\n"),
+				valid: false
+			});
+			reportCommandError("Validation failed", error, { json: options.json });
 		}
 	});
 };
@@ -2770,9 +2761,18 @@ registerAuthCommands(program);
 registerNewCommand(program);
 registerValidateCommand(program);
 registerPushCommand(program);
+registerProjectsCommand(program);
 registerDevCommand(program);
 registerAnalyticsCommand(program);
-program.parse();
+program.addHelpText("after", "\nExample:\n  $ blodemd push ./docs --project my-docs\n");
+try {
+	await program.parseAsync();
+} catch (error) {
+	const cliError = toCliError(error);
+	console.error(cliError.message);
+	if (cliError.hint) console.error(cliError.hint);
+	process.exitCode = cliError.exitCode;
+}
 //#endregion
 export {};