@xanots/sdk 0.0.9 → 0.0.10

package/dist/status-command-AL47VG7H.js

@@ -0,0 +1,162 @@
+import {
+  getEphemeral,
+  isExpired
+} from "./chunk-VNQM3V2C.js";
+import {
+  isMachineOutput,
+  writeJson
+} from "./chunk-NUQCEOKA.js";
+import {
+  getEnvironment,
+  readEphemeralState
+} from "./chunk-K5IOND4K.js";
+import {
+  getAccessToken
+} from "./chunk-QKM4U5UK.js";
+import "./chunk-FE5I6S6N.js";
+import {
+  fetchOrExplain,
+  httpFailure
+} from "./chunk-3IGNIP6R.js";
+import "./chunk-GNPVYOPB.js";
+import {
+  formatExpiration,
+  formatFields,
+  stdoutStyle
+} from "./chunk-EZG76F7R.js";
+
+// src/emit/status-command.ts
+var TIMEOUT_MS = 3e4;
+function asString(v) {
+  return typeof v === "string" && v !== "" ? v : void 0;
+}
+async function getJson(url, auth, action) {
+  const res = await fetchOrExplain(
+    url,
+    {
+      headers: { accept: "application/json", Authorization: `Bearer ${auth.access_token}` },
+      signal: AbortSignal.timeout(TIMEOUT_MS)
+    },
+    action,
+    TIMEOUT_MS
+  );
+  const text = await res.text();
+  if (!res.ok) throw new Error(httpFailure(action, res, text));
+  try {
+    return JSON.parse(text);
+  } catch {
+    throw new Error(`${action}: could not parse the response as JSON:
+${text.slice(0, 200)}`);
+  }
+}
+async function readWorkspace(auth) {
+  const list = await getJson(`${auth.instance}/api:meta/workspace`, auth, "workspace list");
+  const all = Array.isArray(list) ? list : [];
+  const match = all.find((w) => w.id === auth.workspaceId);
+  if (match === void 0) {
+    return {
+      id: auth.workspaceId,
+      name: null,
+      credential: auth.credentialType,
+      note: `this credential cannot see workspace ${auth.workspaceId} \u2014 run \`xanots workspace details\` for the ids that would work`
+    };
+  }
+  return {
+    id: auth.workspaceId,
+    name: asString(match.name) ?? null,
+    credential: auth.credentialType
+  };
+}
+async function readEnvironment(auth, cwd) {
+  const tracked = getEnvironment(readEphemeralState(cwd), auth.workspaceId);
+  if (tracked === void 0) return null;
+  const summary = await getEphemeral(auth, { parentWorkspaceId: auth.workspaceId, name: tracked.name });
+  if (summary === null) {
+    return {
+      name: tracked.name,
+      display: tracked.display,
+      url: tracked.url,
+      state: null,
+      expiresAt: tracked.expires_at,
+      alive: false
+    };
+  }
+  return {
+    name: summary.name,
+    display: summary.display,
+    url: summary.url,
+    state: summary.state ?? null,
+    expiresAt: summary.expiresAt,
+    alive: !isExpired(summary.expiresAt)
+  };
+}
+async function readStatus(args, cwd = process.cwd()) {
+  let auth;
+  try {
+    auth = await getAccessToken(args);
+  } catch {
+    return { signedIn: false, instance: null, user: null, workspace: null, environment: null };
+  }
+  const me = await getJson(`${auth.instance}/api:meta/auth/me`, auth, "whoami");
+  return {
+    signedIn: true,
+    instance: auth.instance,
+    user: {
+      id: typeof me.id === "number" ? me.id : void 0,
+      name: asString(me.name),
+      email: asString(me.email)
+    },
+    workspace: await readWorkspace(auth),
+    environment: await readEnvironment(auth, cwd)
+  };
+}
+function prettyStatus(status) {
+  const s = stdoutStyle();
+  if (!status.signedIn) {
+    return `
+${formatFields([
+      ["Signed in", `${s.bold("no")} ${s.dim("\xB7 run `xanots login`")}`]
+    ])}`;
+  }
+  const who = [status.user?.name, status.user?.email && `<${status.user.email}>`].filter(Boolean).join(" ");
+  const rows = [
+    ["Signed in", who !== "" ? who : s.dim("(unknown user)")],
+    ["Instance", s.bold(s.cyan(status.instance ?? ""))]
+  ];
+  const ws = status.workspace;
+  if (ws !== null) {
+    rows.push([
+      "Workspace",
+      `${ws.id}${ws.name === null ? "" : ` \xB7 ${ws.name}`} ${s.dim(`\xB7 ${ws.credential}`)}`
+    ]);
+    if (ws.note !== void 0) rows.push(["", s.dim(ws.note)]);
+  }
+  const env = status.environment;
+  if (env === null) {
+    rows.push(["Environment", s.dim("none yet \xB7 run `xanots deploy`")]);
+  } else if (!env.alive) {
+    rows.push([
+      "Environment",
+      `${env.name} ${s.dim("\xB7 gone or expired \xB7 run `xanots deploy` for a fresh one")}`
+    ]);
+  } else {
+    const state = env.state === null ? "" : ` ${s.dim(`\xB7 ${env.state}`)}`;
+    rows.push(["Environment", `${env.name}${state} ${s.dim(`\xB7 expires ${formatExpiration(env.expiresAt)}`)}`]);
+    if (env.url !== void 0) rows.push(["URL", s.bold(s.cyan(env.url))]);
+  }
+  return `
+${formatFields(rows)}`;
+}
+async function runStatusCommand(args) {
+  const status = await readStatus(args);
+  if (isMachineOutput(args)) {
+    writeJson(status);
+  } else {
+    process.stdout.write(prettyStatus(status));
+  }
+}
+export {
+  readStatus,
+  runStatusCommand
+};
+//# sourceMappingURL=status-command-AL47VG7H.js.map

package/dist/{store-CUCBSYLj.d.ts → store-BG1UPZ3Z.d.ts}

@@ -5051,7 +5051,7 @@ type RealtimeServerHandle = RealtimeServerDef & {
      * IN A BROWSER BUNDLE, prefer the generated manifest: importing this def for
      * its `getUrl()` pulls the SDK runtime in with it (the same ~289 kB floor a
      * query def costs — the factory CALLS that build the def run at module load).
-     * `xanots paths <entry> --emit xano/routes.gen.ts` writes the identical
+     * `xanots routes <entry> --emit xano/routes.gen.ts` writes the identical
      * address, tenant lift included, as `socketUrl("<server>", baseUrl)` in a file
      * that imports nothing.
      *
@@ -5353,7 +5353,7 @@ type RealtimeChannelHandle<I extends Record<string, InputDescriptor> = Record<st
      * channel).
      *
      * IN A BROWSER BUNDLE, prefer the generated manifest's `channelPath()`
-     * (`xanots paths <entry> --emit`): identical output and the same
+     * (`xanots routes <entry> --emit`): identical output and the same
      * compile-time param checking, in a file that imports no SDK runtime.
      */
     getChannel: IsStaticPath<N> extends true ? (params?: Record<string, never>) => string : (params: PathParamValues<N>) => string;
@@ -7332,10 +7332,10 @@ interface ManifestCliFlag {
  * `src/emit/commands.ts` — the same table that renders `--help` and generates the
  * shell completions.
  *
- * It used to be hand-maintained here, and it drifted: `init` and `validate` were
+ * It used to be hand-maintained here, and it drifted: `init` and `preflight` were
  * missing outright, `deploy` was short six flags, and the `--static` description
- * claimed the frontend always lands on the parent workspace (true only under
- * `--dest sandbox`). Deriving it makes that class of drift unrepresentable, which
+ * claimed the frontend lands on the parent workspace, which it does not.
+ * Deriving it makes that class of drift unrepresentable, which
  * matters more now that `llms.txt` no longer documents the CLI — this array and
  * `--help` are the only two surfaces, and they are now one source.
  */

package/dist/{test-command-2F5LKMI6.js → test-command-YAZLKLGQ.js}

@@ -1,25 +1,28 @@
-import {
-  resolveMetaTarget
-} from "./chunk-YNZFIY4J.js";
-import "./chunk-MDXR5E5Q.js";
-import "./chunk-3EYUR3TX.js";
-import "./chunk-NDZFBZHC.js";
-import {
-  getAccessToken
-} from "./chunk-3QW5NFZJ.js";
-import "./chunk-BKDJN76G.js";
 import {
   isMachineOutput,
   writeJson
 } from "./chunk-NUQCEOKA.js";
+import {
+  resolveMetaTarget
+} from "./chunk-ZQ2PKR6R.js";
+import "./chunk-K5IOND4K.js";
+import {
+  getAccessToken
+} from "./chunk-QKM4U5UK.js";
+import "./chunk-FE5I6S6N.js";
 import {
   fetchOrExplain,
   httpFailure,
   serverMessage
 } from "./chunk-3IGNIP6R.js";
 import {
+  parseEnvSelector,
+  unknownEnv
+} from "./chunk-CTD5ZCV6.js";
+import {
+  UsageError,
   unknownSubcommand
-} from "./chunk-JQLR64UC.js";
+} from "./chunk-F6CYJ7TN.js";
 import "./chunk-GNPVYOPB.js";
 import {
   blank,
@@ -29,7 +32,7 @@ import {
   success,
   warn
 } from "./chunk-EZG76F7R.js";
-import "./chunk-OKNSR7MT.js";
+import "./chunk-DIA7CT7J.js";
 
 // src/deploy/tests.ts
 var TIMEOUT_MS = 12e4;
@@ -189,7 +192,7 @@ async function runTest(auth, target, handle) {
 
 // src/emit/test-command.ts
 var EXIT_TESTS_FAILED = 5;
-var DEFAULT_DEST = "ephemeral";
+var DEFAULT_ENV = { kind: "ephemeral" };
 async function mapWithConcurrency(items, limit, work) {
   const results = new Array(items.length);
   let next = 0;
@@ -250,10 +253,22 @@ function report(args, dest, env, outcomes) {
   }
   if (summary.failed > 0) process.exitCode = EXIT_TESTS_FAILED;
 }
-async function resolveTarget(args, auth) {
-  const dest = args.dest ?? DEFAULT_DEST;
-  const target = await resolveMetaTarget(auth, { dest, name: args.name });
-  return { dest, env: target.env ?? null, target };
+function assertNoName(args) {
+  if (args.name === void 0) return;
+  throw new UsageError(
+    `\`xanots test\` takes no \`--name\` \u2014 name the environment inside \`--env\` instead: \`--env ephemeral:${args.name}\`.`,
+    { helpFor: { command: "test", subcommand: args.subcommand } }
+  );
+}
+function selectEnv(args) {
+  if (args.env === void 0) return DEFAULT_ENV;
+  return parseEnvSelector(args.env) ?? (() => {
+    throw unknownEnv("--env", args.env, { command: "test", subcommand: args.subcommand });
+  })();
+}
+async function resolveTarget(selector, auth) {
+  const target = await resolveMetaTarget(auth, selector);
+  return { dest: selector.kind, env: target.env ?? null, target };
 }
 async function collect(auth, target, kind) {
   return listTests(auth, target, {
@@ -264,8 +279,8 @@ async function collect(auth, target, kind) {
 function nameWidth(handles) {
   return Math.max(0, ...handles.map((h) => h.name.length));
 }
-async function runList(args, auth) {
-  const { dest, env, target } = await resolveTarget(args, auth);
+async function runList(args, auth, selector) {
+  const { dest, env, target } = await resolveTarget(selector, auth);
   const handles = await collect(auth, target, args.kind);
   if (isMachineOutput(args)) {
     writeJson({
@@ -300,13 +315,13 @@ function match(handles, needle) {
   if (qualified.length > 0) return qualified;
   return handles.filter((h) => h.name === needle);
 }
-async function runOne(args, auth, name) {
-  const { dest, env, target } = await resolveTarget(args, auth);
+async function runOne(args, auth, selector, name) {
+  const { dest, env, target } = await resolveTarget(selector, auth);
   const handles = await collect(auth, target, args.kind);
   const found = match(handles, name);
   if (found.length === 0) {
     throw new Error(
-      `No test named "${name}" in ${target.label}. Run \`xanots test list${args.dest ? ` --dest ${args.dest}` : ""}\` to see what is there.`
+      `No test named "${name}" in ${target.label}. Run \`xanots test list${args.env ? ` --env ${args.env}` : ""}\` to see what is there.`
     );
   }
   if (found.length > 1) {
@@ -348,8 +363,8 @@ async function runSuite(auth, target, opts) {
     return outcome;
   });
 }
-async function runAll(args, auth) {
-  const { dest, env, target } = await resolveTarget(args, auth);
+async function runAll(args, auth, selector) {
+  const { dest, env, target } = await resolveTarget(selector, auth);
   const outcomes = await runSuite(auth, target, {
     kind: args.kind,
     concurrency: args.concurrency,
@@ -358,19 +373,21 @@ async function runAll(args, auth) {
   report(args, dest, env, outcomes);
 }
 async function runTestCommand(args) {
+  assertNoName(args);
+  const selector = selectEnv(args);
   const auth = await getAccessToken(args);
   switch (args.subcommand) {
     case "list":
-      return runList(args, auth);
+      return runList(args, auth, selector);
     case "run": {
       const name = args.positionals[0];
       if (name === void 0 || name === "") {
         throw new Error('`xanots test run` needs a test name: `xanots test run "<name>"`.');
       }
-      return runOne(args, auth, name);
+      return runOne(args, auth, selector, name);
     }
     case "run-all":
-      return runAll(args, auth);
+      return runAll(args, auth, selector);
     default:
       throw unknownSubcommand("test", args.subcommand);
   }
@@ -380,4 +397,4 @@ export {
   runSuite,
   runTestCommand
 };
-//# sourceMappingURL=test-command-2F5LKMI6.js.map
+//# sourceMappingURL=test-command-YAZLKLGQ.js.map

package/dist/{upgrade-command-QL523I62.js → upgrade-command-FB5QJ363.js}

@@ -1,20 +1,20 @@
 import {
   assertProjectDir
 } from "./chunk-ERQZFWIW.js";
+import {
+  refreshAgentFiles
+} from "./chunk-JGCWTCA7.js";
 import {
   isMachineOutput,
   writeJson
 } from "./chunk-NUQCEOKA.js";
-import {
-  refreshAgentFiles
-} from "./chunk-QIWBCS7N.js";
-import "./chunk-4PE4ZAB7.js";
+import "./chunk-KA6G2L7U.js";
 import {
   runNpm
 } from "./chunk-ZSYZTGJH.js";
 import {
   sdkDep
-} from "./chunk-P5C2YKAM.js";
+} from "./chunk-ANUDXFEX.js";
 import "./chunk-Q77KNEUL.js";
 import {
   checkForUpgrade,
@@ -22,10 +22,11 @@ import {
   registryUrl,
   suppressUpdateNotice,
   upgradeCommand
-} from "./chunk-OW2QZEWL.js";
-import "./chunk-K3YSQDXJ.js";
-import "./chunk-JQLR64UC.js";
+} from "./chunk-5YCQ2QHH.js";
+import "./chunk-ACCBOMCB.js";
+import "./chunk-CTD5ZCV6.js";
 import "./chunk-OYMR5AMJ.js";
+import "./chunk-F6CYJ7TN.js";
 import "./chunk-GNPVYOPB.js";
 import {
   blank,
@@ -35,9 +36,9 @@ import {
   success,
   warn
 } from "./chunk-EZG76F7R.js";
-import "./chunk-UDL46O35.js";
-import "./chunk-OKNSR7MT.js";
-import "./chunk-QONOJO45.js";
+import "./chunk-VKSOTZK3.js";
+import "./chunk-DIA7CT7J.js";
+import "./chunk-LBYWGMOA.js";
 import "./chunk-WHOJWOSV.js";
 import "./chunk-5XZ744TS.js";
 import "./chunk-7JDT4PBU.js";
@@ -174,4 +175,4 @@ function messageOf(err) {
 export {
   runUpgradeCommand
 };
-//# sourceMappingURL=upgrade-command-QL523I62.js.map
+//# sourceMappingURL=upgrade-command-FB5QJ363.js.map

package/dist/{workspace-K72NP7SX.js → workspace-2COHDBM3.js}

@@ -46,4 +46,4 @@ ${text}`);
 export {
   resolveScopedWorkspaceId
 };
-//# sourceMappingURL=workspace-K72NP7SX.js.map
+//# sourceMappingURL=workspace-2COHDBM3.js.map

package/dist/{workspace-command-HYA6JEKK.js → workspace-command-43P42FBP.js}

@@ -1,48 +1,49 @@
-import {
-  fetchWorkspaceBundle,
-  runCodegenCommand
-} from "./chunk-L6TPHWAU.js";
-import "./chunk-ZOYMZZ3S.js";
 import {
   resolveOutputTarget
-} from "./chunk-JQJPFUZI.js";
-import "./chunk-3EYUR3TX.js";
+} from "./chunk-WGPXT2G2.js";
 import {
   printMicroserviceSection,
   readMicroservices
-} from "./chunk-NDZFBZHC.js";
+} from "./chunk-3UABJA4X.js";
+import {
+  isMachineOutput,
+  writeJson
+} from "./chunk-NUQCEOKA.js";
+import {
+  fetchWorkspaceBundle
+} from "./chunk-I7DQDJAM.js";
+import "./chunk-3INK4Y4E.js";
+import "./chunk-ZQ2PKR6R.js";
+import "./chunk-K5IOND4K.js";
 import {
   ENV_WORKSPACE,
   getAccessToken
-} from "./chunk-3QW5NFZJ.js";
-import "./chunk-BKDJN76G.js";
-import "./chunk-QTNO2WD6.js";
+} from "./chunk-QKM4U5UK.js";
+import "./chunk-FE5I6S6N.js";
+import "./chunk-7ZYW652H.js";
 import "./chunk-ZUTSMMAG.js";
 import "./chunk-X4DVXBFY.js";
-import "./chunk-6Z5CNWFC.js";
-import {
-  isMachineOutput,
-  writeJson
-} from "./chunk-NUQCEOKA.js";
-import "./chunk-4PE4ZAB7.js";
-import "./chunk-ZSYZTGJH.js";
 import {
   fetchOrExplain,
   httpFailure
 } from "./chunk-3IGNIP6R.js";
-import "./chunk-5YQOIFT4.js";
+import "./chunk-YYFXVYPX.js";
+import "./chunk-KA6G2L7U.js";
+import "./chunk-ZSYZTGJH.js";
+import "./chunk-75Z74TA7.js";
 import "./chunk-LU7TRWMC.js";
-import "./chunk-MU3O43L2.js";
-import "./chunk-P5C2YKAM.js";
+import "./chunk-YBC3IKMF.js";
+import "./chunk-ANUDXFEX.js";
 import "./chunk-Q77KNEUL.js";
 import "./chunk-4BXJGVZ3.js";
-import "./chunk-ZZLPTHT5.js";
-import "./chunk-K3YSQDXJ.js";
+import "./chunk-P6TAVLOX.js";
+import "./chunk-ACCBOMCB.js";
+import "./chunk-CTD5ZCV6.js";
+import "./chunk-OYMR5AMJ.js";
 import {
   removedSubcommand,
   unknownSubcommand
-} from "./chunk-JQLR64UC.js";
-import "./chunk-OYMR5AMJ.js";
+} from "./chunk-F6CYJ7TN.js";
 import "./chunk-GNPVYOPB.js";
 import {
   formatFields,
@@ -50,9 +51,9 @@ import {
   step,
   success
 } from "./chunk-EZG76F7R.js";
-import "./chunk-UDL46O35.js";
-import "./chunk-OKNSR7MT.js";
-import "./chunk-QONOJO45.js";
+import "./chunk-VKSOTZK3.js";
+import "./chunk-DIA7CT7J.js";
+import "./chunk-LBYWGMOA.js";
 import "./chunk-WHOJWOSV.js";
 import "./chunk-5XZ744TS.js";
 import "./chunk-7JDT4PBU.js";
@@ -67,10 +68,8 @@ async function runWorkspaceCommand(args) {
       return runDetails(args);
     case "export":
       return runExport(args);
-    case "codegen":
-      return runCodegenCommand(args, { kind: "workspace" });
     case "branch": {
-      const { runBranchCommand } = await import("./branch-commands-PBQ36L4A.js");
+      const { runBranchCommand } = await import("./branch-commands-2BLOC2GR.js");
       return runBranchCommand(args);
     }
     case "deploy":
@@ -160,4 +159,4 @@ async function runExport(args) {
 export {
   runWorkspaceCommand
 };
-//# sourceMappingURL=workspace-command-HYA6JEKK.js.map
+//# sourceMappingURL=workspace-command-43P42FBP.js.map

package/dist/{workspace-export-AJMGN3CQ.js → workspace-export-DURY5WYL.js}

@@ -1,10 +1,10 @@
 import {
   exportWorkspaceBundle
-} from "./chunk-QTNO2WD6.js";
+} from "./chunk-7ZYW652H.js";
 import "./chunk-ZUTSMMAG.js";
 import "./chunk-X4DVXBFY.js";
 import "./chunk-3IGNIP6R.js";
 export {
   exportWorkspaceBundle
 };
-//# sourceMappingURL=workspace-export-AJMGN3CQ.js.map
+//# sourceMappingURL=workspace-export-DURY5WYL.js.map

package/guides/README.md

@@ -11,10 +11,10 @@ typed, so your editor's autocomplete is usually the faster lookup — tab-comple
 | [Object kinds](object-kinds.md) | Every authorable kind, and splitting a workspace across microservices |
 | [Authoring reference](authoring.md) | Tables and fields, statements, values, inputs, middleware, request history |
 | [CLI](cli.md) | Every command, shell completion, and what failures look like |
-| [Signing in & deploying](deploying.md) | Auth, ephemerals, `--static`, releasing to production, `xanots validate` |
+| [Signing in & deploying](deploying.md) | Auth, ephemerals, `--static`, releasing to production, `xanots preflight` |
 | [Environment & identity](environment.md) | Every environment variable, and how `xano.lock` pins identity |
 | [The typed frontend surface](typed-frontend.md) | Path resolution, input/response inference, bundle cost, the route manifest |
-| [Pulling an existing workspace](codegen.md) | What `xanots codegen` writes, how faithful it is, and how to read its report |
+| [Pulling an existing workspace](codegen.md) | What `xanots init --from` writes, how faithful it is, and how to read its report |
 | [Coverage & agent grounding](coverage.md) | What's covered, what's out of scope, and the files agents read |
 
 ## The agent-facing surface

package/guides/cli.md

@@ -24,14 +24,13 @@ xanots export ./xano/index.ts --lock       # opt into xano.lock (created beside
 xanots export ./xano/index.ts --frozen-lock  # CI guard: fail if the export would change the lock
 xanots lock rename --entry=xano/index.ts table users members  # move a lock entry after renaming in code
 xanots lock prune ./xano/index.ts --yes    # drop lock entries nothing exports anymore
-xanots lock prune --no-verify --entry=xano/index.ts --yes dbo:notes  # …or drop named keys without running the workspace
-xanots lock adopt live-export.json --entry=xano/index.ts --yes  # seed the lock from a live engine export
+xanots lock prune --identity-only --entry=xano/index.ts --yes dbo:notes  # …or drop named keys without running the workspace
+xanots lock import live-export.json --entry=xano/index.ts --yes  # seed the lock from a live engine export
 
 xanots login                               # OAuth sign-in (once) — pick the instance + workspace at consent
 xanots login --paste                       # …when the browser can't reach this machine's 127.0.0.1 (remote shell, container, Codespace)
 xanots workspace details                   # which instance/workspace am I bound to, and via which credential?
 xanots deploy ./xano/index.ts              # compile + import into a live ephemeral (the dev loop) → URL
-xanots deploy ./xano/index.ts --dest sandbox             # …or your throwaway singleton sandbox
 xanots deploy ./xano/index.ts --static ./frontend/dist   # also deploy a static frontend (onto the ephemeral)
 xanots deploy ./xano/index.ts --static ./frontend/dist --static-env PK=pk_live_1   # + extra public config
 xanots deploy --bundle ws.json             # deploy an already-exported bundle
@@ -43,33 +42,32 @@ xanots ephemeral impersonate <tenant>      # open it in the builder (--guest = r
 xanots release ./xano/index.ts --dry-run   # preview what promoting to your main workspace would change
 xanots release ./xano/index.ts             # promote: add + update, never delete, never touch table data
 xanots release ./xano/index.ts --prune     # …also delete objects this project released and no longer defines (needs xano.lock)
-xanots sandbox export                      # export the DEPLOYED sandbox workspace as a JSON bundle → ./sandbox.json
-xanots sandbox export --format multidoc --name backend               # …or the deployed sandbox as XanoScript → backend.xs
-xanots sandbox export --format multidoc --path -                     # …stream the multidoc to stdout (deploy first)
-xanots sandbox details                     # print the sandbox base URL + tenant details (pretty on a TTY, JSON when piped)
+xanots ephemeral export <tenant>           # export a DEPLOYED ephemeral as a JSON bundle → ./<tenant>.json
+xanots ephemeral export <tenant> --format multidoc --name backend    # …or as XanoScript → backend.xs
+xanots ephemeral export <tenant> --format multidoc --path -          # …stream the multidoc to stdout (deploy first)
 
 xanots workspace details                   # which workspace your token is scoped to (instance, id, name, guid)
 xanots workspace export --path ws.json     # your REAL workspace as a JSON bundle (`--path -` streams to stdout)
-xanots workspace codegen my-app            # …or as a runnable project (the pull direction)
-xanots sandbox codegen my-app              # same, from your sandbox
-xanots ephemeral codegen <tenant> my-app   # same, from an ephemeral (tenant first, path second)
-xanots codegen ws.json my-app              # …or from a bundle already on disk (offline, no auth)
+xanots init my-app --from workspace        # …or as a runnable project (the pull direction)
+xanots init my-app --from ephemeral:<tenant>   # same, from an ephemeral (the env is named inside the flag)
+xanots init my-app --from ./ws.json        # …or from a bundle already on disk (offline, no auth)
 
-xanots profile me                          # print the scoped user + instance base URL (pretty on a TTY, JSON when piped)
-xanots whoami                              # alias for `profile me`
+xanots status                              # who am I, which workspace, and the env this project last deployed to
+xanots whoami                              # print the scoped user + instance base URL (pretty on a TTY, JSON when piped)
+xanots profile me                          # alias for `whoami`
 xanots logout                              # revoke the refresh token + clear the shared cache (--local for the project one)
 xanots version                             # print the installed @xanots/sdk version
 xanots upgrade --check                     # is a newer @xanots/sdk published? exits 7 if so, 0 if current
 xanots upgrade                             # install it (-g or -D, matching how this CLI is installed)
 xanots help                                # grouped command reference (also the no-arg default)
 xanots <command> --help                    # that command's usage, subcommands, and flags (`xanots deploy --help`)
-xanots <noun> <verb> --help                # scoped to one verb (`xanots workspace codegen --help`)
+xanots <noun> <verb> --help                # scoped to one verb (`xanots workspace export --help`)
 xanots <command> --json                    # force JSON on stdout (otherwise: whenever stdout isn't a terminal)
 xanots completion zsh                      # shell completion script (also bash, fish) — see below
 
-xanots validate ./xano/index.ts            # import into a live instance, diff each object back
-xanots validate ./xano/index.ts --runtime  # also run each deployed function on the engine
-xanots validate ./xano/index.ts --capture  # write the fetched JSON as fixture candidates
+xanots preflight ./xano/index.ts           # import into a live instance, diff each object back (needs auth + a throwaway tenant)
+xanots preflight ./xano/index.ts --runtime # also run each deployed function on the engine
+xanots preflight ./xano/index.ts --capture # write the fetched JSON as fixture candidates
 ```
 
 ## Bundle key names vs. the names everything else uses
@@ -97,7 +95,7 @@ correctly looks *missing* if you go looking for `payload.table`. And `agent` and
 both land in `payload.toolset`, while the kind actually named `toolset` lands in
 `payload.tool`; matching on the word alone will pick the wrong array.
 
-This is also the format `xanots lock adopt` reads, so both directions are user-facing.
+This is also the format `xanots lock import` reads, so both directions are user-facing.
 
 
 **Build warnings, and `--strict`.** `export`/`deploy` print a `xanots:` warning for the
@@ -113,7 +111,7 @@ The programmatic equivalents are `emitBundle(app, { strict: true })` and
 ## Shell completion
 
 `xanots completion <bash|zsh|fish>` prints a completion script covering every command, verb, flag,
-and closed value set (`--dest ephemeral|sandbox`, `--format json|multidoc`, `--ai claude|codex|cursor|none`).
+and closed value set (`--env ephemeral|workspace`, `--format json|multidoc`, `--ai claude|codex|cursor|none`).
 It is generated from the CLI's own command table, so it never drifts from what the CLI accepts — but it
 is baked at generation time, so re-run it after upgrading.