@prisma/cli 3.0.0-alpha.9 → 3.0.0-beta.1

package/README.md

@@ -1,27 +1,145 @@
-# Prisma CLI Preview
+<p align="center">
+  <img src="https://i.imgur.com/h6UIYTu.png" alt="Prisma" width="360" />
+</p>
 
-Preview npm package for the unified Prisma CLI.
+# Prisma CLI
 
-Install:
+[![npm version](https://img.shields.io/npm/v/@prisma/cli?label=npm)](https://www.npmjs.com/package/@prisma/cli)
+[![license](https://img.shields.io/npm/l/@prisma/cli)](https://github.com/prisma/prisma-cli/blob/main/LICENSE)
+[![Node.js](https://img.shields.io/node/v/@prisma/cli)](https://www.npmjs.com/package/@prisma/cli)
+
+[Quickstart](#quickstart) • [Commands](#commands) • [Beta notes](#beta-notes) • [Documentation](#documentation) • [Support](#support)
+
+---
+
+`@prisma/cli` is the public beta of the new CLI for the
+Prisma Developer Platform.
+
+It is the terminal surface managing your platform projects, branches, apps,
+deployments, and environment variables.
+
+The command model is under active development to include tooling for your
+schema, database, migration, and broader platform workflows.
+
+Looking for Prisma ORM commands such as `prisma generate`, `prisma migrate`, or
+`prisma studio`? Use the [`prisma`](https://www.npmjs.com/package/prisma)
+package.
+
+---
+
+## Quickstart
+
+Install the beta package locally:
 
 ```bash
-pnpm add -D @prisma/cli@preview
+npm install --save-dev @prisma/cli
 ```
 
-Run:
+Run the binary exposed by this package:
 
 ```bash
-pnpm prisma-cli --help
+npx prisma-cli --help
+npx prisma-cli auth login
+npx prisma-cli app deploy
+```
+
+With `pnpm`:
+
+```bash
+pnpm add -D @prisma/cli
 pnpm prisma-cli auth login
-pnpm prisma-cli app deploy --env DATABASE_URL=postgresql://example
-pnpm prisma-cli app list-env
+pnpm prisma-cli app deploy
+```
+
+Useful next commands:
+
+```bash
+npx prisma-cli app logs
+npx prisma-cli app open
+npx prisma-cli project env add DATABASE_URL=postgresql://example --role preview
+npx prisma-cli project env list --role preview
 ```
 
-The package exposes `prisma-cli` so it can coexist with the existing `prisma`
-executable.
+The beta package exposes `prisma-cli` so it can coexist with the existing
+`prisma` executable.
+
+---
+
+## Commands
+
+| Group | What it does |
+| --- | --- |
+| `version` | Show the installed CLI build and host environment. |
+| `auth` | Log in, log out, and inspect the active Prisma account. |
+| `project` | List projects, show the resolved project, and manage project environment variables. |
+| `git` | Connect or disconnect a project from a GitHub repository. |
+| `branch` | Inspect the Prisma branch that maps to the current work context. |
+| `app` | Build, run, deploy, inspect, open, stream logs, promote, roll back, and remove apps. |
+
+Common examples:
+
+```bash
+npx prisma-cli version
+npx prisma-cli auth whoami
+npx prisma-cli project show
+npx prisma-cli branch show
+npx prisma-cli app deploy --branch feat-login --framework nextjs
+npx prisma-cli app promote <deployment-id>
+```
+
+### Built for humans, CI, and agents
+
+- Human-readable output by default.
+- `--json` for structured output.
+- `--no-interactive` and `--yes` for automation.
+- `PRISMA_SERVICE_TOKEN` for headless authenticated commands.
+- Stable command groups, flags, and error codes for scripts and agents.
+- Environment variable values are not printed back to the terminal.
+
+### Agent skills
+
+For agent-guided Next.js deploys, install the Prisma CLI skill cluster at the
+project level. Match the skill ref to the installed CLI version:
+
+```bash
+npx prisma-cli version
+pnpm dlx skills@latest add prisma/prisma-cli/skills#cli-v<cli-version> --all
+```
+
+The skills teach agents how to prepare a Next.js app, run `app deploy`, verify
+the result, and route CLI / Compute feedback to the right Prisma channel.
+
+---
+
+## Beta notes
+
+- Requires Node.js 20 or newer.
+- This is a beta package and may change quickly.
+- Official beta releases publish as `@prisma/cli`.
+- The package binary is `prisma-cli`, not `prisma`, during beta.
+- Local project context is cached in `.prisma/local.json`, which is gitignored and not a declarative repo config file.
+
+---
+
+## Documentation
+
+- [CLI docs index](https://github.com/prisma/prisma-cli/blob/main/docs/README.md)
+- [Resource model](https://github.com/prisma/prisma-cli/blob/main/docs/product/resource-model.md)
+- [Command principles](https://github.com/prisma/prisma-cli/blob/main/docs/product/command-principles.md)
+- [Command spec](https://github.com/prisma/prisma-cli/blob/main/docs/product/command-spec.md)
+- [Output conventions](https://github.com/prisma/prisma-cli/blob/main/docs/product/output-conventions.md)
+- [Error conventions](https://github.com/prisma/prisma-cli/blob/main/docs/product/error-conventions.md)
+
+## Support
+
+Issues and feedback are welcome while the CLI is in public beta. Please use
+[GitHub issues](https://github.com/prisma/prisma-cli/issues) for bug reports and
+feature requests.
+
+Security reports should follow Prisma's
+[security policy](https://github.com/prisma/prisma-cli/blob/main/SECURITY.md)
+and should not be filed as public issues.
 
-Notes:
+## License
 
-- This is a preview package and may change quickly.
-- `prisma.config.ts` stores linked project context for this CLI.
-- Environment variable values passed with `--env` are not printed back to the terminal.
+Apache-2.0

package/dist/adapters/token-storage.js

@@ -1,5 +1,8 @@
 import { getAuthFilePath } from "../lib/auth/client.js";
+import fs from "node:fs/promises";
+import path from "node:path";
 import { CredentialsStore } from "@prisma/credentials-store";
+import { randomUUID } from "node:crypto";
 //#region src/adapters/token-storage.ts
 function findLatestValidTokens(allCredentials) {
 	for (let i = allCredentials.length - 1; i >= 0; i -= 1) {
@@ -14,10 +17,19 @@ function findLatestValidTokens(allCredentials) {
 	}
 	return null;
 }
+function tokensEqual(a, b) {
+	return a?.workspaceId === b?.workspaceId && a?.accessToken === b?.accessToken && a?.refreshToken === b?.refreshToken;
+}
+function sleep(ms) {
+	return new Promise((resolve) => setTimeout(resolve, ms));
+}
 var FileTokenStorage = class {
 	credentialsStore;
+	lockFilePath;
 	constructor(env = process.env) {
-		this.credentialsStore = new CredentialsStore(getAuthFilePath(env));
+		const authFilePath = getAuthFilePath(env);
+		this.credentialsStore = new CredentialsStore(authFilePath);
+		this.lockFilePath = `${authFilePath}.lock`;
 	}
 	async getTokens() {
 		try {
@@ -38,6 +50,50 @@ var FileTokenStorage = class {
 		if (!tokens) return;
 		await this.credentialsStore.deleteCredentials(tokens.workspaceId);
 	}
+	async clearTokensIfCurrent(tokens) {
+		if (!tokensEqual(await this.getTokens(), tokens)) return;
+		await this.clearTokens();
+	}
+	async withRefreshLock(fn) {
+		const lockId = await this.acquireRefreshLock();
+		try {
+			return await fn();
+		} finally {
+			await this.releaseRefreshLock(lockId);
+		}
+	}
+	async acquireRefreshLock() {
+		const lockId = randomUUID();
+		await fs.mkdir(path.dirname(this.lockFilePath), { recursive: true });
+		while (true) try {
+			const handle = await fs.open(this.lockFilePath, "wx");
+			try {
+				await handle.writeFile(lockId, "utf8");
+			} finally {
+				await handle.close();
+			}
+			return lockId;
+		} catch (error) {
+			if (error.code !== "EEXIST") throw error;
+			const staleLockId = await this.getStaleRefreshLockId();
+			if (staleLockId) {
+				await this.releaseRefreshLock(staleLockId);
+				continue;
+			}
+			await sleep(100);
+		}
+	}
+	async getStaleRefreshLockId() {
+		const lockId = await fs.readFile(this.lockFilePath, "utf8").catch(() => null);
+		if (lockId === null) return null;
+		const stats = await fs.stat(this.lockFilePath).catch(() => null);
+		if (!stats) return null;
+		return Date.now() - stats.mtimeMs > 3e4 ? lockId : null;
+	}
+	async releaseRefreshLock(lockId) {
+		if (await fs.readFile(this.lockFilePath, "utf8").catch(() => null) !== lockId) return;
+		await fs.unlink(this.lockFilePath).catch(() => {});
+	}
 };
 //#endregion
 export { FileTokenStorage };

package/dist/commands/app/index.js

@@ -2,8 +2,8 @@ import { attachCommandDescriptor } from "../../shell/command-meta.js";
 import { addCompactGlobalFlags, addGlobalFlags } from "../../shell/global-flags.js";
 import { configureRuntimeCommand } from "../../shell/runtime.js";
 import { PREVIEW_BUILD_TYPES } from "../../lib/app/preview-build.js";
-import { runAppBuild, runAppDeploy, runAppListDeploys, runAppListEnv, runAppLogs, runAppOpen, runAppPromote, runAppRemove, runAppRollback, runAppRun, runAppShow, runAppShowDeploy, runAppUpdateEnv } from "../../controllers/app.js";
-import { renderAppBuild, renderAppDeploy, renderAppListDeploys, renderAppListEnv, renderAppOpen, renderAppPromote, renderAppRemove, renderAppRollback, renderAppRun, renderAppShow, renderAppShowDeploy, renderAppUpdateEnv, serializeAppBuild, serializeAppDeploy, serializeAppListDeploys, serializeAppListEnv, serializeAppOpen, serializeAppPromote, serializeAppRemove, serializeAppRollback, serializeAppRun, serializeAppShow, serializeAppShowDeploy, serializeAppUpdateEnv } from "../../presenters/app.js";
+import { runAppBuild, runAppDeploy, runAppDomainAdd, runAppDomainRemove, runAppDomainRetry, runAppDomainShow, runAppDomainWait, runAppListDeploys, runAppLogs, runAppOpen, runAppPromote, runAppRemove, runAppRollback, runAppRun, runAppShow, runAppShowDeploy } from "../../controllers/app.js";
+import { renderAppBuild, renderAppDeploy, renderAppDomainAdd, renderAppDomainRemove, renderAppDomainRetry, renderAppDomainShow, renderAppListDeploys, renderAppOpen, renderAppPromote, renderAppRemove, renderAppRollback, renderAppRun, renderAppShow, renderAppShowDeploy, serializeAppBuild, serializeAppDeploy, serializeAppDomainAdd, serializeAppDomainRemove, serializeAppDomainRetry, serializeAppDomainShow, serializeAppListDeploys, serializeAppOpen, serializeAppPromote, serializeAppRemove, serializeAppRollback, serializeAppRun, serializeAppShow, serializeAppShowDeploy } from "../../presenters/app.js";
 import { runCommand, runStreamingCommand } from "../../shell/command-runner.js";
 import { Command, Option } from "commander";
 //#region src/commands/app/index.ts
@@ -13,10 +13,9 @@ function createAppCommand(runtime) {
 	app.addCommand(createBuildCommand(runtime));
 	app.addCommand(createRunCommand(runtime));
 	app.addCommand(createDeployCommand(runtime));
-	app.addCommand(createUpdateEnvCommand(runtime));
-	app.addCommand(createListEnvCommand(runtime));
 	app.addCommand(createShowCommand(runtime));
 	app.addCommand(createOpenCommand(runtime));
+	app.addCommand(createDomainCommand(runtime));
 	app.addCommand(createLogsCommand(runtime));
 	app.addCommand(createListDeploysCommand(runtime));
 	app.addCommand(createShowDeployCommand(runtime));
@@ -60,26 +59,27 @@ function createRunCommand(runtime) {
 }
 function createDeployCommand(runtime) {
 	const command = attachCommandDescriptor(configureRuntimeCommand(new Command("deploy"), runtime), "app.deploy");
-	command.addOption(new Option("--app <name>", "App name")).addOption(new Option("--project <id-or-name>", "Project id or name")).addOption(new Option("--branch <name>", "Branch name")).addOption(new Option("--framework <name>", "Framework to deploy").choices([
+	command.addOption(new Option("--app <name>", "App name")).addOption(new Option("--project <id-or-name>", "Project id or name")).addOption(new Option("--create-project <name>", "Create and link a new Project before deploying")).addOption(new Option("--branch <name>", "Branch name")).addOption(new Option("--framework <name>", "Framework to deploy").choices([
 		"nextjs",
 		"hono",
-		"tanstack-start"
-	])).addOption(new Option("--entry <path>", "Entrypoint path for Bun or auto deploys")).addOption(new Option("--build-type <type>", "Legacy deploy build type").choices([...PREVIEW_BUILD_TYPES]).default("auto").hideHelp()).addOption(new Option("--http-port <port>", "HTTP port override for the deployed app")).addOption(new Option("--env <name=value>", "Environment variable").argParser(collectRepeatableValues));
+		"tanstack-start",
+		"bun"
+	])).addOption(new Option("--entry <path>", "Entrypoint path for Bun deploys")).addOption(new Option("--http-port <port>", "HTTP port override for the deployed app")).addOption(new Option("--env <name=value>", "Environment variable").argParser(collectRepeatableValues));
 	addGlobalFlags(command);
 	command.action(async (options) => {
 		const appName = options.app;
 		const entry = options.entry;
-		const buildType = options.buildType;
 		const branchName = options.branch;
 		const framework = options.framework;
 		const httpPort = options.httpPort;
 		const envAssignments = options.env;
 		const projectRef = options.project;
+		const createProjectName = options.createProject;
 		await runCommand(runtime, "app.deploy", options, (context) => runAppDeploy(context, appName, {
 			projectRef,
+			createProjectName,
 			branchName,
 			entrypoint: entry,
-			buildType,
 			framework,
 			httpPort,
 			envAssignments
@@ -90,63 +90,147 @@ function createDeployCommand(runtime) {
 	});
 	return command;
 }
-function createUpdateEnvCommand(runtime) {
-	const command = attachCommandDescriptor(configureRuntimeCommand(new Command("update-env"), runtime), "app.update-env");
-	command.addOption(new Option("--app <name>", "App name")).addOption(new Option("--project <id-or-name>", "Project id or name")).addOption(new Option("--env <name=value>", "Environment variable").argParser(collectRepeatableValues));
+function createShowCommand(runtime) {
+	const command = attachCommandDescriptor(configureRuntimeCommand(new Command("show"), runtime), "app.show");
+	command.addOption(new Option("--app <name>", "App name")).addOption(new Option("--project <id-or-name>", "Project id or name"));
 	addGlobalFlags(command);
 	command.action(async (options) => {
 		const appName = options.app;
-		const envAssignments = options.env;
 		const projectRef = options.project;
-		await runCommand(runtime, "app.update-env", options, (context) => runAppUpdateEnv(context, appName, envAssignments, projectRef), {
-			renderHuman: (context, descriptor, result) => renderAppUpdateEnv(context, descriptor, result),
-			renderJson: (result) => serializeAppUpdateEnv(result)
+		await runCommand(runtime, "app.show", options, (context) => runAppShow(context, appName, projectRef), {
+			renderHuman: (context, descriptor, result) => renderAppShow(context, descriptor, result),
+			renderJson: (result) => serializeAppShow(result)
 		});
 	});
 	return command;
 }
-function createListEnvCommand(runtime) {
-	const command = attachCommandDescriptor(configureRuntimeCommand(new Command("list-env"), runtime), "app.list-env");
+function createOpenCommand(runtime) {
+	const command = attachCommandDescriptor(configureRuntimeCommand(new Command("open"), runtime), "app.open");
 	command.addOption(new Option("--app <name>", "App name")).addOption(new Option("--project <id-or-name>", "Project id or name"));
 	addGlobalFlags(command);
 	command.action(async (options) => {
 		const appName = options.app;
 		const projectRef = options.project;
-		await runCommand(runtime, "app.list-env", options, (context) => runAppListEnv(context, appName, projectRef), {
-			renderHuman: (context, descriptor, result) => renderAppListEnv(context, descriptor, result),
-			renderJson: (result) => serializeAppListEnv(result)
+		await runCommand(runtime, "app.open", options, (context) => runAppOpen(context, appName, projectRef), {
+			renderHuman: (context, descriptor, result) => renderAppOpen(context, descriptor, result),
+			renderJson: (result) => serializeAppOpen(result)
 		});
 	});
 	return command;
 }
-function createShowCommand(runtime) {
-	const command = attachCommandDescriptor(configureRuntimeCommand(new Command("show"), runtime), "app.show");
-	command.addOption(new Option("--app <name>", "App name")).addOption(new Option("--project <id-or-name>", "Project id or name"));
+function createDomainCommand(runtime) {
+	const command = attachCommandDescriptor(configureRuntimeCommand(new Command("domain"), runtime), "app.domain");
+	addCompactGlobalFlags(command);
+	command.addCommand(createDomainAddCommand(runtime));
+	command.addCommand(createDomainShowCommand(runtime));
+	command.addCommand(createDomainRemoveCommand(runtime));
+	command.addCommand(createDomainRetryCommand(runtime));
+	command.addCommand(createDomainWaitCommand(runtime));
+	return command;
+}
+function addDomainTargetOptions(command) {
+	return command.addOption(new Option("--app <name>", "App name")).addOption(new Option("--project <id-or-name>", "Project id or name")).addOption(new Option("--branch <name>", "Branch name"));
+}
+function createDomainAddCommand(runtime) {
+	const command = attachCommandDescriptor(configureRuntimeCommand(new Command("add"), runtime), "app.domain.add");
+	command.argument("<hostname>", "Custom domain hostname");
+	addDomainTargetOptions(command);
 	addGlobalFlags(command);
-	command.action(async (options) => {
+	command.action(async (hostname, options) => {
 		const appName = options.app;
 		const projectRef = options.project;
-		await runCommand(runtime, "app.show", options, (context) => runAppShow(context, appName, projectRef), {
-			renderHuman: (context, descriptor, result) => renderAppShow(context, descriptor, result),
-			renderJson: (result) => serializeAppShow(result)
+		const branchName = options.branch;
+		await runCommand(runtime, "app.domain.add", options, (context) => runAppDomainAdd(context, hostname, {
+			appName,
+			projectRef,
+			branchName
+		}), {
+			renderHuman: (context, descriptor, result) => renderAppDomainAdd(context, descriptor, result),
+			renderJson: (result) => serializeAppDomainAdd(result)
 		});
 	});
 	return command;
 }
-function createOpenCommand(runtime) {
-	const command = attachCommandDescriptor(configureRuntimeCommand(new Command("open"), runtime), "app.open");
-	command.addOption(new Option("--app <name>", "App name")).addOption(new Option("--project <id-or-name>", "Project id or name"));
+function createDomainShowCommand(runtime) {
+	const command = attachCommandDescriptor(configureRuntimeCommand(new Command("show"), runtime), "app.domain.show");
+	command.argument("<hostname>", "Custom domain hostname");
+	addDomainTargetOptions(command);
 	addGlobalFlags(command);
-	command.action(async (options) => {
+	command.action(async (hostname, options) => {
 		const appName = options.app;
 		const projectRef = options.project;
-		await runCommand(runtime, "app.open", options, (context) => runAppOpen(context, appName, projectRef), {
-			renderHuman: (context, descriptor, result) => renderAppOpen(context, descriptor, result),
-			renderJson: (result) => serializeAppOpen(result)
+		const branchName = options.branch;
+		await runCommand(runtime, "app.domain.show", options, (context) => runAppDomainShow(context, hostname, {
+			appName,
+			projectRef,
+			branchName
+		}), {
+			renderHuman: (context, descriptor, result) => renderAppDomainShow(context, descriptor, result),
+			renderJson: (result) => serializeAppDomainShow(result)
+		});
+	});
+	return command;
+}
+function createDomainRemoveCommand(runtime) {
+	const command = attachCommandDescriptor(configureRuntimeCommand(new Command("remove"), runtime), "app.domain.remove");
+	command.argument("<hostname>", "Custom domain hostname");
+	addDomainTargetOptions(command);
+	addGlobalFlags(command);
+	command.action(async (hostname, options) => {
+		const appName = options.app;
+		const projectRef = options.project;
+		const branchName = options.branch;
+		await runCommand(runtime, "app.domain.remove", options, (context) => runAppDomainRemove(context, hostname, {
+			appName,
+			projectRef,
+			branchName
+		}), {
+			renderHuman: (context, descriptor, result) => renderAppDomainRemove(context, descriptor, result),
+			renderJson: (result) => serializeAppDomainRemove(result)
+		});
+	});
+	return command;
+}
+function createDomainRetryCommand(runtime) {
+	const command = attachCommandDescriptor(configureRuntimeCommand(new Command("retry"), runtime), "app.domain.retry");
+	command.argument("<hostname>", "Custom domain hostname");
+	addDomainTargetOptions(command);
+	addGlobalFlags(command);
+	command.action(async (hostname, options) => {
+		const appName = options.app;
+		const projectRef = options.project;
+		const branchName = options.branch;
+		await runCommand(runtime, "app.domain.retry", options, (context) => runAppDomainRetry(context, hostname, {
+			appName,
+			projectRef,
+			branchName
+		}), {
+			renderHuman: (context, descriptor, result) => renderAppDomainRetry(context, descriptor, result),
+			renderJson: (result) => serializeAppDomainRetry(result)
 		});
 	});
 	return command;
 }
+function createDomainWaitCommand(runtime) {
+	const command = attachCommandDescriptor(configureRuntimeCommand(new Command("wait"), runtime), "app.domain.wait");
+	command.argument("<hostname>", "Custom domain hostname");
+	addDomainTargetOptions(command);
+	command.addOption(new Option("--timeout <duration>", "Maximum time to wait").default("15m"));
+	addGlobalFlags(command);
+	command.action(async (hostname, options) => {
+		const appName = options.app;
+		const projectRef = options.project;
+		const branchName = options.branch;
+		const timeout = options.timeout;
+		await runStreamingCommand(runtime, "app.domain.wait", options, (context) => runAppDomainWait(context, hostname, {
+			appName,
+			projectRef,
+			branchName,
+			timeout
+		}));
+	});
+	return command;
+}
 function createLogsCommand(runtime) {
 	const command = attachCommandDescriptor(configureRuntimeCommand(new Command("logs"), runtime), "app.logs");
 	command.addOption(new Option("--app <name>", "App name")).addOption(new Option("--project <id-or-name>", "Project id or name")).addOption(new Option("--deployment <id>", "Deployment id"));

package/dist/commands/env.js

@@ -2,7 +2,7 @@ import { attachCommandDescriptor } from "../shell/command-meta.js";
 import { addGlobalFlags } from "../shell/global-flags.js";
 import { configureRuntimeCommand } from "../shell/runtime.js";
 import { runCommand } from "../shell/command-runner.js";
-import { runEnvAdd, runEnvList, runEnvRm, runEnvUpdate } from "../controllers/app-env.js";
+import { runEnvAdd, runEnvList, runEnvRemove, runEnvUpdate } from "../controllers/app-env.js";
 import { renderEnvAdd, renderEnvList, renderEnvRm, renderEnvUpdate, serializeEnvAdd, serializeEnvList, serializeEnvRm, serializeEnvUpdate } from "../presenters/app-env.js";
 import { Command, Option } from "commander";
 //#region src/commands/env.ts
@@ -12,18 +12,20 @@ function createEnvCommand(runtime) {
 	env.addCommand(createEnvAddCommand(runtime));
 	env.addCommand(createEnvUpdateCommand(runtime));
 	env.addCommand(createEnvListCommand(runtime));
-	env.addCommand(createEnvRmCommand(runtime));
+	env.addCommand(createEnvRemoveCommand(runtime));
 	return env;
 }
 function createEnvAddCommand(runtime) {
 	const command = attachCommandDescriptor(configureRuntimeCommand(new Command("add"), runtime), "project.env.add");
-	command.argument("<assignment>", "Variable assignment as KEY=VALUE or KEY from the current environment").addOption(new Option("--role <role>", "Project template scope (production or preview)").choices(["production", "preview"])).addOption(new Option("--project <id-or-name>", "Project id or name"));
+	command.argument("<assignment>", "Variable assignment as KEY=VALUE or KEY from the current environment").addOption(new Option("--role <role>", "Project template scope (production or preview)").choices(["production", "preview"])).addOption(new Option("--branch <git-name>", "Preview branch override scope")).addOption(new Option("--project <id-or-name>", "Project id or name"));
 	addGlobalFlags(command);
 	command.action(async (assignment, options) => {
 		const roleName = options.role;
+		const branchName = options.branch;
 		const projectRef = options.project;
 		await runCommand(runtime, "project.env.add", options, (context) => runEnvAdd(context, assignment, {
 			roleName,
+			branchName,
 			projectRef
 		}), {
 			renderHuman: (context, descriptor, result) => renderEnvAdd(context, descriptor, result),
@@ -34,13 +36,15 @@ function createEnvAddCommand(runtime) {
 }
 function createEnvUpdateCommand(runtime) {
 	const command = attachCommandDescriptor(configureRuntimeCommand(new Command("update"), runtime), "project.env.update");
-	command.argument("<assignment>", "Variable assignment as KEY=VALUE or KEY from the current environment").addOption(new Option("--role <role>", "Project template scope (production or preview)").choices(["production", "preview"])).addOption(new Option("--project <id-or-name>", "Project id or name"));
+	command.argument("<assignment>", "Variable assignment as KEY=VALUE or KEY from the current environment").addOption(new Option("--role <role>", "Project template scope (production or preview)").choices(["production", "preview"])).addOption(new Option("--branch <git-name>", "Preview branch override scope")).addOption(new Option("--project <id-or-name>", "Project id or name"));
 	addGlobalFlags(command);
 	command.action(async (assignment, options) => {
 		const roleName = options.role;
+		const branchName = options.branch;
 		const projectRef = options.project;
 		await runCommand(runtime, "project.env.update", options, (context) => runEnvUpdate(context, assignment, {
 			roleName,
+			branchName,
 			projectRef
 		}), {
 			renderHuman: (context, descriptor, result) => renderEnvUpdate(context, descriptor, result),
@@ -51,13 +55,15 @@ function createEnvUpdateCommand(runtime) {
 }
 function createEnvListCommand(runtime) {
 	const command = attachCommandDescriptor(configureRuntimeCommand(new Command("list"), runtime), "project.env.list");
-	command.addOption(new Option("--role <role>", "Project template scope").choices(["production", "preview"])).addOption(new Option("--project <id-or-name>", "Project id or name"));
+	command.addOption(new Option("--role <role>", "Project template scope").choices(["production", "preview"])).addOption(new Option("--branch <git-name>", "Preview branch resolved scope")).addOption(new Option("--project <id-or-name>", "Project id or name"));
 	addGlobalFlags(command);
 	command.action(async (options) => {
 		const roleName = options.role;
+		const branchName = options.branch;
 		const projectRef = options.project;
 		await runCommand(runtime, "project.env.list", options, (context) => runEnvList(context, {
 			roleName,
+			branchName,
 			projectRef
 		}), {
 			renderHuman: (context, descriptor, result) => renderEnvList(context, descriptor, result),
@@ -66,15 +72,17 @@ function createEnvListCommand(runtime) {
 	});
 	return command;
 }
-function createEnvRmCommand(runtime) {
-	const command = attachCommandDescriptor(configureRuntimeCommand(new Command("rm"), runtime), "project.env.rm");
-	command.argument("<key>", "Variable key to remove").addOption(new Option("--role <role>", "Project template scope (production or preview)").choices(["production", "preview"])).addOption(new Option("--project <id-or-name>", "Project id or name"));
+function createEnvRemoveCommand(runtime) {
+	const command = attachCommandDescriptor(configureRuntimeCommand(new Command("remove"), runtime), "project.env.remove");
+	command.alias("rm").argument("<key>", "Variable key to remove").addOption(new Option("--role <role>", "Project template scope (production or preview)").choices(["production", "preview"])).addOption(new Option("--branch <git-name>", "Preview branch override scope")).addOption(new Option("--project <id-or-name>", "Project id or name"));
 	addGlobalFlags(command);
 	command.action(async (key, options) => {
 		const roleName = options.role;
+		const branchName = options.branch;
 		const projectRef = options.project;
-		await runCommand(runtime, "project.env.rm", options, (context) => runEnvRm(context, key, {
+		await runCommand(runtime, "project.env.remove", options, (context) => runEnvRemove(context, key, {
 			roleName,
+			branchName,
 			projectRef
 		}), {
 			renderHuman: (context, descriptor, result) => renderEnvRm(context, descriptor, result),

package/dist/commands/project/index.js

@@ -1,9 +1,9 @@
 import { attachCommandDescriptor } from "../../shell/command-meta.js";
 import { addCompactGlobalFlags, addGlobalFlags } from "../../shell/global-flags.js";
 import { configureRuntimeCommand } from "../../shell/runtime.js";
-import { runProjectList, runProjectShow } from "../../controllers/project.js";
+import { runProjectCreate, runProjectLink, runProjectList, runProjectShow } from "../../controllers/project.js";
 import { runCommand } from "../../shell/command-runner.js";
-import { renderProjectList, renderProjectShow, serializeProjectList, serializeProjectShow } from "../../presenters/project.js";
+import { renderProjectList, renderProjectSetup, renderProjectShow, serializeProjectList, serializeProjectSetup, serializeProjectShow } from "../../presenters/project.js";
 import { createEnvCommand } from "../env.js";
 import { Command } from "commander";
 //#region src/commands/project/index.ts
@@ -12,9 +12,35 @@ function createProjectCommand(runtime) {
 	addCompactGlobalFlags(project);
 	project.addCommand(createProjectListCommand(runtime));
 	project.addCommand(createProjectShowCommand(runtime));
+	project.addCommand(createProjectCreateCommand(runtime));
+	project.addCommand(createProjectLinkCommand(runtime));
 	project.addCommand(createEnvCommand(runtime));
 	return project;
 }
+function createProjectCreateCommand(runtime) {
+	const command = attachCommandDescriptor(configureRuntimeCommand(new Command("create"), runtime), "project.create");
+	command.argument("<name>", "Project name");
+	addGlobalFlags(command);
+	command.action(async (name, options) => {
+		await runCommand(runtime, "project.create", options, (context) => runProjectCreate(context, String(name)), {
+			renderHuman: (context, descriptor, result) => renderProjectSetup(context, descriptor, result),
+			renderJson: (result) => serializeProjectSetup(result)
+		});
+	});
+	return command;
+}
+function createProjectLinkCommand(runtime) {
+	const command = attachCommandDescriptor(configureRuntimeCommand(new Command("link"), runtime), "project.link");
+	command.argument("[id-or-name]", "Project id or name");
+	addGlobalFlags(command);
+	command.action(async (projectRef, options) => {
+		await runCommand(runtime, "project.link", options, (context) => runProjectLink(context, typeof projectRef === "string" ? projectRef : void 0), {
+			renderHuman: (context, descriptor, result) => renderProjectSetup(context, descriptor, result),
+			renderJson: (result) => serializeProjectSetup(result)
+		});
+	});
+	return command;
+}
 function createProjectListCommand(runtime) {
 	const command = attachCommandDescriptor(configureRuntimeCommand(new Command("list"), runtime), "project.list");
 	addGlobalFlags(command);