xapi-to 0.1.18 → 0.1.20

package/dist/index.js

@@ -1,549 +1,54 @@
 #!/usr/bin/env node
-var __defProp = Object.defineProperty;
-var __export = (target, all) => {
-  for (var name in all)
-    __defProp(target, name, { get: all[name], enumerable: true });
-};
-
-// src/config.ts
-import { existsSync, readFileSync, writeFileSync, mkdirSync } from "fs";
-
-// src/format.ts
-function getFormat() {
-  const f = process.env.XAPI_OUTPUT || "json";
-  if (f === "pretty" || f === "table") return f;
-  return "json";
-}
-function output(data, format) {
-  const fmt = format || getFormat();
-  if (fmt === "json") {
-    console.log(JSON.stringify(data));
-    return;
-  }
-  if (fmt === "pretty") {
-    console.log(JSON.stringify(data, null, 2));
-    return;
-  }
-  if (fmt === "table") {
-    const rows = tableRows(data);
-    if (rows) {
-      printTable(rows);
-      return;
-    }
-  }
-  console.log(JSON.stringify(data, null, 2));
-}
-function tableRows(data) {
-  if (Array.isArray(data)) return normalizeRows(data, "value");
-  if (!data || typeof data !== "object") return null;
-  const obj = data;
-  const preferredKeys = ["items", "actions", "results", "services", "categories", "bindings", "providers"];
-  for (const key of preferredKeys) {
-    const value = obj[key];
-    if (Array.isArray(value)) return normalizeRows(value, singularKey(key));
-  }
-  const firstArray = Object.entries(obj).find(([, value]) => Array.isArray(value));
-  return firstArray ? normalizeRows(firstArray[1], singularKey(firstArray[0])) : null;
-}
-function normalizeRows(rows, primitiveKey) {
-  return rows.map((row) => {
-    if (row && typeof row === "object" && !Array.isArray(row)) {
-      return row;
-    }
-    return { [primitiveKey]: row };
-  });
-}
-function singularKey(key) {
-  if (key === "categories") return "category";
-  if (key.endsWith("ies")) return `${key.slice(0, -3)}y`;
-  if (key.endsWith("s")) return key.slice(0, -1);
-  return "value";
-}
-function formatCell(value) {
-  if (value === null || value === void 0) return "";
-  if (typeof value === "object") return JSON.stringify(value);
-  return String(value);
-}
-function printTable(rows) {
-  if (rows.length === 0) {
-    console.log("(empty)");
-    return;
-  }
-  const keys = Object.keys(rows[0]);
-  const widths = keys.map(
-    (k) => Math.min(40, Math.max(k.length, ...rows.map((r) => formatCell(r[k]).length)))
-  );
-  const sep = widths.map((w) => "-".repeat(w)).join("  ");
-  const header = keys.map((k, i) => k.padEnd(widths[i])).join("  ");
-  console.log(header);
-  console.log(sep);
-  for (const row of rows) {
-    const line = keys.map((k, i) => formatCell(row[k]).slice(0, widths[i]).padEnd(widths[i])).join("  ");
-    console.log(line);
-  }
-}
-function err(msg, detail) {
-  if (process.stderr.isTTY) {
-    console.error(`Error: ${msg}`);
-    if (detail !== void 0) console.error(`  ${detail}`);
-  } else {
-    const out = { error: msg };
-    if (detail !== void 0) out.detail = detail;
-    console.error(JSON.stringify(out));
-  }
-  process.exit(1);
-}
-
-// src/config.ts
-import { homedir } from "os";
-import { join } from "path";
-var XAPI_ACTION_HOST = process.env.XAPI_ACTION_HOST || "action.xapi.to";
-var XAPI_API_HOST = process.env.XAPI_API_HOST || "api.xapi.to";
-function scheme(host) {
-  return isLoopbackHost(host) ? "http" : "https";
-}
-var ALLOWED_HOST_EXACT = ["xapi.to", "xapi.xyz"];
-var ALLOWED_HOST_SUFFIXES = [".xapi.to", ".xapi.xyz"];
-function hostnameOf(hostOrUrl) {
-  const raw = hostOrUrl.includes("://") ? hostOrUrl : `http://${hostOrUrl}`;
-  try {
-    return new URL(raw).hostname.toLowerCase();
-  } catch {
-    return "";
-  }
-}
-function isLoopbackIPv4(h) {
-  const m = /^(\d{1,3})\.(\d{1,3})\.(\d{1,3})\.(\d{1,3})$/.exec(h);
-  if (!m) return false;
-  const octets = m.slice(1).map(Number);
-  return octets.every((o) => o <= 255) && octets[0] === 127;
-}
-function isLoopbackHostname(h) {
-  return h === "localhost" || h.endsWith(".localhost") || h === "::1" || h === "[::1]" || isLoopbackIPv4(h);
-}
-function isLoopbackHost(hostOrUrl) {
-  return isLoopbackHostname(hostnameOf(hostOrUrl));
-}
-function isAllowedHost(hostOrUrl) {
-  const h = hostnameOf(hostOrUrl);
-  if (!h) return false;
-  if (isLoopbackHostname(h)) return true;
-  if (ALLOWED_HOST_EXACT.includes(h)) return true;
-  return ALLOWED_HOST_SUFFIXES.some((suffix) => h.endsWith(suffix));
-}
-function assertAllowedHost(hostOrUrl) {
-  if (!isAllowedHost(hostOrUrl)) {
-    throw new Error(
-      `refusing to contact untrusted host "${hostnameOf(hostOrUrl) || hostOrUrl}": the xapi API key may only be sent to *.xapi.to, *.xapi.xyz, or localhost`
-    );
-  }
-}
-var CONFIG_DIR = join(homedir(), ".xapi");
-var CONFIG_FILE = join(CONFIG_DIR, "config.json");
-function loadFileConfig() {
-  if (!existsSync(CONFIG_FILE)) return {};
-  try {
-    return JSON.parse(readFileSync(CONFIG_FILE, "utf-8"));
-  } catch {
-    return {};
-  }
-}
-function getConfig() {
-  const file = loadFileConfig();
-  return {
-    actionHost: XAPI_ACTION_HOST,
-    apiKey: process.env.XAPI_KEY || process.env.XAPI_API_KEY || file.apiKey
-  };
-}
-function requireApiKey(cfg) {
-  if (!cfg.apiKey) {
-    err("API key not configured", 'Run "npx xapi-to register" to create an account, or "npx xapi-to config set apiKey=<key>" to set an existing key.');
-  }
-}
-function saveConfig(updates) {
-  const current = loadFileConfig();
-  const merged = { ...current, ...updates };
-  if (!existsSync(CONFIG_DIR)) mkdirSync(CONFIG_DIR, { recursive: true, mode: 448 });
-  writeFileSync(CONFIG_FILE, JSON.stringify(merged, null, 2), { mode: 384 });
-}
-function showConfig() {
-  const cfg = getConfig();
-  const file = loadFileConfig();
-  console.log(JSON.stringify({
-    actionHost: cfg.actionHost,
-    apiKey: cfg.apiKey ? `${cfg.apiKey.slice(0, 8)}...` : void 0,
-    source: {
-      apiKey: process.env.XAPI_KEY || process.env.XAPI_API_KEY ? "env" : file.apiKey ? "file" : "none"
-    },
-    configFile: CONFIG_FILE
-  }, null, 2));
-}
-
-// src/client.ts
-import { open, rm } from "fs/promises";
-import { resolve } from "path";
-import { Readable, Transform } from "stream";
-import { pipeline } from "stream/promises";
-var DEFAULT_TIMEOUT_MS = 3e4;
-var EXECUTE_TIMEOUT_MS = 6e4;
-var IDEMPOTENT_RETRIES = 2;
-var RETRY_BASE_DELAY_MS = 500;
-var RETRY_MAX_DELAY_MS = 8e3;
-var HttpError = class extends Error {
-  constructor(status, detail, retryAfterMs) {
-    super(`HTTP ${status}: ${detail}`);
-    this.status = status;
-    this.retryAfterMs = retryAfterMs;
-    this.name = "HttpError";
-  }
-  status;
-  retryAfterMs;
-};
-var RequestTimeoutError = class extends Error {
-  constructor(timeoutMs) {
-    super(`request timed out after ${timeoutMs}ms`);
-    this.timeoutMs = timeoutMs;
-    this.name = "RequestTimeoutError";
-  }
-  timeoutMs;
-};
-function isRetryableStatus(status) {
-  return status === 408 || status === 429 || status === 502 || status === 503 || status === 504;
-}
-function isRetryableNetworkError(e) {
-  if (!(e instanceof Error)) return false;
-  if (e instanceof HttpError || e instanceof RequestTimeoutError) return false;
-  if (e.name === "AbortError") return false;
-  return e instanceof TypeError || /network|fetch failed|econn|etimedout|eai_again|socket|dns/i.test(e.message);
-}
-function isRetryableRequestError(e) {
-  if (e instanceof HttpError) return isRetryableStatus(e.status);
-  if (e instanceof RequestTimeoutError) return true;
-  return isRetryableNetworkError(e);
-}
-function retryBaseDelayMs() {
-  const override = Number(process.env.XAPI_RETRY_BASE_MS);
-  return Number.isFinite(override) && override > 0 ? override : RETRY_BASE_DELAY_MS;
-}
-function backoffDelayMs(attempt, retryAfterMs) {
-  if (retryAfterMs !== void 0 && Number.isFinite(retryAfterMs) && retryAfterMs >= 0) {
-    return Math.min(retryAfterMs, RETRY_MAX_DELAY_MS);
-  }
-  const capped = Math.min(retryBaseDelayMs() * 2 ** attempt, RETRY_MAX_DELAY_MS);
-  return capped / 2 + Math.random() * (capped / 2);
-}
-function parseRetryAfterMs(res) {
-  const header = res.headers.get("retry-after");
-  if (!header) return void 0;
-  const seconds = Number(header);
-  if (Number.isFinite(seconds)) return seconds * 1e3;
-  const at = Date.parse(header);
-  return Number.isFinite(at) ? Math.max(0, at - Date.now()) : void 0;
-}
-function sleep(ms) {
-  return new Promise((resolve2) => setTimeout(resolve2, ms));
-}
-async function request(url, options, timeoutMs = DEFAULT_TIMEOUT_MS, retries = 0) {
-  assertAllowedHost(url);
-  let attempt = 0;
-  while (true) {
-    const controller = new AbortController();
-    let timedOut = false;
-    const timer = setTimeout(() => {
-      timedOut = true;
-      controller.abort();
-    }, timeoutMs);
-    try {
-      const res = await fetch(url, { ...options, redirect: "manual", signal: controller.signal });
-      if (res.status >= 300 && res.status < 400) {
-        throw new Error(
-          `refusing to follow redirect to "${res.headers.get("location") ?? "?"}" (would forward the API key past the host allowlist)`
-        );
-      }
-      if (!res.ok) {
-        const retryAfterMs = isRetryableStatus(res.status) ? parseRetryAfterMs(res) : void 0;
-        if (isRetryableStatus(res.status) && attempt < retries) {
-          await res.text().catch(() => "");
-          clearTimeout(timer);
-          await sleep(backoffDelayMs(attempt, retryAfterMs));
-          attempt++;
-          continue;
-        }
-        const text2 = await res.text();
-        throw new HttpError(res.status, text2.slice(0, 300), retryAfterMs);
-      }
-      if (res.status === 204) {
-        return void 0;
-      }
-      const text = await res.text();
-      if (!text.trim()) {
-        return void 0;
-      }
-      const body = JSON.parse(text);
-      if (body && typeof body === "object" && "success" in body && body.success === false) {
-        const data = body.data;
-        if (data?.statusCode === 401 || data?.error === "Unauthorized") {
-          throw new Error(
-            "Authentication failed: " + (data.message || "Invalid or missing API key") + '. Run "npx xapi-to config set apiKey=<key>" to update your key.'
-          );
-        }
-        if (data?.error === "OAuth Required" || data?.statusCode === 403 && data?.message?.includes("OAuth")) {
-          throw new Error(
-            (data.message || "OAuth authorization required") + '. Run "xapi-to oauth bind" to connect your account.'
-          );
-        }
-      }
-      return body;
-    } catch (e) {
-      if (timedOut) {
-        throw new RequestTimeoutError(timeoutMs);
-      }
-      if (isRetryableNetworkError(e) && attempt < retries) {
-        clearTimeout(timer);
-        await sleep(backoffDelayMs(attempt));
-        attempt++;
-        continue;
-      }
-      throw e;
-    } finally {
-      clearTimeout(timer);
-    }
-  }
-}
-function headers(apiKey) {
-  const h = { "Content-Type": "application/json" };
-  if (apiKey) h["XAPI-Key"] = apiKey;
-  return h;
-}
-function baseUrl(opts) {
-  return `${scheme(opts.actionHost)}://${opts.actionHost}`;
-}
-async function actionList(opts, params = {}) {
-  const url = new URL(`${baseUrl(opts)}/v1/actions`);
-  if (params.page) url.searchParams.set("page", String(params.page));
-  if (params.page_size) url.searchParams.set("page_size", String(params.page_size));
-  if (params.category) url.searchParams.set("category", params.category);
-  if (params.source) url.searchParams.set("source", params.source);
-  if (params.service_id) url.searchParams.set("service_id", params.service_id);
-  return request(
-    url.toString(),
-    { method: "GET", headers: headers(opts.apiKey) },
-    DEFAULT_TIMEOUT_MS,
-    IDEMPOTENT_RETRIES
-  );
-}
-async function actionSearch(query, opts, params = {}) {
-  const url = new URL(`${baseUrl(opts)}/v1/actions/search`);
-  url.searchParams.set("q", query);
-  if (params.category) url.searchParams.set("category", params.category);
-  if (params.source) url.searchParams.set("source", params.source);
-  if (params.page) url.searchParams.set("page", String(params.page));
-  if (params.page_size) url.searchParams.set("page_size", String(params.page_size));
-  return request(
-    url.toString(),
-    { method: "GET", headers: headers(opts.apiKey) },
-    DEFAULT_TIMEOUT_MS,
-    IDEMPOTENT_RETRIES
-  );
-}
-async function actionCategories(opts, params = {}) {
-  const url = new URL(`${baseUrl(opts)}/v1/actions/categories`);
-  if (params.source) url.searchParams.set("source", params.source);
-  return request(
-    url.toString(),
-    { method: "GET", headers: headers(opts.apiKey) },
-    DEFAULT_TIMEOUT_MS,
-    IDEMPOTENT_RETRIES
-  );
-}
-async function actionGet(id, opts) {
-  return request(
-    `${baseUrl(opts)}/v1/actions/${encodeURIComponent(id)}`,
-    { method: "GET", headers: headers(opts.apiKey) },
-    DEFAULT_TIMEOUT_MS,
-    IDEMPOTENT_RETRIES
-  );
-}
-async function actionCall(actionId, input, opts, httpMethod, retries = 0, timeoutMs = EXECUTE_TIMEOUT_MS) {
-  return request(
-    `${baseUrl(opts)}/v1/actions/execute`,
-    {
-      method: "POST",
-      headers: headers(opts.apiKey),
-      body: JSON.stringify({ action_id: actionId, ...httpMethod ? { method: httpMethod } : {}, input })
-    },
-    Math.min(timeoutMs, EXECUTE_TIMEOUT_MS),
-    retries
-  );
-}
-async function actionDownload(actionId, input, opts, outputPath, httpMethod) {
-  const controller = new AbortController();
-  let timedOut = false;
-  const timer = setTimeout(() => {
-    timedOut = true;
-    controller.abort();
-  }, EXECUTE_TIMEOUT_MS);
-  const target = resolve(outputPath);
-  let file;
-  let complete = false;
-  try {
-    try {
-      file = await open(target, "wx");
-    } catch (error) {
-      if (error?.code === "EEXIST") {
-        throw new Error(`Output file already exists: ${target}`);
-      }
-      throw error;
-    }
-    const url = `${baseUrl(opts)}/v1/actions/execute`;
-    assertAllowedHost(url);
-    const res = await fetch(url, {
-      method: "POST",
-      headers: headers(opts.apiKey),
-      body: JSON.stringify({
-        action_id: actionId,
-        ...httpMethod ? { method: httpMethod } : {},
-        input,
-        response_mode: "raw"
-      }),
-      redirect: "manual",
-      signal: controller.signal
-    });
-    if (res.status >= 300 && res.status < 400) {
-      throw new Error(
-        `refusing to follow redirect to "${res.headers.get("location") ?? "?"}" (would forward the API key past the host allowlist)`
-      );
-    }
-    if (!res.ok) {
-      const text = await res.text();
-      throw new HttpError(
-        res.status,
-        text.slice(0, 300),
-        isRetryableStatus(res.status) ? parseRetryAfterMs(res) : void 0
-      );
-    }
-    let bytes = 0;
-    if (res.body) {
-      const source = Readable.fromWeb(res.body);
-      const counter = new Transform({
-        transform(chunk, _encoding, callback) {
-          bytes += Buffer.isBuffer(chunk) ? chunk.length : Buffer.byteLength(chunk);
-          callback(null, chunk);
-        }
-      });
-      await pipeline(source, counter, file.createWriteStream());
-    } else {
-      await file.close();
-    }
-    complete = true;
-    return {
-      output: target,
-      bytes,
-      contentType: res.headers.get("content-type") || void 0,
-      contentDisposition: res.headers.get("content-disposition") || void 0,
-      status: res.status
-    };
-  } catch (error) {
-    if (timedOut) throw new RequestTimeoutError(EXECUTE_TIMEOUT_MS);
-    throw error;
-  } finally {
-    clearTimeout(timer);
-    if (!complete && file) {
-      await file.close().catch(() => void 0);
-      await rm(target, { force: true }).catch(() => void 0);
-    }
-  }
-}
-async function actionServices(opts, params = {}) {
-  const url = new URL(`${baseUrl(opts)}/v1/actions/services`);
-  if (params.page) url.searchParams.set("page", String(params.page));
-  if (params.page_size) url.searchParams.set("page_size", String(params.page_size));
-  if (params.category) url.searchParams.set("category", params.category);
-  return request(
-    url.toString(),
-    { method: "GET", headers: headers(opts.apiKey) },
-    DEFAULT_TIMEOUT_MS,
-    IDEMPOTENT_RETRIES
-  );
-}
-async function healthCheck(opts) {
-  return request(
-    `${baseUrl(opts)}/health`,
-    { method: "GET", headers: headers(opts.apiKey) },
-    5e3,
-    0
-    // health is a quick connectivity probe — fail fast, don't retry
-  );
-}
-async function loginWithApiKey(apiKey, apiHost) {
-  return request(
-    `${scheme(apiHost)}://${apiHost}/api/auth/login/apikey`,
-    {
-      method: "POST",
-      headers: { "Content-Type": "application/json" },
-      body: JSON.stringify({ apiKey })
-    },
-    DEFAULT_TIMEOUT_MS,
-    IDEMPOTENT_RETRIES
-    // auth exchange has no side effect — safe to retry
-  );
-}
-function jwtHeaders(jwtToken) {
-  return { "Content-Type": "application/json", Authorization: `Bearer ${jwtToken}` };
-}
-async function listKeys(jwtToken, apiHost) {
-  return request(
-    `${scheme(apiHost)}://${apiHost}/api/keys`,
-    { method: "GET", headers: jwtHeaders(jwtToken) },
-    DEFAULT_TIMEOUT_MS,
-    IDEMPOTENT_RETRIES
-  );
-}
-async function enableOAuthForKey(keyId, plaintextKey, jwtToken, apiHost) {
-  return request(
-    `${scheme(apiHost)}://${apiHost}/api/keys/${keyId}/enable-oauth`,
-    {
-      method: "POST",
-      headers: jwtHeaders(jwtToken),
-      body: JSON.stringify({ plaintextKey })
-    }
-  );
-}
-async function listOAuthProviders(apiHost) {
-  return request(
-    `${scheme(apiHost)}://${apiHost}/api/oauth/providers`,
-    { method: "GET", headers: { "Content-Type": "application/json" } },
-    DEFAULT_TIMEOUT_MS,
-    IDEMPOTENT_RETRIES
-  );
-}
-async function initiateOAuth(apiKeyId, providerId, jwtToken, apiHost, scopes) {
-  const body = { apiKeyId, providerId };
-  if (scopes) body.scopes = scopes;
-  return request(
-    `${scheme(apiHost)}://${apiHost}/api/oauth/authorize`,
-    {
-      method: "POST",
-      headers: jwtHeaders(jwtToken),
-      body: JSON.stringify(body)
-    }
-  );
-}
-async function listOAuthBindings(jwtToken, apiHost) {
-  return request(
-    `${scheme(apiHost)}://${apiHost}/api/oauth/bindings`,
-    { method: "GET", headers: jwtHeaders(jwtToken) },
-    DEFAULT_TIMEOUT_MS,
-    IDEMPOTENT_RETRIES
-  );
-}
-async function deleteOAuthBinding(bindingId, jwtToken, apiHost) {
-  const result = await request(
-    `${scheme(apiHost)}://${apiHost}/api/oauth/bindings/${bindingId}`,
-    { method: "DELETE", headers: jwtHeaders(jwtToken) }
-  );
-  return result ?? { success: true };
-}
+import {
+  HttpError,
+  XAPI_API_HOST,
+  XAPI_SANDBOX_HOST,
+  __export,
+  actionBatch,
+  actionCall,
+  actionCategories,
+  actionDownload,
+  actionGet,
+  actionList,
+  actionSearch,
+  actionServices,
+  actionStream,
+  assertAllowedHost,
+  deleteOAuthBinding,
+  enableOAuthForKey,
+  err,
+  getApiKeySource,
+  getConfig,
+  getFormat,
+  healthCheck,
+  initiateOAuth,
+  isRetryableRequestError,
+  listKeys,
+  listOAuthBindings,
+  listOAuthProviders,
+  loginWithApiKey,
+  output,
+  request,
+  requireApiKey,
+  sandboxAudit,
+  sandboxCreate,
+  sandboxExec,
+  sandboxExtension,
+  sandboxFileList,
+  sandboxFileRead,
+  sandboxFileWrite,
+  sandboxGet,
+  sandboxHistory,
+  sandboxList,
+  sandboxOfferings,
+  sandboxPort,
+  sandboxQuote,
+  sandboxStateAction,
+  sandboxWait,
+  saveConfig,
+  scheme,
+  showConfig
+} from "./chunk-TYY6JR6O.js";
 
 // src/codegen.ts
 var TARGET_MAP = {
@@ -618,7 +123,7 @@ function validateHost(host) {
     throw new Error(`invalid actionHost: "${host}" \u2014 must be a valid hostname with optional port`);
   }
 }
-function baseUrl2(actionHost) {
+function baseUrl(actionHost) {
   validateHost(actionHost);
   return `${scheme(actionHost)}://${actionHost}/v1/actions/execute`;
 }
@@ -634,7 +139,7 @@ function shellEscape(s) {
   return s.replace(/'/g, "'\\''");
 }
 function genCurl(params) {
-  const url = baseUrl2(params.actionHost);
+  const url = baseUrl(params.actionHost);
   const body = jsonBody(params.actionId, params.input, params.method);
   return [
     "# Set XAPI_KEY env var or replace with your key",
@@ -645,7 +150,7 @@ function genCurl(params) {
   ].join("\n");
 }
 function genPython(lib, params) {
-  const url = baseUrl2(params.actionHost);
+  const url = baseUrl(params.actionHost);
   const payload = { action_id: params.actionId, ...params.method ? { method: params.method } : {}, input: params.input };
   return [
     `# pip install ${lib}`,
@@ -665,7 +170,7 @@ function genPython(lib, params) {
   ].join("\n");
 }
 function genJavaScriptFetch(params) {
-  const url = baseUrl2(params.actionHost);
+  const url = baseUrl(params.actionHost);
   const body = jsonBody(params.actionId, params.input, params.method);
   return [
     "// Set XAPI_KEY env var or replace with your key",
@@ -681,7 +186,7 @@ function genJavaScriptFetch(params) {
   ].join("\n");
 }
 function genJavaScriptAxios(params) {
-  const url = baseUrl2(params.actionHost);
+  const url = baseUrl(params.actionHost);
   const body = jsonBody(params.actionId, params.input, params.method);
   return [
     "// npm install axios",
@@ -702,7 +207,7 @@ function genJavaScriptAxios(params) {
   ].join("\n");
 }
 function genTypescriptFetch(params) {
-  const url = baseUrl2(params.actionHost);
+  const url = baseUrl(params.actionHost);
   const body = jsonBody(params.actionId, params.input, params.method);
   return [
     "// Set XAPI_KEY env var or replace with your key",
@@ -719,7 +224,7 @@ function genTypescriptFetch(params) {
   ].join("\n");
 }
 function genGo(params) {
-  const url = baseUrl2(params.actionHost);
+  const url = baseUrl(params.actionHost);
   const body = jsonBody(params.actionId, params.input, params.method);
   const escaped = body.replace(/`/g, '` + "`" + `');
   return [
@@ -801,6 +306,7 @@ function generateCode(target, params) {
 
 // src/commands/action.ts
 var VALID_SOURCES = ["capability", "api"];
+var VALID_SEARCH_SORTS = ["default", "relevance", "price"];
 var LIST_HELP = `xapi-to list - List all actions
 
 USAGE
@@ -829,12 +335,50 @@ FLAGS
   --category <name>         Filter by category
   --page N                  Page number (default: 1)
   --page-size N             Results per page
+  --sort default|relevance|price
+                            Recommended (default), strongest match, or lowest
+                            comparable price after exact-id/local-match guards
+  --include-all-versions    Include active non-default major versions
   --format json|pretty|table  Output format
 
 EXAMPLES
   xapi-to search twitter
   xapi-to search "tweet detail" --source api
+  xapi-to search "tweet detail" --sort relevance
+  xapi-to search weather --sort price
   xapi-to search weather --category utility --format table
+  xapi-to search twitter --include-all-versions
+`;
+var CATEGORIES_HELP = `xapi-to categories - List action categories
+
+USAGE
+  xapi-to categories [flags]
+
+FLAGS
+  --source capability|api   Filter by source type
+  --format json|pretty|table  Output format
+`;
+var SERVICES_HELP = `xapi-to services - List services
+
+USAGE
+  xapi-to services [flags]
+
+FLAGS
+  --category <name>         Filter by category
+  --page N                  Page number
+  --page-size N             Results per page
+  --format json|pretty|table  Output format
+`;
+var GET_BATCH_HELP = `xapi-to get-batch - Get multiple action schemas
+
+USAGE
+  xapi-to get-batch <id> [id ...] [flags]
+
+FLAGS
+  --format json|pretty|table  Output format
+
+EXAMPLES
+  xapi-to get-batch twitter.tweet_detail crypto.token.price
 `;
 var GET_HELP = `xapi-to get - Get action schema
 
@@ -878,6 +422,7 @@ FLAGS
   --input <json>            Input payload as JSON (required for execution)
   --method GET|POST|...     Override HTTP method
   --output <path>           Save a raw binary response to a new file
+  --stream                  Forward the action's HTTP SSE response unchanged
   --code <target>           Generate code snippet instead of executing
   --format json|pretty|table  Output format
 
@@ -901,6 +446,7 @@ CODE TARGETS
 EXAMPLES
   xapi-to call twitter.tweet_detail --input '{"tweet_id":"1234567890"}'
   xapi-to call openrouter.audio_speech --input '{"body":{"input":"Hello"}}' --output speech.mp3
+  xapi-to call ai.text.chat.fast --input '{"messages":[{"role":"user","content":"Hello"}]}' --stream
   xapi-to call twitter.tweet_detail --input '{"tweet_id":"123"}' --code py
   xapi-to call twitter.tweet_detail --input '{"tweet_id":"123"}' --code curl --format pretty
 `;
@@ -931,6 +477,31 @@ function getSource(flags) {
   }
   return flags.source;
 }
+function getSearchSort(flags) {
+  const value = flags.sort;
+  if (value === void 0) return void 0;
+  if (value === "true") {
+    err("--sort requires a value: default, relevance, or price");
+  }
+  if (!VALID_SEARCH_SORTS.includes(value)) {
+    err(`invalid --sort value: "${value}". Must be default, relevance, or price.`);
+  }
+  return value;
+}
+function positiveIntegerFlag(value, name) {
+  if (value === void 0) return void 0;
+  if (!/^\d+$/.test(value) || Number(value) < 1) {
+    err(`${name} must be a positive integer`);
+  }
+  return Number(value);
+}
+function httpMethodFlag(value) {
+  if (value === void 0) return void 0;
+  if (value === "true" || !/^[A-Za-z]+$/.test(value)) {
+    err("--method requires an HTTP method, e.g. --method POST");
+  }
+  return value.toUpperCase();
+}
 async function actionList2(args, flags) {
   showHelpIfRequested(flags, LIST_HELP);
   const cfg = getConfig();
@@ -938,8 +509,8 @@ async function actionList2(args, flags) {
   try {
     const res = await actionList(cfg, {
       source: getSource(flags),
-      page: flags.page ? parseInt(flags.page) : void 0,
-      page_size: flags["page-size"] ? parseInt(flags["page-size"]) : void 0,
+      page: positiveIntegerFlag(flags.page, "--page"),
+      page_size: positiveIntegerFlag(flags["page-size"], "--page-size"),
       category: flags.category,
       service_id: flags["service-id"]
     });
@@ -965,15 +536,24 @@ async function actionSearch2(args, flags) {
   showHelpIfRequested(flags, SEARCH_HELP);
   const query = args[0];
   if (!query) err("usage: xapi-to search <query>");
+  const requestedSort = getSearchSort(flags);
   const cfg = getConfig();
   const fmt = flags.format || getFormat();
   try {
     const res = await actionSearch(query, cfg, {
       source: getSource(flags),
       category: flags.category,
-      page: flags.page ? parseInt(flags.page) : void 0,
-      page_size: flags["page-size"] ? parseInt(flags["page-size"]) : void 0
+      page: positiveIntegerFlag(flags.page, "--page"),
+      page_size: positiveIntegerFlag(flags["page-size"], "--page-size"),
+      // Backward-compatible aliases from the original feature branch.
+      include_all_versions: ["include-all-versions", "all-versions", "include-history"].some((name) => flags[name] === "true"),
+      sort: requestedSort
     });
+    if (requestedSort && res.sort !== requestedSort) {
+      throw new Error(
+        res.sort ? `backend applied sort "${res.sort}" instead of requested "${requestedSort}"` : "backend does not support search sorting yet; deploy the updated backend before using --sort"
+      );
+    }
     const results = res.results || [];
     if (fmt === "table") {
       output(results.map((a) => ({
@@ -983,7 +563,8 @@ async function actionSearch2(args, flags) {
         source: a.source ?? "",
         category: a.meta?.category ?? "",
         status: a.status ?? "",
-        cost: a.meta?.cost ?? ""
+        price: a.meta?.pricing?.comparable ? a.meta.pricing.listed_price : "",
+        pricing: a.meta?.pricing?.billing_type ?? ""
       })), "table");
     } else {
       output(res, flags.format);
@@ -993,6 +574,7 @@ async function actionSearch2(args, flags) {
   }
 }
 async function actionCategories2(args, flags) {
+  showHelpIfRequested(flags, CATEGORIES_HELP);
   const cfg = getConfig();
   const fmt = flags.format || getFormat();
   try {
@@ -1007,12 +589,13 @@ async function actionCategories2(args, flags) {
   }
 }
 async function actionServices2(args, flags) {
+  showHelpIfRequested(flags, SERVICES_HELP);
   const cfg = getConfig();
   const fmt = flags.format || getFormat();
   try {
     const res = await actionServices(cfg, {
-      page: flags.page ? parseInt(flags.page) : void 0,
-      page_size: flags["page-size"] ? parseInt(flags["page-size"]) : void 0,
+      page: positiveIntegerFlag(flags.page, "--page"),
+      page_size: positiveIntegerFlag(flags["page-size"], "--page-size"),
       category: flags.category
     });
     const services = res.services || [];
@@ -1037,11 +620,11 @@ async function actionGet2(args, flags) {
   const id = args[0];
   if (!id) err("usage: xapi-to get <id> [--method GET|POST|DELETE|...]");
   if (flags.code) validateCodeFlag(flags);
+  const methodFilter = httpMethodFlag(flags.method);
   const cfg = getConfig();
   try {
     const res = await actionGet(id, cfg);
     const actions = Array.isArray(res) ? res : [res];
-    const methodFilter = flags.method?.toUpperCase();
     const filtered = methodFilter ? actions.filter((a) => a.method?.toUpperCase() === methodFilter) : actions;
     if (filtered.length === 0) {
       err(`no endpoint found for method "${methodFilter}" in action "${id}"`);
@@ -1064,15 +647,30 @@ async function actionGet2(args, flags) {
     err("get failed", e.message);
   }
 }
+async function actionBatchGet(args, flags) {
+  showHelpIfRequested(flags, GET_BATCH_HELP);
+  if (args.length === 0) err("usage: xapi-to get-batch <id> [id ...]");
+  if (args.length > 100) err("get-batch accepts at most 100 action IDs");
+  const cfg = getConfig();
+  try {
+    const res = await actionBatch(args, cfg);
+    output(res, flags.format);
+  } catch (e) {
+    err("get-batch failed", e.message);
+  }
+}
 async function actionCall2(args, flags) {
   showHelpIfRequested(flags, CALL_HELP);
   const id = args[0];
   if (!id) err(`usage: xapi-to call <id> --input '{"key":"val"}'`);
   if (flags.code) validateCodeFlag(flags);
   if (flags.output === "true") err("--output requires a file path");
+  const stream = flags.stream === "true" || flags.stream === "1" || flags.stream === "yes";
   if (flags.code && flags.output) {
     err("--output cannot be combined with --code");
   }
+  if (stream && flags.output) err("--stream cannot be combined with --output");
+  if (stream && flags.code) err("--stream cannot be combined with --code");
   const cfg = getConfig();
   let input = {};
   if (flags.input) {
@@ -1086,7 +684,7 @@ async function actionCall2(args, flags) {
     }
   }
   const { method: inputMethod, ...cleanInput } = input;
-  const method = flags.method?.toUpperCase() || (typeof inputMethod === "string" ? inputMethod.toUpperCase() : void 0);
+  const method = httpMethodFlag(flags.method) || (typeof inputMethod === "string" ? inputMethod.toUpperCase() : void 0);
   if (flags.code) {
     const result = generateCode(flags.code, { actionId: id, input: cleanInput, actionHost: cfg.actionHost, method });
     outputCode(result, flags);
@@ -1094,6 +692,10 @@ async function actionCall2(args, flags) {
   }
   requireApiKey(cfg);
   try {
+    if (stream) {
+      await actionStream(id, cleanInput, cfg, method);
+      return;
+    }
     if (flags.output) {
       const result = await actionDownload(
         id,
@@ -1126,11 +728,12 @@ async function actionCall2(args, flags) {
 var config_exports = {};
 __export(config_exports, {
   CONFIG_HELP: () => CONFIG_HELP,
+  HEALTH_HELP: () => HEALTH_HELP,
   configHealth: () => configHealth,
   configSet: () => configSet,
   configShow: () => configShow
 });
-import { readFileSync as readFileSync2 } from "fs";
+import { readFileSync } from "fs";
 var CONFIG_HELP = `xapi-to config - Manage CLI configuration
 
 USAGE
@@ -1144,14 +747,23 @@ COMMANDS
 FLAGS
   --format json|pretty|table   Output format
 
+ENVIRONMENT OVERRIDES
+  XAPI_KEY takes precedence over XAPI_API_KEY, which takes precedence over the file.
+  Saving a file key does not replace an active environment-variable key.
+
 EXAMPLES
   xapi-to config show
   xapi-to config set apiKey=xapi_abc123
   echo "$XAPI_KEY" | xapi-to config set apiKey=-   # keeps the key out of shell history
   xapi-to config health
 `;
+var HEALTH_HELP = `xapi-to health - Check backend connectivity
+
+USAGE
+  xapi-to health [--format json|pretty|table]
+`;
 async function configShow(args, flags) {
-  showConfig();
+  output(showConfig(), flags.format);
 }
 async function configSet(args, flags) {
   if (args.length === 0) err("usage: xapi-to config set apiKey=<key>");
@@ -1164,15 +776,27 @@ async function configSet(args, flags) {
     if (key !== "apiKey") err(`unknown config key: ${key} (only apiKey is configurable)`);
     let value = arg.slice(eq + 1);
     if (value === "-") {
-      value = readFileSync2(0, "utf-8").trim();
+      value = readFileSync(0, "utf-8").trim();
     }
     if (!value) err("apiKey is empty");
     updates.apiKey = value;
   }
+  const sourceBeforeSave = getApiKeySource();
   saveConfig(updates);
-  console.log(JSON.stringify({ ok: true, updated: Object.keys(updates) }));
+  const source = sourceBeforeSave === "XAPI_KEY" || sourceBeforeSave === "XAPI_API_KEY" ? sourceBeforeSave : "file";
+  output({
+    ok: true,
+    updated: Object.keys(updates),
+    effective: source === "file",
+    source,
+    ...source === "XAPI_KEY" || source === "XAPI_API_KEY" ? { warning: `${source} still overrides the saved file key` } : {}
+  }, flags.format);
 }
 async function configHealth(args, flags) {
+  if (flags.help) {
+    console.log(HEALTH_HELP);
+    return;
+  }
   const cfg = getConfig();
   const start = Date.now();
   try {
@@ -1185,6 +809,30 @@ async function configHealth(args, flags) {
 }
 
 // src/commands/register.ts
+var REGISTER_HELP = `xapi-to register - Create a new xAPI account
+
+USAGE
+  xapi-to register [referral-code] [flags]
+
+FLAGS
+  --referral-code <code>    Submit an inviter's referral code
+  --referralCode <code>     Alias for --referral-code
+  --force                   Replace an existing file-based API key
+  --format json|pretty|table  Output format
+
+The API key is saved to ~/.xapi/config.json. If XAPI_KEY or XAPI_API_KEY is set,
+unset it before registering because environment variables override the saved file.
+`;
+function validateRegisterResponse(value) {
+  const res = value;
+  if (!res || typeof res.apiKey !== "string" || !res.apiKey.trim()) {
+    throw new Error("invalid register response: missing apiKey");
+  }
+  if (typeof res.referralCode !== "string" || !res.user || typeof res.user.id !== "string") {
+    throw new Error("invalid register response: missing account details");
+  }
+  return res;
+}
 async function registerAccount(referralCode) {
   assertAllowedHost(XAPI_API_HOST);
   const controller = new AbortController();
@@ -1194,39 +842,57 @@ async function registerAccount(referralCode) {
       method: "POST",
       headers: { "Content-Type": "application/json" },
       body: JSON.stringify(referralCode ? { referralCode } : {}),
-      signal: controller.signal
+      signal: controller.signal,
+      redirect: "manual"
     });
+    if (res.status >= 300 && res.status < 400) {
+      throw new Error(`refusing to follow redirect to "${res.headers.get("location") ?? "?"}"`);
+    }
     if (!res.ok) {
       const text = await res.text();
       throw new Error(`HTTP ${res.status}: ${text.slice(0, 300)}`);
     }
-    return res.json();
+    return validateRegisterResponse(await res.json());
   } finally {
     clearTimeout(timer);
   }
 }
 async function register(args, flags) {
+  if (flags.help) {
+    console.log(REGISTER_HELP);
+    return;
+  }
   try {
     const cfg = getConfig();
     const force = flags.force === "true" || flags.force === "1" || flags.force === "yes";
+    const source = getApiKeySource();
+    if (source === "XAPI_KEY" || source === "XAPI_API_KEY") {
+      err(
+        "register cannot replace an API key supplied by an environment variable",
+        `Unset ${source} first; it would continue to override the newly saved key.`
+      );
+    }
     if (cfg.apiKey && !force) {
       err("register would overwrite existing apiKey", 'Run "xapi-to register --force" to create a new account and replace the saved key.');
     }
     const rawReferral = flags["referral-code"] ?? flags["referralCode"] ?? args[0];
-    const referralCode = typeof rawReferral === "string" && rawReferral !== "true" && rawReferral.length > 0 ? rawReferral : void 0;
+    if (rawReferral === "true") {
+      err("--referral-code requires a code");
+    }
+    const referralCode = typeof rawReferral === "string" && rawReferral.length > 0 ? rawReferral : void 0;
     const res = await registerAccount(referralCode);
+    const bindUrl = res.bindUrl || res.claimUrl;
     saveConfig({ apiKey: res.apiKey });
     output({
       apiKey: res.apiKey,
       user: res.user,
       referralCode: res.referralCode,
-      claim: {
-        code: res.claimCode,
-        sessionId: res.claimSessionId,
-        url: res.claimUrl
-      },
-      tweetTemplate: res.tweetTemplate,
-      ...referralCode ? { referredBy: referralCode } : {},
+      bindUrl,
+      // Keep the backend's legacy field visible while clients migrate to bindUrl.
+      claimUrl: res.claimUrl || bindUrl,
+      // The backend may accept the registration while ignoring an invalid code,
+      // so only report that the code was submitted, not that a referral exists.
+      ...referralCode ? { referralCodeProvided: referralCode } : {},
       note: force && cfg.apiKey ? "apiKey replaced in ~/.xapi/config.json" : "apiKey saved to ~/.xapi/config.json"
     }, flags.format);
   } catch (e) {
@@ -1236,23 +902,50 @@ async function register(args, flags) {
 
 // src/commands/topup.ts
 var TOPUP_BASE_URL = "https://www.xapi.to/topup/payment";
+var TOPUP_HELP = `xapi-to topup - Generate a private payment URL
+
+USAGE
+  xapi-to topup [--amount <usd>] [--method stripe|x402]
+
+The generated URL can contain your API key. Do not log or share it.
+`;
 async function topup(args, flags) {
+  if (flags.help) {
+    console.log(TOPUP_HELP);
+    return;
+  }
   const cfg = getConfig();
   const url = new URL(TOPUP_BASE_URL);
   if (cfg.apiKey) url.searchParams.set("apikey", cfg.apiKey);
-  if (flags.method) url.searchParams.set("method", flags.method);
+  if (flags.method) {
+    if (!["stripe", "x402"].includes(flags.method)) {
+      err("invalid --method value", "Expected stripe or x402.");
+    }
+    url.searchParams.set("method", flags.method);
+  }
   const amountStr = flags.amount || args[0];
   if (amountStr) {
-    const amountUsd = parseFloat(amountStr);
-    if (!isNaN(amountUsd) && amountUsd > 0) {
-      url.searchParams.set("amount", String(amountUsd));
+    const normalizedAmount = amountStr.trim();
+    const amountUsd = Number(normalizedAmount);
+    if (!/^(?:\d+(?:\.\d*)?|\.\d+)$/.test(normalizedAmount) || !Number.isFinite(amountUsd) || amountUsd <= 0) {
+      err("invalid top-up amount", "Expected a positive USD number, e.g. --amount 10.");
     }
+    url.searchParams.set("amount", String(amountUsd));
   }
   output({ url: url.toString() }, flags.format);
 }
 
 // src/commands/balance.ts
+var BALANCE_HELP = `xapi-to balance - Show the current account balance
+
+USAGE
+  xapi-to balance [--format json|pretty|table]
+`;
 async function balance(args, flags) {
+  if (flags.help) {
+    console.log(BALANCE_HELP);
+    return;
+  }
   const cfg = getConfig();
   requireApiKey(cfg);
   let token;
@@ -1289,9 +982,10 @@ __export(oauth_exports, {
 });
 import { spawnSync } from "child_process";
 function openBrowser(url) {
-  const cmd = process.platform === "win32" ? "start" : process.platform === "darwin" ? "open" : "xdg-open";
+  const cmd = process.platform === "win32" ? "rundll32.exe" : process.platform === "darwin" ? "open" : "xdg-open";
+  const args = process.platform === "win32" ? ["url.dll,FileProtocolHandler", url] : [url];
   try {
-    spawnSync(cmd, [url], { stdio: "ignore" });
+    spawnSync(cmd, args, { stdio: "ignore" });
   } catch {
   }
 }
@@ -1335,9 +1029,11 @@ async function findCurrentKeyRecord(plaintextKey, jwtToken) {
     throw new Error("No API keys found for this account");
   }
   const prefix = plaintextKey.substring(0, 7);
-  const match = keys.find((k) => k.keyPreview.startsWith(prefix));
+  const suffix = plaintextKey.slice(-4);
+  const expectedPreview = `${prefix}****${suffix}`;
+  const match = keys.find((k) => k.keyPreview === expectedPreview);
   if (match) return match;
-  if (keys.length === 1) return keys[0];
+  if (keys.length === 1 && !keys[0].keyPreview.includes("****")) return keys[0];
   throw new Error(
     `Current API key (${prefix}...) was not found in your account keys. Run "xapi-to config set apiKey=<key>" with a valid key before binding OAuth.`
   );
@@ -1454,13 +1150,20 @@ FLAGS
 EXAMPLES
   xapi-to oauth bind
   xapi-to oauth bind --provider twitter
-  xapi-to oauth bind --scopes "tweet.read users.read"
+  xapi-to oauth providers                    # inspect current default scopes
+  xapi-to oauth bind --scopes "<scope list>"  # override only when needed
   xapi-to oauth status
   xapi-to oauth status --format pretty
   xapi-to oauth unbind abc123
   xapi-to oauth providers
 `;
 async function oauthBind(args, flags) {
+  if (flags.provider === "true") {
+    err("--provider requires a provider name, e.g. --provider twitter");
+  }
+  if (flags.scopes === "true") {
+    err("--scopes requires a space-separated scope list");
+  }
   const cfg = getConfig();
   requireApiKey(cfg);
   const apiKey = cfg.apiKey;
@@ -1518,6 +1221,16 @@ async function oauthBind(args, flags) {
     const authorizationStartedAt = /* @__PURE__ */ new Date();
     const result = await initiateOAuth(keyRecord.id, provider.id, jwtToken, XAPI_API_HOST, scopes);
     const { authorizationUrl } = result;
+    let authorizationTarget;
+    try {
+      authorizationTarget = new URL(authorizationUrl);
+    } catch {
+      throw new Error("OAuth provider returned an invalid authorization URL");
+    }
+    const localHttp = authorizationTarget.protocol === "http:" && ["localhost", "127.0.0.1", "::1"].includes(authorizationTarget.hostname);
+    if (authorizationTarget.protocol !== "https:" && !localHttp) {
+      throw new Error(`OAuth provider returned an unsupported authorization URL protocol: ${authorizationTarget.protocol}`);
+    }
     if (isTTY) {
       if (!headerPrinted) {
         console.error(`
@@ -1704,7 +1417,7 @@ function parsePositiveInt(raw, flagName) {
   }
   return n;
 }
-function sleep2(ms) {
+function sleep(ms) {
   if (ms <= 0) return Promise.resolve();
   return new Promise((resolve2) => setTimeout(resolve2, ms));
 }
@@ -1801,13 +1514,891 @@ async function taskWait(args, flags) {
     }
     const desiredWaitMs = retryDelayMs ?? intervalMs;
     const waitMs = deadline !== void 0 ? Math.min(desiredWaitMs, Math.max(0, deadline - Date.now())) : desiredWaitMs;
-    await sleep2(waitMs);
+    await sleep(waitMs);
   }
 }
 function taskHelp() {
   return TASK_HELP;
 }
 
+// src/commands/sandbox.ts
+import { randomUUID } from "crypto";
+import { readFile, open, rm } from "fs/promises";
+import { resolve } from "path";
+var SANDBOX_HELP = `xapi-to sandbox - Managed, auditable cloud sandboxes
+
+USAGE
+  xapi-to sandbox <command> [args] [flags]
+
+QUICK START
+  sandbox run --command <shell>     Quote, create, wait, execute, and terminate
+  sandbox run -- <command...>       Positional shorthand after a bare --
+
+LIFECYCLE
+  offerings                         List available provider offerings
+  quote                             Quote requirements without creating
+  list                              List sandbox instances
+  history                           Search paginated instance history
+  get <id>                          Get instance state, usage, and cost
+  create                            Create from a quote, offering, or requirements
+  wait <id>                         Wait for a state (default: RUNNING)
+  exec <id> --command <shell>       Execute a shell command
+  suspend|resume|terminate <id>     Change state and wait for completion
+
+FILES, PORTS, AUDIT
+  file write <id> <remote> --file <local>
+  file write <id> <remote> --content <text>
+  file read <id> <remote> [--output <local>]
+  file list <id> [--path <remote>] [--depth N]
+  port <id> <port>                  Get a public URL for a listening port
+  extension <id> <extension-id>     Invoke an offering-declared extension
+  audit <id> [--kind operations|events|usageSegments|billingPeriods]
+
+SELECTION FLAGS
+  --provider auto|daytona|cf-edge|e2b|runpod|runloop|modal|vc-sandbox|fly|blaxel|cubesandbox
+                                      Pin a provider gateway (default: auto)
+  --capabilities exec,files,ports   Required capabilities
+  --cpu N  --memory N  --volume N  Minimum resources
+  --gpu-count N  --gpu-model NAME   GPU requirements
+  --regions a,b                     Allowed regions
+  --requirements <json>             Complete requirements object
+  --max-hourly-usd N                Price ceiling (sandbox run default: 0.20)
+
+COMMON FLAGS
+  --host <sandbox.xapi.to>          Override gateway; must be *.xapi.to/localhost
+  --wait-timeout 5m                 State wait timeout (default: 5m)
+  --interval 2s                     State polling interval (default: 2s)
+  --format json|pretty|table        Output format
+
+HISTORY FLAGS
+  --state ALL|ACTIVE|HISTORY|RUNNING|SUSPENDED|TERMINATED|FAILED
+  --search <text>  --from <ISO time>  --to <ISO time>
+  --page N  --page-size N           Pagination (page size: 1-100)
+
+SAFETY
+  sandbox run terminates in finally, including command failure. Use --keep only
+  when you intentionally want billing to continue after the CLI exits.
+
+EXAMPLES
+  xapi-to sandbox offerings --format table
+  xapi-to sandbox quote --capabilities exec,files --max-hourly-usd 0.20
+  xapi-to sandbox run --command 'python3 -c "print(6*7)"'
+  xapi-to sandbox run --provider cf-edge --capabilities exec,files,ports --command 'pwd'
+  xapi-to sandbox exec <id> -- npm test
+  xapi-to sandbox extension <id> runpod.connection_info --input '{}'
+  xapi-to sandbox terminate <id>
+`;
+var SANDBOX_COMMAND_HELP = {
+  offerings: `USAGE
+  xapi-to sandbox offerings [--provider NAME] [--format json|pretty|table]
+
+Lists current resources, capabilities, lifecycle support, and hourly prices.
+This command does not create or bill an instance.`,
+  quote: `USAGE
+  xapi-to sandbox quote [selection flags] [--max-hourly-usd N]
+
+SELECTION
+  --capabilities exec,files,ports   Required capabilities
+  --cpu N  --memory N  --volume N  Minimum resources
+  --gpu-count N  --gpu-model NAME   GPU requirements
+  --regions a,b                     Allowed regions
+  --requirements <json>             Complete requirements object
+  --max-hourly-usd N                Hard hourly price ceiling
+
+Returns a short-lived quote without creating or billing an instance.`,
+  list: `USAGE
+  xapi-to sandbox list [--provider NAME] [--format json|pretty|table]
+
+Lists current Sandbox instances visible to the configured xAPI key.`,
+  history: `USAGE
+  xapi-to sandbox history [--state STATE] [--search TEXT] [--from ISO] [--to ISO]
+    [--page N] [--page-size 1-100] [--format json|pretty|table]
+
+Searches current and historical Sandbox instances with server-side pagination.`,
+  get: `USAGE
+  xapi-to sandbox get <id> [--format json|pretty|table]
+
+Returns current state, operations, usage, billing, and service-calculated cost.`,
+  create: `USAGE
+  xapi-to sandbox create [selection flags] [--max-hourly-usd N] [--wait]
+
+SELECTION MODES
+  --quote-id ID                      Create from an existing quote
+  --offering-id ID                   Create an exact offering (cannot use a price ceiling)
+  --requirements <json>              Create from requirements
+  --capabilities/--cpu/--memory/...  Requirements shortcuts
+
+CONTROL
+  --idempotency-key KEY              Stable retry key; generated and returned if omitted
+  --metadata <json>                  Instance metadata
+  --resume-on-access                 Request automatic resume on supported providers
+  --wait                             Wait until RUNNING
+  --wait-timeout 5m  --interval 2s   Polling controls
+
+On a wait failure, the error includes the instance ID and recovery instructions.`,
+  wait: `USAGE
+  xapi-to sandbox wait <id> [--state RUNNING[,STATE]]
+    [--wait-timeout 5m] [--interval 2s]
+
+State names are case-insensitive and validated before polling.`,
+  exec: `USAGE
+  xapi-to sandbox exec <id> --command <shell> [--cwd PATH] [--timeout SECONDS]
+    [--background]
+  xapi-to sandbox exec <id> -- <command...>
+
+Executes a command and maps a remote non-zero exit code to the local process.
+--background requires offering.capabilities.backgroundExec=true and returns a
+provider-managed session immediately; use it for long-running Web servers.`,
+  file: `USAGE
+  xapi-to sandbox file write <id> <remote> (--file <local>|--content <text>)
+  xapi-to sandbox file read <id> <remote> [--output <local>]
+  xapi-to sandbox file list <id> [--path <remote>] [--depth N]
+
+Binary local files are transferred as base64. --output never overwrites a file.`,
+  port: `USAGE
+  xapi-to sandbox port <id> <1-65535>
+
+Returns the provider's temporary public URL for a listening instance port.`,
+  extension: `USAGE
+  xapi-to sandbox extension <id> <extension-id> [--input <json>]
+    [--idempotency-key KEY]
+
+Invoke only extension IDs declared by the selected offering.`,
+  audit: `USAGE
+  xapi-to sandbox audit <id> [--kind operations|events|usageSegments|billingPeriods]
+    [--page N] [--page-size 1-100] [--format json|pretty|table]`,
+  suspend: `USAGE
+  xapi-to sandbox suspend <id> [--no-wait] [--idempotency-key KEY]
+    [--wait-timeout 5m] [--interval 2s]
+
+Check offering lifecycle support before suspending; storage may continue billing.`,
+  resume: `USAGE
+  xapi-to sandbox resume <id> [--no-wait] [--idempotency-key KEY]
+    [--wait-timeout 5m] [--interval 2s]`,
+  terminate: `USAGE
+  xapi-to sandbox terminate <id> [--no-wait] [--idempotency-key KEY]
+    [--wait-timeout 5m] [--interval 2s]
+
+Waits for TERMINATED or FAILED by default.`,
+  run: `USAGE
+  xapi-to sandbox run --command <shell> [selection flags] [run flags]
+  xapi-to sandbox run [selection flags] -- <command...>
+
+RUN FLAGS
+  --max-hourly-usd N                Hard ceiling (default: 0.20)
+  --timeout SECONDS                 Remote command timeout (default: 60)
+  --cwd PATH                        Remote working directory
+  --metadata <json>                 Instance metadata for audit correlation
+  --idempotency-key KEY             Stable create retry key
+  --wait-timeout 5m  --interval 2s  Lifecycle polling controls
+  --keep                            Keep the instance running and billing
+
+Runs quote -> create -> wait -> exec -> terminate. Cleanup also runs after
+command failure, SIGINT, or SIGTERM.`
+};
+var COMMON_FLAGS = ["help", "host", "provider", "format"];
+var SELECTION_FLAGS = [
+  "capabilities",
+  "cpu",
+  "memory",
+  "volume",
+  "gpu-count",
+  "gpu-model",
+  "regions",
+  "requirements",
+  "max-hourly-usd"
+];
+var POLL_FLAGS = ["wait-timeout", "interval"];
+function help(flags, command) {
+  if (flags.help) {
+    console.log(`xapi-to sandbox ${command}
+
+${SANDBOX_COMMAND_HELP[command]}
+
+COMMON
+  --host HOST  --provider NAME  --format json|pretty|table  --help`);
+    process.exit(0);
+  }
+}
+function validateFlags(flags, command, allowed = []) {
+  const valid = /* @__PURE__ */ new Set([...COMMON_FLAGS, ...allowed]);
+  const unknown = Object.keys(flags).filter((flag) => !valid.has(flag));
+  if (unknown.length) {
+    err(`unknown flag${unknown.length > 1 ? "s" : ""} for sandbox ${command}: ${unknown.map((flag) => `--${flag}`).join(", ")}`, {
+      hint: `run xapi-to sandbox ${command} --help`,
+      validFlags: [...valid].sort().map((flag) => `--${flag}`)
+    });
+  }
+  if (flags.format && !["json", "pretty", "table"].includes(flags.format)) {
+    err("--format must be one of: json, pretty, table");
+  }
+}
+function collection(data) {
+  if (Array.isArray(data)) return data;
+  if (Array.isArray(data?.items)) return data.items;
+  if (Array.isArray(data?.data)) return data.data;
+  return data ? [data] : [];
+}
+function capability(value, name) {
+  const enabled = value?.capabilities?.[name];
+  return enabled === true ? "yes" : enabled === false ? "no" : "";
+}
+function sandboxTableRows(view, data) {
+  if (view === "offerings") {
+    return collection(data).map((item) => ({
+      id: item.id,
+      name: item.name,
+      cpu: item.resources?.cpu,
+      memoryGiB: item.resources?.memoryGiB,
+      volumeGiB: item.resources?.volumeGiB,
+      gpu: Array.isArray(item.resources?.gpu) ? item.resources.gpu.map((gpu) => `${gpu.count || 1}x ${gpu.model || "GPU"}`).join(", ") : "",
+      exec: capability(item, "exec"),
+      background: capability(item, "backgroundExec"),
+      files: capability(item, "files"),
+      ports: capability(item, "ports"),
+      suspend: item.lifecycle?.suspension?.supported === true ? "yes" : "no",
+      hourlyUsd: item.billing?.estimatedHourlyUsdByState?.RUNNING,
+      extensions: Array.isArray(item.capabilities?.extensionIds) ? item.capabilities.extensionIds.join(",") : ""
+    }));
+  }
+  if (view === "quote") {
+    return collection(data).map((item) => ({
+      quoteId: item.quoteId || item.id,
+      offeringId: item.offeringId || item.offering?.id,
+      offering: item.offering?.name || item.offeringName,
+      provider: item.provider?.name || item.providerName || item.provider,
+      hourlyUsd: item.estimatedHourlyUsd || item.hourlyUsd || item.offering?.billing?.estimatedHourlyUsdByState?.RUNNING,
+      expiresAt: item.expiresAt
+    }));
+  }
+  if (view === "run") {
+    return collection(data).map((item) => ({
+      instanceId: item.instanceId,
+      provider: item.provider,
+      offering: item.offering?.name || item.offering,
+      exitCode: item.result?.exitCode,
+      finalState: item.finalState,
+      cleanup: item.cleanup?.state || (item.cleanup?.kept ? "KEPT" : ""),
+      totalCost: item.totalCost
+    }));
+  }
+  return collection(data).map((item) => ({
+    id: item.id || item.instanceId,
+    state: item.observedState || item.state || item.finalState,
+    desiredState: item.desiredState,
+    offering: item.offering?.name || item.offeringName || item.offeringId,
+    provider: item.provider?.name || item.providerName || item.provider,
+    createdAt: item.createdAt,
+    updatedAt: item.updatedAt,
+    totalCost: item.totalCost
+  }));
+}
+function sandboxOutput(view, data, flags) {
+  const format = flags.format || getFormat();
+  if (format === "table") {
+    output(sandboxTableRows(view, data), "table");
+    return;
+  }
+  output(data, flags.format);
+}
+function flagValue(flags, name) {
+  const value = flags[name];
+  if (value === "true") err(`--${name} requires a value`);
+  return value;
+}
+function booleanFlag(flags, name) {
+  const raw = flags[name];
+  if (raw === void 0 || raw === "false") return false;
+  if (raw === "true") return true;
+  err(`--${name} must be a boolean flag or --${name}=true|false`);
+}
+function positiveNumber(raw, name) {
+  if (raw === void 0) return void 0;
+  const value = Number(raw);
+  if (!Number.isFinite(value) || value <= 0) err(`--${name} must be a positive number`);
+  return value;
+}
+function positiveInteger(raw, name) {
+  const value = positiveNumber(raw, name);
+  if (value !== void 0 && !Number.isInteger(value)) err(`--${name} must be a positive integer`);
+  return value;
+}
+function durationMs(raw, fallback, name) {
+  if (raw === void 0) return fallback;
+  if (raw === "true") err(`--${name} requires a value`);
+  const match = raw.trim().toLowerCase().match(/^(\d+)(ms|s|m|h)?$/);
+  if (!match || Number(match[1]) <= 0) err(`--${name} must be a duration like 500ms, 2s, 5m, or 1h`);
+  const value = Number(match[1]);
+  return value * { ms: 1, s: 1e3, m: 6e4, h: 36e5 }[match[2] || "ms"];
+}
+function jsonObject(raw, name) {
+  try {
+    const value = JSON.parse(raw);
+    if (!value || typeof value !== "object" || Array.isArray(value)) throw new Error("expected an object");
+    return value;
+  } catch (error) {
+    err(`--${name} must be a valid JSON object`, error.message);
+  }
+}
+function csv(raw) {
+  if (!raw) return void 0;
+  return raw.split(",").map((value) => value.trim()).filter(Boolean);
+}
+function sandboxOptions(flags) {
+  const cfg = getConfig();
+  requireApiKey(cfg);
+  const host = flagValue(flags, "host") || cfg.sandboxHost || XAPI_SANDBOX_HOST;
+  const provider = flagValue(flags, "provider");
+  return { sandboxHost: host, apiKey: cfg.apiKey, ...provider ? { provider } : {} };
+}
+function requirementsFromFlags(flags, defaultCapabilities) {
+  const requirements = flagValue(flags, "requirements") ? jsonObject(flagValue(flags, "requirements"), "requirements") : {};
+  const capabilities = csv(flagValue(flags, "capabilities")) || (Array.isArray(requirements.capabilities) ? void 0 : defaultCapabilities);
+  const regions = csv(flagValue(flags, "regions"));
+  const cpu = positiveNumber(flagValue(flags, "cpu"), "cpu");
+  const memory = positiveNumber(flagValue(flags, "memory"), "memory");
+  const volume = positiveNumber(flagValue(flags, "volume"), "volume");
+  const gpuCount = positiveInteger(flagValue(flags, "gpu-count"), "gpu-count");
+  const gpuModel = flagValue(flags, "gpu-model");
+  if (gpuModel && gpuCount === void 0 && !(Number(requirements.gpu?.count) > 0)) {
+    err("--gpu-model requires --gpu-count (or requirements.gpu.count)");
+  }
+  if (capabilities?.length) requirements.capabilities = capabilities;
+  if (regions?.length) requirements.regions = regions;
+  if (cpu !== void 0) requirements.cpu = { ...requirements.cpu || {}, min: cpu };
+  if (memory !== void 0) requirements.memoryGiB = { ...requirements.memoryGiB || {}, min: memory };
+  if (volume !== void 0) requirements.volumeGiB = { ...requirements.volumeGiB || {}, min: volume };
+  if (gpuCount !== void 0 || gpuModel) {
+    requirements.gpu = {
+      ...requirements.gpu || {},
+      ...gpuCount !== void 0 ? { count: gpuCount } : {},
+      ...gpuModel ? { model: gpuModel } : {}
+    };
+  }
+  return requirements;
+}
+function quoteBody(flags, defaultCapabilities) {
+  const max = positiveNumber(flagValue(flags, "max-hourly-usd"), "max-hourly-usd");
+  return {
+    requirements: requirementsFromFlags(flags, defaultCapabilities),
+    ...max !== void 0 ? { maxEstimatedHourlyUsd: max.toFixed(8) } : {}
+  };
+}
+function createDefaultCapabilities(flags) {
+  if (flagValue(flags, "requirements") || flagValue(flags, "provider") === "runpod" || flagValue(flags, "gpu-count") || flagValue(flags, "gpu-model")) return void 0;
+  return ["exec"];
+}
+function waitSettings(flags) {
+  return {
+    timeoutMs: durationMs(flags["wait-timeout"], 3e5, "wait-timeout"),
+    intervalMs: durationMs(flags.interval, 2e3, "interval")
+  };
+}
+function commandFrom(args, flags, usage) {
+  const fromFlag = flagValue(flags, "command");
+  const command = fromFlag ?? args.join(" ");
+  if (!command.trim()) err(usage);
+  return command;
+}
+function instanceId(args, usage) {
+  if (!args[0]) err(usage);
+  return args[0];
+}
+async function terminateAndWait(opts, id, flags) {
+  const { timeoutMs, intervalMs } = waitSettings(flags);
+  const deadline = Date.now() + timeoutMs;
+  const clientIdempotencyKey = flagValue(flags, "idempotency-key") || `cli:terminate:${randomUUID()}`;
+  let operation;
+  while (Date.now() < deadline) {
+    const detail2 = await sandboxGet(opts, id);
+    if (["TERMINATED", "FAILED"].includes(String(detail2.observedState))) {
+      return { operation, sandbox: detail2, clientIdempotencyKey };
+    }
+    try {
+      operation = await sandboxStateAction(opts, id, "terminate", {
+        idempotencyKey: clientIdempotencyKey
+      });
+      break;
+    } catch (error) {
+      if (!(error instanceof HttpError) || error.status !== 409) throw error;
+      await new Promise((resolve2) => setTimeout(resolve2, intervalMs));
+    }
+  }
+  const remaining = Math.max(1, deadline - Date.now());
+  let detail;
+  try {
+    detail = await sandboxWait(opts, id, ["TERMINATED", "FAILED"], remaining, intervalMs);
+  } catch (error) {
+    if (!(error instanceof HttpError) || error.status !== 404 || !opts.provider) throw error;
+    detail = await sandboxWait(
+      { ...opts, provider: void 0 },
+      id,
+      ["TERMINATED", "FAILED"],
+      Math.max(1, deadline - Date.now()),
+      intervalMs
+    );
+  }
+  return { operation, sandbox: detail, clientIdempotencyKey };
+}
+function cleanupSummary(cleanup) {
+  if (!cleanup) return void 0;
+  if (cleanup.error) return { error: cleanup.error };
+  return {
+    operationId: cleanup.operation?.id,
+    operationStatus: cleanup.sandbox?.operations?.find?.((item) => item.type === "TERMINATE")?.status || cleanup.operation?.status,
+    state: cleanup.sandbox?.observedState,
+    totalCost: cleanup.sandbox?.totalCost
+  };
+}
+function sandboxResultExitCode(result) {
+  const value = result?.exitCode;
+  if (typeof value !== "number" || value === 0) return void 0;
+  return Math.min(255, Math.max(1, Math.trunc(value)));
+}
+async function sandboxOfferings2(args, flags) {
+  help(flags, "offerings");
+  validateFlags(flags, "offerings");
+  try {
+    sandboxOutput("offerings", await sandboxOfferings(sandboxOptions(flags)), flags);
+  } catch (error) {
+    err("sandbox offerings failed", error.message);
+  }
+}
+async function sandboxQuote2(args, flags) {
+  help(flags, "quote");
+  validateFlags(flags, "quote", SELECTION_FLAGS);
+  try {
+    sandboxOutput("quote", await sandboxQuote(sandboxOptions(flags), quoteBody(flags)), flags);
+  } catch (error) {
+    err("sandbox quote failed", error.message);
+  }
+}
+async function sandboxList2(args, flags) {
+  help(flags, "list");
+  validateFlags(flags, "list");
+  try {
+    sandboxOutput("instances", await sandboxList(sandboxOptions(flags)), flags);
+  } catch (error) {
+    err("sandbox list failed", error.message);
+  }
+}
+async function sandboxHistory2(args, flags) {
+  help(flags, "history");
+  validateFlags(flags, "history", ["state", "search", "from", "to", "page", "page-size"]);
+  const state = flagValue(flags, "state");
+  const allowedStates = ["ALL", "ACTIVE", "HISTORY", "PROVISIONING", "RUNNING", "SUSPENDED", "TERMINATED", "FAILED", "UNKNOWN"];
+  if (state && !allowedStates.includes(state.toUpperCase())) {
+    err(`--state must be one of: ${allowedStates.join(", ")}`);
+  }
+  const page = positiveInteger(flagValue(flags, "page"), "page") || 1;
+  const pageSize = positiveInteger(flagValue(flags, "page-size"), "page-size") || 100;
+  if (pageSize > 100) err("--page-size must be at most 100");
+  try {
+    sandboxOutput("instances", await sandboxHistory(sandboxOptions(flags), {
+      ...state ? { state: state.toUpperCase() } : {},
+      ...flagValue(flags, "search") ? { search: flagValue(flags, "search") } : {},
+      ...flagValue(flags, "from") ? { from: flagValue(flags, "from") } : {},
+      ...flagValue(flags, "to") ? { to: flagValue(flags, "to") } : {},
+      page,
+      pageSize
+    }), flags);
+  } catch (error) {
+    err("sandbox history failed", error.message);
+  }
+}
+async function sandboxGet2(args, flags) {
+  help(flags, "get");
+  validateFlags(flags, "get");
+  const id = instanceId(args, "usage: xapi-to sandbox get <id>");
+  try {
+    sandboxOutput("detail", await sandboxGet(sandboxOptions(flags), id), flags);
+  } catch (error) {
+    err("sandbox get failed", error.message);
+  }
+}
+async function sandboxCreate2(args, flags) {
+  help(flags, "create");
+  validateFlags(flags, "create", [
+    ...SELECTION_FLAGS,
+    ...POLL_FLAGS,
+    "quote-id",
+    "offering-id",
+    "metadata",
+    "idempotency-key",
+    "resume-on-access",
+    "wait"
+  ]);
+  const wait = booleanFlag(flags, "wait");
+  const resumeOnAccess = booleanFlag(flags, "resume-on-access");
+  const opts = sandboxOptions(flags);
+  const quoteId = flagValue(flags, "quote-id");
+  const offeringId = flagValue(flags, "offering-id");
+  const maxHourly = flagValue(flags, "max-hourly-usd");
+  const requirementFlags = [
+    "requirements",
+    "capabilities",
+    "cpu",
+    "memory",
+    "volume",
+    "gpu-count",
+    "gpu-model",
+    "regions"
+  ].filter((name) => flagValue(flags, name) !== void 0);
+  if (quoteId && offeringId) err("--quote-id and --offering-id are mutually exclusive");
+  if ((quoteId || offeringId) && requirementFlags.length) {
+    err(`${quoteId ? "--quote-id" : "--offering-id"} cannot be combined with requirement flags`, {
+      conflictingFlags: requirementFlags.map((name) => `--${name}`)
+    });
+  }
+  if (quoteId && maxHourly) {
+    err("--max-hourly-usd cannot be combined with --quote-id; the quote already fixes the price");
+  }
+  if (offeringId && maxHourly) {
+    err("--max-hourly-usd cannot be combined with --offering-id; create from requirements to enforce a price ceiling");
+  }
+  const idempotencyKey = flagValue(flags, "idempotency-key") || `cli:create:${randomUUID()}`;
+  let created;
+  try {
+    let selection;
+    if (quoteId) selection = { quoteId };
+    else if (offeringId) selection = { offeringId };
+    else if (maxHourly) {
+      const quoted = await sandboxQuote(opts, quoteBody(flags, createDefaultCapabilities(flags)));
+      if (!quoted?.quoteId) throw new Error("quote response did not include quoteId");
+      selection = { quoteId: quoted.quoteId };
+    } else selection = { requirements: requirementsFromFlags(flags, createDefaultCapabilities(flags)) };
+    const metadata = flagValue(flags, "metadata") ? jsonObject(flagValue(flags, "metadata"), "metadata") : { client: "xapi-cli" };
+    created = await sandboxCreate(opts, {
+      selection,
+      metadata,
+      idempotencyKey,
+      policy: { resumeOnAccess }
+    });
+    let result = created;
+    if (wait && created.id) {
+      const settings = waitSettings(flags);
+      result = await sandboxWait(opts, created.id, ["RUNNING"], settings.timeoutMs, settings.intervalMs);
+    }
+    sandboxOutput("detail", { ...result, clientIdempotencyKey: idempotencyKey }, flags);
+  } catch (error) {
+    let latest = created;
+    if (created?.id) {
+      try {
+        latest = await sandboxGet(opts, created.id);
+      } catch {
+      }
+    }
+    err("sandbox create failed", {
+      message: error.message,
+      instanceId: created?.id,
+      observedState: latest?.observedState,
+      clientIdempotencyKey: idempotencyKey,
+      recovery: created?.id ? {
+        inspect: `xapi-to sandbox get ${created.id}`,
+        terminate: `xapi-to sandbox terminate ${created.id}`
+      } : {
+        retry: `repeat the create command with --idempotency-key ${idempotencyKey}`,
+        reconcile: "xapi-to sandbox history --state ACTIVE --page-size 100"
+      }
+    });
+  }
+}
+async function sandboxWait2(args, flags) {
+  help(flags, "wait");
+  validateFlags(flags, "wait", ["state", ...POLL_FLAGS]);
+  const id = instanceId(args, "usage: xapi-to sandbox wait <id> [--state RUNNING]");
+  const allowedStates = ["PROVISIONING", "RUNNING", "SUSPENDING", "SUSPENDED", "RESUMING", "TERMINATING", "TERMINATED", "FAILED", "UNKNOWN"];
+  const wanted = (csv(flagValue(flags, "state")) || ["RUNNING"]).map((state) => state.toUpperCase());
+  const invalid = wanted.filter((state) => !allowedStates.includes(state));
+  if (invalid.length) err(`--state must contain only: ${allowedStates.join(", ")}`);
+  const settings = waitSettings(flags);
+  try {
+    output(await sandboxWait(sandboxOptions(flags), id, wanted, settings.timeoutMs, settings.intervalMs), flags.format);
+  } catch (error) {
+    err("sandbox wait failed", error.message);
+  }
+}
+async function sandboxExec2(args, flags) {
+  help(flags, "exec");
+  validateFlags(flags, "exec", ["command", "timeout", "cwd", "background"]);
+  const id = instanceId(args, "usage: xapi-to sandbox exec <id> --command <shell>");
+  const command = commandFrom(args.slice(1), flags, "usage: xapi-to sandbox exec <id> --command <shell>");
+  const timeoutSeconds = positiveInteger(flagValue(flags, "timeout"), "timeout") || 60;
+  const background = booleanFlag(flags, "background");
+  try {
+    const result = await sandboxExec(sandboxOptions(flags), id, {
+      command,
+      timeoutSeconds,
+      ...flagValue(flags, "cwd") ? { cwd: flagValue(flags, "cwd") } : {},
+      ...background ? { background: true } : {}
+    });
+    output(result, flags.format);
+    const exitCode = sandboxResultExitCode(result);
+    if (exitCode !== void 0) process.exitCode = exitCode;
+  } catch (error) {
+    err("sandbox exec failed", error.message);
+  }
+}
+async function sandboxFile(args, flags) {
+  help(flags, "file");
+  validateFlags(flags, "file", ["file", "content", "output", "path", "depth"]);
+  const [action, id, remote] = args;
+  if (!action || !id) err("usage: xapi-to sandbox file <write|read|list> <id> [remote-path]");
+  const opts = sandboxOptions(flags);
+  try {
+    if (action === "write") {
+      if (!remote) err("usage: xapi-to sandbox file write <id> <remote-path> (--file <local>|--content <text>)");
+      const local = flagValue(flags, "file");
+      const inline = flagValue(flags, "content");
+      if (Boolean(local) === Boolean(inline)) err("provide exactly one of --file or --content");
+      const body = local ? { path: remote, content: (await readFile(local)).toString("base64"), encoding: "base64" } : { path: remote, content: inline, encoding: "utf8" };
+      output(await sandboxFileWrite(opts, id, body), flags.format);
+      return;
+    }
+    if (action === "read") {
+      if (!remote) err("usage: xapi-to sandbox file read <id> <remote-path> [--output <local>]");
+      const outputPath = flagValue(flags, "output");
+      const result = await sandboxFileRead(opts, id, remote, outputPath ? "base64" : "utf8");
+      if (!outputPath) {
+        output(result, flags.format);
+        return;
+      }
+      const target = resolve(outputPath);
+      const file = await open(target, "wx");
+      let complete = false;
+      try {
+        const data = result?.encoding === "base64" ? Buffer.from(String(result.content || ""), "base64") : Buffer.from(String(result?.content || ""), "utf8");
+        await file.writeFile(data);
+        complete = true;
+        output({ output: target, bytes: data.length, path: remote }, flags.format);
+      } finally {
+        await file.close();
+        if (!complete) await rm(target, { force: true });
+      }
+      return;
+    }
+    if (action === "list") {
+      const depth = positiveInteger(flagValue(flags, "depth"), "depth") || 2;
+      output(await sandboxFileList(opts, id, flagValue(flags, "path") || remote || ".", depth), flags.format);
+      return;
+    }
+    err(`unknown sandbox file command: ${action}`);
+  } catch (error) {
+    err(`sandbox file ${action} failed`, error.message);
+  }
+}
+async function sandboxPort2(args, flags) {
+  help(flags, "port");
+  validateFlags(flags, "port");
+  const id = instanceId(args, "usage: xapi-to sandbox port <id> <port>");
+  const port = positiveInteger(args[1], "port");
+  if (!port || port > 65535) err("port must be between 1 and 65535");
+  try {
+    output(await sandboxPort(sandboxOptions(flags), id, port), flags.format);
+  } catch (error) {
+    err("sandbox port failed", error.message);
+  }
+}
+async function sandboxExtension2(args, flags) {
+  help(flags, "extension");
+  validateFlags(flags, "extension", ["input", "idempotency-key"]);
+  const id = instanceId(args, "usage: xapi-to sandbox extension <id> <extension-id> --input <json>");
+  const extensionId = args[1];
+  if (!extensionId) err("usage: xapi-to sandbox extension <id> <extension-id> --input <json>");
+  if (!/^[a-z0-9][a-z0-9._-]{0,119}$/i.test(extensionId)) err("invalid Sandbox extension id");
+  const input = flagValue(flags, "input") ? jsonObject(flagValue(flags, "input"), "input") : {};
+  const clientIdempotencyKey = flagValue(flags, "idempotency-key") || `cli:extension:${extensionId}:${randomUUID()}`;
+  try {
+    const result = await sandboxExtension(sandboxOptions(flags), id, extensionId, {
+      input,
+      idempotencyKey: clientIdempotencyKey
+    });
+    output({ ...result, clientIdempotencyKey }, flags.format);
+  } catch (error) {
+    err("sandbox extension failed", {
+      message: error.message,
+      clientIdempotencyKey,
+      retry: `repeat with --idempotency-key ${clientIdempotencyKey}`
+    });
+  }
+}
+async function sandboxAudit2(args, flags) {
+  help(flags, "audit");
+  validateFlags(flags, "audit", ["kind", "page", "page-size"]);
+  const id = instanceId(args, "usage: xapi-to sandbox audit <id> [--kind operations]");
+  const kind = flagValue(flags, "kind") || "operations";
+  const allowed = ["operations", "events", "usageSegments", "billingPeriods"];
+  if (!allowed.includes(kind)) err(`--kind must be one of: ${allowed.join(", ")}`);
+  const page = positiveInteger(flagValue(flags, "page"), "page") || 1;
+  const pageSize = positiveInteger(flagValue(flags, "page-size"), "page-size") || 100;
+  if (pageSize > 100) err("--page-size must be at most 100");
+  try {
+    output(await sandboxAudit(sandboxOptions(flags), id, kind, page, pageSize), flags.format);
+  } catch (error) {
+    err("sandbox audit failed", error.message);
+  }
+}
+async function sandboxState(action, args, flags) {
+  help(flags, action);
+  validateFlags(flags, action, [...POLL_FLAGS, "no-wait", "idempotency-key"]);
+  const id = instanceId(args, `usage: xapi-to sandbox ${action} <id>`);
+  const opts = sandboxOptions(flags);
+  const noWait = booleanFlag(flags, "no-wait");
+  const clientIdempotencyKey = flagValue(flags, "idempotency-key") || `cli:${action}:${randomUUID()}`;
+  try {
+    if (action === "terminate" && !noWait) {
+      output(await terminateAndWait(opts, id, flags), flags.format);
+      return;
+    }
+    const operation = await sandboxStateAction(opts, id, action, {
+      idempotencyKey: clientIdempotencyKey
+    });
+    if (noWait) {
+      output({ ...operation, clientIdempotencyKey }, flags.format);
+      return;
+    }
+    const wanted = action === "suspend" ? ["SUSPENDED"] : action === "resume" ? ["RUNNING"] : ["TERMINATED", "FAILED"];
+    const settings = waitSettings(flags);
+    const detail = await sandboxWait(opts, id, wanted, settings.timeoutMs, settings.intervalMs);
+    output({ operation, sandbox: detail, clientIdempotencyKey }, flags.format);
+  } catch (error) {
+    err(`sandbox ${action} failed`, {
+      message: error.message,
+      instanceId: id,
+      clientIdempotencyKey,
+      recovery: {
+        inspect: `xapi-to sandbox get ${id}`,
+        retry: `repeat with --idempotency-key ${clientIdempotencyKey}`
+      }
+    });
+  }
+}
+async function sandboxRun(args, flags) {
+  help(flags, "run");
+  validateFlags(flags, "run", [
+    ...SELECTION_FLAGS,
+    ...POLL_FLAGS,
+    "command",
+    "timeout",
+    "cwd",
+    "metadata",
+    "keep",
+    "idempotency-key"
+  ]);
+  const command = commandFrom(args, flags, "usage: xapi-to sandbox run --command <shell>");
+  const opts = sandboxOptions(flags);
+  const maxHourly = flagValue(flags, "max-hourly-usd") || "0.20";
+  positiveNumber(maxHourly, "max-hourly-usd");
+  const timeoutSeconds = positiveInteger(flagValue(flags, "timeout"), "timeout") || 60;
+  const settings = waitSettings(flags);
+  const idempotencyKey = flagValue(flags, "idempotency-key") || `cli:run:${randomUUID()}`;
+  const metadata = flagValue(flags, "metadata") ? jsonObject(flagValue(flags, "metadata"), "metadata") : {};
+  const keep = booleanFlag(flags, "keep");
+  let id;
+  let failure;
+  let quote;
+  let created;
+  let ready;
+  let result;
+  let cleanup;
+  let interruptedBy;
+  const waitAbort = new AbortController();
+  const interrupt = (signal) => {
+    interruptedBy = signal;
+    waitAbort.abort();
+  };
+  const interruptSigint = () => interrupt("SIGINT");
+  const interruptSigterm = () => interrupt("SIGTERM");
+  const throwIfInterrupted = () => {
+    if (interruptedBy) throw new Error(`interrupted by ${interruptedBy}`);
+  };
+  process.once("SIGINT", interruptSigint);
+  process.once("SIGTERM", interruptSigterm);
+  try {
+    quote = await sandboxQuote(
+      opts,
+      quoteBody({ ...flags, "max-hourly-usd": maxHourly }, ["exec"]),
+      waitAbort.signal
+    );
+    if (!quote?.quoteId) throw new Error("quote response did not include quoteId");
+    throwIfInterrupted();
+    created = await sandboxCreate(opts, {
+      selection: { quoteId: quote.quoteId },
+      metadata: { ...metadata, client: "xapi-cli", command: "sandbox run" },
+      policy: { resumeOnAccess: false },
+      idempotencyKey
+    });
+    id = created?.id;
+    if (!id) throw new Error("create response did not include sandbox id");
+    throwIfInterrupted();
+    ready = await sandboxWait(
+      opts,
+      id,
+      ["RUNNING"],
+      settings.timeoutMs,
+      settings.intervalMs,
+      waitAbort.signal
+    );
+    throwIfInterrupted();
+    result = await sandboxExec(opts, id, {
+      command,
+      timeoutSeconds,
+      ...flagValue(flags, "cwd") ? { cwd: flagValue(flags, "cwd") } : {}
+    }, waitAbort.signal);
+    throwIfInterrupted();
+  } catch (error) {
+    failure = error;
+  } finally {
+    if (id && !keep) {
+      try {
+        cleanup = await terminateAndWait(opts, id, flags);
+      } catch (cleanupError) {
+        cleanup = { error: cleanupError.message };
+        if (!failure) failure = new Error(`command completed but cleanup failed: ${cleanupError.message}`);
+      }
+    }
+    process.removeListener("SIGINT", interruptSigint);
+    process.removeListener("SIGTERM", interruptSigterm);
+  }
+  if (failure) {
+    err("sandbox run failed", {
+      message: failure?.message || String(failure),
+      instanceId: id,
+      clientIdempotencyKey: idempotencyKey,
+      cleanup: keep ? { kept: true, warning: "billing continues until terminated" } : cleanupSummary(cleanup),
+      recovery: id ? { inspect: `xapi-to sandbox get ${id}`, terminate: `xapi-to sandbox terminate ${id}` } : {
+        reconcile: "xapi-to sandbox history --state ACTIVE --page-size 100",
+        retryCreateWithSameKey: idempotencyKey
+      }
+    });
+  }
+  let finalDetail;
+  let finalReadError;
+  if (id) {
+    try {
+      finalDetail = await sandboxGet(opts, id);
+    } catch (error) {
+      finalReadError = error.message;
+    }
+  }
+  const summary = {
+    instanceId: id,
+    clientIdempotencyKey: idempotencyKey,
+    provider: opts.provider || "auto",
+    offering: quote?.offering,
+    createdState: created?.observedState,
+    readyState: ready?.observedState,
+    result,
+    cleanup: keep ? { kept: true, warning: "billing continues until terminated" } : cleanupSummary(cleanup),
+    finalState: finalDetail?.observedState || cleanup?.sandbox?.observedState,
+    totalCost: finalDetail?.totalCost || cleanup?.sandbox?.totalCost,
+    ...finalReadError ? { finalReadError } : {}
+  };
+  sandboxOutput("run", summary, flags);
+  const remoteExitCode = sandboxResultExitCode(result);
+  if (remoteExitCode !== void 0) process.exitCode = remoteExitCode;
+}
+
 // src/args.ts
 function parseArgs(argv) {
   const positional = [];
@@ -1859,10 +2450,12 @@ COMMANDS
     --page N  --page-size N         Pagination
     --category <name>               Filter by category
     --service-id <id>               Filter by service
-  search <query>                    Search actions by keyword
+  search <query>                    Search actions by keyword (--all-versions: \u542B\u975E\u9ED8\u8BA4\u4F46\u4ECD\u5728\u8DD1\u7684\u5927\u7248\u672C)
     --source capability|api         Filter by source type
     --category <name>               Filter by category
     --page N  --page-size N         Pagination
+    --sort default|relevance|price  Recommended, strongest match, or comparable price
+    --include-all-versions          Include active non-default major versions
   categories                        List all action categories
     --source capability|api         Filter by source type
   services                          List all services
@@ -1870,9 +2463,11 @@ COMMANDS
     --category <name>               Filter by category
   get <id> [--method GET|POST|...]   Get action schema (filter by HTTP method)
     --code <target>                  Generate code snippet (curl, py, js, ts, go)
+  get-batch <id> [id ...]           Get up to 100 action schemas
   call <id> --input '{"key":"val"}'  Execute an action
     --method GET|POST|...            Override HTTP method
     --output <path>                   Save a raw binary response to a new file
+    --stream                          Forward HTTP SSE frames unchanged
     --code <target>                  Generate code snippet instead of executing
     Variants: python.requests, python.httpx, javascript.fetch, javascript.axios
 
@@ -1882,6 +2477,12 @@ COMMANDS
     --timeout <duration>             Max wait duration, e.g. 10m
     --max-attempts <number>          Max poll attempts
 
+  sandbox <command>                  Managed cloud sandbox lifecycle
+    run --command <shell>            Quote, create, execute, and auto-terminate
+    offerings|quote|list|history|get|create|wait|exec
+    file|port|extension|audit|suspend|resume|terminate
+    Run "xapi-to sandbox --help" for selection and safety flags
+
   oauth bind [--provider twitter]   Bind Twitter OAuth to your API key
   oauth status                      List current OAuth bindings
   oauth unbind <binding-id>         Remove an OAuth binding
@@ -1889,7 +2490,7 @@ COMMANDS
 
   register [referral-code]          Create a new user account (apiKey saved automatically)
     --referral-code <code>          Register with an inviter's referral code (also: --referralCode, or as positional arg)
-    --force                         Replace an existing saved apiKey
+    --force                         Replace an existing file-based apiKey
   balance                           Show current account balance
   topup [--amount <usd>] [--method stripe|x402]   Generate payment URL
 
@@ -1904,9 +2505,13 @@ GLOBAL FLAGS
   --help                            Show help (use with a command for details, e.g. xapi-to get --help)
 
 ENV VARS
-  XAPI_KEY       API key (header: XAPI-Key)
+  XAPI_KEY          API key (highest precedence; header: XAPI-Key)
+  XAPI_API_KEY      Compatible API key alias
   XAPI_ACTION_HOST   Action service host (default: action.xapi.to)
+  XAPI_API_HOST      Auth/account service host (default: api.xapi.to)
+  XAPI_SANDBOX_HOST  Sandbox gateway host (default: sandbox.xapi.to)
   XAPI_OUTPUT        Default output format
+  XAPI_TRANSFER_IDLE_TIMEOUT_MS  SSE/download idle timeout (default: 60000)
 
 EXAMPLES
   xapi-to register
@@ -1916,6 +2521,7 @@ EXAMPLES
   xapi-to list --source capability
   xapi-to search twitter --source api
   xapi-to get twitter.tweet_detail
+  xapi-to get-batch twitter.tweet_detail crypto.token.price
   xapi-to get twitter.tweet_detail --code curl
   xapi-to get twitter.tweet_detail --code py --format pretty
   xapi-to call twitter.tweet_detail --input '{"tweet_id":"1234567890"}'
@@ -1923,6 +2529,7 @@ EXAMPLES
   xapi-to call twitter.tweet_detail --input '{"tweet_id":"1234567890"}' --code python
   xapi-to task poll 550e8400-e29b-41d4-a716-446655440000
   xapi-to task wait 550e8400-e29b-41d4-a716-446655440000 --interval 2s --timeout 10m
+  xapi-to sandbox run --command 'python3 -c "print(6*7)"'
   xapi-to categories
   xapi-to services --format table
   xapi-to config set apiKey=xapi_abc123
@@ -1934,7 +2541,16 @@ async function main() {
     console.log(HELP);
     process.exit(0);
   }
-  if (flags.format) process.env.XAPI_OUTPUT = flags.format;
+  if (flags.format) {
+    if (!["json", "pretty", "table"].includes(flags.format)) {
+      console.error(JSON.stringify({
+        error: `invalid --format value: ${flags.format}`,
+        hint: "expected json, pretty, or table"
+      }));
+      process.exit(1);
+    }
+    process.env.XAPI_OUTPUT = flags.format;
+  }
   const [cmd, ...rest] = positional;
   switch (cmd) {
     // ── Action commands (top-level) ──
@@ -1948,6 +2564,8 @@ async function main() {
       return actionServices2(rest, flags);
     case "get":
       return actionGet2(rest, flags);
+    case "get-batch":
+      return actionBatchGet(rest, flags);
     case "call":
       return actionCall2(rest, flags);
     case "task": {
@@ -1967,6 +2585,54 @@ async function main() {
       }
       break;
     }
+    case "sandbox": {
+      if (rest.length === 0) {
+        console.log(SANDBOX_HELP);
+        process.exit(0);
+      }
+      const [subCmd, ...subRest] = rest;
+      switch (subCmd) {
+        case "offerings":
+          return sandboxOfferings2(subRest, flags);
+        case "quote":
+          return sandboxQuote2(subRest, flags);
+        case "list":
+          return sandboxList2(subRest, flags);
+        case "history":
+          return sandboxHistory2(subRest, flags);
+        case "get":
+          return sandboxGet2(subRest, flags);
+        case "create":
+          return sandboxCreate2(subRest, flags);
+        case "wait":
+          return sandboxWait2(subRest, flags);
+        case "exec":
+          return sandboxExec2(subRest, flags);
+        case "file":
+          return sandboxFile(subRest, flags);
+        case "port":
+          return sandboxPort2(subRest, flags);
+        case "extension":
+          return sandboxExtension2(subRest, flags);
+        case "audit":
+          return sandboxAudit2(subRest, flags);
+        case "suspend":
+          return sandboxState("suspend", subRest, flags);
+        case "resume":
+          return sandboxState("resume", subRest, flags);
+        case "terminate":
+          return sandboxState("terminate", subRest, flags);
+        case "run":
+          return sandboxRun(subRest, flags);
+        default:
+          console.error(JSON.stringify({
+            error: `unknown sandbox command: ${subCmd}`,
+            hint: "run xapi-to sandbox --help"
+          }));
+          process.exit(1);
+      }
+      break;
+    }
     // ── OAuth commands ──
     case "oauth": {
       if (flags.help || rest.length === 0) {