@oya-ai/cli 1.0.110 → 1.0.111

package/dist/index.js

@@ -1,26 +1,127 @@
 #!/usr/bin/env node
 
 // src/args.ts
-function parse(argv) {
-  const [command2 = "help", ...rest] = argv;
-  const args2 = [];
-  const flags2 = {};
+import { readFileSync } from "fs";
+
+// src/errors.ts
+var CliError = class extends Error {
+  /** usage, invalid_json, unreachable, no_api_key, no_browser, partial_failure, and the like. */
+  code;
+  /** A second line with the next step, when there is one. */
+  hint;
+  /** Already printed by the command (a partial failure's own lines), so not printed again. */
+  shown;
+  /** Records the message, code, hint and whether it was shown. */
+  constructor(message, code, { hint: hint2, shown: shown2 = false } = {}) {
+    super(message);
+    this.name = "CliError";
+    this.code = code;
+    this.hint = hint2;
+    this.shown = shown2;
+  }
+};
+var usage = (message, hint2) => new CliError(message, "usage", { hint: hint2 });
+var invalidJson = (message, hint2) => new CliError(message, "invalid_json", { hint: hint2 });
+
+// src/args.ts
+var SWITCHES = /* @__PURE__ */ new Set([
+  "all",
+  "debug",
+  "dry-run",
+  "force",
+  "governed",
+  "help",
+  "json",
+  "live",
+  "preview",
+  "replace",
+  "version"
+]);
+var VALUE_FLAGS = {
+  after: "--after 120",
+  "budget-usd": "--budget-usd 5",
+  config: "--config oya-install.json",
+  format: "--format playwright",
+  geo: "--geo us",
+  id: "--id oya-k3f9",
+  "idempotency-key": "--idempotency-key checkout-42",
+  key: "--key oya_...",
+  label: "--label ci",
+  locale: "--locale en-US",
+  max: "--max 3",
+  name: "--name shopper",
+  out: "--out cookies.json",
+  persona: "--persona auto",
+  platform: "--platform MacIntel",
+  policy: `--policy '{"allowedHosts":["example.com"]}'`,
+  priority: "--priority normal",
+  provider: "--provider cdp",
+  "queue-ms": "--queue-ms 30000",
+  role: "--role operator",
+  tz: "--tz Europe/Berlin",
+  url: "--url http://127.0.0.1:3100",
+  "ws-url": "--ws-url ws://127.0.0.1:9222"
+};
+function parse(argv2) {
+  const [command = "help", ...rest] = argv2;
+  const args = [];
+  const flags = {};
   for (let i = 0; i < rest.length; i++) {
-    if (!rest[i].startsWith("--")) args2.push(rest[i]);
-    else if (takeFlag(rest[i].slice("--".length), rest[i + 1], flags2)) i++;
+    if (!rest[i].startsWith("--")) args.push(rest[i]);
+    else if (takeFlag(rest[i].slice("--".length), rest[i + 1], flags)) i++;
+  }
+  return { command, args, flags };
+}
+function takeFlag(token2, next, flags) {
+  const [name, inline] = splitOnce(token2);
+  if (SWITCHES.has(name) && inline !== void 0) throw usage(`--${name} takes no value.`);
+  flags[name] = SWITCHES.has(name) || valueOf(name, inline, next);
+  return !SWITCHES.has(name) && inline === void 0;
+}
+function valueOf(name, inline, next) {
+  if (!Object.hasOwn(VALUE_FLAGS, name)) throw usage(`Unknown flag --${name}. Run oya help for the flags.`);
+  if (inline !== void 0) return inline;
+  if (next === void 0 || next.startsWith("--"))
+    throw usage(`--${name} needs a value, such as ${VALUE_FLAGS[name]}.`);
+  return next;
+}
+function splitOnce(token2) {
+  const at = token2.indexOf("=");
+  return at < 0 ? [token2, void 0] : [token2.slice(0, at), token2.slice(at + 1)];
+}
+var flagStr = (flags, name) => typeof flags[name] === "string" ? flags[name] : void 0;
+function flagNum(flags, name) {
+  const raw = flagStr(flags, name);
+  if (raw === void 0) return void 0;
+  if (raw.trim() === "" || !Number.isFinite(Number(raw))) throw usage(`--${name} must be a number, not "${raw}".`);
+  return Number(raw);
+}
+function flagCount(flags, name, { allowNone = false } = {}) {
+  const raw = flagStr(flags, name);
+  if (raw === void 0) return void 0;
+  if (allowNone && raw === "none") return null;
+  if (/^[1-9]\d*$/.test(raw)) return Number(raw);
+  throw usage(`--${name} must be a whole number of 1 or more${allowNone ? ", or none" : ""}, not "${raw}".`);
+}
+function parseJson(text, subject, hint2, verb = "is") {
+  try {
+    return JSON.parse(text);
+  } catch (err) {
+    throw invalidJson(`${subject} ${verb} not valid JSON: ${err.message}.`, hint2);
   }
-  return { command: command2, args: args2, flags: flags2 };
 }
-function takeFlag(name, next, flags2) {
-  const bare = next === void 0 || next.startsWith("--");
-  flags2[name] = bare ? true : next;
-  return !bare;
+function readJsonFile(file) {
+  let text;
+  try {
+    text = readFileSync(file, "utf8");
+  } catch (err) {
+    throw usage(`${file} could not be read: ${err.code ?? err.message}.`);
+  }
+  return parseJson(text, file);
 }
-var flagStr = (flags2, name) => typeof flags2[name] === "string" ? flags2[name] : void 0;
-var flagNum = (flags2, name) => flagStr(flags2, name) === void 0 ? void 0 : Number(flagStr(flags2, name));
 
 // src/install.ts
-import { readFileSync as readFileSync2, writeFileSync as writeFileSync3 } from "fs";
+import { writeFileSync as writeFileSync3 } from "fs";
 import { join as join5 } from "path";
 
 // src/prompt/style.ts
@@ -78,9 +179,9 @@ function steps(total) {
 }
 function step(title, hint2) {
   counter.number += 1;
-  const shown = counter.total ? style.grey(`${counter.number}/${counter.total}`) : "";
+  const shown2 = counter.total ? style.grey(`${counter.number}/${counter.total}`) : "";
   stdout2.write(`
-${style.cyan("\u25C6")} ${style.bold(title)} ${shown}
+${style.cyan("\u25C6")} ${style.bold(title)} ${shown2}
 `);
   if (hint2) stdout2.write(`${style.grey("  " + hint2)}
 `);
@@ -132,6 +233,11 @@ var masked = false;
 var pending = [];
 var waiter = null;
 var ended = false;
+var linesRead = 0;
+function readLine(line) {
+  linesRead++;
+  deliver(line);
+}
 function deliver(line) {
   if (waiter) {
     const w = waiter;
@@ -153,7 +259,7 @@ function maskEcho(line) {
 function iface() {
   if (rl) return rl;
   rl = createInterface({ input: stdin, output: stdout3, terminal: !!stdin.isTTY });
-  rl.on("line", deliver);
+  rl.on("line", readLine);
   rl.on("close", close);
   maskEcho(rl);
   return rl;
@@ -170,6 +276,9 @@ function nextLine() {
 function setMasked(on) {
   masked = on;
 }
+function answered() {
+  return !!stdin.isTTY || linesRead > 0;
+}
 function inputExhausted() {
   return ended && !pending.length;
 }
@@ -401,27 +510,27 @@ var Status = {
 };
 
 // src/install/shell.ts
-function settle(cmd, args2, resolve, reject) {
-  return (code) => code === 0 ? resolve() : reject(new Error(`${cmd} ${args2.join(" ")} exited ${code}`));
+function settle(cmd, args, resolve, reject) {
+  return (code) => code === 0 ? resolve() : reject(new Error(`${cmd} ${args.join(" ")} exited ${code}`));
 }
-function run(cmd, args2, opts = { cwd: process.cwd() }) {
+function run(cmd, args, opts = { cwd: process.cwd() }) {
   return new Promise((resolve, reject) => {
-    const child = spawn(cmd, args2, { cwd: opts.cwd, stdio: opts.quiet ? "ignore" : "inherit" });
+    const child = spawn(cmd, args, { cwd: opts.cwd, stdio: opts.quiet ? "ignore" : "inherit" });
     child.on("error", reject);
-    child.on("close", settle(cmd, args2, resolve, reject));
+    child.on("close", settle(cmd, args, resolve, reject));
   });
 }
-function pipeTo(cmd, args2, stdin4, cwd) {
+function pipeTo(cmd, args, stdin4, cwd) {
   return new Promise((resolve, reject) => {
-    const child = spawn(cmd, args2, { cwd, stdio: ["pipe", "inherit", "inherit"] });
+    const child = spawn(cmd, args, { cwd, stdio: ["pipe", "inherit", "inherit"] });
     child.on("error", reject);
-    child.on("close", settle(cmd, args2, resolve, reject));
+    child.on("close", settle(cmd, args, resolve, reject));
     child.stdin.end(stdin4);
   });
 }
-async function capture(cmd, args2, cwd = process.cwd()) {
+async function capture(cmd, args, cwd = process.cwd()) {
   return new Promise((resolve) => {
-    const child = spawn(cmd, args2, { cwd, stdio: ["ignore", "pipe", "ignore"] });
+    const child = spawn(cmd, args, { cwd, stdio: ["ignore", "pipe", "ignore"] });
     const out2 = [];
     child.stdout.on("data", (d) => out2.push(String(d)));
     child.on("error", () => resolve(null));
@@ -429,8 +538,8 @@ async function capture(cmd, args2, cwd = process.cwd()) {
   });
 }
 var has = async (cmd) => await capture(cmd, ["--version"]) !== null;
-function atLeast(version, major, minor) {
-  const m = /(\d+)\.(\d+)/.exec(version || "");
+function atLeast(version2, major, minor) {
+  const m = /(\d+)\.(\d+)/.exec(version2 || "");
   if (!m) return false;
   return Number(m[1]) > major || Number(m[1]) === major && Number(m[2]) >= minor;
 }
@@ -459,14 +568,19 @@ function findRepoRoot(from = process.cwd()) {
   }
   return null;
 }
-async function locateRepo() {
+var REPO_URL = "https://github.com/OyadotAI/oya-browser.git";
+async function locateRepo(dryRun = false) {
   const found = findRepoRoot();
   if (found) return found;
   console.log("\nThis does not look like an oya-browser checkout.");
   const where = await ask("Clone it to:", join(process.cwd(), "oya-browser"));
+  if (dryRun) return wouldClone(where);
   if (existsSync(where)) throw new Error(`${where} already exists`);
-  const repo = "https://github.com/OyadotAI/oya-browser.git";
-  await run("git", ["clone", "--depth", "1", repo, where], { cwd: process.cwd() });
+  await run("git", ["clone", "--depth", "1", REPO_URL, where], { cwd: process.cwd() });
+  return where;
+}
+function wouldClone(where) {
+  console.log(`--dry-run: would clone ${REPO_URL} to ${where}`);
   return where;
 }
 
@@ -759,11 +873,11 @@ function composeCheck(compose) {
   return { ok, label: "docker compose \u2265 2.24", detail: compose || "not found", fatal: true };
 }
 async function dockerChecks() {
-  const version = await capture("docker", ["--version"]);
+  const version2 = await capture("docker", ["--version"]);
   const daemon = await capture("docker", ["info", "--format", "{{.ID}}"]);
   const compose = await capture("docker", ["compose", "version", "--short"]);
   return [
-    { ok: !!version, label: "docker", detail: version || "not found", fatal: true },
+    { ok: !!version2, label: "docker", detail: version2 || "not found", fatal: true },
     { ok: !!daemon, label: "docker daemon reachable", detail: daemon ? "ok" : "not running", fatal: true },
     composeCheck(compose)
   ];
@@ -773,10 +887,10 @@ function nodeCheck() {
   return { ok, label: "node \u2265 22.13 (node:sqlite)", detail: process.versions.node, fatal: true };
 }
 async function kubeChecks() {
-  const version = await capture("kubectl", ["version", "--client=true", "-o", "json"]);
+  const version2 = await capture("kubectl", ["version", "--client=true", "-o", "json"]);
   const cluster = await capture("kubectl", ["get", "namespace", "kube-system", "-o", "name"]);
   return [
-    { ok: !!version, label: "kubectl", detail: version ? "ok" : "not found", fatal: true },
+    { ok: !!version2, label: "kubectl", detail: version2 ? "ok" : "not found", fatal: true },
     { ok: !!cluster, label: "cluster reachable", detail: cluster || "kubectl cannot reach a cluster", fatal: true }
   ];
 }
@@ -811,7 +925,7 @@ async function preflight(root, a) {
 }
 
 // src/install/env-file.ts
-import { existsSync as existsSync3, readFileSync, writeFileSync, chmodSync } from "fs";
+import { existsSync as existsSync3, readFileSync as readFileSync2, writeFileSync, chmodSync } from "fs";
 var SECRET_KEYS = /* @__PURE__ */ new Set([
   "OYA_PROFILE_SECRET",
   "OYA_OPERATOR_TOKEN",
@@ -864,7 +978,7 @@ var SECTIONS = [
 function readEnv(path) {
   if (!existsSync3(path)) return {};
   const out2 = {};
-  for (const line of readFileSync(path, "utf8").split("\n")) {
+  for (const line of readFileSync2(path, "utf8").split("\n")) {
     const m = /^([A-Z0-9_]+)=(.*)$/.exec(line.trim());
     if (m) out2[m[1]] = m[2];
   }
@@ -1191,9 +1305,9 @@ function printDone(publicUrl, apiKey) {
 
 // src/install.ts
 var ANSWERS_FILE = "oya-install.json";
-async function gather(configPath2) {
-  const root = await locateRepo();
-  const preset = configPath2 ? JSON.parse(readFileSync2(configPath2, "utf8")) : {};
+async function gather(configPath2, dryRun) {
+  const root = await locateRepo(dryRun);
+  const preset = configPath2 ? readJsonFile(configPath2) : {};
   banner("Oya Browser, self-host install", root);
   if (configPath2) note(`replaying ${configPath2}`);
   steps(configPath2 ? 0 : INTERVIEW_STEPS);
@@ -1219,8 +1333,8 @@ async function guardKek(existing, answers, root, dryRun) {
   const reused = await resolveKekConflict(volume, root);
   if (reused) existing.OYA_PROFILE_SECRET = reused;
 }
-async function plan(flags2, dryRun) {
-  const interviewed = await gather(typeof flags2.config === "string" ? flags2.config : null);
+async function plan(flags, dryRun) {
+  const interviewed = await gather(typeof flags.config === "string" ? flags.config : null, dryRun);
   const { root, answers, secrets } = interviewed;
   await checkMachine(root, answers, dryRun);
   warnLocalDatabase(answers, secrets.DATABASE_URL);
@@ -1252,9 +1366,9 @@ async function apply2(p) {
   await waitReady(p.answers.publicUrl);
   printDone(p.answers.publicUrl, p.env.apiKey);
 }
-async function cmdInstall(flags2) {
-  const dryRun = flags2["dry-run"] === true;
-  const p = await plan(flags2, dryRun);
+async function cmdInstall(flags) {
+  const dryRun = flags["dry-run"] === true;
+  const p = await plan(flags, dryRun);
   printPlan(p.answers, p.envPath);
   if (dryRun) return printDryRun(p.env.values);
   await apply2(p);
@@ -1267,6 +1381,17 @@ import { join as join6, dirname as dirname2 } from "path";
 
 // src/constants.ts
 var ARGV_SKIP = 2;
+var KEY_TAIL = 4;
+var MIN_KEY_FOR_TAIL = 12;
+var LOGIN_TIMEOUT_MS = 6e4;
+var ExitCode = {
+  /** Done. */
+  DONE: 0,
+  /** The request failed: the server or the browser refused it, or no answer came. */
+  FAILED: 1,
+  /** The command could not be run as typed; nothing was sent. */
+  USAGE: 2
+};
 var JSON_INDENT2 = 2;
 var DEFAULT_BASE_URL = "https://oyabrowser.com";
 var CONFIG_FILE_MODE = 384;
@@ -1291,6 +1416,10 @@ var PERSONA_NAME_WIDTH = 20;
 var Status2 = {
   /** The API key was rejected. */
   UNAUTHORIZED: 401,
+  /** A role refusal, or the auth layer's answer for an unknown key. */
+  FORBIDDEN: 403,
+  /** An endpoint another browser already holds. */
+  CONFLICT: 409,
   /** A quota or a persona concurrency cap. */
   TOO_MANY_REQUESTS: 429
 };
@@ -1311,65 +1440,65 @@ function save(values) {
   chmodSync2(FILE, CONFIG_FILE_MODE);
 }
 var configPath = FILE;
-function resolved() {
-  const saved = load();
-  return {
-    apiKey: process.env.OYA_API_KEY || saved.apiKey || "",
-    baseUrl: (process.env.OYA_BASE_URL || saved.baseUrl || DEFAULT_BASE_URL).replace(/\/+$/, "")
-  };
+function first(flag, env2, saved, names) {
+  if (flag) return { value: flag, from: names[0] };
+  if (env2) return { value: env2, from: names[1] };
+  return saved ? { value: saved, from: names[2] } : null;
 }
-
-// src/commands/login.ts
-async function postJson(url, body, token2) {
-  const headers = { ...token2 ? { Authorization: `Bearer ${token2}` } : {}, "Content-Type": "application/json" };
-  const res = await fetch(url, { method: "POST", headers, body: JSON.stringify(body) });
-  return { ok: res.ok, body: await res.json() };
-}
-async function mintKey(baseUrl) {
-  const email = await ask("Email:");
-  const password = await askSecret("Password:");
-  const session2 = await postJson(`${baseUrl}/api/auth/login`, { email, password });
-  if (!session2.ok || !session2.body.access_token) throw new Error(session2.body.error || "Sign-in failed");
-  const minted = await postJson(`${baseUrl}/api/auth/keys`, { label: "CLI" }, session2.body.access_token);
-  if (!minted.ok || !minted.body.key) throw new Error(minted.body.error || "Could not create an API key");
-  console.log('  Created a new API key labelled "CLI".');
-  return minted.body.key;
-}
-function chooseMethod() {
-  return choose("How do you want to authenticate?", [
-    { id: "paste", label: "Paste an API key", note: "from the dashboard, or a self-hosted key" },
-    { id: "password", label: "Sign in with email and password", note: "mints a new key for this machine" }
-  ]);
-}
-async function obtainKey(flags2, baseUrl) {
-  const given = flagStr(flags2, "key") || "";
-  if (given) return given;
-  const how = await chooseMethod();
-  if (how === "paste") return askSecret("API key:");
-  return mintKey(baseUrl);
-}
-async function verifyKey(baseUrl, apiKey) {
-  const check2 = await fetch(`${baseUrl}/api/config`, { headers: { Authorization: `Bearer ${apiKey}` } });
-  if (!check2.ok) throw new Error(`That key was rejected by ${baseUrl} (${check2.status})`);
-}
-async function loginUrl(flags2) {
-  const current = resolved().baseUrl;
-  const url = flagStr(flags2, "url") || (flagStr(flags2, "key") ? current : await ask("Control plane URL:", current));
-  return url.replace(/\/+$/, "");
-}
-async function cmdLogin(flags2) {
-  const baseUrl = await loginUrl(flags2);
-  const apiKey = await obtainKey(flags2, baseUrl);
-  if (!apiKey) throw new Error("No API key given");
-  await verifyKey(baseUrl, apiKey);
-  save({ apiKey, baseUrl });
-  console.log(`
-\u2705 Signed in to ${baseUrl}. Saved to ${configPath}`);
-  console.log("   Scripts using @oya-ai/browser read this file too, so `new Oya()` needs no environment.");
-  console.log("   Next: `oya init` to pick your model and browser provider.");
+function origin({ apiKey, baseUrl } = {}) {
+  const saved = load();
+  const key = first(apiKey, process.env.OYA_API_KEY, saved.apiKey, KEY_SOURCES);
+  const url = first(baseUrl, process.env.OYA_BASE_URL, saved.baseUrl, URL_SOURCES);
+  const address = (url?.value ?? DEFAULT_BASE_URL).replace(/\/+$/, "");
+  const found = { apiKey: key?.value ?? "", apiKeyFrom: key?.from ?? "none", baseUrl: address };
+  return { ...found, baseUrlFrom: url?.from ?? "default", savedKey: !!saved.apiKey };
+}
+var KEY_SOURCES = ["--key", "OYA_API_KEY", "saved"];
+var URL_SOURCES = ["--url", "OYA_BASE_URL", "saved"];
+function resolved() {
+  const { apiKey, baseUrl } = origin();
+  return { apiKey, baseUrl };
 }
 
 // ../sdk/dist/index.js
+var DEFAULT_BASE_URL2 = "https://oyabrowser.com";
+var DEFAULT_TIMEOUT_MS = 6e4;
+var START_TIMEOUT_MS = 12e4;
+var READY_TIMEOUT_MS2 = 12e4;
+var READY_POLL_MS2 = 2e3;
+var NAVIGATE_TIMEOUT_MS = 12e4;
+var CHALLENGE_TIMEOUT_MS = 18e4;
+var AGENT_TIMEOUT_MS = 6e5;
+var PLAYBOOK_TIMEOUT_MS = 12e4;
+var STOP_TIMEOUT_MS = 6e4;
+var WAIT_FOR_DEFAULT_MS = 3e4;
+var WAIT_FOR_GRACE_MS = 5e3;
+var AIMED_SCROLL_AMOUNT = 500;
+var RUN_POLL_MS = 2e3;
+var MAX_RUN_POLL_ERRORS = 5;
+var BYTES_PER_MB = 1048576;
+var MAX_FILE_MB = 10;
+var MS_PER_SECOND = 1e3;
+var LATIN1_MAX = 255;
+var SPACE = 32;
+var TAB = 9;
+var DEL = 127;
+var HEX = 16;
+var CODE_POINT_DIGITS = 4;
+var Status3 = {
+  /** The caller passed something unusable, such as a non-numeric element id. */
+  BAD_REQUEST: 400,
+  /** The server does not know that session. */
+  NOT_FOUND: 404,
+  /** The browser is in a state that needs attention first. */
+  CONFLICT: 409,
+  /** A browser command ran and failed. */
+  UNPROCESSABLE: 422,
+  /** A run failed without saying why. */
+  SERVER_ERROR: 500,
+  /** A browser did not come up in time. */
+  GATEWAY_TIMEOUT: 504
+};
 var OyaError = class extends Error {
   /** The HTTP status, or the SDK's own status for errors it raises itself. */
   status;
@@ -1383,6 +1512,10 @@ var OyaError = class extends Error {
     this.body = body;
   }
 };
+function refusal(message, field, suggestion) {
+  const body = { error: message, code: "invalid_request", field, ...suggestion ? { suggestion } : {} };
+  return new OyaError(message, Status3.BAD_REQUEST, body);
+}
 var node = () => globalThis.process;
 function builtin(name) {
   const get = node()?.getBuiltinModule;
@@ -1403,54 +1536,25 @@ function savedConfig() {
     return {};
   }
 }
-var DEFAULT_BASE_URL2 = "https://oyabrowser.com";
-var DEFAULT_TIMEOUT_MS = 6e4;
-var START_TIMEOUT_MS = 12e4;
-var READY_TIMEOUT_MS2 = 12e4;
-var READY_POLL_MS2 = 2e3;
-var NAVIGATE_TIMEOUT_MS = 12e4;
-var CHALLENGE_TIMEOUT_MS = 18e4;
-var AGENT_TIMEOUT_MS = 6e5;
-var PLAYBOOK_TIMEOUT_MS = 12e4;
-var STOP_TIMEOUT_MS = 6e4;
-var WAIT_FOR_DEFAULT_MS = 3e4;
-var WAIT_FOR_GRACE_MS = 5e3;
-var AIMED_SCROLL_AMOUNT = 500;
-var RUN_POLL_MS = 2e3;
-var MAX_RUN_POLL_ERRORS = 5;
-var BYTES_PER_MB = 1048576;
-var MAX_FILE_MB = 10;
-var MS_PER_SECOND = 1e3;
-var Status3 = {
-  /** The caller passed something unusable, such as a non-numeric element id. */
-  BAD_REQUEST: 400,
-  /** The server does not know that session. */
-  NOT_FOUND: 404,
-  /** The browser is in a state that needs attention first. */
-  CONFLICT: 409,
-  /** A browser command ran and failed. */
-  UNPROCESSABLE: 422,
-  /** A run failed without saying why. */
-  SERVER_ERROR: 500,
-  /** A browser did not come up in time. */
-  GATEWAY_TIMEOUT: 504
-};
+var OPTIONS_ORIGIN = { apiKeyFrom: "the apiKey option", baseUrlFrom: "the baseUrl option", savedKey: false };
 var Http = class {
-  /** Stores where to call, with which key, how long to wait and which fetch to use. */
-  constructor(baseUrl, apiKey, timeoutMs, fetchImpl) {
+  /** Stores where to call, with which key, how long to wait, which fetch to use, and where the key and address came from. */
+  constructor(baseUrl, apiKey, timeoutMs, fetchImpl, origin3 = OPTIONS_ORIGIN) {
     this.baseUrl = baseUrl;
     this.apiKey = apiKey;
     this.timeoutMs = timeoutMs;
     this.fetchImpl = fetchImpl;
+    this.origin = origin3;
   }
   baseUrl;
   apiKey;
   timeoutMs;
   fetchImpl;
+  origin;
   /** Sends one request and returns the parsed answer, or throws an OyaError when it failed. */
   async request(method, path, body, timeoutMs = this.timeoutMs, headers = {}) {
     const res = await this.send(`${this.baseUrl}${path}`, this.init(method, body, timeoutMs, headers), timeoutMs);
-    return readAnswer2(res, `${method} ${path}`, this.baseUrl);
+    return readAnswer2(res, `${method} ${path}`, this);
   }
   /** The fetch options for one call, with this client's key on them. */
   init(method, body, timeoutMs, headers) {
@@ -1465,23 +1569,34 @@ var Http = class {
     try {
       return await this.fetchImpl(url, init);
     } catch (err) {
-      throw new OyaError(unreachable(this.baseUrl, timeoutMs, err), 0, { error: String(err?.message) });
+      throw noAnswer(this, timeoutMs, err);
     }
   }
 };
-function unreachable(baseUrl, timeoutMs, err) {
-  const cause = err?.name === "TimeoutError" || /abort/i.test(String(err?.message));
-  if (cause) return `No answer from ${baseUrl} within ${timeoutMs}ms. Is it reachable, and is the call this slow?`;
-  return `Could not reach ${baseUrl}. Is the server running, and is OYA_BASE_URL right?`;
+var timedOut = (err) => err?.name === "TimeoutError" || /abort/i.test(String(err?.message));
+function causeOf(err) {
+  const cause = err?.cause;
+  return cause?.code ?? cause?.errors?.[0]?.code;
+}
+function noAnswer(http, timeoutMs, err) {
+  const code = timedOut(err) ? "timeout" : "unreachable";
+  const body = { error: String(err?.message), code, ...causeOf(err) ? { cause: causeOf(err) } : {} };
+  return new OyaError(unreachable(http, timeoutMs, code), 0, body);
+}
+function unreachable({ baseUrl, origin: origin3 }, timeoutMs, code) {
+  if (code === "timeout")
+    return `No answer from ${baseUrl} within ${timeoutMs}ms. Is it reachable, and is the call this slow?`;
+  if (origin3.baseUrlFrom === "default") return `Could not reach ${baseUrl}. Check your connection.`;
+  return `Could not reach ${baseUrl}. Is the server running, and is ${origin3.baseUrlFrom} right?`;
 }
 function requestInit(method, body, timeoutMs, headers) {
   const json = body === void 0 ? {} : { "Content-Type": "application/json" };
   const payload = body === void 0 ? void 0 : JSON.stringify(body);
   return { method, headers: { ...headers, ...json }, body: payload, signal: AbortSignal.timeout(timeoutMs) };
 }
-async function readAnswer2(res, call2, baseUrl) {
+async function readAnswer2(res, call2, http) {
   const payload = parseBody(await res.text());
-  if (!res.ok) throw failure(call2, res.status, payload, baseUrl);
+  if (!res.ok) throw failure(call2, res.status, payload, http);
   return payload;
 }
 function parseBody(text) {
@@ -1491,22 +1606,74 @@ function parseBody(text) {
     return text;
   }
 }
-function failure(call2, status, payload, baseUrl) {
-  let message = payload?.error || `${call2} failed (${status})`;
-  if (message === "Invalid API key") {
-    message += ` for ${baseUrl}. Check OYA_API_KEY: a value exported in your shell beats .env.`;
-  }
-  return new OyaError(message, status, payload);
+function failure(call2, status, payload, http) {
+  const message = payload?.error || `${call2} failed (${status})`;
+  return new OyaError(message === "Invalid API key" ? invalidKey(http) : message, status, payload);
+}
+function invalidKey({ baseUrl, origin: origin3 }) {
+  const overrides = origin3.apiKeyFrom === "OYA_API_KEY" && origin3.savedKey;
+  const rest = overrides ? ", which overrides the one saved in ~/.oya/config.json" : "";
+  return `Invalid API key for ${baseUrl}. The key came from ${origin3.apiKeyFrom}${rest}.`;
 }
 var env = (name) => globalThis.process?.env?.[name];
+function firstOf(option, name, saved, optionName) {
+  if (option) return { value: option, from: `the ${optionName} option` };
+  if (env(name)) return { value: env(name), from: name };
+  return { value: saved, from: "~/.oya/config.json" };
+}
+function addressOf(options, saved) {
+  const found = firstOf(options.baseUrl, "OYA_BASE_URL", saved, "baseUrl");
+  return found.value ? found : { value: DEFAULT_BASE_URL2, from: "default" };
+}
+function keyOf(options, saved) {
+  const found = firstOf(options.apiKey, "OYA_API_KEY", saved, "apiKey");
+  if (!found.value) throw new Error("No API key. Pass { apiKey }, set OYA_API_KEY, or run `npx @oya-ai/cli login`.");
+  return { ...found, value: headerSafe(found.value, "apiKey", "Copy the key again.") };
+}
 function createHttp(options) {
   const saved = savedConfig();
-  const apiKey = options.apiKey || env("OYA_API_KEY") || saved.apiKey;
-  if (!apiKey) throw new Error("No API key. Pass { apiKey }, set OYA_API_KEY, or run `npx @oya-ai/cli login`.");
-  const baseUrl = (options.baseUrl || env("OYA_BASE_URL") || saved.baseUrl || DEFAULT_BASE_URL2).replace(/\/+$/, "");
+  const key = keyOf(options, saved.apiKey);
+  const address = addressOf(options, saved.baseUrl);
   const fetchImpl = options.fetch || globalThis.fetch;
   if (!fetchImpl) throw new Error("No fetch available, pass { fetch } or use Node 18+.");
-  return new Http(baseUrl, apiKey, options.timeoutMs ?? DEFAULT_TIMEOUT_MS, fetchImpl.bind(globalThis));
+  const origin3 = { apiKeyFrom: key.from, baseUrlFrom: address.from, savedKey: !!saved.apiKey };
+  const timeout = options.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+  return new Http(webAddress(address), key.value, timeout, fetchImpl.bind(globalThis), origin3);
+}
+var LOCAL_HOST = /^(localhost|127\.)/i;
+function webAddress({ value, from }) {
+  const url = value.trim().replace(/\/+$/, "");
+  if (/^https?:\/\//i.test(url)) return url;
+  const name = from.startsWith("the ") ? "baseUrl" : from === "OYA_BASE_URL" ? from : `baseUrl in ${from}`;
+  const suggestion = suggestionFor(url);
+  const tryIt = suggestion ? ` Try ${suggestion}.` : "";
+  throw refusal(`${name} must start with http:// or https://, not "${url}".${tryIt}`, "baseUrl", suggestion);
+}
+function suggestionFor(url) {
+  if (/^[a-z][a-z0-9+.-]*:/i.test(url) && !/^[^:/]+:\d+(\/|$)/.test(url)) return void 0;
+  return `${LOCAL_HOST.test(url) ? "http" : "https"}://${url}`;
+}
+function notInAHeader(ch) {
+  const code = ch.codePointAt(0);
+  return code < SPACE && code !== TAB || code === DEL || code > LATIN1_MAX;
+}
+function headerSafe(value, field, ending) {
+  const trimmed = value.trim();
+  const chars = Array.from(trimmed);
+  const at = chars.findIndex(notInAHeader);
+  if (at < 0) return trimmed;
+  const leading = Array.from(value).length - Array.from(value.trimStart()).length;
+  const where = `position ${leading + at + 1} (${codePoint(chars[at])})`;
+  throw refusal(`${field} has a character HTTP headers cannot carry at ${where}. ${ending}`, field);
+}
+var codePoint = (ch) => `U+${ch.codePointAt(0).toString(HEX).toUpperCase().padStart(CODE_POINT_DIGITS, "0")}`;
+var shown = (value) => typeof value === "string" ? JSON.stringify(value) : String(value);
+function segment(value, field = "id") {
+  if (typeof value !== "string" || !value)
+    throw refusal(`${field} must be a non-empty string, not ${shown(value)}`, field);
+  if (value.includes("/") || value === "." || value === "..")
+    throw refusal(`${field} must be a single path segment (no "/" and not "." or ".."), not ${shown(value)}`, field);
+  return encodeURIComponent(value);
 }
 var sleep = (ms) => new Promise((r) => setTimeout(r, ms));
 async function call(fn) {
@@ -1739,7 +1906,7 @@ var Browser = class {
    * Play `'<name>:draft'` to try a draft before promoting it.
    */
   async play(name, data = {}, { autoHeal = true } = {}) {
-    const path = `/api/browsers/${this.id}/playbooks/${encodeURIComponent(name)}/play`;
+    const path = `/api/browsers/${this.id}/playbooks/${segment(name, "name")}/play`;
     return agentAnswer(
       await this.http.request("POST", path, { variables: data, autoHeal }, AGENT_TIMEOUT_MS)
     );
@@ -1790,7 +1957,7 @@ var Browser = class {
   }
   /** Revoke a link from `shareUrl()` before it expires, by the id it returned. */
   async revokeShare(id) {
-    await this.http.request("DELETE", `/api/control/credentials/${encodeURIComponent(id)}`);
+    await this.http.request("DELETE", `/api/control/credentials/${segment(id)}`);
   }
   /** Counters, health and the last 50 things this browser did. */
   status() {
@@ -1844,8 +2011,9 @@ function startBody(options) {
   const { profile, persona, provider, wsUrl, name, queueMs, priority, budgetUsd, governed, policy } = options;
   return { profile: profile || persona, provider, wsUrl, name, queueMs, priority, budgetUsd, governed, policy };
 }
+var idempotencyKeyOf = ({ idempotencyKey }) => idempotencyKey ? headerSafe(idempotencyKey, "idempotencyKey", 'Use letters, digits, "-" and "_".') : globalThis.crypto.randomUUID();
 async function start(http, wait, options) {
-  const headers = { "Idempotency-Key": options.idempotencyKey || globalThis.crypto.randomUUID() };
+  const headers = { "Idempotency-Key": idempotencyKeyOf(options) };
   const path = "/api/browsers/start";
   const started = await http().request("POST", path, startBody(options), START_TIMEOUT_MS, headers);
   if (started.status === "starting") {
@@ -1854,7 +2022,7 @@ async function start(http, wait, options) {
   }
   return new Browser(http(), started, options.captcha === "auto");
 }
-var fetchBrowser = (http, id) => http().request("GET", `/api/browsers/${encodeURIComponent(id)}`);
+var fetchBrowser = (http, id) => http().request("GET", `/api/browsers/${segment(id)}`);
 async function reattach(http, id) {
   const found = await fetchBrowser(http, id);
   return new Browser(http(), asStarted(found), false);
@@ -1866,67 +2034,77 @@ function asStarted(found) {
 var stopBrowsers = (http, ids) => http().request("POST", "/api/browsers/stop", ids === "all" ? { all: true } : { ids }, START_TIMEOUT_MS);
 var browserApi = (http, wait) => ({
   /** Start a browser and wait until it can take commands. */
-  start: (options = {}) => start(http, wait, options),
+  start: async (options = {}) => start(http, wait, options),
   /** Reattach to a browser that is already running. */
-  get: (id) => reattach(http, id),
+  get: async (id) => reattach(http, id),
   /** Every browser on this key. */
-  list: () => http().request("GET", "/api/browsers"),
+  list: async () => http().request("GET", "/api/browsers"),
   /** Stop some (`ids`) or every browser on this key. Each reports separately. */
-  stop: (ids) => stopBrowsers(http, ids),
+  stop: async (ids) => stopBrowsers(http, ids),
   /** Stop every browser on this key; returns how many stopped. */
   stopAll: async () => (await stopBrowsers(http, "all")).stopped
 });
-var session = (id, action = "") => `/api/control/sessions/${encodeURIComponent(id)}${action}`;
-var item = (kind, id) => `/api/control/${kind}/${encodeURIComponent(id)}`;
+var session = (id, action = "") => `/api/control/sessions/${segment(id)}${action}`;
+var item = (kind, id) => `/api/control/${kind}/${segment(id)}`;
 var sessionCalls = (http) => ({
   /** Settings, sessions and recent events at a glance. */
-  overview: () => http().request("GET", "/api/control"),
+  overview: async () => http().request("GET", "/api/control"),
   /** Every session, including disconnected and cleanup-pending ones. */
-  sessions: () => http().request("GET", "/api/control/sessions"),
+  sessions: async () => http().request("GET", "/api/control/sessions"),
   /** One session. */
-  session: (id) => http().request("GET", session(id)),
+  session: async (id) => http().request("GET", session(id)),
   /** Update limits, rate cards and retention. */
-  settings: (changes) => http().request("PATCH", "/api/control/project", changes)
+  settings: async (changes) => http().request("PATCH", "/api/control/project", changes)
 });
 var lifecycleCalls = (http) => ({
-  /** Cancel queued or provisioning work. */
-  cancel: (id) => http().request("POST", session(id, "/cancel"), {}),
+  /** Stop a session in any state; answers its final state. */
+  cancel: async (id) => http().request("POST", session(id, "/cancel"), {}),
   /** Stop a session; `force` stops despite a profile-save error, or reconciles. */
-  stop: (id, force = false) => http().request("POST", session(id, "/stop"), { force }),
+  stop: async (id, force = false) => http().request("POST", session(id, "/stop"), { force }),
   /** Acquire or release human control, or acknowledge the agent's resume. */
-  takeover: (id, action) => http().request("POST", session(id, "/control"), { action }),
+  takeover: async (id, action) => http().request("POST", session(id, "/control"), { action }),
   /** Send one input as the human holding the control lease. */
-  input: (id, action, params) => http().request("POST", session(id, "/input"), { action, params })
+  input: async (id, action, params) => http().request("POST", session(id, "/input"), { action, params })
 });
+function recoverBody(options) {
+  const { replace = false, wsUrl } = typeof options === "boolean" ? { replace: options } : options ?? {};
+  if (wsUrl && !replace)
+    throw refusal("wsUrl is only used with replace: true; recovering in place keeps the endpoint it had.", "wsUrl");
+  return wsUrl ? { replace, wsUrl } : { replace };
+}
 var recoveryCalls = (http) => ({
-  /** Explicitly recover a session, or replace it with a fresh one. */
-  recover: (id, replace = false) => http().request("POST", session(id, "/recover"), { replace }),
+  /**
+   * Explicitly recover a session, or replace it with a fresh one. A cdp
+   * session's replacement needs the Chrome it runs on: `{ replace: true, wsUrl }`.
+   * `recover(id, true)` still means replace.
+   */
+  recover: async (id, options = {}) => http().request("POST", session(id, "/recover"), recoverBody(options)),
   /** A single-use ticket for the live stream. */
-  ticket: (id) => http().request("POST", session(id, "/ticket"), {}),
+  ticket: async (id) => http().request("POST", session(id, "/ticket"), {}),
   /** Durable lifecycle events after a cursor. */
-  events: (after = 0) => http().request("GET", `/api/control/events?after=${after}`)
+  events: async (after = 0) => http().request("GET", `/api/control/events?after=${after}`)
 });
 var credentialCalls = (http) => ({
   /** Mint a service credential. Its token is returned this once. */
-  createCredential: (options) => http().request("POST", "/api/control/credentials", options),
+  createCredential: async (options) => http().request("POST", "/api/control/credentials", options),
   /** Revoke a service credential. */
-  revokeCredential: (id) => http().request("DELETE", item("credentials", id))
+  revokeCredential: async (id) => http().request("DELETE", item("credentials", id))
 });
 var memberCalls = (http) => ({
   /** The owner and every member. */
-  members: () => http().request("GET", "/api/control/members"),
+  members: async () => http().request("GET", "/api/control/members"),
   /** An invitation code for a new member. */
-  inviteMember: (role = "operator") => http().request("POST", "/api/control/members/invite", { role }),
+  inviteMember: async (role = "operator") => http().request("POST", "/api/control/members/invite", { role }),
   /** Remove a member. */
-  removeMember: (userId) => http().request("DELETE", item("members", userId))
+  removeMember: async (userId) => http().request("DELETE", item("members", userId))
 });
 var webhookCalls = (http) => ({
   /** Register a webhook; `types` limits which events it receives. */
-  createWebhook: (url, types = []) => http().request("POST", "/api/control/webhooks", { url, types }),
+  createWebhook: async (url, types = []) => http().request("POST", "/api/control/webhooks", { url, types }),
   /** Disable a webhook. */
-  removeWebhook: (id) => http().request("DELETE", item("webhooks", id)),
+  removeWebhook: async (id) => http().request("DELETE", item("webhooks", id)),
   /** Send a delivery again. */
-  replayDelivery: (id) => http().request("POST", `${item("deliveries", id)}/replay`, {})
+  replayDelivery: async (id) => http().request("POST", `${item("deliveries", id)}/replay`, {})
 });
 var controlApi = (http) => ({
   ...sessionCalls(http),
@@ -1936,7 +2114,7 @@ var controlApi = (http) => ({
   ...memberCalls(http),
   ...webhookCalls(http)
 });
-var playbook = (name) => `/api/playbooks/${encodeURIComponent(name)}`;
+var playbook = (name) => `/api/playbooks/${segment(name, "name")}`;
 var playbookApi = (http) => ({
   /** Every saved playbook, with any draft waiting on it. */
   list: async () => (await http().request("GET", "/api/playbooks")).playbooks,
@@ -1945,16 +2123,16 @@ var playbookApi = (http) => ({
     await http().request("DELETE", playbook(name));
   },
   /** Replace a playbook with the draft a healed replay saved. Try it first with `browser.play('<name>:draft')`. */
-  promote: (name) => http().request("POST", `${playbook(name)}/promote`, {})
+  promote: async (name) => http().request("POST", `${playbook(name)}/promote`, {})
 });
 var proxyApi = (http) => ({
   /** Every proxy this key can use, shared ones included. */
   list: async () => (await http().request("GET", "/api/proxies")).proxies,
   /** Add a proxy. Its credentials are never read back. */
-  create: (proxy) => http().request("POST", "/api/proxies", proxy),
+  create: async (proxy) => http().request("POST", "/api/proxies", proxy),
   /** Remove one of this key's proxies. */
   remove: async (id) => {
-    await http().request("DELETE", `/api/proxies/${encodeURIComponent(id)}`);
+    await http().request("DELETE", `/api/proxies/${segment(id)}`);
   },
   /** Dial each proxy and learn its real exit IP. Failing ones cool down and are skipped. */
   check: async () => (await http().request("POST", "/api/proxies/check", {})).results
@@ -1963,35 +2141,38 @@ var identityCalls = (http) => ({
   /** Every persona on this key. */
   list: async () => (await http().request("GET", "/api/personas")).personas,
   /** One persona. */
-  get: (id) => http().request("GET", `/api/personas/${id}`),
+  get: async (id) => http().request("GET", `/api/personas/${segment(id)}`),
   /**
    * Create an identity. The device, platform, timezone, locale, is chosen
    * here and fixed for its life; `preview()` shows what a choice produces.
    */
-  create: (options = {}) => http().request("POST", "/api/personas", options),
+  create: async (options = {}) => http().request("POST", "/api/personas", options),
   /** Name, concurrency cap and proxy hint. Never the device, clone for that. */
-  update: (id, changes) => http().request("PUT", `/api/personas/${id}`, changes),
+  update: async (id, changes) => http().request("PUT", `/api/personas/${segment(id)}`, changes),
   /** A new persona of the same kind of device: same choices, fresh identity, empty jar. */
-  clone: (id, options = {}) => http().request("POST", `/api/personas/${id}/clone`, options)
+  clone: async (id, options = {}) => http().request("POST", `/api/personas/${segment(id)}/clone`, options)
 });
 var deviceCalls = (http) => ({
   /** The fingerprint these choices would produce. Persists nothing. */
   preview: async (prefs = {}) => (await http().request("POST", "/api/personas/preview", { prefs })).fingerprint,
   /** Platforms, and the timezones and locales each may coherently claim. */
-  options: () => http().request("GET", "/api/personas/options"),
+  options: async () => http().request("GET", "/api/personas/options"),
   /** Pin the persona to one of your proxies, or `null` to let assignment happen at connect. */
-  pinProxy: (id, proxyId) => http().request("PUT", `/api/personas/${id}/proxy`, { proxyId }),
+  pinProxy: async (id, proxyId) => http().request("PUT", `/api/personas/${segment(id)}/proxy`, { proxyId }),
   /** Delete a persona. */
   remove: async (id) => {
-    await http().request("DELETE", `/api/personas/${id}`);
+    await http().request("DELETE", `/api/personas/${segment(id)}`);
   }
 });
 var mfaCalls = (http) => ({
   /** Store the second factor for this identity. Sealed at rest, never read back. */
-  setMfa: (id, config) => http().request("PUT", `/api/personas/${id}/mfa`, config),
+  setMfa: async (id, config) => http().request("PUT", `/api/personas/${segment(id)}/mfa`, config),
   /** Remove the persona-wide factor, or the one filed against `domain`. */
   clearMfa: async (id, domain) => {
-    await http().request("DELETE", `/api/personas/${id}/mfa${domain ? `?domain=${encodeURIComponent(domain)}` : ""}`);
+    await http().request(
+      "DELETE",
+      `/api/personas/${segment(id)}/mfa${domain ? `?domain=${encodeURIComponent(domain)}` : ""}`
+    );
   }
 });
 var loginCalls = (http) => ({
@@ -2002,20 +2183,20 @@ var loginCalls = (http) => ({
    * better path. This is for portals that expire a session server-side
    * between runs, where an unattended run has nothing else to recover with.
    */
-  setCredentials: (id, config) => http().request("PUT", `/api/personas/${id}/credentials`, config),
+  setCredentials: async (id, config) => http().request("PUT", `/api/personas/${segment(id)}/credentials`, config),
   /** Which sites this identity can sign in to. Usernames only. */
-  credentials: (id) => http().request("GET", `/api/personas/${id}/credentials`),
+  credentials: async (id) => http().request("GET", `/api/personas/${segment(id)}/credentials`),
   /** Remove the login stored for one site. */
   clearCredentials: async (id, domain) => {
-    await http().request("DELETE", `/api/personas/${id}/credentials?domain=${encodeURIComponent(domain)}`);
+    await http().request("DELETE", `/api/personas/${segment(id)}/credentials?domain=${encodeURIComponent(domain)}`);
   }
 });
-var jarPath = (id) => `/api/pool/cookies?persona=${encodeURIComponent(id)}`;
+var jarPath = (id) => `/api/pool/cookies?persona=${segment(id)}`;
 var jarCalls = (http) => ({
   /** Every cookie in the jar; `format: 'playwright'` is ready for `context.addCookies()`. */
-  cookies: async (id, format = "json") => (await http().request("GET", `${jarPath(id)}&format=${format}`)).cookies,
+  cookies: async (id, format = "json") => (await http().request("GET", `${jarPath(id)}&format=${encodeURIComponent(format)}`)).cookies,
   /** Merge cookies into the jar. The persona's browsers pick them up on their next visit to each site. */
-  importCookies: (id, list2) => http().request("PUT", jarPath(id), { cookies: list2 })
+  importCookies: async (id, list2) => http().request("PUT", jarPath(id), { cookies: list2 })
 });
 var cookieCalls = (http) => ({
   ...jarCalls(http),
@@ -2115,32 +2296,101 @@ var Oya = class {
 };
 
 // src/context.ts
-function client(flags2) {
-  const saved = resolved();
-  const apiKey = flagStr(flags2, "key") || saved.apiKey;
-  const baseUrl = flagStr(flags2, "url") || saved.baseUrl;
-  if (!apiKey) {
-    console.error("No API key. Run `oya login`, or pass --key / set OYA_API_KEY.");
-    process.exit(1);
-  }
+var origin2 = (flags) => origin({ apiKey: flagStr(flags, "key"), baseUrl: flagStr(flags, "url") });
+function client(flags) {
+  const { apiKey, baseUrl } = origin2(flags);
+  if (!apiKey)
+    throw new CliError("No API key.", "no_api_key", { hint: "Run oya login, or pass --key, or set OYA_API_KEY." });
   return new Oya({ apiKey, baseUrl });
 }
 var printJson = (value) => console.log(JSON.stringify(value, null, JSON_INDENT2));
-var out = (flags2, value, human) => {
-  if (flags2.json) printJson(value);
+var out = (flags, value, human) => {
+  if (flags.json) printJson(value);
   else human();
 };
-async function targetBrowser(oya, flags2) {
-  const id = flagStr(flags2, "id");
+async function targetBrowser(oya, flags) {
+  const id = flagStr(flags, "id");
   if (id) return oya.browser.get(id);
   const all = await oya.browser.list();
-  if (!all.length) {
-    console.error("No browsers running. Start one with `oya start`.");
-    process.exit(1);
-  }
+  if (!all.length) throw new CliError("No browsers running.", "no_browser", { hint: "Start one with oya start." });
   return oya.browser.get(all[all.length - 1].id);
 }
 
+// src/commands/login.ts
+async function postJson(url, body, token2) {
+  const headers = { ...token2 ? { Authorization: `Bearer ${token2}` } : {}, "Content-Type": "application/json" };
+  const signal = AbortSignal.timeout(LOGIN_TIMEOUT_MS);
+  const res = await fetch(url, { method: "POST", headers, body: JSON.stringify(body), signal }).catch(() => {
+    throw new CliError(`Could not reach ${new URL(url).origin}.`, "unreachable", {
+      hint: "Check the address, then run oya login again."
+    });
+  });
+  return { ok: res.ok, body: jsonOr(await res.text(), `${res.status} from ${url}`) };
+}
+function jsonOr(text, answer) {
+  try {
+    return JSON.parse(text);
+  } catch {
+    return { error: `Not a JSON answer: ${answer}` };
+  }
+}
+async function mintKey(baseUrl) {
+  const email = await ask("Email:");
+  const password = await askSecret("Password:");
+  const session2 = await postJson(`${baseUrl}/api/auth/login`, { email, password });
+  if (!session2.ok || !session2.body.access_token) throw new Error(session2.body.error || "Sign-in failed");
+  const minted = await postJson(`${baseUrl}/api/auth/keys`, { label: "CLI" }, session2.body.access_token);
+  if (!minted.ok || !minted.body.key) throw new Error(minted.body.error || "Could not create an API key");
+  console.log('  Created a new API key labelled "CLI".');
+  return minted.body.key;
+}
+function chooseMethod() {
+  return choose("How do you want to authenticate?", [
+    { id: "paste", label: "Paste an API key", note: "from the dashboard, or a self-hosted key" },
+    { id: "password", label: "Sign in with email and password", note: "mints a new key for this machine" }
+  ]);
+}
+async function obtainKey(flags, baseUrl) {
+  const given = flagStr(flags, "key") || "";
+  if (given) return given;
+  const how = await chooseMethod();
+  if (how === "paste") return askSecret("API key:");
+  return mintKey(baseUrl);
+}
+async function verifyKey(baseUrl, apiKey) {
+  await new Oya({ apiKey, baseUrl }).config.get().catch((err) => {
+    throw namedFailure(err, baseUrl);
+  });
+}
+function namedFailure(err, baseUrl) {
+  const status = err.status;
+  const again = "then run oya login again.";
+  if (status === 0)
+    return new CliError(`Could not reach ${baseUrl}.`, "unreachable", { hint: `Check the address, ${again}` });
+  if (status !== Status2.UNAUTHORIZED && status !== Status2.FORBIDDEN) return err;
+  return new CliError(`${baseUrl} rejected that key.`, "invalid_key", { hint: `Check the key, ${again}` });
+}
+async function loginUrl(flags) {
+  const current = resolved().baseUrl;
+  const url = flagStr(flags, "url") || (flagStr(flags, "key") ? current : await ask("Control plane URL:", current));
+  return url.replace(/\/+$/, "");
+}
+async function cmdLogin(flags) {
+  if (flags.json && !flagStr(flags, "key")) throw usage("oya login --json never prompts, so it needs --key <key>.");
+  const baseUrl = await loginUrl(flags);
+  const apiKey = await obtainKey(flags, baseUrl);
+  if (!apiKey) throw usage("No API key given.");
+  await verifyKey(baseUrl, apiKey);
+  save({ apiKey, baseUrl });
+  out(flags, { ok: true, baseUrl, configPath }, () => signedIn(baseUrl));
+}
+function signedIn(baseUrl) {
+  console.log(`
+\u2705 Signed in to ${baseUrl}. Saved to ${configPath}`);
+  console.log("   Scripts using @oya-ai/browser read this file too, so `new Oya()` needs no environment.");
+  console.log("   Next: `oya init` to pick your model and browser provider.");
+}
+
 // src/commands/init.ts
 var PRESETS = {
   anthropic: { name: "Anthropic", model: "claude-sonnet-5" },
@@ -2167,20 +2417,29 @@ async function askModelDetails(llm, updates) {
   const model = await ask("Default model:", PRESETS[llm].model);
   if (model) updates.chat_model = model;
 }
+var needsNote = (p) => p.needs.some((f) => f.endsWith("_url")) ? "needs its ws:// address" : "needs an API key";
+function fieldLabel(p, field) {
+  if (field.endsWith("_url")) return "Chrome DevTools address, such as ws://127.0.0.1:9222:";
+  if (field.endsWith("_api_key")) return `${p.label} API key:`;
+  return `${p.label} ${field.replace(/^[a-z]+_/, "").replace(/_/g, " ")}:`;
+}
 function providerOptions(current) {
-  const note2 = (p) => p.needs.length ? p.configured ? "configured" : "needs an API key" : void 0;
+  const note2 = (p) => p.needs.length ? p.configured ? "configured" : needsNote(p) : void 0;
   return current.providers.map((p) => ({ id: p.id, label: p.label, note: note2(p) }));
 }
 async function askProvider(current, updates) {
   console.log("\n\u2500\u2500 2. Where your browsers run \u2500\u2500");
   const provider = await choose("Browser provider:", providerOptions(current));
   updates.browser_provider = provider;
-  for (const field of current.providers.find((p) => p.id === provider)?.needs || []) {
-    const value = await askSecret(`${field.replace(/_/g, " ")}:`);
-    if (value) updates[field] = value;
-  }
+  const info = current.providers.find((p) => p.id === provider);
+  for (const field of info?.needs || []) await askField(info, field, updates);
   return provider;
 }
+async function askField(info, field, updates) {
+  const label = fieldLabel(info, field);
+  const value = field.endsWith("_url") ? await ask(label) : await askSecret(label);
+  if (value) updates[field] = value;
+}
 var CAPTCHA_OPTIONS2 = [
   { id: "", label: "No", note: "providers that solve natively still will" },
   { id: "capsolver", label: "Yes, via CapSolver" }
@@ -2200,18 +2459,23 @@ function signInHint(provider) {
   console.log("   arrive already logged in, as the same identity, from the same fingerprint.");
   console.log(`   Download the desktop browser: ${resolved().baseUrl}/downloads`);
 }
+var NO_ANSWERS = "oya init had no input to read, so its defaults were never chosen. Nothing was saved. Run it in a terminal, or pipe the answers in.";
+async function saveAnswers(oya, updates) {
+  if (!answered()) throw new InputError(NO_ANSWERS);
+  updates.onboarded = "true";
+  await oya.config.set(updates);
+}
 async function interview2(oya) {
   const current = await oya.config.get();
   const updates = {};
   await askModel(current, updates);
   const provider = await askProvider(current, updates);
   await askCaptcha(updates);
-  updates.onboarded = "true";
-  await oya.config.set(updates);
+  await saveAnswers(oya, updates);
   return provider;
 }
-async function cmdInit(flags2) {
-  const provider = await interview2(client(flags2));
+async function cmdInit(flags) {
+  const provider = await interview2(client(flags));
   console.log("\n\u2705 Saved against your API key.");
   signInHint(provider);
   console.log("\n   Then:  oya start && oya goto https://example.com");
@@ -2219,47 +2483,48 @@ async function cmdInit(flags2) {
 
 // src/commands/browsers.ts
 import { spawn as spawn3 } from "child_process";
-function identityOptions(flags2) {
+function identityOptions(flags) {
   return {
-    persona: flagStr(flags2, "persona") || "default",
-    captcha: flags2.captcha === false ? "off" : "auto",
-    provider: flagStr(flags2, "provider"),
-    wsUrl: flagStr(flags2, "ws-url"),
-    name: flagStr(flags2, "name"),
-    idempotencyKey: flagStr(flags2, "idempotency-key")
+    persona: flagStr(flags, "persona") || "default",
+    provider: flagStr(flags, "provider"),
+    wsUrl: flagStr(flags, "ws-url"),
+    name: flagStr(flags, "name"),
+    idempotencyKey: flagStr(flags, "idempotency-key")
   };
 }
-function governanceOptions(flags2) {
+function governanceOptions(flags) {
   return {
-    queueMs: flagNum(flags2, "queue-ms"),
-    budgetUsd: flagNum(flags2, "budget-usd"),
-    governed: flags2.governed === true,
-    priority: flagStr(flags2, "priority"),
-    policy: flagStr(flags2, "policy") ? JSON.parse(flagStr(flags2, "policy")) : void 0
+    queueMs: flagNum(flags, "queue-ms"),
+    budgetUsd: flagNum(flags, "budget-usd"),
+    governed: flags.governed === true,
+    priority: flagStr(flags, "priority"),
+    policy: flagStr(flags, "policy") ? policyOf(flagStr(flags, "policy")) : void 0
   };
 }
-var startOptions = (flags2) => ({ ...identityOptions(flags2), ...governanceOptions(flags2) });
-async function cmdStart(flags2) {
-  const browser = await client(flags2).browser.start(startOptions(flags2));
+var policyOf = (text) => parseJson(text, "--policy", `Quote it: --policy '{"allowedHosts":["example.com"]}'.`);
+var startOptions = (flags) => ({ ...identityOptions(flags), ...governanceOptions(flags) });
+async function cmdStart(flags) {
+  const browser = await client(flags).browser.start(startOptions(flags));
   const { id, provider, persona, cdpUrl } = browser;
-  out(flags2, { id, provider, persona, cdpUrl }, () => {
+  out(flags, { id, provider, persona, cdpUrl }, () => {
     console.log(`\u2705 ${id}`);
     console.log(`   provider: ${provider}   persona: ${persona}`);
     if (cdpUrl) console.log(`   cdp:      ${cdpUrl}`);
   });
 }
-async function cmdGoto(args2, flags2) {
-  const url = args2[0];
-  if (!url) throw new Error("Usage: oya goto <url>");
-  const browser = await targetBrowser(client(flags2), flags2);
+async function cmdGoto(args, flags) {
+  const url = args[0];
+  if (!url) throw usage("oya goto needs an address: oya goto <url>.");
+  const browser = await targetBrowser(client(flags), flags);
   await browser.goto(url);
-  console.log(`\u2705 ${browser.id} \u2192 ${url}`);
+  out(flags, { id: browser.id, url }, () => console.log(`\u2705 ${browser.id} \u2192 ${url}`));
 }
-async function cmdAsk(args2, flags2) {
-  const prompt = args2.join(" ");
-  if (!prompt) throw new Error('Usage: oya ask "find the pricing page"');
-  const browser = await targetBrowser(client(flags2), flags2);
-  console.log(await browser.ask(prompt));
+async function cmdAsk(args, flags) {
+  const prompt = args.join(" ");
+  if (!prompt) throw usage('oya ask needs a prompt: oya ask "find the pricing page".');
+  const browser = await targetBrowser(client(flags), flags);
+  const answer = await browser.ask(prompt);
+  out(flags, { id: browser.id, answer }, () => console.log(answer));
 }
 var DOT = { ok: "\u25CF", stale: "\u25D0", errors: "\u2717", dead: "\u25CB" };
 function lsRow(b) {
@@ -2268,9 +2533,9 @@ function lsRow(b) {
   const url = b.currentUrl.replace(/^https?:\/\//, "").slice(0, LsColumns.URL);
   return `${DOT[b.health] || "\xB7"} ${b.id}  ${provider} ${persona} ${b.name.padEnd(LsColumns.NAME)} ${b.commands}\xB7${b.errors}  ${url}`;
 }
-async function cmdLs(flags2) {
-  const all = await client(flags2).browser.list();
-  out(flags2, all, () => {
+async function cmdLs(flags) {
+  const all = await client(flags).browser.list();
+  out(flags, all, () => {
     if (!all.length) return console.log("No browsers running.");
     for (const b of all) console.log(lsRow(b));
     console.log(`
@@ -2282,13 +2547,19 @@ function rmLine(x) {
   const note2 = x.sandboxRemoved === false ? ", sandbox NOT removed, check Oya Cloud" : removed;
   return `${x.ok ? "\u2705" : "\u2717"} ${x.id}${note2}${x.error ? ` ${x.error}` : ""}`;
 }
-async function cmdRm(args2, flags2) {
-  const oya = client(flags2);
-  if (!flags2.all && !args2.length) throw new Error("Usage: oya rm <id>\u2026 | oya rm --all");
-  const r = await oya.browser.stop(flags2.all ? "all" : args2);
-  for (const x of r.results) console.log(rmLine(x));
-  console.log(`stopped ${r.stopped}`);
+async function cmdRm(args, flags) {
+  const oya = client(flags);
+  if (!flags.all && !args.length) throw usage("oya rm needs a browser id, or --all: oya rm <id>... | oya rm --all.");
+  const r = await oya.browser.stop(flags.all ? "all" : args);
+  out(flags, r, () => printStops(r.results));
+  const failed = r.results.filter((x) => !x.ok).length;
+  if (failed) throw stopsFailed(r.results.length - failed, r.results.length, !!flags.json);
 }
+function printStops(results) {
+  for (const x of results) (x.ok ? console.log : console.error)(rmLine(x));
+  console.log(`stopped ${results.filter((x) => x.ok).length} of ${results.length}`);
+}
+var stopsFailed = (stopped, of, json) => new CliError(`stopped ${stopped} of ${of}`, "partial_failure", { shown: !json });
 function activityLine(a) {
   const error = a.error ? `, ${a.error}` : "";
   return `    ${a.ok ? "\xB7" : "\u2717"} ${a.action.padEnd(StatusColumns.ACTION)} ${a.summary}${error}  ${a.ms}ms`;
@@ -2302,21 +2573,21 @@ function printStatus(s) {
   console.log("  recent:");
   for (const a of s.activity.slice(0, StatusColumns.RECENT)) console.log(activityLine(a));
 }
-async function cmdStatus(flags2) {
-  const browser = await targetBrowser(client(flags2), flags2);
+async function cmdStatus(flags) {
+  const browser = await targetBrowser(client(flags), flags);
   const s = await browser.status();
-  out(flags2, s, () => printStatus(s));
+  out(flags, s, () => printStatus(s));
 }
 function opener(url) {
   if (process.platform === "darwin") return ["open", [url]];
   if (process.platform === "win32") return ["cmd", ["/c", "start", "", url]];
   return ["xdg-open", [url]];
 }
-async function cmdOpen(flags2) {
-  const browser = await targetBrowser(client(flags2), flags2);
-  const [command2, args2] = opener(browser.liveViewUrl());
-  spawn3(command2, args2, { detached: true, stdio: "ignore" }).unref();
-  console.log(`Opening ${browser.id}`);
+async function cmdOpen(flags) {
+  const browser = await targetBrowser(client(flags), flags);
+  const [command, args] = opener(browser.liveViewUrl());
+  spawn3(command, args, { detached: true, stdio: "ignore" }).unref();
+  out(flags, { ok: true, id: browser.id }, () => console.log(`Opening the live view of ${browser.id}`));
 }
 
 // src/commands/personas.ts
@@ -2330,61 +2601,74 @@ var PLATFORM_ALIAS = {
   linux: "Linux x86_64",
   "linux x86_64": "Linux x86_64"
 };
-function prefsFrom(flags2) {
-  const platformFlag = flagStr(flags2, "platform");
+function prefsFrom(flags) {
+  const platformFlag = flagStr(flags, "platform");
   return {
     ...platformFlag ? { platform: PLATFORM_ALIAS[platformFlag.toLowerCase()] || platformFlag } : {},
-    ...flagStr(flags2, "tz") ? { timezone: flagStr(flags2, "tz") } : {},
-    ...flagStr(flags2, "locale") ? { locale: flagStr(flags2, "locale") } : {}
+    ...flagStr(flags, "tz") ? { timezone: flagStr(flags, "tz") } : {},
+    ...flagStr(flags, "locale") ? { locale: flagStr(flags, "locale") } : {}
   };
 }
-function createOptions(flags2, rest, prefs) {
+function createOptions(flags, rest, prefs) {
   return {
-    name: flagStr(flags2, "name") || rest[0],
+    name: flagStr(flags, "name") || rest[0],
     prefs,
-    proxy: flagStr(flags2, "geo") ? { geo: flagStr(flags2, "geo") } : void 0,
-    maxConcurrent: flagStr(flags2, "max") ? Number(flagStr(flags2, "max")) : void 0
+    proxy: flagStr(flags, "geo") ? { geo: flagStr(flags, "geo") } : void 0,
+    maxConcurrent: flagCount(flags, "max") ?? void 0
   };
 }
-var create = async (oya, rest, flags2) => {
-  const prefs = prefsFrom(flags2);
-  if (flags2.preview) return preview(oya, prefs, flags2);
-  const created = await oya.personas.create(createOptions(flags2, rest, prefs));
+var create = async (oya, rest, flags) => {
+  const prefs = prefsFrom(flags);
+  if (flags.preview) return preview(oya, prefs, flags);
+  const created = await oya.personas.create(createOptions(flags, rest, prefs));
   const fp = created.fingerprint;
-  out(flags2, created, () => console.log(`\u2705 ${created.id}  ${created.name}  ${fp.platform} \xB7 ${fp.timezone}`));
+  out(flags, created, () => console.log(`\u2705 ${created.id}  ${created.name}  ${fp.platform} \xB7 ${fp.timezone}`));
 };
-async function preview(oya, prefs, flags2) {
+async function preview(oya, prefs, flags) {
   const fp = await oya.personas.preview(prefs);
-  out(flags2, fp, () => console.log(`${fp.platform} \xB7 ${fp.timezone} \xB7 ${fp.locale} \xB7 ${fp.screen} \xB7 ${fp.webgl}`));
+  out(flags, fp, () => console.log(`${fp.platform} \xB7 ${fp.timezone} \xB7 ${fp.locale} \xB7 ${fp.screen} \xB7 ${fp.webgl}`));
 }
-function editChanges(flags2) {
-  const max = flagStr(flags2, "max");
+function editChanges(flags) {
+  const max = flagCount(flags, "max", { allowNone: true });
   return {
-    ...flagStr(flags2, "name") ? { name: flagStr(flags2, "name") } : {},
-    ...max ? { maxConcurrent: max === "none" ? null : Number(max) } : {},
-    ...flagStr(flags2, "geo") ? { proxy: { geo: flagStr(flags2, "geo") } } : {}
+    ...flagStr(flags, "name") ? { name: flagStr(flags, "name") } : {},
+    ...max !== void 0 ? { maxConcurrent: max } : {},
+    ...flagStr(flags, "geo") ? { proxy: { geo: flagStr(flags, "geo") } } : {}
   };
 }
-var edit = async (oya, rest, flags2) => {
-  if (!rest[0]) throw new Error("Usage: oya personas edit <id> --name <n> --max <n> --geo <cc>");
-  const updated = await oya.personas.update(rest[0], editChanges(flags2));
-  out(flags2, updated, () => console.log(`\u2705 ${updated.id}  ${updated.name}  cap ${updated.maxConcurrent ?? "\u221E"}`));
+var edit = async (oya, rest, flags) => {
+  if (!rest[0]) throw usage("oya personas edit needs a persona id: oya personas edit <id> --name <n>.");
+  const updated = await oya.personas.update(rest[0], editChanges(flags));
+  out(flags, updated, () => console.log(`\u2705 ${updated.id}  ${updated.name}  cap ${updated.maxConcurrent ?? "\u221E"}`));
 };
-var clone = async (oya, rest, flags2) => {
-  if (!rest[0]) throw new Error("Usage: oya personas clone <id> [--name <n>]");
-  const c = await oya.personas.clone(rest[0], { name: flagStr(flags2, "name") });
+var clone = async (oya, rest, flags) => {
+  if (!rest[0]) throw usage("oya personas clone needs a persona id: oya personas clone <id>.");
+  const c = await oya.personas.clone(rest[0], { name: flagStr(flags, "name") });
   const fp = c.fingerprint;
   out(
-    flags2,
+    flags,
     c,
     () => console.log(`\u2705 ${c.id}  ${c.name}  ${fp.platform} \xB7 ${fp.timezone}  (new identity, same kind of device)`)
   );
 };
-var remove = async (oya, rest) => {
-  if (!rest[0]) throw new Error("Usage: oya personas rm <id>");
-  await oya.personas.remove(rest[0]);
-  console.log(`\u2705 removed ${rest[0]}`);
+var remove = async (oya, rest, flags) => {
+  if (!rest.length) throw usage("oya personas rm needs a persona id: oya personas rm <id>...");
+  const removed = [];
+  for (const id of rest) await removeOne(oya, id, flags, removed);
+  out(flags, { ok: removed.length === rest.length, id: removed }, () => {
+  });
+  if (removed.length < rest.length) throw removalsFailed(removed.length, rest.length, !!flags.json);
 };
+async function removeOne(oya, id, flags, removed) {
+  try {
+    await oya.personas.remove(id);
+    removed.push(id);
+    if (!flags.json) console.log(`\u2705 removed ${id}`);
+  } catch (err) {
+    if (!flags.json) console.error(`\u2717 ${id} ${err.message}`);
+  }
+}
+var removalsFailed = (removed, of, json) => new CliError(`removed ${removed} of ${of}`, "partial_failure", { shown: !json });
 function personaLine(p) {
   const cap = p.maxConcurrent === null ? "\u221E" : String(p.maxConcurrent);
   const where = p.exit ? `  via ${p.exit.label}` : p.proxy?.geo ? `  geo ${p.proxy.geo}` : "";
@@ -2392,104 +2676,117 @@ function personaLine(p) {
   const device = `${p.fingerprint.platform} \xB7 ${p.fingerprint.timezone}`;
   return `${p.id}  ${p.name.padEnd(PERSONA_NAME_WIDTH)} ${p.activeBrowsers}/${cap} running  ${device}${extras}`;
 }
-var list = async (oya, _rest, flags2) => {
+var list = async (oya, _rest, flags) => {
   const all = await oya.personas.list();
-  out(flags2, all, () => {
+  out(flags, all, () => {
     if (!all.length) return console.log("No personas yet, `oya personas new`.");
     for (const p of all) console.log(personaLine(p));
   });
 };
 var SUBCOMMANDS = { new: create, create, edit, clone, rm: remove, delete: remove };
-async function cmdPersonas(args2, flags2) {
-  const oya = client(flags2);
-  const [sub, ...rest] = args2;
-  const run2 = sub !== void 0 && Object.hasOwn(SUBCOMMANDS, sub) ? SUBCOMMANDS[sub] : list;
-  await run2(oya, rest, flags2);
+async function cmdPersonas(args, flags) {
+  const [sub, ...rest] = args;
+  if (sub !== void 0 && !Object.hasOwn(SUBCOMMANDS, sub))
+    throw usage(`Unknown personas subcommand "${sub}". Use new, edit, clone or rm.`);
+  await (sub === void 0 ? list : SUBCOMMANDS[sub])(client(flags), rest, flags);
 }
 
 // src/commands/cookies.ts
-import { readFileSync as readFileSync4, writeFileSync as writeFileSync5 } from "fs";
-var USAGE = `Usage: oya cookies export <persona> [--format json|playwright] [--out <file>]
-       oya cookies import <persona> <file.json>
-       oya cookies copy <from-persona> <to-persona>
-       oya cookies clear <persona>`;
-var exportJar = async (oya, rest, flags2) => {
-  if (!rest[0]) throw new Error("Usage: oya cookies export <persona> [--format json|playwright] [--out <file>]");
-  const cookies = await oya.personas.cookies(rest[0], flagStr(flags2, "format") || "json");
-  const file = flagStr(flags2, "out");
-  if (!file) return console.log(JSON.stringify(cookies, null, JSON_INDENT2));
+import { chmodSync as chmodSync3, writeFileSync as writeFileSync5 } from "fs";
+var FORMATS = ["json", "playwright"];
+function formatOf(flags) {
+  const format = flagStr(flags, "format") || "json";
+  if (FORMATS.includes(format)) return format;
+  throw usage(`Unknown format "${format}". Use --format json or --format playwright.`);
+}
+function writeJar(file, cookies) {
   writeFileSync5(file, JSON.stringify(cookies, null, JSON_INDENT2) + "\n", { mode: PRIVATE_FILE_MODE });
-  console.log(`\u2705 ${cookies.length} cookie${cookies.length === 1 ? "" : "s"} written to ${file}`);
+  chmodSync3(file, PRIVATE_FILE_MODE);
+}
+var exportJar = async (oya, rest, flags) => {
+  if (!rest[0]) throw usage("oya cookies export needs a persona id: oya cookies export <persona> [--out <file>].");
+  const cookies = await oya.personas.cookies(rest[0], formatOf(flags));
+  if (!Array.isArray(cookies)) throw new Error("The server sent no cookie list, so nothing was written.");
+  const file = flagStr(flags, "out");
+  if (!file) return console.log(JSON.stringify(cookies, null, JSON_INDENT2));
+  writeJar(file, cookies);
+  const written = `\u2705 ${cookies.length} cookie${cookies.length === 1 ? "" : "s"} written to ${file}`;
+  out(flags, { ok: true, id: rest[0], file, count: cookies.length }, () => console.log(written));
 };
 function cookiesIn(file) {
-  const parsed = JSON.parse(readFileSync4(file, "utf8"));
+  const parsed = readJsonFile(file);
   const list2 = Array.isArray(parsed) ? parsed : parsed?.cookies;
-  if (!Array.isArray(list2)) throw new Error(`${file} holds no list of cookies`);
+  if (!Array.isArray(list2)) throw usage(`${file} holds no list of cookies.`);
   return list2;
 }
-var importJar = async (oya, rest, flags2) => {
-  if (!rest[0] || !rest[1]) throw new Error("Usage: oya cookies import <persona> <file.json>");
+var importJar = async (oya, rest, flags) => {
+  if (!rest[0] || !rest[1])
+    throw usage("oya cookies import needs a persona and a file: oya cookies import <persona> <file>.");
   const done = await oya.personas.importCookies(rest[0], cookiesIn(rest[1]));
   out(
-    flags2,
+    flags,
     done,
     () => console.log(`\u2705 ${done.imported} imported, ${done.skipped} skipped, ${done.total} in the jar`)
   );
 };
-var copy = async (oya, rest, flags2) => {
-  if (!rest[0] || !rest[1]) throw new Error("Usage: oya cookies copy <from-persona> <to-persona>");
+var copy = async (oya, rest, flags) => {
+  if (!rest[0] || !rest[1]) throw usage("oya cookies copy needs two persona ids: oya cookies copy <from> <to>.");
   const done = await oya.personas.copyCookies(rest[0], rest[1]);
-  out(flags2, done, () => console.log(`\u2705 ${done.imported} copied to ${rest[1]}, ${done.total} in its jar`));
+  out(flags, done, () => console.log(`\u2705 ${done.imported} copied to ${rest[1]}, ${done.total} in its jar`));
 };
-var clear = async (oya, rest) => {
-  if (!rest[0]) throw new Error("Usage: oya cookies clear <persona>");
-  await oya.personas.clearCookies(rest[0]);
-  console.log(`\u2705 cleared ${rest[0]}`);
+var clear = async (oya, rest, flags) => {
+  if (!rest[0]) throw usage("oya cookies clear needs a persona id: oya cookies clear <persona>.");
+  const done = await oya.personas.clearCookies(rest[0]);
+  out(flags, done ?? { ok: true, id: rest[0] }, () => console.log(`\u2705 cleared ${rest[0]}`));
 };
 var SUBCOMMANDS2 = { export: exportJar, import: importJar, copy, clear };
-async function cmdCookies(args2, flags2) {
-  const [sub, ...rest] = args2;
-  if (sub === void 0 || !Object.hasOwn(SUBCOMMANDS2, sub)) throw new Error(USAGE);
-  await SUBCOMMANDS2[sub](client(flags2), rest, flags2);
+async function cmdCookies(args, flags) {
+  const [sub, ...rest] = args;
+  if (sub === void 0 || !Object.hasOwn(SUBCOMMANDS2, sub))
+    throw usage(`Unknown cookies subcommand "${sub ?? ""}". Use export, import, copy or clear.`);
+  await SUBCOMMANDS2[sub](client(flags), rest, flags);
 }
 
 // src/commands/settings.ts
-function parsePairs(args2) {
+function parsePairs(args) {
   const updates = {};
-  for (const pair of args2) {
+  for (const pair of args) {
     const index = pair.indexOf("=");
-    if (index < 1) throw new Error(`Expected key=value, got "${pair}"`);
+    if (index < 1) throw usage(`oya config takes settings as key=value, not "${pair}".`);
     updates[pair.slice(0, index)] = pair.slice(index + 1);
   }
   return updates;
 }
-async function cmdConfig(args2, flags2) {
-  const oya = client(flags2);
-  if (!args2.length) {
+async function cmdConfig(args, flags) {
+  const oya = client(flags);
+  if (!args.length) {
     const current = await oya.config.get();
-    return out(flags2, current, () => printJson(current));
+    return out(flags, current, () => printJson(current));
   }
-  const updates = parsePairs(args2);
-  await oya.config.set(updates);
-  console.log(`\u2705 updated ${Object.keys(updates).join(", ")}`);
+  const updates = parsePairs(args);
+  const saved = await oya.config.set(updates);
+  out(flags, saved, () => console.log(`\u2705 updated ${Object.keys(updates).join(", ")}`));
 }
-async function cmdUsage(flags2) {
-  printJson(await client(flags2).usage());
+async function cmdUsage(flags) {
+  printJson(await client(flags).usage());
 }
-async function cmdWhoami() {
-  printJson({ ...resolved(), apiKey: load().apiKey ? "saved" : "none" });
+async function cmdWhoami(flags) {
+  const { apiKey, apiKeyFrom, baseUrl, baseUrlFrom, savedKey } = origin2(flags);
+  const tail = apiKey.length >= MIN_KEY_FOR_TAIL ? { apiKeyEnds: apiKey.slice(-KEY_TAIL) } : {};
+  const ignored = savedKey && apiKeyFrom !== "saved" ? { savedKeyIgnored: true } : {};
+  printJson({ baseUrl, baseUrlFrom, apiKeyFrom, ...tail, ...ignored, configPath });
 }
 
 // src/commands/stealth.ts
 import { spawn as spawn4 } from "child_process";
 var HARNESS = "tests/integration/stealth.test.js";
-var spawnHarness = (flags2) => spawn4("node", [HARNESS, ...flags2.live ? ["--live"] : []], {
+var spawnHarness = (flags) => spawn4("node", [HARNESS, ...flags.live ? ["--live"] : []], {
   cwd: process.env.OYA_SERVER_DIR || "server",
   stdio: "inherit"
 });
-function cmdStealthTest(flags2) {
+function cmdStealthTest(flags) {
   return new Promise((resolve, reject) => {
-    const child = spawnHarness(flags2);
+    const child = spawnHarness(flags);
     const missing = "Could not find the stealth harness. Run it from a checkout, or set OYA_SERVER_DIR.";
     child.on("error", () => reject(new Error(missing)));
     child.on("exit", (code) => code === 0 ? resolve() : reject(new Error(`stealth test exited ${code}`)));
@@ -2498,167 +2795,301 @@ function cmdStealthTest(flags2) {
 
 // src/commands/control.ts
 var ROLES = ["viewer", "operator", "administrator"];
-function required(args2, i = 0) {
-  if (!args2[i]) throw new Error("Missing argument; run oya help");
-  return args2[i];
+function required(args, i, command, what) {
+  if (!args[i]) throw usage(`oya ${command} needs ${what}: oya ${command} <${what.split(" ").pop()}>.`);
+  return args[i];
 }
-function roleFlag(flags2) {
-  const role = flagStr(flags2, "role") || "operator";
-  if (!ROLES.includes(role)) throw new Error("Invalid role");
+function roleFlag(flags) {
+  const role = flagStr(flags, "role") || "operator";
+  if (!ROLES.includes(role)) throw usage(`--role must be viewer, operator or administrator, not "${role}".`);
   return role;
 }
-function subcommand(table, sub, call2, usage) {
-  if (!Object.hasOwn(table, sub)) throw new Error(usage);
+function subcommand(table, sub, call2, command) {
+  if (!Object.hasOwn(table, sub))
+    throw usage(`Unknown ${command} subcommand "${sub}". Use ${orList(Object.keys(table))}.`);
   return table[sub](call2);
 }
+var orList = (names) => names.join(", ").replace(/, ([^,]*)$/, " or $1");
 var members = (call2) => {
   if (!call2.args[0]) return call2.c.members();
   const table = {
-    remove: ({ c, args: args2 }) => c.removeMember(required(args2, 1)),
-    invite: ({ c, flags: flags2 }) => c.inviteMember(roleFlag(flags2))
+    remove: ({ c, args }) => c.removeMember(required(args, 1, "members remove", "a user id")),
+    invite: ({ c, flags }) => c.inviteMember(roleFlag(flags))
   };
-  return subcommand(table, call2.args[0], call2, "Use members, members invite, or members remove");
+  return subcommand(table, call2.args[0], call2, "members");
 };
 var credential = (call2) => {
   const table = {
-    revoke: ({ c, args: args2 }) => c.revokeCredential(required(args2, 1)),
-    new: ({ c, flags: flags2 }) => c.createCredential({ role: roleFlag(flags2), label: flagStr(flags2, "label") })
+    revoke: ({ c, args }) => c.revokeCredential(required(args, 1, "credential revoke", "a credential id")),
+    new: ({ c, flags }) => c.createCredential({ role: roleFlag(flags), label: flagStr(flags, "label") })
   };
-  return subcommand(table, required(call2.args), call2, "Use credential new or credential revoke");
+  return subcommand(table, required(call2.args, 0, "credential", "new or revoke"), call2, "credential");
 };
 var webhook = (call2) => {
   const table = {
-    new: ({ c, args: args2 }) => c.createWebhook(required(args2, 1)),
-    remove: ({ c, args: args2 }) => c.removeWebhook(required(args2, 1)),
-    replay: ({ c, args: args2 }) => c.replayDelivery(required(args2, 1))
+    new: ({ c, args }) => c.createWebhook(required(args, 1, "webhook new", "an https url")),
+    remove: ({ c, args }) => c.removeWebhook(required(args, 1, "webhook remove", "a webhook id")),
+    replay: ({ c, args }) => c.replayDelivery(required(args, 1, "webhook replay", "a delivery id"))
   };
-  return subcommand(table, required(call2.args), call2, "Use webhook new, remove, or replay");
+  return subcommand(table, required(call2.args, 0, "webhook", "new, remove or replay"), call2, "webhook");
 };
-var takeover = ({ c, command: command2, args: args2 }) => c.takeover(required(args2), command2 === "takeover" ? "acquire" : command2);
-var COMMANDS = {
+function recoverOptions(flags) {
+  const wsUrl = flagStr(flags, "ws-url");
+  if (wsUrl && flags.replace !== true)
+    throw usage("--ws-url is only used with --replace; recovering in place keeps the endpoint it had.");
+  return { replace: flags.replace === true, ...wsUrl ? { wsUrl } : {} };
+}
+var projectSettings = (text) => parseJson(
+  text,
+  "The settings for oya project",
+  `Quote them: oya project '{"retentionDays":7}'.`,
+  "are"
+);
+var takeover = ({ c, command, args }) => c.takeover(
+  required(args, 0, command, "a session id"),
+  command === "takeover" ? "acquire" : command
+);
+var CONTROL_COMMANDS = {
   control: ({ c }) => c.overview(),
-  sessions: ({ c, args: args2 }) => args2[0] ? c.session(args2[0]) : c.sessions(),
-  cancel: ({ c, args: args2 }) => c.cancel(required(args2)),
-  recover: ({ c, args: args2, flags: flags2 }) => c.recover(required(args2), flags2.replace === true),
+  sessions: ({ c, args }) => args[0] ? c.session(args[0]) : c.sessions(),
+  cancel: ({ c, args }) => c.cancel(required(args, 0, "cancel", "a session id")),
+  recover: ({ c, args, flags }) => c.recover(required(args, 0, "recover", "a session id"), recoverOptions(flags)),
   members,
-  stop: ({ c, args: args2, flags: flags2 }) => c.stop(required(args2), flags2.force === true),
+  stop: ({ c, args, flags }) => c.stop(required(args, 0, "stop", "a session id"), flags.force === true),
   takeover,
   release: takeover,
   resume: takeover,
-  events: ({ c, flags: flags2 }) => c.events(Number(flagStr(flags2, "after") || 0)),
-  project: ({ c, args: args2 }) => c.settings(JSON.parse(required(args2))),
+  events: ({ c, flags }) => c.events(flagNum(flags, "after") ?? 0),
+  project: ({ c, args }) => c.settings(projectSettings(required(args, 0, "project", "settings as JSON"))),
   credential,
   webhook
 };
-function isControlCommand(command2, flags2) {
-  if (command2 === "stop") return flags2.force === true;
-  return Object.hasOwn(COMMANDS, command2);
+function isControlCommand(command, flags) {
+  if (command === "stop") return flags.force === true;
+  return Object.hasOwn(CONTROL_COMMANDS, command);
 }
-async function runControl(command2, args2, flags2) {
-  const c = client(flags2).control;
-  printJson(await COMMANDS[command2]({ c, command: command2, args: args2, flags: flags2 }));
+async function runControl(command, args, flags) {
+  const c = client(flags).control;
+  printJson(await CONTROL_COMMANDS[command]({ c, command, args, flags }));
 }
 
 // src/help.ts
 var HELP = `oya, thousands of browsers, one API
 
-  oya install                     Stand up a self-hosted control plane
-            [--dry-run] [--config oya-install.json]
-  oya login                       Save an API key for this machine
-  oya init                        Set your model, browser provider and sign-ins
-  oya start [--persona auto]      Start a browser and print its id
-  oya goto <url> [--id <id>]      Navigate (defaults to the newest browser)
-  oya ask "<prompt>" [--id <id>]  Drive it in plain language
-  oya ls                          List running browsers
-  oya rm <id> | --all             Stop browsers
-  oya personas                    Identities: fingerprint + cookies + proxy
-  oya personas new [name]         --platform Win32|MacIntel|Linux --tz <zone> --locale <l> --max <n>
-  oya personas edit <id>          --name <n> --max <n> --geo <cc>
-  oya personas clone|rm <id>      A new device of the same kind \xB7 delete
-  oya cookies export <persona>    Logins to stdout or --out <file>; --format playwright for addCookies()
-  oya cookies import <persona> <file>   Logins from a JSON file
-  oya cookies copy <from> <to>    One persona's logins into another
-  oya status [--id <id>]          Health, counters and what it has been doing
-  oya open [--id <id>]            Open the live view in your browser
-  oya config [key=value ...]      Show or change this key's settings
-  oya control                     Durable project overview
-  oya sessions [id]               All sessions, including pending cleanup
-  oya stop <id> --force           Stop despite a profile-save error, or reconcile
-  oya takeover <id>               Acquire human control
-  oya release <id>                Release human control, leaving the agent paused
-  oya resume <id>                 Acknowledge agent resume
-  oya events [--after <cursor>]   Read durable lifecycle events
-  oya project <settings-json>     Update limits, rate cards and retention
-  oya start --governed --provider oya-selfhosted [--queue-ms 30000]
-            [--budget-usd 5] [--policy JSON] [--idempotency-key ID]
-  oya cancel <id>               Cancel queued or provisioning work
-  oya recover <id> [--replace]   Explicitly recover or replace a session
-  oya members [invite|remove]   List members, invite, or remove a user
-  oya credential new [--role viewer|operator|administrator]
-  oya credential revoke <id>     Revoke a service credential
-  oya webhook new <https-url>    Register a signed event webhook
-  oya webhook remove <id>        Disable a webhook
-  oya webhook replay <id>        Replay a delivery
-  oya usage                       What this key has spent
-  oya stealth-test [--live]       Score this deployment against bot detectors
+Usage: oya <command> [arguments] [options]
+
+Set up
+  oya install [--dry-run] [--config <file>]  Stand up a self-hosted control plane
+  oya login [--key <key>] [--url <url>]      Save an API key for this machine
+  oya init                                   Set your model, browser provider and sign-ins
+  oya whoami                                 Which control plane and key are in use, and from where
 
-Options: --url <control plane>   --key <api key>   --json
-Config:  ${configPath}
+Browsers
+  oya start                                  Start a browser and print its id
+      [--persona <id|auto>] [--name <name>] [--idempotency-key <key>]
+      [--provider cdp --ws-url ws://127.0.0.1:9222]        on a Chrome you run
+      [--governed] [--queue-ms 30000] [--budget-usd 5] [--priority low|normal|high] [--policy '<json>']
+  oya goto <url> [--id <id>]                 Navigate (defaults to the newest browser)
+  oya ask "<prompt>" [--id <id>]             Drive it in plain language
+  oya ls | list                              List running browsers
+  oya status [--id <id>]                     Health, counters and what it has been doing
+  oya open [--id <id>]                       Open the live view in your browser
+  oya rm | stop <id>... | --all              Stop browsers
+
+Personas and cookies
+  oya personas                               List identities: fingerprint + cookies + proxy
+  oya personas new | create [name]           [--name <n>] [--platform Win32|MacIntel|Linux] [--tz <zone>]
+                                             [--locale <l>] [--max <n>] [--geo <cc>] [--preview]
+  oya personas edit <id>                     [--name <n>] [--max <n|none>] [--geo <cc>]
+  oya personas clone <id> [--name <n>]       A new device of the same kind
+  oya personas rm | delete <id>...           Delete personas
+  oya cookies export <persona>               Logins to stdout; [--out <file>] [--format json|playwright]
+  oya cookies import <persona> <file>        Logins from a JSON file
+  oya cookies copy <from> <to>               One persona's logins into another
+  oya cookies clear <persona>                Delete a persona's logins
+
+Account
+  oya config [key=value ...]                 Show or change this key's settings
+  oya usage                                  What this key has spent
+  oya stealth-test [--live]                  Score this deployment against bot detectors
+
+Control plane (always prints JSON)
+  oya control                                Durable project overview
+  oya sessions [<id>]                        All sessions, including pending cleanup
+  oya cancel <id>                            Stop a session in any state; prints its final state
+  oya stop <id> --force                      Stop despite a profile-save error, or reconcile
+  oya recover <id> [--replace [--ws-url ws://host:9222]]
+                                             Recover in place, or replace it (a cdp session needs --ws-url)
+  oya takeover <id>                          Take human control
+  oya release <id>                           Hand control back, leaving the agent paused
+  oya resume <id>                            Let the agent carry on
+  oya events [--after <cursor>]              Read durable lifecycle events
+  oya project '<settings-json>'              Update limits, rate cards and retention
+  oya members                                List the owner and members
+  oya members invite [--role <role>]         An invitation code; role viewer|operator|administrator
+  oya members remove <user>                  Remove a member
+  oya credential new [--role <role>] [--label <text>]   Mint a service credential (shown once)
+  oya credential revoke <id>                 Revoke a service credential
+  oya webhook new <https-url>                Register a signed event webhook
+  oya webhook remove <id>                    Disable a webhook
+  oya webhook replay <id>                    Send a delivery again
+
+Options
+  --json          One JSON document on stdout; errors as JSON on stderr
+  --url <url>     Control plane for this call (else OYA_BASE_URL, else the one oya login saved)
+  --key <key>     API key for this call (else OYA_API_KEY, else the one oya login saved)
+  --debug         On failure, also print the status, the response body and the stack
+  --version       Print the version
+  --help, -h      This text; the command is not run
+
+Exit codes: 0 done \xB7 1 failed, or no answer \xB7 2 usage error, nothing was sent
+Config: ${configPath}
 `;
 
 // src/commands/index.ts
+import { createRequire } from "module";
 var help = async () => console.log(HELP);
-var COMMANDS2 = {
-  install: (_args, flags2) => cmdInstall(flags2),
-  login: (_args, flags2) => cmdLogin(flags2),
-  init: (_args, flags2) => cmdInit(flags2),
-  start: (_args, flags2) => cmdStart(flags2),
+function packageVersion() {
+  const require2 = createRequire(import.meta.url);
+  for (const path of ["../package.json", "../../package.json"]) {
+    try {
+      return require2(path).version;
+    } catch {
+    }
+  }
+  return "unknown";
+}
+var VERSION = packageVersion();
+var version = async (_args, flags) => out(flags, { version: VERSION }, () => console.log(`oya ${VERSION}`));
+var noJson = (command, run2, instead) => async (args, flags) => {
+  if (flags.json) throw usage(`oya ${command} has no --json output. ${instead}`);
+  await run2(args, flags);
+};
+var COMMANDS = {
+  install: noJson("install", (_args, flags) => cmdInstall(flags), "For an unattended install, use --config <file>."),
+  login: (_args, flags) => cmdLogin(flags),
+  init: noJson("init", (_args, flags) => cmdInit(flags), "Use oya config key=value --json."),
+  start: (_args, flags) => cmdStart(flags),
   goto: cmdGoto,
   ask: cmdAsk,
-  ls: (_args, flags2) => cmdLs(flags2),
-  list: (_args, flags2) => cmdLs(flags2),
-  status: (_args, flags2) => cmdStatus(flags2),
+  ls: (_args, flags) => cmdLs(flags),
+  list: (_args, flags) => cmdLs(flags),
+  status: (_args, flags) => cmdStatus(flags),
   rm: cmdRm,
   stop: cmdRm,
   personas: cmdPersonas,
   cookies: cmdCookies,
-  open: (_args, flags2) => cmdOpen(flags2),
+  open: (_args, flags) => cmdOpen(flags),
   config: cmdConfig,
-  usage: (_args, flags2) => cmdUsage(flags2),
-  "stealth-test": (_args, flags2) => cmdStealthTest(flags2),
-  whoami: () => cmdWhoami(),
+  usage: (_args, flags) => cmdUsage(flags),
+  "stealth-test": noJson("stealth-test", (_args, flags) => cmdStealthTest(flags), "Read its report from the terminal."),
+  whoami: (_args, flags) => cmdWhoami(flags),
+  version,
   help,
   "--help": help,
   "-h": help
 };
-function unknown(command2) {
-  console.error(`Unknown command: ${command2}
-`);
-  console.log(HELP);
-  process.exit(1);
+var unknown = (command) => usage(`Unknown command "${command}". Run oya help for the list.`);
+var wantsHelp = (args, flags) => Object.hasOwn(flags, "help") || args.includes("-h");
+async function dispatch(command, args, flags) {
+  if (wantsHelp(args, flags)) return help(args, flags);
+  if (flags.version || command === "--version") return version(args, flags);
+  if (isControlCommand(command, flags)) return runControl(command, args, flags);
+  if (!Object.hasOwn(COMMANDS, command)) throw unknown(command);
+  await COMMANDS[command](args, flags);
+}
+
+// src/failure.ts
+var USAGE_CODES = /* @__PURE__ */ new Set(["usage", "invalid_json"]);
+function fail2(err, argv2) {
+  const failure2 = describe(err, origin(sourceFlags(argv2)));
+  process.exitCode = USAGE_CODES.has(failure2.code) ? ExitCode.USAGE : ExitCode.FAILED;
+  if (argv2.includes("--json")) printJson2(failure2, err, debugging(argv2));
+  else printPlain(failure2, err, debugging(argv2));
+}
+var debugging = (argv2) => argv2.includes("--debug") || process.env.OYA_DEBUG === "1";
+function sourceFlags(argv2) {
+  const valueOf2 = (name) => {
+    const at = argv2.findIndex((a) => a === `--${name}` || a.startsWith(`--${name}=`));
+    if (at < 0) return void 0;
+    return argv2[at].includes("=") ? argv2[at].split("=").slice(1).join("=") : argv2[at + 1];
+  };
+  return { apiKey: valueOf2("key"), baseUrl: valueOf2("url") };
+}
+function describe(err, origin3) {
+  if (err instanceof CliError)
+    return { message: err.message, code: err.code, status: 0, hint: err.hint, shown: err.shown };
+  const e = err;
+  if (typeof e?.status !== "number")
+    return { message: String(err?.message ?? err), code: "internal", status: 0 };
+  return fromServer(e, origin3);
+}
+function fromServer(e, origin3) {
+  const body = e.body ?? {};
+  const code = typeof body.code === "string" ? body.code : e.status === 0 ? "unreachable" : "http_error";
+  const base = { code, status: e.status, browserId: typeof body.browserId === "string" ? body.browserId : void 0 };
+  if (e.status === 0 && code === "unreachable") return { ...base, ...unreachable2(origin3, body.cause) };
+  if (isInvalidKey(e, body)) return { ...base, ...invalidKey2(origin3) };
+  return { ...base, message: renamed(e.message, body, origin3), hint: hintFor(e.status, code, base.browserId) };
+}
+function renamed(message, body, origin3) {
+  if (body.field !== "baseUrl" || !message.startsWith("baseUrl ")) return message;
+  const source = origin3.baseUrlFrom === "saved" ? "The URL saved by oya login" : origin3.baseUrlFrom;
+  return `${source}${message.slice("baseUrl".length)}`;
+}
+var isInvalidKey = (e, body) => e.status === Status2.UNAUTHORIZED || e.status === Status2.FORBIDDEN && body.error === "Invalid API key";
+var CAUSES = { ECONNREFUSED: "nothing is listening there", ENOTFOUND: "no such host" };
+var URL_HINTS = {
+  "--url": "The URL came from --url. Start the server there, or pass the right --url.",
+  OYA_BASE_URL: "The URL came from OYA_BASE_URL. Start the server there, or export the right URL.",
+  saved: "The URL was saved by oya login. Start the server there, or run oya login --url <url>.",
+  default: "That is the hosted default. Check your connection, or pass --url for a self-hosted server."
+};
+function unreachable2(origin3, cause) {
+  const why = typeof cause === "string" ? Object.hasOwn(CAUSES, cause) ? CAUSES[cause] : cause : "no answer";
+  return { message: `Could not reach ${origin3.baseUrl}: ${why}.`, hint: URL_HINTS[origin3.baseUrlFrom] };
+}
+var KEY_NAMES = {
+  "--key": "--key",
+  OYA_API_KEY: "OYA_API_KEY",
+  saved: "oya login",
+  none: "nowhere"
+};
+function invalidKey2(origin3) {
+  const message = `Invalid API key for ${origin3.baseUrl} (the key came from ${KEY_NAMES[origin3.apiKeyFrom]}).`;
+  const overrides = origin3.apiKeyFrom === "OYA_API_KEY" && origin3.savedKey;
+  const hint2 = overrides ? "OYA_API_KEY overrides the key saved by oya login. Unset it, or export the right key." : "Run oya login to save a new key.";
+  return { message, hint: hint2 };
+}
+function hintFor(status, code, holder) {
+  if (status === Status2.TOO_MANY_REQUESTS)
+    return "A quota or a persona concurrency cap. oya personas shows what is running.";
+  if (holder) return `oya stop ${holder} frees it; oya goto <url> --id ${holder} drives it.`;
+  if (code === "replacement_endpoint_required")
+    return "Add --ws-url ws://host:9222, the Chrome the replacement runs on.";
+  return void 0;
 }
-async function dispatch(command2, args2, flags2) {
-  if (isControlCommand(command2, flags2)) return runControl(command2, args2, flags2);
-  if (!Object.hasOwn(COMMANDS2, command2)) unknown(command2);
-  await COMMANDS2[command2](args2, flags2);
+function printPlain(failure2, err, debug) {
+  if (!failure2.shown) console.error(`\u2717 ${failure2.message}`);
+  if (failure2.hint && !failure2.shown) console.error(`  ${failure2.hint}`);
+  if (!debug) return;
+  console.error(`  status ${failure2.status} \xB7 code ${failure2.code}`);
+  if (err?.body !== void 0) console.error(JSON.stringify(err.body));
+  if (err?.stack) console.error(err.stack);
+}
+function printJson2(failure2, err, debug) {
+  const { message, code, status, browserId } = failure2;
+  const stack = debug ? { stack: err?.stack } : {};
+  console.error(JSON.stringify({ error: message, code, status, ...browserId ? { browserId } : {}, ...stack }));
 }
 
 // src/index.ts
-function fail2(err) {
-  const error = err;
-  console.error(`
-\u2717 ${error.message}`);
-  if (error.status === Status2.UNAUTHORIZED) console.error("  The API key was rejected. Run `oya login`.");
-  if (error.status === Status2.TOO_MANY_REQUESTS) {
-    console.error("  A quota or a persona concurrency cap. `oya personas` shows what is running.");
-  }
-  process.exit(1);
-}
-var { command, args, flags } = parse(process.argv.slice(ARGV_SKIP));
+var argv = process.argv.slice(ARGV_SKIP);
 try {
+  const { command, args, flags } = parse(argv);
   await dispatch(command, args, flags);
 } catch (err) {
-  fail2(err);
+  fail2(err, argv);
 } finally {
   closePrompts();
 }