@rebasepro/cli 0.25.1 → 0.26.0

package/dist/{context-DHiiiJ5C.js → context-GUxkZm-S.js}

@@ -1,4 +1,4 @@
-import { S as switchOn, b as parseCommandArgs, c as findProjectRoot } from "./project-g4K6kV1t.js";
+import { C as switchOn, c as findProjectRoot, x as parseCommandArgs } from "./project-CasK56vN.js";
 import { t as cliUserAgent } from "./version-Buyyo1ut.js";
 import chalk from "chalk";
 import arg from "arg";
@@ -166,6 +166,194 @@ function wantsRawError(argv = process.argv) {
 	return switchOn(argv, "--debug") || parseEnvBoolean(process.env.REBASE_DEBUG) === true;
 }
 //#endregion
+//#region src/commands/cloud/token-capabilities.ts
+/** Every capability, in the order they are offered. */
+var TOKEN_CAPABILITY_NAMES = [
+	"deploy",
+	"logs",
+	"env",
+	"database",
+	"backups"
+];
+/**
+* Scopes every token holds, whatever it was created for: resolving a project
+* by its slug, reading the deployment a command follows (a production one, or
+* a preview's), the organization a project belongs to, and the control plane's
+* public description of itself.
+*/
+var ALWAYS_SCOPES = [
+	"data:read:projects",
+	"data:read:deployments",
+	"data:read:preview-deployments",
+	"data:read:organizations",
+	"functions:invoke:platform-config"
+];
+/** Each capability: what it lets a token do, and the scopes that does on one project. */
+var TOKEN_CAPABILITIES = {
+	deploy: {
+		label: "Deploy the project and follow its builds",
+		scopes: (projectId) => [
+			`project:read:${projectId}`,
+			`project:deploy:${projectId}`,
+			"functions:invoke:deploy",
+			"functions:invoke:previews"
+		]
+	},
+	logs: {
+		label: "Read build and runtime logs, cron history, live metrics and usage",
+		scopes: (projectId) => [
+			`project:read:${projectId}`,
+			`project:logs:${projectId}`,
+			"functions:invoke:runtime-logs",
+			"functions:invoke:metrics",
+			"functions:invoke:runtime-token",
+			"functions:invoke:previews",
+			"functions:invoke:usage"
+		]
+	},
+	env: {
+		label: "Read and change environment variables, secrets included",
+		scopes: (projectId) => [
+			`project:env:${projectId}`,
+			"functions:invoke:env-vars",
+			"functions:invoke:previews"
+		]
+	},
+	database: {
+		label: "Connect to the database and read its password",
+		scopes: (projectId) => [
+			`project:read:${projectId}`,
+			`project:database:${projectId}`,
+			"functions:invoke:db-info",
+			"data:read:databases"
+		]
+	},
+	backups: {
+		label: "List, create and download backups (restoring needs a signed-in person)",
+		scopes: (projectId) => [
+			`project:read:${projectId}`,
+			`project:backups:${projectId}`,
+			"functions:invoke:backup"
+		]
+	}
+};
+/** Whether a word names a capability. */
+function isTokenCapability(value) {
+	return TOKEN_CAPABILITY_NAMES.includes(value);
+}
+/**
+* The scopes a token for `capabilities` on one project holds: {@link ALWAYS_SCOPES}
+* first, then each capability's, each scope once.
+*
+* Throws on a project id a scope cannot carry — empty, or with whitespace — and
+* on an unknown capability, both of which are a caller's mistake rather than
+* something to mint a token from.
+*/
+function scopesForCapabilities(projectId, capabilities) {
+	if (projectId.length === 0 || /\s/.test(projectId)) throw new Error(`"${projectId}" is not a project id a scope can be narrowed to.`);
+	const scopes = new Set(ALWAYS_SCOPES);
+	for (const capability of capabilities) {
+		if (!isTokenCapability(capability)) throw new Error(`"${String(capability)}" is not a token capability. Capabilities: ${TOKEN_CAPABILITY_NAMES.join(", ")}.`);
+		for (const scope of TOKEN_CAPABILITIES[capability].scopes(projectId)) scopes.add(scope);
+	}
+	return [...scopes];
+}
+/**
+* Read a token's scopes back as capabilities: the projects its project scopes
+* name, and, for each, the capabilities it holds every scope of.
+*
+* For showing a token — `rebase cloud tokens list`, `rebase cloud whoami` — so
+* a list of fifteen scope strings reads as "deploy, logs on <project>".
+*/
+function capabilitiesInScopes(scopes) {
+	const held = new Set(scopes);
+	const projectIds = [];
+	for (const scope of scopes) {
+		const match = /^project:[a-z][a-z0-9-]*:(.+)$/.exec(scope);
+		if (match && !projectIds.includes(match[1])) projectIds.push(match[1]);
+	}
+	return projectIds.map((projectId) => ({
+		projectId,
+		capabilities: TOKEN_CAPABILITY_NAMES.filter((capability) => TOKEN_CAPABILITIES[capability].scopes(projectId).every((scope) => held.has(scope)))
+	}));
+}
+/**
+* Whether a token's scopes reach one project: a project scope narrowed to it,
+* or an unnarrowed one, which reaches every project.
+*
+* What decides, in a directory `rebase cloud init --claim` linked, whether
+* `REBASE_TOKEN` or the token stored for that project acts on it: a
+* `REBASE_TOKEN` made for other projects would be refused on this one.
+*/
+function scopesReachProject(scopes, projectId) {
+	return scopes.some((scope) => {
+		const match = /^project:[a-z][a-z0-9-]*(?::(.+))?$/.exec(scope);
+		return match !== null && (match[1] === void 0 || match[1] === projectId);
+	});
+}
+/** Every organization capability, in the order they are offered. */
+var ORG_CAPABILITY_NAMES = [
+	"billing",
+	"audit",
+	"notifications"
+];
+/** Each organization capability: what it lets a token do, and the scopes that does on one organization. */
+var ORG_CAPABILITIES = {
+	billing: {
+		label: "Read the organization's billing: card on file, invoices and the next invoice (owners and admins)",
+		scopes: (organizationId) => [
+			`org:billing:${organizationId}`,
+			"functions:invoke:stripe-billing",
+			"data:read:billing-accounts"
+		]
+	},
+	audit: {
+		label: "Read the organization's activity log (owners and admins)",
+		scopes: (organizationId) => [`org:audit:${organizationId}`, "functions:invoke:audit"]
+	},
+	notifications: {
+		label: "Manage notifications: your own email choices, and its projects' webhooks",
+		scopes: (organizationId) => [`org:notifications:${organizationId}`, "functions:invoke:notifications"]
+	}
+};
+/** Whether a word names an organization capability. */
+function isOrgCapability(value) {
+	return ORG_CAPABILITY_NAMES.includes(value);
+}
+/**
+* The scopes `capabilities` hold on one organization, each once — added to a
+* token's project scopes, so not {@link ALWAYS_SCOPES}.
+*
+* Throws on an organization id a scope cannot carry, and on an unknown
+* capability.
+*/
+function scopesForOrgCapabilities(organizationId, capabilities) {
+	if (organizationId.length === 0 || /\s/.test(organizationId)) throw new Error(`"${organizationId}" is not an organization id a scope can be narrowed to.`);
+	const scopes = /* @__PURE__ */ new Set();
+	for (const capability of capabilities) {
+		if (!isOrgCapability(capability)) throw new Error(`"${String(capability)}" is not an organization capability. Capabilities: ${ORG_CAPABILITY_NAMES.join(", ")}.`);
+		for (const scope of ORG_CAPABILITIES[capability].scopes(organizationId)) scopes.add(scope);
+	}
+	return [...scopes];
+}
+/**
+* Read a token's `org:*` scopes back as organization capabilities: the
+* organizations they name, and, for each, the capabilities it holds every
+* scope of.
+*/
+function orgCapabilitiesInScopes(scopes) {
+	const held = new Set(scopes);
+	const organizationIds = [];
+	for (const scope of scopes) {
+		const match = /^org:[a-z][a-z0-9-]*:(.+)$/.exec(scope);
+		if (match && !organizationIds.includes(match[1])) organizationIds.push(match[1]);
+	}
+	return organizationIds.map((organizationId) => ({
+		organizationId,
+		capabilities: ORG_CAPABILITY_NAMES.filter((capability) => ORG_CAPABILITIES[capability].scopes(organizationId).every((scope) => held.has(scope)))
+	}));
+}
+//#endregion
 //#region src/commands/cloud/context.ts
 /**
 * Shared foundation for the `rebase cloud` command family.
@@ -226,13 +414,123 @@ function readCredentials() {
 		return { contexts: {} };
 	}
 }
+/**
+* Replace the credentials file with `data`: written beside it, then renamed
+* over it. Every command reads the whole file and writes it back, and several
+* may run at once (MCP runs cloud tools concurrently). Written in place, a
+* reader landing between the truncate and the write saw a half file, read it
+* as empty, and wrote back one without the login and the grants; a disk-full
+* error left it empty. A rename is atomic: a reader sees the old file or the
+* new one.
+*/
 function writeCredentials(data) {
 	const file = credentialsPath();
 	fs.mkdirSync(path.dirname(file), { recursive: true });
-	fs.writeFileSync(file, JSON.stringify(data, null, 2), { mode: 384 });
+	const temporary = `${file}.${process.pid}.${Date.now()}.tmp`;
 	try {
-		fs.chmodSync(file, 384);
-	} catch {}
+		fs.writeFileSync(temporary, JSON.stringify(data, null, 2), { mode: 384 });
+		try {
+			fs.chmodSync(temporary, 384);
+		} catch {}
+		fs.renameSync(temporary, file);
+	} catch (error) {
+		fs.rmSync(temporary, { force: true });
+		throw error;
+	}
+}
+/** Keep an unclaimed project's token and claim link for this host. */
+function saveEphemeralGrant(url, projectId, grant) {
+	const creds = readCredentials();
+	const entry = creds.contexts[url] || {};
+	entry.ephemeral = {
+		...entry.ephemeral ?? {},
+		[projectId]: grant
+	};
+	creds.contexts[url] = entry;
+	writeCredentials(creds);
+}
+/** Drop a grant — once its project is claimed, or its token is refused. */
+function forgetEphemeralGrant(url, projectId) {
+	const creds = readCredentials();
+	const entry = creds.contexts[url];
+	if (!entry?.ephemeral?.[projectId]) return;
+	delete entry.ephemeral[projectId];
+	writeCredentials(creds);
+}
+/** The grant for a project on a host, while it has not expired. */
+function ephemeralGrantFor(url, projectId, now = Date.now()) {
+	const grant = readCredentials().contexts[url]?.ephemeral?.[projectId];
+	if (!grant || !(Date.parse(grant.expiresAt) > now)) return void 0;
+	return grant;
+}
+/**
+* The grant as it is stored, expired or not: what a message about a refused
+* token can still show (the claim link) after the token itself stops counting.
+*/
+function storedEphemeralGrant(url, projectId) {
+	return readCredentials().contexts[url]?.ephemeral?.[projectId];
+}
+/**
+* The grant for the project this directory is linked to, when the command
+* targets the host it was provisioned on.
+*/
+function linkedEphemeralGrant(url) {
+	const link = readLink();
+	if (!link?.projectId || link.mode === "direct" || normalizeUrl(link.url) !== url) return void 0;
+	const grant = ephemeralGrantFor(url, link.projectId);
+	return grant ? {
+		projectId: link.projectId,
+		grant
+	} : void 0;
+}
+/**
+* The unexpired grant for the project a link names, on the host it names: what
+* `status`, `unlink` and `init` read the claim URL back from. Undefined for a
+* claimed project (its grant is gone), a direct link, or no link.
+*/
+function grantForLink(link) {
+	if (!link?.projectId || link.mode === "direct") return void 0;
+	return ephemeralGrantFor(normalizeUrl(link.url), link.projectId);
+}
+/**
+* The grant a link names as it is stored, expired or not, with the host it is
+* kept under: what `rebase cloud claim` reads, so it can say "expired" rather
+* than "never had one".
+*/
+function storedGrantForLink(link) {
+	if (!link?.projectId || link.mode === "direct") return void 0;
+	const url = normalizeUrl(link.url);
+	const grant = storedEphemeralGrant(url, link.projectId);
+	return grant ? {
+		url,
+		grant
+	} : void 0;
+}
+/** Whether a `.env` sets a variable to something: an empty `KEY=` or `KEY=""` does not. */
+function dotenvSets(file, key) {
+	if (!fs.existsSync(file)) return false;
+	const pattern = new RegExp(`^\\s*(export\\s+)?${key}\\s*=(.*)$`);
+	return fs.readFileSync(file, "utf-8").split("\n").some((l) => {
+		const value = pattern.exec(l)?.[2]?.trim();
+		return value !== void 0 && value !== "" && value !== "\"\"" && value !== "''";
+	});
+}
+/** The variable `init --claim` writes the app's key to, and the MCP server and the SDK read. */
+var APP_KEY_ENV = "REBASE_API_TOKEN";
+/** Whether this project's `.env` (at its root, else here) holds an app key. */
+function projectDotenvSetsAppKey() {
+	return dotenvSets(path.join(findProjectRoot() ?? process.cwd(), ".env"), APP_KEY_ENV);
+}
+/**
+* When the app key `init --claim` minted stops working, and what to do about
+* it. It is minted to expire with the claim window; a claim hands it over to
+* the person who claims (the control plane lifts its expiry), so an unclaimed
+* project's key stops at the window's end and a claimed one's does not. The
+* claimer replaces it — the agent holds a copy — with `rebase cloud app-key
+* rotate`. Every command that knows the date says so.
+*/
+function appKeyExpiryNote(expiresAt) {
+	return `${APP_KEY_ENV} in .env stops working at ${new Date(expiresAt).toLocaleString()} unless the project is claimed first: claiming hands the key to the person who claims it, and it stops expiring. They can replace it with \`rebase cloud app-key rotate\`.`;
 }
 /** Host that a bare `rebase cloud` command should target, if any. */
 function currentContextUrl() {
@@ -388,6 +686,16 @@ function envToken() {
 }
 /** The token each token-authenticated client was built with — see {@link freshAccessToken}. */
 var STATIC_TOKENS = /* @__PURE__ */ new WeakMap();
+/** The project each client built from an `init --claim` grant acts for — see {@link grantProjectOf}. */
+var GRANT_CLIENTS = /* @__PURE__ */ new WeakMap();
+/**
+* The project whose `rebase cloud init --claim` token a client holds, or
+* undefined for a session or `REBASE_TOKEN`: what `whoami` reports, since
+* {@link requireClient} may pick the grant over `REBASE_TOKEN`.
+*/
+function grantProjectOf(client) {
+	return GRANT_CLIENTS.get(client);
+}
 /**
 * A client that sends `token` as its bearer and nothing else.
 *
@@ -397,11 +705,12 @@ var STATIC_TOKENS = /* @__PURE__ */ new WeakMap();
 * rather than by the SDK's session refresh, because there is no session to
 * refresh and "log in again" is the wrong remedy for a token.
 */
-function createTokenClient(url, token) {
+function createTokenClient(url, token, ephemeralProjectId) {
 	const client = createRebaseClient({
 		baseUrl: url,
 		realtime: false,
 		headers: { "User-Agent": cliUserAgent() },
+		fetch: deprecationAwareFetch,
 		token,
 		auth: {
 			storage: createMemoryStorage(),
@@ -409,10 +718,109 @@ function createTokenClient(url, token) {
 			autoRefresh: false
 		}
 	});
-	client.setOnUnauthorized(() => explainRefusedToken(url, token));
+	client.setOnUnauthorized(() => ephemeralProjectId ? explainRefusedGrant(url, ephemeralProjectId, token) : explainRefusedToken(url, token));
 	STATIC_TOKENS.set(client, token);
+	if (ephemeralProjectId) GRANT_CLIENTS.set(client, ephemeralProjectId);
 	return client;
 }
+/** The deprecation notices already printed, once each per process. */
+var TOLD_DEPRECATED = /* @__PURE__ */ new Set();
+/**
+* Say, once, that the control plane marked a token's request as deprecated.
+*
+* The control plane answers a request it still serves, but will not in a later
+* release, with `Deprecation: true` (RFC 9745), a `Link` with
+* `rel="deprecation"` to the page that explains it, and an
+* `X-Rebase-Deprecation` sentence saying what to do — a token from before
+* `org:billing` reading billing is the first. CI logs are where that is seen,
+* so it goes to stderr as a warning, once per notice per process, and never
+* into the `--json` value on stdout.
+*
+* Exported so its test can hand it a response.
+*/
+function noticeDeprecation(response) {
+	if (response.headers?.get?.("Deprecation") == null) return;
+	const notice = response.headers.get("X-Rebase-Deprecation")?.trim() || "The control plane marked a request this command made as deprecated: it may stop working in a later release.";
+	if (TOLD_DEPRECATED.has(notice)) return;
+	TOLD_DEPRECATED.add(notice);
+	const link = /<([^>]+)>\s*;\s*rel="?deprecation"?/i.exec(response.headers.get("Link") ?? "")?.[1];
+	warn(notice, link ? `See ${link}` : void 0);
+}
+/**
+* `fetch` for a token client: the global one — read at call time, so a test's
+* stand-in is used — with every answer shown to {@link noticeDeprecation}.
+*/
+var deprecationAwareFetch = async (input, init) => {
+	const response = await globalThis.fetch(input, init);
+	noticeDeprecation(response);
+	return response;
+};
+/** What `/api/auth/scopes` said each token holds, asked once per process. */
+var TOKEN_SCOPES = /* @__PURE__ */ new Map();
+/** The projects already told that `REBASE_TOKEN` was set aside for their own token. */
+var TOLD_GRANT_PREFERRED = /* @__PURE__ */ new Set();
+/**
+* The scopes the control plane says a token holds — one `/api/auth/scopes`
+* request per token and host for the life of the process — or undefined when
+* it could not say: refused, unreachable, or an answer without `held`.
+*/
+function tokenScopes(url, token) {
+	const key = `${url}\n${token}`;
+	let pending = TOKEN_SCOPES.get(key);
+	if (!pending) {
+		pending = (async () => {
+			try {
+				const res = await fetch(`${url}/api/auth/scopes`, { headers: {
+					Authorization: `Bearer ${token}`,
+					"User-Agent": cliUserAgent()
+				} });
+				if (!res.ok) return void 0;
+				const body = await res.json();
+				const held = typeof body === "object" && body !== null ? body.held : void 0;
+				return Array.isArray(held) && held.every((s) => typeof s === "string") ? held : void 0;
+			} catch {
+				return;
+			}
+		})();
+		TOKEN_SCOPES.set(key, pending);
+	}
+	return pending;
+}
+/**
+* Whether a command line names a project other than the linked one with
+* `--project`: the grant acts only on its own project, so such a command
+* keeps `REBASE_TOKEN` whatever it holds.
+*/
+function namesAnotherProject(rawArgs, projectId) {
+	const ref = arg({
+		"--project": String,
+		"-p": "--project"
+	}, {
+		argv: rawArgs.slice(2),
+		permissive: true
+	})["--project"];
+	if (!ref) return false;
+	const link = readLink();
+	return ref !== projectId && ref !== link?.slug;
+}
+/**
+* Whether the control plane still accepts a token: one request to
+* `/api/auth/scopes`, the route every token may read. `refused` only when it
+* answered 401 or 403; `unknown` when it could not be asked, or answered
+* something else — which proves nothing about the token.
+*/
+async function probeToken(url, token) {
+	try {
+		const probe = await fetch(`${url}/api/auth/scopes`, { headers: {
+			Authorization: `Bearer ${token}`,
+			"User-Agent": cliUserAgent()
+		} });
+		if (probe.ok) return "accepted";
+		return probe.status === 401 || probe.status === 403 ? "refused" : "unknown";
+	} catch {
+		return "unknown";
+	}
+}
 /**
 * Why the control plane answered a token-authenticated request with 401, and
 * what to do about it. Never returns.
@@ -425,14 +833,7 @@ function createTokenClient(url, token) {
 * neither is answered with the other's remedy.
 */
 async function explainRefusedToken(url, token) {
-	let tokenAccepted = false;
-	try {
-		tokenAccepted = (await fetch(`${url}/api/auth/scopes`, { headers: {
-			Authorization: `Bearer ${token}`,
-			"User-Agent": cliUserAgent()
-		} })).ok;
-	} catch {}
-	if (tokenAccepted) fail(`This command needs a signed-in session, and ${TOKEN_ENV} is an API token.`, `Unset ${TOKEN_ENV} and run ${chalk.bold("rebase cloud login")} to run it.`, "session_required");
+	if (await probeToken(url, token) === "accepted") fail(`This command needs a signed-in session, and ${TOKEN_ENV} is an API token.`, `Unset ${TOKEN_ENV} and run ${chalk.bold("rebase cloud login")} to run it.`, "session_required");
 	fail(`${TOKEN_ENV} was rejected by ${url}: it has expired, been revoked, or was not issued by this control plane.`, `Create a new one with ${chalk.bold("rebase cloud tokens create")} and put it in ${TOKEN_ENV}.`, "token_rejected");
 }
 /** Two minutes of head-room before a token is treated as expired. */
@@ -459,17 +860,71 @@ async function freshAccessToken(client) {
 	return (await client.auth.refreshSession()).accessToken;
 }
 /**
+* A request made with an unclaimed project's token was refused. Never returns.
+*
+* Two causes reach that 401, as for {@link explainRefusedToken}. The project was
+* claimed (which revokes the token) or expired, and the token is dead. Or the
+* command called a route that takes only a person's session — `whoami` and
+* `projects create` read `/auth/me` — which refuses a perfectly good token too.
+* The grant holds the project's only token and the only stored copy of its
+* claim link, so it is forgotten only once `/api/auth/scopes` refuses the token
+* as well; and even then the claim link is printed before it goes.
+*/
+async function explainRefusedGrant(url, projectId, token) {
+	const verdict = await probeToken(url, token);
+	if (verdict === "accepted") fail(`This command needs a signed-in session, and this directory uses the token \`rebase cloud init --claim\` stored for project ${projectId}.`, `That token still deploys, reads logs and metrics, sets environment variables and runs \`db info\`, but reads no secret back (no variable's value, no database password) and cannot open \`db connect\` or a preview; ${chalk.bold("rebase cloud whoami")} shows it, the claim URL and when it expires. Run this command as a person once the project is claimed: ${chalk.bold("rebase cloud login")}.`, "session_required");
+	if (verdict === "unknown") fail(`The token \`rebase cloud init --claim\` stored for project ${projectId} was refused by ${url}, and the control plane could not say why.`, `The token and the claim URL are kept. Check your connection and run the command again; ${chalk.bold("rebase cloud whoami")} shows the claim URL.`, "token_rejected");
+	const grant = storedEphemeralGrant(url, projectId);
+	forgetEphemeralGrant(url, projectId);
+	const keyNote = grant && projectDotenvSetsAppKey() ? ` ${appKeyExpiryNote(grant.expiresAt)}` : "";
+	if (readCredentials().contexts[url]?.auth) fail(`The token \`rebase cloud init --claim\` stored for project ${projectId} was refused by ${url}: the project was claimed, or it expired.`, `It is forgotten, and you are signed in to ${url}: run the command again and it uses your login.${keyNote}`, "token_rejected");
+	const claim = grant ? ` If nobody has claimed it yet, its claim URL was ${chalk.bold(grant.claimUrl)} (expires ${new Date(grant.expiresAt).toLocaleString()}).` + keyNote : "";
+	fail(`The token \`rebase cloud init --claim\` stored for project ${projectId} was refused by ${url}.`, `Once a project is claimed its agent token stops working: sign in with ${chalk.bold("rebase cloud login")} as the account that claimed it, or create a token there with ${chalk.bold("rebase cloud tokens create")}.${claim}`, "token_rejected");
+}
+/**
 * Return an authenticated client for the resolved host.
 *
 * With `REBASE_TOKEN` set, that token is the credential for every request and
-* the stored login is not consulted at all. Otherwise it is the `cloud login`
-* session — see {@link requireSessionClient}.
+* the stored login is not consulted at all — except in a directory linked to a
+* project `init --claim` provisioned, when `REBASE_TOKEN` holds no scope on that
+* project (one `/api/auth/scopes` call): the project's own token acts there
+* instead, and the command says so once. Next, a directory linked to a
+* project `rebase cloud init --claim` provisioned uses the token stored for it
+* (see {@link EphemeralGrant}) until it expires: nobody can sign in as that
+* project's owner, so a login could not reach it anyway. Otherwise it is the
+* `cloud login` session — see {@link requireSessionClient}.
 */
 async function requireClient(rawArgs) {
 	const token = envToken();
-	if (!token) return requireSessionClient(rawArgs);
+	if (!token) {
+		const linked = linkedEphemeralGrant(resolveCloudUrl(rawArgs));
+		if (!linked) return requireSessionClient(rawArgs);
+		refuseDirectLink(rawArgs);
+		const url = resolveCloudUrl(rawArgs);
+		return {
+			client: createTokenClient(url, linked.grant.token, linked.projectId),
+			url
+		};
+	}
 	refuseDirectLink(rawArgs);
 	const url = resolveCloudUrl(rawArgs);
+	const displaced = linkedEphemeralGrant(url);
+	if (displaced) {
+		if (!namesAnotherProject(rawArgs, displaced.projectId)) {
+			const held = await tokenScopes(url, token);
+			if (held && !scopesReachProject(held, displaced.projectId)) {
+				if (!TOLD_GRANT_PREFERRED.has(displaced.projectId)) {
+					TOLD_GRANT_PREFERRED.add(displaced.projectId);
+					warn(`${TOKEN_ENV} holds no scope on project ${displaced.projectId}, so the token \`rebase cloud init --claim\` stored for it is used instead.`, `Pass --project to act on another project with ${TOKEN_ENV}, or give ${TOKEN_ENV} a capability on this one.`);
+				}
+				return {
+					client: createTokenClient(url, displaced.grant.token, displaced.projectId),
+					url
+				};
+			}
+		}
+		warn(`${TOKEN_ENV} is set, so it is used instead of the token \`rebase cloud init --claim\` stored for project ${displaced.projectId}.`, `Unset ${TOKEN_ENV} to act on that project with its own token.`);
+	}
 	return {
 		client: createTokenClient(url, token),
 		url
@@ -483,15 +938,17 @@ async function requireClient(rawArgs) {
 *
 * For the commands a token cannot run — minting and revoking tokens: a key that
 * could mint keys could mint its own successor, so the control plane refuses
-* every key on those routes.
+* every key on those routes. Inviting people is the other: it hands out access
+* to every project in an organization, which no token capability grants.
+* `action` names what the refusal says a token cannot do.
 */
-async function requireSessionClient(rawArgs) {
+async function requireSessionClient(rawArgs, action = "manage tokens") {
 	refuseDirectLink(rawArgs);
 	const url = resolveCloudUrl(rawArgs);
 	const client = createCloudClient(url);
 	const session = client.auth.getSession();
 	if (!session || !session.accessToken) {
-		if (envToken()) fail(`This command needs a signed-in session for ${chalk.cyan(url)}, and ${TOKEN_ENV} is an API token.`, `A token cannot manage tokens. Run ${chalk.bold("rebase cloud login")} first.`, "session_required");
+		if (envToken()) fail(`This command needs a signed-in session for ${chalk.cyan(url)}, and ${TOKEN_ENV} is an API token.`, `A token cannot ${action}. Run ${chalk.bold("rebase cloud login")} first.`, "session_required");
 		fail(`Not logged in to ${chalk.cyan(url)}.`, `Run ${chalk.bold("rebase cloud login")} first.`, "not_logged_in");
 	}
 	if (session.expiresAt <= Date.now() + EXPIRY_BUFFER_MS) try {
@@ -701,12 +1158,12 @@ var JSON_MODE = false;
 * `cloudCommand`, before anything can print or `fail`. Returns the resolved mode
 * (handy for tests, which otherwise leave it at its `false` default).
 */
-function initOutputMode(rawArgs) {
+function initOutputMode(rawArgs, opts = {}) {
 	if (arg({ "--json": Boolean }, {
 		argv: rawArgs.slice(2),
 		permissive: true
 	})["--json"]) JSON_MODE = true;
-	else JSON_MODE = parseEnvBoolean(process.env.REBASE_JSON) ?? process.stdout.isTTY !== true;
+	else JSON_MODE = parseEnvBoolean(process.env.REBASE_JSON) ?? (opts.whenPiped === "human" ? false : process.stdout.isTTY !== true);
 	return JSON_MODE;
 }
 /** Whether the current invocation is emitting machine-readable JSON. */
@@ -1228,6 +1685,6 @@ function requireCloudRow(row, what) {
 	return parsed;
 }
 //#endregion
-export { projectHost as A, requireProject as B, lookupProjectId as C, parseCloudArgs as D, openUrl as E, reportError as F, resolveProjectRef as G, requireSessionClient as H, requireClient as I, setCurrentContext as J, resolveTimeoutMs as K, requireCloudRow as L, readLink as M, refuseDirectLink as N, printGroupHelp as O, removeLink as P, wantsRawError as Q, requireInteractive as R, keyValues as S, noteBlank as T, resolveCloudTarget as U, requireProjectRef as V, resolveCloudUrl as W, warn as X, success as Y, writeLink as Z, freshAccessToken as _, cloudRow as a, isJsonMode as b, confirmDestructive as c, emit as d, emitHelp as f, fetchTenantBaseDomain as g, fetchDeployTargets as h, billingAccountIdOf as i, projectLinkPath as j, printJson as k, createCloudClient as l, fail as m, GLOBAL_HELP_FLAGS as n, cloudRows as o, envToken as p, setContextOrg as q, TOKEN_ENV as r, colorStatus as s, GLOBAL_CLOUD_FLAGS as t, displayProjectRef as u, getContextOrg as v, note as w, isKnownControlPlane as x, initOutputMode as y, requireKnownAction as z };
+export { resolveCloudUrl as $, lookupProjectId as A, projectLinkPath as B, grantForLink as C, isKnownControlPlane as D, isJsonMode as E, printGroupHelp as F, requireClient as G, refuseDirectLink as H, printJson as I, requireKnownAction as J, requireCloudRow as K, probeToken as L, noteBlank as M, openUrl as N, keyValues as O, parseCloudArgs as P, resolveCloudTarget as Q, projectDotenvSetsAppKey as R, getContextOrg as S, initOutputMode as T, removeLink as U, readLink as V, reportError as W, requireProjectRef as X, requireProject as Y, requireSessionClient as Z, fail as _, orgCapabilitiesInScopes as _t, billingAccountIdOf as a, storedGrantForLink as at, forgetEphemeralGrant as b, wantsRawError as bt, colorStatus as c, writeLink as ct, displayProjectRef as d, ORG_CAPABILITY_NAMES as dt, resolveProjectRef as et, dotenvSets as f, TOKEN_CAPABILITIES as ft, ephemeralGrantFor as g, isTokenCapability as gt, envToken as h, isOrgCapability as ht, appKeyExpiryNote as i, setCurrentContext as it, note as j, linkedEphemeralGrant as k, confirmDestructive as l, ALWAYS_SCOPES as lt, emitHelp as m, capabilitiesInScopes as mt, GLOBAL_HELP_FLAGS as n, saveEphemeralGrant as nt, cloudRow as o, success as ot, emit as p, TOKEN_CAPABILITY_NAMES as pt, requireInteractive as q, TOKEN_ENV as r, setContextOrg as rt, cloudRows as s, warn as st, GLOBAL_CLOUD_FLAGS as t, resolveTimeoutMs as tt, createCloudClient as u, ORG_CAPABILITIES as ut, fetchDeployTargets as v, scopesForCapabilities as vt, grantProjectOf as w, freshAccessToken as x, fetchTenantBaseDomain as y, scopesForOrgCapabilities as yt, projectHost as z };
 
-//# sourceMappingURL=context-DHiiiJ5C.js.map
+//# sourceMappingURL=context-GUxkZm-S.js.map