@runtypelabs/cli 2.59.0 → 2.59.2

package/dist/chunk-BhgLSfH6.js

@@ -0,0 +1,1123 @@
+#!/usr/bin/env node
+import { P as getRuntypeHomeDir, b as CredentialStore, t as isTTY } from "./index.js";
+import { ConfirmPrompt, DataList, EntityCard, MutationResult, React, Text, mutationResultProps, render, useEffect, useMutationState, useState } from "./chunk-CoAWdSiE.js";
+import { b as pkceCodeChallengeSchema, d as apiKeyFileSlug, f as apiKeyFileUsageHint, m as isForbiddenRequestedPermission, n as API_KEY_REQUEST_MAX_TTL_SECONDS, r as API_KEY_REQUEST_POLL_INTERVAL_MS, t as API_KEY_FILE_FORMAT, u as apiKeyFileSchema, x as pkceCodeVerifierSchema } from "./chunk-ucu5lrDZ.js";
+import { i as getApiUrl, r as createCliClient } from "./chunk-BW2fg46T.js";
+import { n as ensureAuth } from "./chunk-CJraEBVd.js";
+import { a as printJson, i as printDetail, r as getTotalCount } from "./chunk-CcFCyqbB.js";
+import { Command, InvalidArgumentError } from "commander";
+import chalk from "chalk";
+import path from "node:path";
+import { createHash, randomBytes, randomUUID } from "node:crypto";
+import open from "open";
+import { chmod, mkdir, open as open$1, rename, rm, stat, writeFile } from "node:fs/promises";
+var ApiKeyFileExistsError = class extends Error {
+	path;
+	constructor(path) {
+		super(`A key file already exists at ${path}. Pass --force to overwrite it, or --out <path> to write somewhere else.`);
+		this.path = path;
+		this.name = "ApiKeyFileExistsError";
+	}
+};
+/** Directory key files live in: `$RUNTYPE_STATE_DIR/keys` (default `~/.runtype/keys`). */
+function getApiKeyFileDir() {
+	return path.join(getRuntypeHomeDir(), "keys");
+}
+/** Default destination for a key named `name`: `<keys dir>/<slug>.json`. */
+function defaultApiKeyFilePath(name) {
+	return path.join(getApiKeyFileDir(), `${apiKeyFileSlug(name)}.json`);
+}
+/**
+* Throw `ApiKeyFileExistsError` if a key file already sits at the destination.
+* A read-only pre-flight for callers that must not spend something irreversible only to collide afterwards.
+* Unlike the write path this reserves nothing; it's advisory, and `writeApiKeyFile`'s `open(..., 'wx')` is still authoritative.
+*/
+async function assertApiKeyFilePathFree(outPath, name) {
+	if (!outPath && !name) return;
+	const targetPath = path.resolve(outPath ?? defaultApiKeyFilePath(name));
+	try {
+		await stat(targetPath);
+	} catch (error) {
+		if (error?.code === "ENOENT") return;
+		throw error;
+	}
+	throw new ApiKeyFileExistsError(targetPath);
+}
+/**
+* Validate and write a key file. The content is parsed through
+* `apiKeyFileSchema` first so a malformed record never reaches disk under the
+* canonical format name.
+*/
+async function writeApiKeyFile(file, options = {}) {
+	const parsed = apiKeyFileSchema.parse(file);
+	const targetPath = path.resolve(options.outPath ?? defaultApiKeyFilePath(parsed.name));
+	const directory = path.dirname(targetPath);
+	if (await mkdir(directory, {
+		recursive: true,
+		mode: 448
+	}) !== void 0 || directory === getApiKeyFileDir()) await chmod(directory, 448);
+	if (!options.force) try {
+		await (await open$1(targetPath, "wx", 384)).close();
+	} catch (error) {
+		if (error?.code === "EEXIST") throw new ApiKeyFileExistsError(targetPath);
+		throw error;
+	}
+	const temporaryPath = path.join(directory, `.runtype-key-${randomUUID()}.tmp`);
+	try {
+		await writeFile(temporaryPath, `${JSON.stringify(parsed, null, 2)}\n`, {
+			mode: 384,
+			flag: "wx"
+		});
+		await chmod(temporaryPath, 384);
+		await rename(temporaryPath, targetPath);
+	} finally {
+		await rm(temporaryPath, { force: true });
+	}
+	return {
+		path: targetPath,
+		format: API_KEY_FILE_FORMAT,
+		usageHint: apiKeyFileUsageHint(targetPath)
+	};
+}
+// src/lib/api-key-request-flow.ts
+var ApiKeyRequestError = class extends Error {
+	code;
+	resumeCommand;
+	constructor(message, code, resumeCommand) {
+		super(message);
+		this.code = code;
+		this.resumeCommand = resumeCommand;
+		this.name = "ApiKeyRequestError";
+	}
+};
+function base64Url(bytes) {
+	return Buffer.from(bytes).toString("base64url");
+}
+/** S256 challenge for a verifier, matching the api's `oauth-code-store` derivation. */
+function deriveCodeChallenge(codeVerifier) {
+	return base64Url(createHash("sha256").update(codeVerifier).digest());
+}
+/**
+* 32 random bytes base64url-encoded → 43 characters, inside both the verifier
+* grammar (43–128 unreserved chars) and the challenge grammar the api pins.
+*/
+function generatePkcePair() {
+	const codeVerifier = base64Url(randomBytes(32));
+	const codeChallenge = deriveCodeChallenge(codeVerifier);
+	pkceCodeVerifierSchema.parse(codeVerifier);
+	pkceCodeChallengeSchema.parse(codeChallenge);
+	return {
+		codeVerifier,
+		codeChallenge
+	};
+}
+const DURATION_UNIT_SECONDS = {
+	s: 1,
+	m: 60,
+	h: 3600,
+	d: 86400,
+	w: 604800
+};
+/** `30d`, `12h`, `90m`, `3600s`, or a bare number of seconds. */
+function parseDurationSeconds(input) {
+	const trimmed = input.trim().toLowerCase();
+	const match = /^(\d+)([smhdw]?)$/.exec(trimmed);
+	if (!match) throw new ApiKeyRequestError(`Could not read "${input}" as a duration. Use a number of seconds or a suffixed value like 30d, 12h, 90m.`, "invalid_ttl");
+	const seconds = Number(match[1]) * DURATION_UNIT_SECONDS[match[2] || "s"];
+	if (seconds <= 0) throw new ApiKeyRequestError("TTL must be greater than zero.", "invalid_ttl");
+	if (seconds > 7776e3) throw new ApiKeyRequestError(`TTL ${input} exceeds the maximum requestable lifetime of ${API_KEY_REQUEST_MAX_TTL_SECONDS / 86400} days.`, "invalid_ttl");
+	return seconds;
+}
+/**
+* Comma (or whitespace) separated scope list, upper-cased because the api's
+* permission registry is upper-case. Scopes an agent may never ask for are
+* rejected here so the user sees the reason before a human is paged.
+*/
+function parseScopes(input) {
+	const scopes = input.split(/[,\s]+/).map((scope) => scope.trim().toUpperCase()).filter((scope) => scope.length > 0);
+	if (scopes.length === 0) throw new ApiKeyRequestError("At least one scope is required, e.g. --scopes FLOWS:READ,RECORDS:READ", "invalid_scopes");
+	const forbidden = scopes.filter((scope) => isForbiddenRequestedPermission(scope));
+	if (forbidden.length > 0) throw new ApiKeyRequestError(`These scopes can never be requested by an agent: ${forbidden.join(", ")}. Ask for the narrowest scopes the task needs.`, "forbidden_scopes");
+	return [...new Set(scopes)];
+}
+function wireDeliveryFor(delivery) {
+	return delivery.mode === "secret" ? "secret" : "inline";
+}
+async function createApiKeyRequest(client, input) {
+	return client.create({
+		name: input.name,
+		permissions: input.permissions,
+		reason: input.reason,
+		environment: input.environment,
+		...input.ttlSeconds !== void 0 ? { ttlSeconds: input.ttlSeconds } : {},
+		preferredDelivery: input.preferredDelivery,
+		codeChallenge: input.codeChallenge,
+		codeChallengeMethod: "S256",
+		...input.returnUrl ? { returnUrl: input.returnUrl } : {},
+		allowUnauthenticatedClaim: input.allowUnauthenticatedClaim === true
+	});
+}
+async function getApiKeyRequest(client, requestId) {
+	return client.get(requestId);
+}
+const MAX_CONSECUTIVE_POLL_FAILURES = 5;
+function retryAfterMs(error) {
+	const raw = (error?.headers)?.get?.("retry-after");
+	if (!raw) return null;
+	const seconds = Number(raw);
+	if (Number.isFinite(seconds) && seconds >= 0) return seconds * 1e3;
+	const date = Date.parse(raw);
+	if (Number.isFinite(date)) return Math.max(0, date - Date.now());
+	return null;
+}
+function statusCodeOf(error) {
+	const code = error?.statusCode;
+	return typeof code === "number" ? code : void 0;
+}
+const defaultSleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+/**
+* Poll a pending request until it leaves `pending`.
+* Returns whatever terminal request the api reports; a decline comes back as data, not an exception.
+* Transient failures (429 w/ Retry-After, 5xx, network) are retried; a non-rate-limit 4xx is fatal.
+*/
+async function waitForDecision(client, requestId, options = {}) {
+	const sleep = options.sleep ?? defaultSleep;
+	const now = options.now ?? (() => Date.now());
+	const interval = options.pollIntervalMs ?? 5e3;
+	const startedAt = now();
+	let consecutiveFailures = 0;
+	let deadlineMs = options.deadlineMs;
+	for (;;) {
+		let request;
+		try {
+			request = await getApiKeyRequest(client, requestId);
+			consecutiveFailures = 0;
+		} catch (error) {
+			const status = statusCodeOf(error);
+			const wait = retryAfterMs(error);
+			const transient = status === 429 || status === void 0 || status >= 500;
+			consecutiveFailures += 1;
+			if (!transient || consecutiveFailures > MAX_CONSECUTIVE_POLL_FAILURES) throw error;
+			await sleep(wait ?? interval);
+			continue;
+		}
+		if (request.status !== "pending") return request;
+		if (deadlineMs === void 0) {
+			const expiresAt = Date.parse(request.expiresAt);
+			deadlineMs = Number.isFinite(expiresAt) ? expiresAt : void 0;
+		}
+		options.onPoll?.(request, now() - startedAt);
+		if (deadlineMs !== void 0 && now() + interval > deadlineMs) throw new ApiKeyRequestError(`Request ${requestId} is still pending and its approval window closes at ${request.expiresAt}.`, "pending_timeout");
+		await sleep(interval);
+	}
+}
+/** Human-readable explanation for a request that ended somewhere other than `approved`. */
+function describeUnapprovedRequest(request) {
+	switch (request.status) {
+		case "declined": return new ApiKeyRequestError(`Request ${request.id} was declined${request.declineReason ? `: ${request.declineReason}` : "."}`, "declined");
+		case "claimed": return new ApiKeyRequestError(`Request ${request.id} was already claimed at ${request.claimedAt}. A request can only be redeemed once; file a new one.`, "already_claimed");
+		case "expired": return new ApiKeyRequestError(`Request ${request.id} expired before it was redeemed. File a new request.`, "expired");
+		case "cancelled": return new ApiKeyRequestError(`Request ${request.id} was cancelled.`, "cancelled");
+		case "pending": return new ApiKeyRequestError(`Request ${request.id} has not been decided yet. Run: RUNTYPE_KEY_REQUEST_VERIFIER=<verifier> runtype api-keys claim ${request.id}`, "pending");
+		default: return new ApiKeyRequestError(`Request ${request.id} is in an unexpected state: ${request.status}`, "unexpected_status");
+	}
+}
+/**
+* Fail BEFORE the claim if the key file's destination is already taken.
+* Claiming is one-shot and irreversible: a write failure after claiming discards the only copy of a live key.
+* A retry can only answer ALREADY_CLAIMED; re-running a rotation with the same name is exactly this collision.
+* Checking here turns it into an ordinary pre-flight error naming `--force`, before anything is spent.
+*/
+async function assertKeyFileDestinationFree(delivery) {
+	if (delivery.mode !== "keyfile" || delivery.force) return;
+	if (!delivery.outPath && !delivery.name) return;
+	try {
+		await assertApiKeyFilePathFree(delivery.outPath, delivery.name);
+	} catch (error) {
+		if (error instanceof ApiKeyFileExistsError) throw new ApiKeyRequestError(error.message, "key_file_exists");
+		throw error;
+	}
+}
+function errorCodeOf(error) {
+	const code = error?.data?.code;
+	return typeof code === "string" ? code : void 0;
+}
+function verifierClaimFailure(error, requestId) {
+	const status = statusCodeOf(error);
+	const code = errorCodeOf(error);
+	if (status === 404) return new ApiKeyRequestError(`Request ${requestId} could not be redeemed without a login. Either the verifier is wrong, or the request was not filed with unauthenticated claim allowed. Log in with \`runtype auth login\` and run this command again.`, "not_found_unauthenticated");
+	if (status === 409) return new ApiKeyRequestError(`Request ${requestId} was already claimed or its claim window closed. A request can only be redeemed once; file a new one.`, "already_claimed");
+	if (status === 410) {
+		const reason = code === "DECLINED" ? "declined" : code === "CANCELLED" ? "cancelled" : "expired";
+		return new ApiKeyRequestError(`Request ${requestId} was ${reason}. File a new request.`, reason);
+	}
+	if (status === 403) return new ApiKeyRequestError(error instanceof Error ? error.message : `Request ${requestId} cannot be redeemed without a login.`, "grant_too_broad");
+	return null;
+}
+async function claimWithVerifierUntilDecided(client, requestId, codeVerifier, options) {
+	const sleep = options.sleep ?? defaultSleep;
+	const now = options.now ?? (() => Date.now());
+	const startedAt = now();
+	let consecutiveFailures = 0;
+	for (;;) try {
+		return await client.claimWithVerifier(requestId, { codeVerifier });
+	} catch (error) {
+		const status = statusCodeOf(error);
+		if (status === 425) {
+			consecutiveFailures = 0;
+			if (!options.wait) throw new ApiKeyRequestError(`Request ${requestId} has not been approved yet. Ask the approver to open its request page, then re-run this command (or add --wait to poll until they decide).`, "pending");
+			options.onPending?.(now() - startedAt);
+			await sleep(retryAfterMs(error) ?? 5e3);
+			continue;
+		}
+		const mapped = verifierClaimFailure(error, requestId);
+		if (mapped) throw mapped;
+		const transient = status === 429 || status === void 0 || status >= 500;
+		consecutiveFailures += 1;
+		if (!transient || consecutiveFailures > MAX_CONSECUTIVE_POLL_FAILURES) throw error;
+		await sleep(retryAfterMs(error) ?? 5e3);
+	}
+}
+async function claimApiKeyRequest(client, requestId, codeVerifier, delivery) {
+	await assertKeyFileDestinationFree(delivery);
+	return client.claim(requestId, {
+		codeVerifier,
+		delivery: wireDeliveryFor(delivery),
+		...delivery.mode === "secret" && delivery.secretKey ? { secretKey: delivery.secretKey } : {}
+	});
+}
+function buildApiKeyFileContent(input) {
+	return apiKeyFileSchema.parse({
+		format: API_KEY_FILE_FORMAT,
+		apiKey: input.apiKey,
+		keyId: input.keyId,
+		name: input.name,
+		environment: input.environment,
+		permissions: input.permissions,
+		apiUrl: input.apiUrl ?? getApiUrl(),
+		organizationId: input.organizationId,
+		expiresAt: input.expiresAt,
+		createdAt: input.createdAt ?? (/* @__PURE__ */ new Date()).toISOString(),
+		requestId: input.requestId
+	});
+}
+/**
+* Turn a claim response into the artifact the caller asked for. The plaintext
+* key is carried on the result ONLY for `inline` — every other mode leaves it
+* on disk or in the secret plane, so `--json` output cannot leak it.
+*/
+async function deliverClaimedKey(response, delivery) {
+	const base = {
+		keyId: response.keyId,
+		name: response.name,
+		environment: response.environment,
+		permissions: response.permissions,
+		expiresAt: response.expiresAt
+	};
+	if (delivery.mode === "secret") {
+		if (!response.secretRef) throw new ApiKeyRequestError("The claim succeeded but the API returned no secret reference. Re-run with --inline or --out to recover the key.", "missing_secret_ref");
+		return {
+			...base,
+			delivery: "secret",
+			secretRef: response.secretRef,
+			secretKey: response.secretKey,
+			nextSteps: response.nextSteps
+		};
+	}
+	if (!response.apiKey) throw new ApiKeyRequestError("The claim succeeded but the API returned no key. It cannot be re-issued — file a new request.", "missing_plaintext");
+	if (delivery.mode === "inline") return {
+		...base,
+		delivery: "inline",
+		apiKey: response.apiKey,
+		nextSteps: response.nextSteps
+	};
+	let file;
+	try {
+		file = await writeApiKeyFile(buildApiKeyFileContent({
+			apiKey: response.apiKey,
+			keyId: response.keyId,
+			name: response.name,
+			environment: response.environment,
+			permissions: response.permissions,
+			expiresAt: response.expiresAt,
+			organizationId: response.request?.organizationId ?? null,
+			requestId: response.request?.id ?? null
+		}), {
+			outPath: delivery.outPath,
+			force: delivery.force
+		});
+	} catch (error) {
+		throw new ApiKeyRequestError(`The key was minted but could not be written to disk (${error instanceof Error ? error.message : String(error)}). It cannot be re-issued: this request is already claimed. Revoke key ${response.keyId} and file a new request.`, "key_file_write_failed");
+	}
+	return {
+		...base,
+		delivery: "keyfile",
+		file,
+		nextSteps: file.usageHint
+	};
+}
+/**
+* `--json` projection. The plaintext key appears only when the caller asked
+* for `--inline`; a key file or secret delivery emits its pointer instead.
+*/
+function deliveredKeyJson(delivered) {
+	return {
+		keyId: delivered.keyId,
+		name: delivered.name,
+		environment: delivered.environment,
+		permissions: delivered.permissions,
+		expiresAt: delivered.expiresAt,
+		delivery: delivered.delivery,
+		...delivered.file ? {
+			path: delivered.file.path,
+			format: delivered.file.format,
+			usageHint: delivered.file.usageHint
+		} : {},
+		...delivered.apiKey ? { apiKey: delivered.apiKey } : {},
+		...delivered.secretRef ? { secretRef: delivered.secretRef } : {},
+		...delivered.secretKey ? { secretKey: delivered.secretKey } : {},
+		nextSteps: delivered.nextSteps
+	};
+}
+// src/commands/api-keys-requests.ts
+/**
+* `runtype api-keys request` and `runtype api-keys claim` are the CLI half of the agent key-request ceremony.
+* `request` files the request, hands a human the approval URL, polls, and redeems.
+* `claim` is the resume/handoff entry point for an MCP-driven agent that cannot hold a file.
+* The ceremony itself lives in lib/api-key-request-flow.ts; this module is flags, prompts and output.
+*/
+/**
+* Resolve the mutually exclusive delivery flags shared by both commands.
+* Default is a key file, because the point of the ceremony is that a local
+* agent can USE the key without it ever appearing in a transcript.
+*/
+function resolveDelivery(options, keyName) {
+	const chosen = [];
+	if (options.out !== void 0) chosen.push("--out");
+	if (options.secret !== void 0 && options.secret !== false) chosen.push("--secret");
+	if (options.inline) chosen.push("--inline");
+	if (chosen.length > 1) throw new ApiKeyRequestError(`Choose one delivery: ${chosen.join(", ")} cannot be combined.`, "conflicting_delivery");
+	if (options.secret !== void 0 && options.secret !== false) {
+		if (typeof options.secret === "string") {
+			if (!/^[A-Z][A-Z0-9_]{1,99}$/.test(options.secret)) throw new ApiKeyRequestError(`"${options.secret}" is not a valid secret key. Use uppercase letters, digits and underscores, starting with a letter (for example RUNTYPE_API_KEY_DEPLOY_BOT).`, "invalid_secret_key");
+			return {
+				mode: "secret",
+				secretKey: options.secret
+			};
+		}
+		return { mode: "secret" };
+	}
+	if (options.inline) return { mode: "inline" };
+	return {
+		mode: "keyfile",
+		outPath: options.out,
+		force: options.force,
+		...keyName ? { name: keyName } : {}
+	};
+}
+function formatElapsed(ms) {
+	const total = Math.max(0, Math.floor(ms / 1e3));
+	const minutes = Math.floor(total / 60);
+	const seconds = total % 60;
+	return minutes > 0 ? `${minutes}m ${seconds}s` : `${seconds}s`;
+}
+/** Run `work` under an ink spinner when the terminal can show one. */
+async function withSpinner(useInk, initialLabel, work) {
+	if (!useInk) {
+		console.log(chalk.gray(initialLabel));
+		return work(() => {});
+	}
+	const { Spinner } = await import("@runtypelabs/ink-components");
+	const instance = render(React.createElement(Spinner, { label: initialLabel }));
+	try {
+		return await work((label) => {
+			instance.rerender(React.createElement(Spinner, { label }));
+		});
+	} finally {
+		instance.unmount();
+	}
+}
+function printDeliveredKey(delivered) {
+	console.log(chalk.green("API key claimed"));
+	console.log(`  Key ID: ${chalk.green(delivered.keyId)}`);
+	console.log(`  Name: ${delivered.name}`);
+	console.log(`  Environment: ${delivered.environment}`);
+	console.log(`  Scopes: ${delivered.permissions.join(", ")}`);
+	console.log(`  Expires: ${delivered.expiresAt ?? "never"}`);
+	if (delivered.file) console.log(`  Key file: ${chalk.cyan(delivered.file.path)}`);
+	if (delivered.secretRef) console.log(`  Secret: ${chalk.cyan(delivered.secretRef)}`);
+	if (delivered.apiKey) {
+		console.log(`  Key: ${chalk.yellow(delivered.apiKey)}`);
+		console.log(chalk.yellow("  Shown once. Store it now, and do not paste it into a chat transcript or commit it."));
+	}
+	console.log("");
+	console.log(delivered.nextSteps);
+}
+/** States where re-running `claim` cannot help, so no resume hint is offered. */
+const UNRESUMABLE_CODES = /* @__PURE__ */ new Set([
+	"declined",
+	"expired",
+	"cancelled",
+	"already_claimed",
+	"missing_plaintext",
+	"key_file_write_failed"
+]);
+function failRequest(error, resumeCommand) {
+	const message = error instanceof Error ? error.message : String(error);
+	const code = error instanceof ApiKeyRequestError ? error.code : void 0;
+	console.error(chalk.red(message));
+	if (resumeCommand && (!code || !UNRESUMABLE_CODES.has(code))) console.error(chalk.gray(`Resume with: ${resumeCommand}`));
+	process.exit(1);
+}
+/**
+* Poll for the decision, then redeem. Shared by `request` (which just filed
+* the request) and `claim --wait`.
+*/
+async function awaitDecisionAndClaim(args) {
+	const decided = await withSpinner(args.useInk, "Waiting for a human to approve this request...", async (setLabel) => waitForDecision(args.client, args.requestId, {
+		pollIntervalMs: args.pollIntervalMs,
+		onPoll: (_request, elapsedMs) => {
+			setLabel(`Waiting for a human to approve this request... (${formatElapsed(elapsedMs)})`);
+		}
+	}));
+	if (decided.status !== "approved") throw describeUnapprovedRequest(decided);
+	return deliverClaimedKey(await claimApiKeyRequest(args.client, args.requestId, args.codeVerifier, args.delivery), args.delivery);
+}
+function registerApiKeyRequestCommands(apiKeysCommand) {
+	apiKeysCommand.command("request").description("Ask a human to approve a new, narrower API key, then redeem it").requiredOption("-n, --name <name>", "Name for the requested key").requiredOption("--scopes <list>", "Comma-separated scopes, e.g. FLOWS:READ,RECORDS:READ").requiredOption("--reason <text>", "Why the key is needed (shown to the approver)").option("--ttl <duration>", "Requested lifetime, e.g. 30d, 12h, 3600").option("--env <environment>", "Key environment: live or test", "live").option("--out <path>", "Write the key file here instead of ~/.runtype/keys/<name>.json").option("--secret [key]", "Deliver as a Runtype secret instead of a key file").option("--inline", "Print the key to stdout instead of writing a key file").option("--force", "Overwrite an existing key file").option("--no-open", "Do not launch a browser for the approval page").option("--allow-unauthenticated-claim", "Let the verifier alone redeem the key, on a machine with no Runtype login (own scopes only, at most 7 days)").option("--json", "Output as JSON").option("--tty", "Force TTY mode").option("--no-tty", "Force non-TTY mode").action(async (options) => {
+		let delivery;
+		let permissions;
+		let ttlSeconds;
+		try {
+			delivery = resolveDelivery(options, options.name);
+			permissions = parseScopes(options.scopes);
+			ttlSeconds = options.ttl ? parseDurationSeconds(options.ttl) : void 0;
+		} catch (error) {
+			failRequest(error);
+		}
+		if (options.env !== "live" && options.env !== "test") failRequest(new ApiKeyRequestError(`--env must be "live" or "test" (got "${options.env}").`, "invalid_environment"));
+		const environment = options.env;
+		const apiKey = await ensureAuth();
+		if (!apiKey) return;
+		const client = createCliClient(apiKey).apiKeys.requests;
+		const { codeVerifier, codeChallenge } = generatePkcePair();
+		const useInk = isTTY(options) && !options.json;
+		let created;
+		try {
+			created = await createApiKeyRequest(client, {
+				name: options.name,
+				permissions,
+				reason: options.reason,
+				environment,
+				ttlSeconds,
+				preferredDelivery: delivery.mode,
+				codeChallenge,
+				allowUnauthenticatedClaim: options.allowUnauthenticatedClaim
+			});
+		} catch (error) {
+			const message = error instanceof Error ? error.message : String(error);
+			console.error(chalk.red("Failed to file the API key request"));
+			console.error(chalk.red(message));
+			process.exit(1);
+		}
+		const requestId = created.request.id;
+		const resumeCommand = `RUNTYPE_KEY_REQUEST_VERIFIER=${codeVerifier} runtype api-keys claim ${requestId}`;
+		if (!options.json) {
+			console.log(chalk.green("API key request filed"));
+			console.log(`  Request: ${chalk.green(requestId)}`);
+			console.log(`  Name: ${created.request.name}`);
+			console.log(`  Scopes: ${created.request.requestedPermissions.join(", ")}`);
+			console.log(`  Approve at: ${chalk.cyan(created.handoff.url)}`);
+			console.log("");
+			console.log(created.nextSteps);
+			if (delivery.mode === "inline") console.log(chalk.yellow("Warning: --inline prints the key to stdout. Anything reading this terminal, including a chat transcript, will see it."));
+			console.log("");
+		}
+		if (options.open) try {
+			await open(created.handoff.url);
+		} catch {
+			if (!options.json) console.log(chalk.gray("Could not open a browser. Open the approval URL above."));
+		}
+		const onInterrupt = () => {
+			console.error(chalk.gray(`\nStill pending. Resume with: ${resumeCommand}`));
+			process.exit(130);
+		};
+		process.once("SIGINT", onInterrupt);
+		try {
+			const delivered = await awaitDecisionAndClaim({
+				client,
+				requestId,
+				codeVerifier,
+				delivery,
+				pollIntervalMs: created.pollIntervalMs || 5e3,
+				useInk
+			});
+			if (options.json) printJson({
+				requestId,
+				...deliveredKeyJson(delivered)
+			});
+			else printDeliveredKey(delivered);
+		} catch (error) {
+			failRequest(error, resumeCommand);
+		} finally {
+			process.removeListener("SIGINT", onInterrupt);
+		}
+	});
+	apiKeysCommand.command("claim <requestId>").description("Redeem an approved API key request with its PKCE verifier").option("--verifier <verifier>", `The code verifier (prefer ${VERIFIER_ENV} or --verifier-stdin: argv is visible to other processes)`).option("--verifier-stdin", "Read the code verifier from stdin").option("--out <path>", "Write the key file here (default: key name when logged in, request ID otherwise)").option("--secret [key]", "Deliver as a Runtype secret instead of a key file").option("--inline", "Print the key to stdout instead of writing a key file").option("--force", "Overwrite an existing key file").option("--wait", "Keep polling while the request is still pending").option("--unauthenticated", "Redeem with the verifier alone even when logged in (the request must allow it)").option("--json", "Output as JSON").option("--tty", "Force TTY mode").option("--no-tty", "Force non-TTY mode").action(async (requestId, options) => {
+		let delivery;
+		let codeVerifier;
+		try {
+			delivery = resolveDelivery(options);
+			codeVerifier = await resolveVerifier(options);
+		} catch (error) {
+			failRequest(error);
+		}
+		const resumeCommand = `${VERIFIER_ENV}=<verifier> runtype api-keys claim ${requestId}`;
+		const useInk = isTTY(options) && !options.json;
+		const storedKey = options.unauthenticated ? null : await ensureAuth({
+			interactive: false,
+			exitOnFailure: false
+		});
+		const claimLoggedIn = (apiKey) => claimWithLogin({
+			apiKey,
+			requestId,
+			codeVerifier,
+			options,
+			useInk
+		});
+		try {
+			let delivered;
+			if (storedKey) delivered = await claimLoggedIn(storedKey);
+			else try {
+				delivered = await claimWithoutLogin({
+					requestId,
+					codeVerifier,
+					delivery,
+					wait: options.wait === true,
+					useInk,
+					json: options.json === true
+				});
+			} catch (error) {
+				const apiKey = shouldOfferLogin(options, error) ? await ensureAuth({ exitOnFailure: false }) : null;
+				if (!apiKey) throw error;
+				delivered = await claimLoggedIn(apiKey);
+			}
+			if (options.json) printJson({
+				requestId,
+				...deliveredKeyJson(delivered)
+			});
+			else printDeliveredKey(delivered);
+		} catch (error) {
+			failRequest(error, resumeCommand);
+		}
+	});
+}
+const VERIFIER_ENV = "RUNTYPE_KEY_REQUEST_VERIFIER";
+const LOGIN_RECOVERABLE_CODES = /* @__PURE__ */ new Set(["not_found_unauthenticated", "secret_requires_login"]);
+function shouldOfferLogin(options, error) {
+	return !options.unauthenticated && !options.json && process.stdin.isTTY === true && error instanceof ApiKeyRequestError && LOGIN_RECOVERABLE_CODES.has(error.code);
+}
+/** Logged-in redemption: read the request, re-resolve delivery against its name, then claim. */
+async function claimWithLogin(args) {
+	const { requestId, codeVerifier, options, useInk } = args;
+	const client = createCliClient(args.apiKey).apiKeys.requests;
+	const current = await getApiKeyRequest(client, requestId);
+	if (current.status !== "pending" && current.status !== "approved") throw describeUnapprovedRequest(current);
+	const delivery = resolveDelivery(options, current.name);
+	if (current.status === "pending" && !options.wait) throw new ApiKeyRequestError(`Request ${requestId} has not been approved yet. Ask the approver to open its request page, then re-run this command (or add --wait to poll until they decide).`, "pending");
+	return current.status === "pending" ? awaitDecisionAndClaim({
+		client,
+		requestId,
+		codeVerifier,
+		delivery,
+		pollIntervalMs: API_KEY_REQUEST_POLL_INTERVAL_MS,
+		useInk
+	}) : deliverClaimedKey(await claimApiKeyRequest(client, requestId, codeVerifier, delivery), delivery);
+}
+async function readStdin() {
+	const chunks = [];
+	for await (const chunk of process.stdin) chunks.push(typeof chunk === "string" ? Buffer.from(chunk) : chunk);
+	return Buffer.concat(chunks).toString("utf8");
+}
+/**
+* Exactly one verifier source: `--verifier`, `--verifier-stdin`, or the environment.
+* The flag is kept for compatibility; stdin and the environment keep it out of `ps` and shell history.
+*/
+async function resolveVerifier(options, io = {}) {
+	const fromEnv = (io.env ?? process.env)[VERIFIER_ENV]?.trim() || void 0;
+	const sources = [options.verifier !== void 0 ? "--verifier" : null, options.verifierStdin ? "--verifier-stdin" : null].filter((source) => source !== null);
+	if (sources.length > 1) throw new ApiKeyRequestError(`Choose one verifier source: ${sources.join(", ")} cannot be combined.`, "conflicting_verifier");
+	const verifier = options.verifierStdin ? (await (io.readStdin ?? readStdin)()).trim() : options.verifier ?? fromEnv;
+	if (!verifier) throw new ApiKeyRequestError(`Provide the code verifier via ${VERIFIER_ENV}, --verifier-stdin, or --verifier.`, "missing_verifier");
+	if (!pkceCodeVerifierSchema.safeParse(verifier).success) throw new ApiKeyRequestError("The verifier is not a valid PKCE code verifier (43-128 unreserved characters).", "invalid_verifier");
+	return verifier;
+}
+/** No stored login: redeem through the public verifier-only route, which mints inline only. */
+async function claimWithoutLogin(args) {
+	if (args.delivery.mode === "secret") throw new ApiKeyRequestError("Secret delivery needs a Runtype login. Use the default key file or --inline, or log in with `runtype auth login` first.", "secret_requires_login");
+	const delivery = args.delivery.mode === "keyfile" ? {
+		...args.delivery,
+		outPath: args.delivery.outPath ?? defaultApiKeyFilePath(args.requestId)
+	} : args.delivery;
+	await assertKeyFileDestinationFree(delivery);
+	const client = createCliClient().apiKeys.requests;
+	const redeem = (setLabel) => claimWithVerifierUntilDecided(client, args.requestId, args.codeVerifier, {
+		wait: args.wait,
+		onPending: (elapsedMs) => setLabel(`Waiting for a human to approve this request... (${formatElapsed(elapsedMs)})`)
+	});
+	return deliverClaimedKey(args.json ? await redeem(() => {}) : await withSpinner(args.useInk && args.wait, "Redeeming without a login...", redeem), delivery);
+}
+// src/commands/api-keys.ts
+/** Best-effort org id for the key file; provenance only, never authorization. */
+async function storedOrganizationId() {
+	try {
+		return (await new CredentialStore().getCredentials())?.orgId ?? null;
+	} catch {
+		return null;
+	}
+}
+/** Parses `--permissions FLOWS:*,EVALS:WRITE`; the API has no default scopes, so an empty list is refused. */
+function parsePermissionList(value) {
+	const scopes = [...new Set(value.split(",").map((scope) => scope.trim()).filter(Boolean))];
+	if (scopes.length === 0) throw new InvalidArgumentError("pass at least one scope, e.g. --permissions FLOWS:*,EVALS:WRITE");
+	return scopes;
+}
+const apiKeysCommand = new Command("api-keys").alias("keys").description("Manage API keys");
+apiKeysCommand.command("list").description("List your API keys").option("--json", "Output as JSON").option("--tty", "Force TTY mode").option("--no-tty", "Force non-TTY mode").action(async (options) => {
+	const apiKey = await ensureAuth();
+	if (!apiKey) return;
+	const client = createCliClient(apiKey);
+	if (!isTTY(options) || options.json) {
+		try {
+			const data = await client.get("/api-keys");
+			if (options.json) printJson(data);
+			else {
+				const keys = data.data ?? [];
+				if (keys.length === 0) {
+					console.log(chalk.gray("No API keys found"));
+					return;
+				}
+				console.log(chalk.cyan("Your API Keys:"));
+				for (const key of keys) {
+					const prefix = key.prefix ? chalk.gray(` (${key.prefix}...)`) : "";
+					const lastUsed = key.lastUsedAt ? chalk.gray(` last used: ${key.lastUsedAt}`) : "";
+					console.log(`  ${chalk.green(key.id)} ${key.name}${prefix}${lastUsed}`);
+				}
+				const total = getTotalCount(data.pagination);
+				if (total !== void 0) console.log(chalk.dim(`\n  Total: ${total} keys`));
+			}
+		} catch (error) {
+			const message = error instanceof Error ? error.message : "Unknown error";
+			console.error(chalk.red("Failed to fetch API keys"));
+			console.error(chalk.red(message));
+			process.exit(1);
+		}
+		return;
+	}
+	const App = () => {
+		const [loading, setLoading] = useState(true);
+		const [items, setItems] = useState(null);
+		const [total, setTotal] = useState(void 0);
+		const [error, setError] = useState(null);
+		useEffect(() => {
+			const run = async () => {
+				try {
+					const data = await client.get("/api-keys");
+					setItems(data.data ?? []);
+					setTotal(getTotalCount(data.pagination));
+					setLoading(false);
+				} catch (err) {
+					setError(err instanceof Error ? err : new Error(String(err)));
+					setLoading(false);
+				}
+			};
+			run();
+		}, []);
+		return React.createElement(DataList, {
+			title: "Your API Keys",
+			items,
+			error,
+			loading,
+			total,
+			emptyMessage: "No API keys found",
+			renderCard: (item) => {
+				const k = item;
+				const prefix = k.prefix ? ` (${k.prefix}...)` : "";
+				const lastUsed = k.lastUsedAt ? ` last used: ${k.lastUsedAt}` : "";
+				return React.createElement(Text, null, `  ${k.id} ${k.name}${prefix}${lastUsed}`);
+			}
+		});
+	};
+	const { waitUntilExit } = render(React.createElement(App));
+	await waitUntilExit();
+});
+apiKeysCommand.command("get <id>").description("Get API key details").option("--json", "Output as JSON").option("--tty", "Force TTY mode").option("--no-tty", "Force non-TTY mode").action(async (id, options) => {
+	const apiKey = await ensureAuth();
+	if (!apiKey) return;
+	const client = createCliClient(apiKey);
+	if (!isTTY(options) || options.json) {
+		try {
+			const data = await client.get(`/api-keys/${id}`);
+			if (options.json) printJson(data);
+			else printDetail("API Key", [
+				{
+					label: "ID",
+					value: data.id
+				},
+				{
+					label: "Name",
+					value: data.name
+				},
+				{
+					label: "Prefix",
+					value: data.prefix
+				},
+				{
+					label: "Scopes",
+					value: data.scopes?.join(", ")
+				},
+				{
+					label: "Last used",
+					value: data.lastUsedAt
+				},
+				{
+					label: "Created",
+					value: data.createdAt
+				}
+			]);
+		} catch (error) {
+			const message = error instanceof Error ? error.message : "Unknown error";
+			console.error(chalk.red("Failed to fetch API key"));
+			console.error(chalk.red(message));
+			process.exit(1);
+		}
+		return;
+	}
+	const App = () => {
+		const mutation = useMutationState();
+		useEffect(() => {
+			const run = async () => {
+				try {
+					const data = await client.get(`/api-keys/${id}`);
+					mutation.succeed(React.createElement(EntityCard, { fields: [
+						{
+							label: "ID",
+							value: data.id
+						},
+						{
+							label: "Name",
+							value: data.name
+						},
+						{
+							label: "Prefix",
+							value: data.prefix
+						},
+						{
+							label: "Scopes",
+							value: data.scopes?.join(", ")
+						},
+						{
+							label: "Last used",
+							value: data.lastUsedAt
+						},
+						{
+							label: "Created",
+							value: data.createdAt
+						}
+					] }));
+				} catch (err) {
+					mutation.fail(err);
+				}
+			};
+			run();
+		}, []);
+		return React.createElement(MutationResult, {
+			...mutationResultProps(mutation.state),
+			loadingLabel: "Fetching API key...",
+			successMessage: "API Key"
+		});
+	};
+	const { waitUntilExit } = render(React.createElement(App));
+	await waitUntilExit();
+});
+apiKeysCommand.command("create").description("Create a new API key").requiredOption("-n, --name <name>", "Key name").requiredOption("-p, --permissions <scopes>", "Comma-separated scopes, e.g. FLOWS:*,EVALS:WRITE (required; list them with the API GET /v1/api-keys/options)", parsePermissionList).option("--out <path>", "Write the key to a runtype.api-key/v1 key file (mode 0600)").option("--force", "Overwrite an existing key file at --out").option("--json", "Output as JSON").option("--tty", "Force TTY mode").option("--no-tty", "Force non-TTY mode").action(async (options) => {
+	const apiKey = await ensureAuth();
+	if (!apiKey) return;
+	const client = createCliClient(apiKey);
+	/**
+	* Write the freshly minted plaintext to the canonical key file. Same
+	* writer, same format, and the same 0600 guarantees as the agent
+	* key-request claim path, so there is exactly one on-disk key format.
+	*/
+	const writeKeyFile = async (created) => {
+		if (!options.out || !created.plainKey) return void 0;
+		return writeApiKeyFile(buildApiKeyFileContent({
+			apiKey: created.plainKey,
+			keyId: created.apiKey.id,
+			name: created.apiKey.name ?? options.name,
+			environment: created.apiKey.environment === "test" ? "test" : "live",
+			permissions: created.apiKey.permissions ?? created.apiKey.scopes ?? [],
+			expiresAt: created.apiKey.expiresAt ?? null,
+			organizationId: created.apiKey.organizationId ?? await storedOrganizationId(),
+			requestId: null
+		}), {
+			outPath: options.out,
+			force: options.force
+		});
+	};
+	if (!isTTY(options) || options.json) {
+		try {
+			const created = await client.post("/api-keys", {
+				name: options.name,
+				permissions: options.permissions
+			});
+			const file = await writeKeyFile(created);
+			if (options.json) printJson(file ? {
+				...created,
+				keyFile: {
+					path: file.path,
+					format: file.format,
+					usageHint: file.usageHint
+				}
+			} : created);
+			else {
+				console.log(chalk.green("API key created"));
+				console.log(`  ID: ${chalk.green(created.apiKey.id)}`);
+				console.log(`  Name: ${created.apiKey.name}`);
+				if (file) {
+					console.log(`  Key file: ${chalk.cyan(file.path)}`);
+					console.log("");
+					console.log(file.usageHint);
+				} else if (created.plainKey) console.log(chalk.gray("  Key not shown. Re-run with --out <path> to write a key file, or --json."));
+			}
+		} catch (error) {
+			const message = error instanceof Error ? error.message : "Unknown error";
+			console.error(chalk.red("Failed to create API key"));
+			console.error(chalk.red(message));
+			process.exit(1);
+		}
+		return;
+	}
+	const App = () => {
+		const mutation = useMutationState();
+		useEffect(() => {
+			const run = async () => {
+				try {
+					const created = await client.post("/api-keys", {
+						name: options.name,
+						permissions: options.permissions
+					});
+					const file = await writeKeyFile(created);
+					const fields = [{
+						label: "ID",
+						value: created.apiKey.id,
+						color: "green"
+					}, {
+						label: "Name",
+						value: created.apiKey.name
+					}];
+					if (file) {
+						fields.push({
+							label: "Key file",
+							value: file.path,
+							color: "cyan"
+						});
+						fields.push({
+							label: "Usage",
+							value: file.usageHint
+						});
+					} else if (created.plainKey) {
+						fields.push({
+							label: "Key",
+							value: created.plainKey,
+							color: "yellow"
+						});
+						fields.push({
+							label: "Note",
+							value: "Save this key - it will not be shown again"
+						});
+					}
+					mutation.succeed(React.createElement(EntityCard, { fields }));
+				} catch (err) {
+					mutation.fail(err);
+				}
+			};
+			run();
+		}, []);
+		return React.createElement(MutationResult, {
+			...mutationResultProps(mutation.state),
+			loadingLabel: "Creating API key...",
+			successMessage: "API key created"
+		});
+	};
+	const { waitUntilExit } = render(React.createElement(App));
+	await waitUntilExit();
+});
+apiKeysCommand.command("delete <id>").description("Delete an API key").option("--tty", "Force TTY mode").option("--no-tty", "Force non-TTY mode").option("--yes", "Skip confirmation").action(async (id, options) => {
+	const apiKey = await ensureAuth();
+	if (!apiKey) return;
+	const client = createCliClient(apiKey);
+	if (!isTTY(options)) {
+		try {
+			await client.apiKeys.delete(id);
+			console.log(chalk.green("API key deleted"));
+		} catch (error) {
+			const message = error instanceof Error ? error.message : "Unknown error";
+			console.error(chalk.red("Failed to delete API key"));
+			console.error(chalk.red(message));
+			process.exit(1);
+		}
+		return;
+	}
+	if (options.yes) {
+		const App = () => {
+			const mutation = useMutationState();
+			useEffect(() => {
+				const run = async () => {
+					try {
+						await client.apiKeys.delete(id);
+						mutation.succeed();
+					} catch (err) {
+						mutation.fail(err);
+					}
+				};
+				run();
+			}, []);
+			return React.createElement(MutationResult, {
+				...mutationResultProps(mutation.state),
+				loadingLabel: "Deleting API key...",
+				successMessage: "API key deleted"
+			});
+		};
+		const { waitUntilExit } = render(React.createElement(App));
+		await waitUntilExit();
+		return;
+	}
+	if (!await new Promise((resolve) => {
+		const { unmount } = render(React.createElement(ConfirmPrompt, {
+			message: `Delete API key ${id}?`,
+			defaultValue: false,
+			onConfirm: (result) => {
+				resolve(result);
+				unmount();
+			}
+		}));
+	})) return;
+	const DeleteApp = () => {
+		const mutation = useMutationState();
+		useEffect(() => {
+			const run = async () => {
+				try {
+					await client.apiKeys.delete(id);
+					mutation.succeed();
+				} catch (err) {
+					mutation.fail(err);
+				}
+			};
+			run();
+		}, []);
+		return React.createElement(MutationResult, {
+			...mutationResultProps(mutation.state),
+			loadingLabel: "Deleting API key...",
+			successMessage: "API key deleted"
+		});
+	};
+	const { waitUntilExit } = render(React.createElement(DeleteApp));
+	await waitUntilExit();
+});
+apiKeysCommand.command("regenerate <id>").description("Regenerate an API key").option("--json", "Output as JSON").option("--tty", "Force TTY mode").option("--no-tty", "Force non-TTY mode").action(async (id, options) => {
+	const apiKey = await ensureAuth();
+	if (!apiKey) return;
+	const client = createCliClient(apiKey);
+	if (!isTTY(options) || options.json) {
+		try {
+			const data = await client.post(`/api-keys/${id}/regenerate`);
+			if (options.json) printJson(data);
+			else {
+				console.log(chalk.green("API key regenerated"));
+				if (data.key) {
+					console.log(`  New Key: ${chalk.yellow(data.key)}`);
+					console.log(chalk.gray("  Save this key - it will not be shown again"));
+				}
+			}
+		} catch (error) {
+			const message = error instanceof Error ? error.message : "Unknown error";
+			console.error(chalk.red("Failed to regenerate API key"));
+			console.error(chalk.red(message));
+			process.exit(1);
+		}
+		return;
+	}
+	const App = () => {
+		const mutation = useMutationState();
+		useEffect(() => {
+			const run = async () => {
+				try {
+					const data = await client.post(`/api-keys/${id}/regenerate`);
+					mutation.succeed(data.key ? React.createElement(EntityCard, { fields: [{
+						label: "New Key",
+						value: data.key,
+						color: "yellow"
+					}, {
+						label: "Note",
+						value: "Save this key - it will not be shown again"
+					}] }) : void 0);
+				} catch (err) {
+					mutation.fail(err);
+				}
+			};
+			run();
+		}, []);
+		return React.createElement(MutationResult, {
+			...mutationResultProps(mutation.state),
+			loadingLabel: "Regenerating API key...",
+			successMessage: "API key regenerated"
+		});
+	};
+	const { waitUntilExit } = render(React.createElement(App));
+	await waitUntilExit();
+});
+apiKeysCommand.command("analytics").description("Show API key usage analytics").option("--key <id>", "Specific key ID (defaults to all keys)").option("--json", "Output as JSON").option("--tty", "Force TTY mode").option("--no-tty", "Force non-TTY mode").action(async (options) => {
+	const apiKey = await ensureAuth();
+	if (!apiKey) return;
+	const client = createCliClient(apiKey);
+	if (!isTTY(options) || options.json) {
+		try {
+			const path = options.key ? `/api-keys/${options.key}/analytics` : "/api-keys/analytics";
+			const data = await client.get(path);
+			printJson(data);
+		} catch (error) {
+			const message = error instanceof Error ? error.message : "Unknown error";
+			console.error(chalk.red("Failed to fetch analytics"));
+			console.error(chalk.red(message));
+			process.exit(1);
+		}
+		return;
+	}
+	const App = () => {
+		const mutation = useMutationState();
+		useEffect(() => {
+			const run = async () => {
+				try {
+					const path = options.key ? `/api-keys/${options.key}/analytics` : "/api-keys/analytics";
+					const data = await client.get(path);
+					printJson(data);
+					mutation.succeed();
+				} catch (err) {
+					mutation.fail(err);
+				}
+			};
+			run();
+		}, []);
+		return React.createElement(MutationResult, {
+			...mutationResultProps(mutation.state),
+			loadingLabel: "Fetching analytics...",
+			successMessage: "Analytics"
+		});
+	};
+	const { waitUntilExit } = render(React.createElement(App));
+	await waitUntilExit();
+});
+registerApiKeyRequestCommands(apiKeysCommand);
+export { apiKeysCommand };
+