@vatio-ai/cli 0.52.0 → 0.54.0

package/README.md

@@ -71,7 +71,7 @@ kb write|cat|rm-entry        Entries, from a file or stdin
 kb follow|unfollow|refresh   Read a site into a base, nightly
 
 secrets list|set|rm          Credentials your tools read
-tokens list|create|revoke    Publishable tokens for the widget and the SDK
+tokens list|create|origins|revoke  Publishable tokens and the origins each accepts
 widget [--env NAME]          What the platform enforces, and the tokens there are
 auth --new-key               Keypair that signs the visitor's JWT
 

package/bin/vatio.mjs

@@ -17,6 +17,7 @@ import { helpText } from "../lib/help.mjs";
 import { login, logout } from "../lib/commands/auth.mjs";
 import { configCommand, doctor, init, version } from "../lib/commands/misc.mjs";
 import { diff, publish, push, rollback, status, toolsCheck } from "../lib/commands/deploy.mjs";
+import { env } from "../lib/commands/env.mjs";
 import { secrets, tokens, widget } from "../lib/commands/workspace-admin.mjs";
 import { auth } from "../lib/commands/identity-key.mjs";
 import { chat } from "../lib/commands/chat.mjs";
@@ -70,6 +71,8 @@ async function run(command, args) {
       return await rollback(config);
     case "status":
       return await status(config);
+    case "env":
+      return await env(config, args);
     case "diff":
       return await diff(config, args);
     case "tools":

package/lib/api-client.mjs

@@ -29,9 +29,10 @@ export class ApiClient extends HttpClient {
     return this.post("/deploy/check", body);
   }
 
-  pushPreview({ manifest, gitSha = null, createdBy = null, environment = null }) {
+  pushPreview({ manifest, gitSha = null, gitBranch = null, createdBy = null, environment = null }) {
     const body = { manifest };
     if (gitSha) body.git_sha = gitSha;
+    if (gitBranch) body.git_branch = gitBranch;
     if (createdBy) body.created_by = createdBy;
     if (environment) body.environment = environment;
     return this.put("/deploy/preview", body);
@@ -58,18 +59,36 @@ export class ApiClient extends HttpClient {
     return this.get(`/deploy/revisions/${encode(id)}`);
   }
 
+  // --- environments ---------------------------------------------------
+
+  environments() {
+    return this.get("/deploy/environments");
+  }
+
+  environment(name) {
+    return this.get(`/deploy/environments/${encode(name)}`);
+  }
+
+  deleteEnvironment(name) {
+    return this.delete(`/deploy/environments/${encode(name)}`);
+  }
+
   // --- secrets --------------------------------------------------------
 
-  listSecrets() {
-    return this.get("/deploy/secrets");
+  // Without an environment, the value everywhere; with one, the value only
+  // that environment uses instead.
+  listSecrets({ environment = null } = {}) {
+    return this.get("/deploy/secrets", { environment });
   }
 
-  upsertSecret({ key, value }) {
-    return this.put(`/deploy/secrets/${encode(key)}`, { value });
+  upsertSecret({ key, value, environment = null }) {
+    const body = { value };
+    if (environment) body.environment = environment;
+    return this.put(`/deploy/secrets/${encode(key)}`, body);
   }
 
-  deleteSecret({ key }) {
-    return this.delete(`/deploy/secrets/${encode(key)}`);
+  deleteSecret({ key, environment = null }) {
+    return this.delete(`/deploy/secrets/${encode(key)}${query({ environment })}`);
   }
 
   // --- knowledge bases ------------------------------------------------
@@ -77,12 +96,16 @@ export class ApiClient extends HttpClient {
   // A base holds entries (markdown) and reads sites (a URL or a pattern). Two
   // nouns, and every call below is one of them.
 
-  knowledgeBases() {
-    return this.get("/knowledge_bases");
+  // Every read and write below is as one environment sees the base: a
+  // branch's, which keeps its changes on top of live, or `live` itself.
+  // Without one the platform means `preview`.
+
+  knowledgeBases({ environment = null } = {}) {
+    return this.get("/knowledge_bases", { environment });
   }
 
-  knowledgeBase(name) {
-    return this.get(`/knowledge_bases/${encode(name)}`);
+  knowledgeBase(name, { environment = null } = {}) {
+    return this.get(`/knowledge_bases/${encode(name)}`, { environment });
   }
 
   createKnowledgeBase(name) {
@@ -97,19 +120,21 @@ export class ApiClient extends HttpClient {
     return this.post(`/knowledge_bases/${encode(name)}/refresh`, {});
   }
 
-  knowledgeEntry({ base, name }) {
-    return this.get(`/knowledge_bases/${encode(base)}/entries/${encode(name)}`);
+  knowledgeEntry({ base, name, environment = null, version = null }) {
+    return this.get(`/knowledge_bases/${encode(base)}/entries/${encode(name)}`, { environment, version });
   }
 
   // Put this markdown under this name, whether or not the entry exists yet --
   // one call for "write" and "rewrite", because from the terminal they are the
   // same sentence.
-  writeKnowledgeEntry({ base, name, content }) {
-    return this.patch(`/knowledge_bases/${encode(base)}/entries/${encode(name)}`, { content });
+  writeKnowledgeEntry({ base, name, content, environment = null }) {
+    const body = { content };
+    if (environment) body.environment = environment;
+    return this.patch(`/knowledge_bases/${encode(base)}/entries/${encode(name)}`, body);
   }
 
-  deleteKnowledgeEntry({ base, name }) {
-    return this.delete(`/knowledge_bases/${encode(base)}/entries/${encode(name)}`);
+  deleteKnowledgeEntry({ base, name, environment = null }) {
+    return this.delete(`/knowledge_bases/${encode(base)}/entries/${encode(name)}${query({ environment })}`);
   }
 
   followKnowledgeSite({ base, url }) {
@@ -127,22 +152,19 @@ export class ApiClient extends HttpClient {
     return this.post(`/knowledge_bases/${encode(base)}/sites/refresh`, { url });
   }
 
-  // Writes land in the base's draft, which preview answers from; live moves
-  // only on publish or rollback.
-  knowledgeChanges(base) {
-    return this.get(`/knowledge_bases/${encode(base)}/changes`);
+  // What the environment changed that live does not have yet.
+  knowledgeChanges(base, { environment = null } = {}) {
+    return this.get(`/knowledge_bases/${encode(base)}/changes`, { environment });
   }
 
-  publishKnowledgeBase({ base, note }) {
-    return this.post(`/knowledge_bases/${encode(base)}/publish`, { note });
-  }
-
-  knowledgeSnapshots(base) {
-    return this.get(`/knowledge_bases/${encode(base)}/snapshots`);
+  publishKnowledgeBase({ base, environment = null }) {
+    const body = {};
+    if (environment) body.environment = environment;
+    return this.post(`/knowledge_bases/${encode(base)}/publish`, body);
   }
 
-  rollbackKnowledgeBase({ base, number }) {
-    return this.post(`/knowledge_bases/${encode(base)}/snapshots/${encode(String(number))}/rollback`, {});
+  knowledgeHistory(base) {
+    return this.get(`/knowledge_bases/${encode(base)}/history`);
   }
 
   // --- publishable tokens and the widget ------------------------------
@@ -151,12 +173,17 @@ export class ApiClient extends HttpClient {
     return this.get("/publishable_tokens");
   }
 
-  createPublishableToken({ environment, label = null }) {
+  createPublishableToken({ environment, label = null, allowedOrigins = [] }) {
     const body = { environment };
     if (String(label ?? "").trim() !== "") body.label = String(label).trim();
+    if (allowedOrigins.length > 0) body.allowed_origins = allowedOrigins;
     return this.post("/publishable_tokens", body);
   }
 
+  setPublishableTokenOrigins({ prefix, allowedOrigins }) {
+    return this.patch(`/publishable_tokens/${encode(prefix)}`, { allowed_origins: allowedOrigins });
+  }
+
   revokePublishableToken({ prefix }) {
     return this.delete(`/publishable_tokens/${encode(prefix)}`);
   }
@@ -171,8 +198,15 @@ export class ApiClient extends HttpClient {
     return this.get("/test_phone_numbers");
   }
 
-  addTestPhoneNumber({ phoneNumber }) {
-    return this.post("/test_phone_numbers", { phone_number: phoneNumber });
+  addTestPhoneNumber({ phoneNumber, environment = null }) {
+    const body = { phone_number: phoneNumber };
+    if (environment) body.environment = environment;
+    return this.post("/test_phone_numbers", body);
+  }
+
+  // Which environment the phone reaches on the shared number.
+  pointTestPhoneNumber({ phoneNumber, environment }) {
+    return this.patch(`/test_phone_numbers/${waId(phoneNumber)}`, { environment });
   }
 
   verifyTestPhoneNumber({ phoneNumber, code }) {
@@ -240,8 +274,15 @@ export class ApiClient extends HttpClient {
   // Declares which Instagram account you mean. The code comes later, by DM,
   // once that account writes to the shared preview -- Instagram will not let
   // Vatio message an account that has not messaged it first.
-  addTestInstagramAccount({ username }) {
-    return this.post("/test_instagram_accounts", { username });
+  addTestInstagramAccount({ username, environment = null }) {
+    const body = { username };
+    if (environment) body.environment = environment;
+    return this.post("/test_instagram_accounts", body);
+  }
+
+  // Which environment the account reaches on the shared one.
+  pointTestInstagramAccount({ id, environment }) {
+    return this.patch(`/test_instagram_accounts/${encode(id)}`, { environment });
   }
 
   // Addressed by the code alone: the workspace is already in the path and the
@@ -314,6 +355,16 @@ export class CliClient extends HttpClient {
   }
 }
 
+// A DELETE carries no body, so what it needs beyond the path rides as a query.
+function query(params) {
+  const search = new URLSearchParams();
+  for (const [key, value] of Object.entries(params)) {
+    if (value !== undefined && value !== null && value !== "") search.set(key, String(value));
+  }
+  const text = search.toString();
+  return text ? `?${text}` : "";
+}
+
 // The path carries the digits: "+" and spaces do not survive a URL, and the
 // digits are what the API stores as `wa_id`.
 function waId(phoneNumber) {

package/lib/branch.mjs

@@ -0,0 +1,51 @@
+// The environment a git branch gets, so that working on a branch is working in
+// its own environment without saying so: `vatio push` from `fix/pagos` lands on
+// `fix-pagos`, and so do `vatio kb write`, `vatio secrets set` and `vatio chat`.
+// The pull request opened from that branch deploys to the same one.
+//
+// The default branch is not a branch environment: there, and outside a
+// repository, every command keeps the default it always had.
+//
+// The name is derived exactly as the platform derives it for a pull request
+// (Vatio::Environment.for_branch, backend/app/vatio/environment.rb). Kept in
+// step by hand; both are short.
+
+import { execFileSync } from "node:child_process";
+import { createHash } from "node:crypto";
+
+const RESERVED = new Set(["live", "preview", "staging", "sandbox", "main"]);
+const MAX_LENGTH = 40;
+
+export function environmentForBranch(ref) {
+  const raw = String(ref ?? "").replace(/^refs\/heads\//, "");
+  let slug = raw.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "");
+  if (slug === "") return null;
+
+  if (RESERVED.has(slug)) slug = `branch-${slug}`;
+  if (slug.length <= MAX_LENGTH) return slug;
+
+  const hash = createHash("sha1").update(String(ref)).digest("hex").slice(0, 6);
+  return `${slug.slice(0, 33).replace(/-+$/, "")}-${hash}`;
+}
+
+// { branch, environment } on a branch other than the default one; null on the
+// default branch, outside a repository, or with HEAD detached.
+export function branchEnvironment(cwd) {
+  const branch = git(cwd, ["symbolic-ref", "--short", "-q", "HEAD"]);
+  if (!branch) return null;
+
+  const remoteHead = git(cwd, ["symbolic-ref", "--short", "-q", "refs/remotes/origin/HEAD"]);
+  const defaultBranch = remoteHead ? remoteHead.replace(/^[^/]+\//, "") : null;
+  if (branch === defaultBranch || (!defaultBranch && (branch === "main" || branch === "master"))) return null;
+
+  const environment = environmentForBranch(branch);
+  return environment ? { branch, environment } : null;
+}
+
+function git(cwd, args) {
+  try {
+    return execFileSync("git", args, { cwd, encoding: "utf8", stdio: ["ignore", "pipe", "ignore"] }).trim() || null;
+  } catch {
+    return null;
+  }
+}

package/lib/commands/channels.mjs

@@ -7,7 +7,7 @@
 // would say nothing about which one.
 
 import { deployClient } from "./deploy.mjs";
-import { fail, openBrowser } from "../support.mjs";
+import { fail, openBrowser, takeEnv } from "../support.mjs";
 
 export async function whatsapp(config, args) {
   const workspace = config.resolveWorkspaceRequired();
@@ -33,18 +33,20 @@ export async function whatsapp(config, args) {
       console.log(`Disconnected WhatsApp from workspace ${workspace}. Vatio stops receiving its messages.`);
       return;
     }
-    case "numbers": return await numbers(client, workspace, args);
+    case "numbers": return await numbers(client, workspace, args, config.workspaceRoot);
     default: fail(whatsappUsage());
   }
 }
 
 function whatsappUsage() {
   return `Usage: vatio whatsapp status|connect|check|activate|deactivate|disconnect
-       vatio whatsapp numbers list|add PHONE|verify PHONE CODE|resend PHONE|remove PHONE
+       vatio whatsapp numbers list|add PHONE|point PHONE|verify PHONE CODE|resend PHONE|remove PHONE  [--env NAME]
 
   The bare commands drive your own WhatsApp number, which serves live.
-  \`numbers\` registers test phones on the shared WhatsApp preview, which always
-  reach preview — the counterpart of \`vatio instagram accounts\`.
+  \`numbers\` registers test phones on the shared WhatsApp preview. Each reaches
+  the environment it points at: preview, or a branch's (\`add\` and \`point\`
+  take --env, and default to the branch you are on) — the counterpart of
+  \`vatio instagram accounts\`.
 
   connect
     Prints a link to finish in a browser. Connecting a number is Meta's
@@ -114,9 +116,10 @@ async function connectWhatsapp(client, workspace) {
   openBrowser(url);
 }
 
-async function numbers(client, workspace, args) {
+async function numbers(client, workspace, args, cwd) {
   const sub = args.shift() ?? "list";
-  const usage = "Usage: vatio whatsapp numbers list|add PHONE|verify PHONE CODE|resend PHONE|remove PHONE";
+  const usage = "Usage: vatio whatsapp numbers list|add PHONE|point PHONE|verify PHONE CODE|resend PHONE|remove PHONE  [--env NAME]";
+  const environment = ["add", "point"].includes(sub) ? takeEnv(args, { fallback: null, cwd }) : null;
 
   if (sub === "list") {
     const list = asArray((await client.listTestPhoneNumbers()).test_phone_numbers);
@@ -128,15 +131,22 @@ async function numbers(client, workspace, args) {
     console.log(`Test phone numbers on workspace ${workspace} (${list.length}):`);
     for (const number of list) {
       const suffix = number.status === "verified" ? `verified ${number.verified_at}` : "pending verification";
-      console.log(`  ${number.phone_number}  ${suffix}`);
+      console.log(`  ${number.phone_number}  → ${number.environment}  ${suffix}`);
     }
     console.log("");
-    console.log("They reach the preview deployment on the shared WhatsApp preview number, never live.");
+    console.log("Each reaches its environment on the shared WhatsApp preview number, never live.");
+    console.log("Point one elsewhere: vatio whatsapp numbers point PHONE --env NAME");
+    return;
+  }
+  if (sub === "point") {
+    const phoneNumber = requireArg(args, "vatio whatsapp numbers point +56912345678 [--env NAME]");
+    const number = await client.pointTestPhoneNumber({ phoneNumber, environment: environment ?? "preview" });
+    console.log(`${number.phone_number} now reaches ${number.environment} on workspace ${workspace}.`);
     return;
   }
   if (sub === "add") {
     const phoneNumber = requireArg(args, "vatio whatsapp numbers add +56912345678");
-    const number = await client.addTestPhoneNumber({ phoneNumber });
+    const number = await client.addTestPhoneNumber({ phoneNumber, environment });
     if (number.already_verified) {
       console.log(`${number.phone_number} is already verified on workspace ${workspace} — nothing to do.`);
     } else if (number.moved_from) {
@@ -159,7 +169,7 @@ async function numbers(client, workspace, args) {
         ? `${number.phone_number} was already verified on workspace ${workspace}.`
         : `Verified ${number.phone_number} on workspace ${workspace}.`
     );
-    console.log("Anything you send from that phone now reaches the preview deployment.");
+    console.log(`Anything you send from that phone now reaches ${number.environment}.`);
     return;
   }
   if (sub === "resend") {
@@ -196,18 +206,20 @@ export async function instagram(config, args) {
       console.log(`Disconnected Instagram from workspace ${workspace}. Vatio stops receiving its DMs.`);
       return;
     }
-    case "accounts": return await instagramAccounts(client, workspace, args);
+    case "accounts": return await instagramAccounts(client, workspace, args, config.workspaceRoot);
     default: fail(instagramUsage());
   }
 }
 
 function instagramUsage() {
   return `Usage: vatio instagram status|connect|check|disconnect
-       vatio instagram accounts list|add @HANDLE|verify CODE|resend ID|remove ID
+       vatio instagram accounts list|add @HANDLE|point ID|verify CODE|resend ID|remove ID  [--env NAME]
 
   The bare commands drive your own Instagram account, which serves live.
-  \`accounts\` registers test accounts on the shared Instagram preview, which
-  always reach preview — the counterpart of \`vatio whatsapp numbers\`.`;
+  \`accounts\` registers test accounts on the shared Instagram preview. Each
+  reaches the environment it points at: preview, or a branch's (\`add\` and
+  \`point\` take --env, and default to the branch you are on) — the counterpart
+  of \`vatio whatsapp numbers\`.`;
 }
 
 function printInstagram(account, workspace) {
@@ -254,9 +266,10 @@ async function connectInstagram(client) {
   openBrowser(url);
 }
 
-async function instagramAccounts(client, workspace, args) {
+async function instagramAccounts(client, workspace, args, cwd) {
   const sub = args.shift() ?? "list";
-  const usage = "Usage: vatio instagram accounts list|add @HANDLE|verify CODE|resend ID|remove ID";
+  const usage = "Usage: vatio instagram accounts list|add @HANDLE|point ID|verify CODE|resend ID|remove ID  [--env NAME]";
+  const environment = ["add", "point"].includes(sub) ? takeEnv(args, { fallback: null, cwd }) : null;
 
   if (sub === "list") {
     const list = asArray((await client.listTestInstagramAccounts()).test_instagram_accounts);
@@ -271,13 +284,19 @@ async function instagramAccounts(client, workspace, args) {
         account.status === "verified" ? `verified ${account.verified_at}`
         : account.status === "awaiting_code" ? "code sent — confirm it: vatio instagram accounts verify CODE"
         : `declared — DM @${account.dm_to} from that account to get a code`;
-      console.log(`  [${account.id}] @${account.username}  ${suffix}`);
+      console.log(`  [${account.id}] @${account.username}  → ${account.environment}  ${suffix}`);
     }
     return;
   }
+  if (sub === "point") {
+    const id = requireArg(args, "vatio instagram accounts point ID [--env NAME]");
+    const account = await client.pointTestInstagramAccount({ id, environment: environment ?? "preview" });
+    console.log(`@${account.username} now reaches ${account.environment} on workspace ${workspace}.`);
+    return;
+  }
   if (sub === "add") {
     const username = requireArg(args, "vatio instagram accounts add @yourhandle").replace(/^@/, "");
-    const account = await client.addTestInstagramAccount({ username });
+    const account = await client.addTestInstagramAccount({ username, environment });
     console.log(`Declared @${account.username} on workspace ${workspace}.`);
     console.log("");
     // Meta will not let an app DM an account that has not written first, which
@@ -292,7 +311,7 @@ async function instagramAccounts(client, workspace, args) {
     const code = requireArg(args, "vatio instagram accounts verify 123456");
     const account = await client.verifyTestInstagramAccount({ code });
     console.log(`Verified @${account.username} on workspace ${workspace}.`);
-    console.log("DMs from that account now reach the preview deployment.");
+    console.log(`DMs from that account now reach ${account.environment}.`);
     return;
   }
   if (sub === "resend") {

package/lib/commands/chat.mjs

@@ -28,7 +28,7 @@ export async function chat(config, args) {
     }
   }
 
-  const environment = takeEnv(args, { fallback: "preview" });
+  const environment = takeEnv(args, { fallback: "preview", cwd: config.workspaceRoot });
   const timeout = Number(takeValue(args, "--timeout") ?? 120);
   const lastValue = takeValue(args, "--last");
   const last = Number(lastValue ?? 10);

package/lib/commands/deploy.mjs

@@ -18,6 +18,7 @@ import { buildBundle, BundleError } from "../bundle.mjs";
 import { ApiClient, CliClient } from "../api-client.mjs";
 import { NotFoundError } from "../http.mjs";
 import { deviceLogin } from "./auth.mjs";
+import { branchEnvironment } from "../branch.mjs";
 import { detectGitSha, fail, paint, takeEnv, takeFlag, takeValue } from "../support.mjs";
 
 // The first command that makes something exist on a server, so the first one
@@ -99,15 +100,16 @@ export async function toolsCheck(config, args) {
 export async function push(config, args) {
   // Null, not "preview": the platform owns that default, and sending it
   // explicitly would make a bare `vatio push` and `vatio push --env preview`
-  // two different requests that only happen to agree today.
-  const environment = takeEnv(args, { fallback: null });
+  // two different requests that only happen to agree today. On a branch, the
+  // branch's own environment.
+  const environment = takeEnv(args, { fallback: null, cwd: config.workspaceRoot });
   const workspace = config.resolveWorkspaceRequired();
 
   await ensureAuthorized(config);
 
   // The remote has to exist before the workspace can be checked: the slug is in
-  // the URL of the call that checks it. It is created unnamed -- the push a few
-  // lines down applies `business.name` from the manifest anyway.
+  // the URL of the call that checks it. It is created unnamed; the display name
+  // is a workspace setting edited in the console, not part of a push.
   const clients = workspacesClient(config);
   const created = !(await clients.workspaceExists(workspace));
   if (created) {
@@ -123,15 +125,15 @@ export async function push(config, args) {
   const payload = await client.pushPreview({
     manifest: check.manifest,
     gitSha: detectGitSha(config.workspaceRootRequired()),
+    gitBranch: branchEnvironment(config.workspaceRootRequired())?.branch ?? null,
     createdBy: process.env.USER ?? null,
     environment
   });
 
   const landedOn = payload.environment ?? "preview";
   console.log(`Pushed deployment #${payload.deployment_id} to ${landedOn} (git_sha=${JSON.stringify(payload.git_sha ?? null)})`);
-  // The link that opens without a login -- what makes a preview testable by
-  // someone who is not the developer who pushed it.
-  if (payload.share_url) console.log(`Open it: ${payload.share_url}`);
+  // Where to try it: the console's test screen for that environment.
+  if (payload.share_url) console.log(`Try it: ${payload.share_url}`);
   for (const warning of asArray(payload.warnings)) console.log(`  warning: ${warning}`);
   if (payload.preview_url) console.log(`Preview: ${payload.preview_url}`);
 
@@ -154,10 +156,11 @@ function printNotices(payload) {
 }
 
 export async function publish(config, args) {
-  // Here `--env` names the preview being promoted, not a destination: the
-  // destination of a publish is always live. Without it the platform promotes
-  // the most recent push, whichever preview it landed on.
-  const environment = takeEnv(args, { fallback: null });
+  // Here `--env` names the environment being promoted, not a destination: the
+  // destination of a publish is always live. On a branch it is the branch's;
+  // otherwise the platform promotes the most recent push, whichever preview it
+  // landed on. Its knowledge changes go live with it.
+  const environment = takeEnv(args, { fallback: null, cwd: config.workspaceRoot });
   const workspace = config.resolveWorkspaceRequired();
   const payload = await deployClient(config, workspace).publish({
     createdBy: process.env.USER ?? null,
@@ -166,6 +169,8 @@ export async function publish(config, args) {
   const from = asArray(payload.published_from);
   const source = from.length > 0 ? ` from ${from.join(", ")}` : "";
   console.log(`Published live deployment #${payload.deployment_id}${source} (git_sha=${JSON.stringify(payload.git_sha ?? null)})`);
+  const knowledge = asArray(payload.knowledge);
+  if (knowledge.length > 0) console.log(`Knowledge now live: ${knowledge.join(", ")}`);
   printNotices(payload);
 }
 
@@ -193,7 +198,7 @@ export async function status(config) {
 }
 
 export async function diff(config, args) {
-  const environment = takeEnv(args, { fallback: "preview" });
+  const environment = takeEnv(args, { fallback: "preview", cwd: config.workspaceRoot });
   const full = takeFlag(args, "--full");
   const stat = takeFlag(args, "--stat");
   const nameOnly = takeFlag(args, "--name-only");

package/lib/commands/env.mjs

@@ -0,0 +1,90 @@
+// `vatio env` — where you are working, and how to point things at it.
+//
+// On a branch other than the default one, every command works in the branch's
+// own environment (see branch.mjs): its agent, its knowledge changes on top of
+// live, its secret values. This is the command that says which one that is and
+// hands over what an app needs to talk to it -- the publishable token and the
+// widget snippet -- and the link to try it in the console.
+
+import { deployClient } from "./deploy.mjs";
+import { fail, takeEnv } from "../support.mjs";
+
+export async function env(config, args) {
+  const workspace = config.resolveWorkspaceRequired();
+  const client = deployClient(config, workspace);
+  const sub = ["list", "show", "rm"].includes(args[0]) ? args.shift() : "show";
+
+  if (sub === "list") return await list(client, workspace);
+
+  const named = args.find((arg) => !arg.startsWith("-"));
+  if (named) args.splice(args.indexOf(named), 1);
+  const name = named ?? takeEnv(args, { fallback: "preview", cwd: config.workspaceRoot });
+
+  if (sub === "rm") return await remove(client, workspace, name);
+  return await show(client, workspace, name);
+}
+
+async function list(client, workspace) {
+  const rows = asArray((await client.environments()).data);
+  console.log(`Environments on workspace ${workspace} (${rows.length}):`);
+  for (const row of rows) {
+    const branch = row.git_branch ? `  branch=${row.git_branch}` : "";
+    const deployed = row.deployment_id ? `  deployment=#${row.deployment_id}` : "  (nothing pushed)";
+    const knowledge = row.knowledge_changes_count ? `  knowledge_changes=${row.knowledge_changes_count}` : "";
+    const active = row.last_activity_at ? `  last_activity=${row.last_activity_at}` : "";
+    console.log(`  ${row.name}${branch}${deployed}${knowledge}${active}`);
+  }
+}
+
+async function show(client, workspace, name) {
+  let row;
+  try {
+    row = await client.environment(name);
+  } catch (error) {
+    if (error?.status !== 404) throw error;
+    console.log(`${name} on workspace ${workspace} does not exist yet — \`vatio push\` creates it.`);
+    return;
+  }
+
+  console.log(`${row.name} on workspace ${workspace}`);
+  if (row.git_branch) console.log(`  branch: ${row.git_branch}`);
+  console.log(row.deployment_id
+    ? `  deployment: #${row.deployment_id}${row.git_sha ? ` (${row.git_sha.slice(0, 7)})` : ""}`
+    : "  deployment: none yet — `vatio push`");
+  if (row.share_url) console.log(`  try it: ${row.share_url}`);
+  if (row.page_url) console.log(`  page with the bubble: ${row.page_url}`);
+  if (row.knowledge_url) console.log(`  knowledge diff: ${row.knowledge_url}`);
+
+  if (row.token) {
+    console.log(`  publishable token: ${row.token}`);
+    console.log("\n  widget:");
+    console.log(`    <script src="${row.widget_script_url}"`);
+    console.log(`            data-workspace="${workspace}"`);
+    console.log(`            data-token="${row.token}"></script>`);
+    console.log("\n  SDK: new VatioChat({ workspace, token }) with the token above talks to this environment.");
+  }
+
+  const changes = asArray(row.knowledge_changes);
+  if (changes.length > 0) {
+    console.log(`\n  knowledge changes live does not have (${changes.length}):`);
+    for (const change of changes) {
+      const conflict = change.conflict ? "  CONFLICT: live changed it after you did" : "";
+      console.log(`    ${change.change.padEnd(8)} ${change.base}/${change.name}  v${change.version}${conflict}`);
+    }
+  }
+
+  const secrets = asArray(row.secrets);
+  if (secrets.length > 0) console.log(`\n  secrets with their own value here: ${secrets.join(", ")}`);
+}
+
+async function remove(client, workspace, name) {
+  if (!name || name === "live") fail("usage: vatio env rm NAME   (live cannot be removed)");
+
+  const result = await client.deleteEnvironment(name);
+  console.log(`Removed ${name} from workspace ${workspace} (${result.agents ?? 0} agents, ${result.chats ?? 0} chats)`);
+  console.log("Its unpublished knowledge changes and secret values went with it.");
+}
+
+function asArray(value) {
+  return Array.isArray(value) ? value : [];
+}