@vatio-ai/cli 0.131.0 → 0.133.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -84,20 +84,20 @@ init [SLUG] Create vatio.yml here, and the remote to match
84
84
  login | logout Authorize this machine in a browser, or revoke and forget it
85
85
  doctor Node, config, workspace and token status
86
86
 
87
- push Validate the workspace, then update preview
88
- pull [--env NAME] Write the deployed agent back into vatio.yml and tools/
89
- publish Take preview live, once `vatio test` has tested it
90
- diff [--env NAME] What this directory would change
91
- status Preview and live deployment state
92
- rollback Restore the previous live deployment
93
-
94
- chat "message" [--env NAME] [--new]
87
+ push Validate the workspace, then deploy it: your team has it at once,
88
+ everyone once the tests that pass today pass on it
89
+ pull Write the deployed agent back into vatio.yml and tools/
90
+ diff What this directory would change
91
+ status Where the newest change stands
92
+ rollback Put everyone back on the version before the last change
93
+
94
+ chat "message" [--new]
95
95
  Talk to your own agent; the token is the identity
96
96
  chat show [CHAT_ID] [--json]
97
97
  The chat you are in, or any chat in the workspace, with its tool calls
98
98
 
99
99
  flags Every open report from the inbox, for your coding agent to fix
100
- test Test every report against preview, in the background
100
+ test Test every report against your team's version, in the background
101
101
  test --wait Wait for the report; exits 1 if a case fails
102
102
  tools [--env NAME] How each tool's backend has been answering
103
103
 
@@ -105,7 +105,7 @@ kb list|show|create|rm Knowledge bases
105
105
  kb write|cat|rm-entry Entries, from a file or stdin
106
106
 
107
107
  secrets list|set|rm Credentials your tools read
108
- keys list|create|origins|revoke API keys: publishable (page, app) and secret (backend)
108
+ keys list|create|revoke API keys: publishable (page, app) and secret (backend)
109
109
  auth --new-key Keypair that signs the visitor's JWT
110
110
 
111
111
  whatsapp | instagram Set up in the inbox; prints the link
@@ -114,9 +114,6 @@ docs [--save [PATH]] The whole developer contract
114
114
  config show|set|unset base_url and token, per developer
115
115
  ```
116
116
 
117
- `--env NAME` targets an environment: `preview`, the next version, or `live`,
118
- what visitors talk to.
119
-
120
117
  Run `npx @vatio-ai/cli help` for the whole surface, and see
121
118
  [vatio.ai/docs](https://vatio.ai/docs) for the platform.
122
119
 
@@ -23,7 +23,7 @@ const USAGE =
23
23
 
24
24
  const DESCRIPTION_MOVED =
25
25
  "The business description moved into the agent's instructions: write what the business does in " +
26
- "`agent.instructions` in vatio.yml, where it is tested and published like the rest.";
26
+ "`agent.instructions` in vatio.yml, where it is tested and goes out like the rest.";
27
27
 
28
28
  export async function business(config, args) {
29
29
  const workspace = config.resolveWorkspaceRequired();
@@ -19,7 +19,7 @@ import { basename, dirname, join } from "node:path";
19
19
 
20
20
  import { ApiClient } from "../api-client.mjs";
21
21
  import { configHome } from "../config.mjs";
22
- import { fail, sleep, takeAll, takeEnv, takeFlag, takeValue } from "../support.mjs";
22
+ import { fail, sleep, takeAll, takeEnv, takeFlag, takeSide, takeValue } from "../support.mjs";
23
23
  import { IDENTITY_FLAGS_USAGE, takeIdentity, tokenFor } from "../visitor-identity.mjs";
24
24
 
25
25
  export const STATE_FILE = ".vatio-chat.json";
@@ -53,7 +53,7 @@ export async function chat(config, args) {
53
53
  `\`${arg}\` was removed. A CLI chat is you, the developer holding the token, unless you say who: ` +
54
54
  "--as-phone speaks as your verified WhatsApp (me) or a customer phone, --as-subject ID signs a visitor in " +
55
55
  "with your identity key, and --visitor-token brings a token you have; " +
56
- "to pick a deployment use --env."
56
+ "it talks to the newest version, the one your team has."
57
57
  );
58
58
  }
59
59
  }
@@ -112,13 +112,13 @@ export async function chat(config, args) {
112
112
 
113
113
  export function chatHelp() {
114
114
  return `Usage:
115
- vatio chat "message" [--file PATH]... [--env NAME] [--new] [--timeout N] [--as-phone me|PHONE] ${IDENTITY_FLAGS_USAGE}
115
+ vatio chat "message" [--file PATH]... [--new] [--timeout N] [--as-phone me|PHONE] ${IDENTITY_FLAGS_USAGE}
116
116
  vatio chat --chat CHAT_ID "message" [--file PATH]...
117
- vatio chat show [CHAT_ID] [--env NAME] [--last N] [--json]
117
+ vatio chat show [CHAT_ID] [--last N] [--json]
118
118
  ${EXPORT_USAGE}
119
119
 
120
- --env picks the deployment that answers: preview (default) or live. A chat
121
- against live is a real conversation and shows up in your inbox.
120
+ It talks to the newest version, the one your team has: a change you just
121
+ made answers here before everyone gets it.
122
122
 
123
123
  --file PATH attaches a file to the message, as a visitor would from the web:
124
124
  up to four, 8 MB each, images, PDFs, text files or audio. The message may be
@@ -154,14 +154,14 @@ that new chat and prints its id.
154
154
  \`--chat CHAT_ID\` continues that chat, whatever ${STATE_FILE} says: for
155
155
  conversations running side by side, each command names its own.
156
156
 
157
- \`--as-phone\` opens a preview chat that speaks as a phone, for tools that
157
+ \`--as-phone\` opens a chat that speaks as a phone, for tools that
158
158
  need $contact.phone_number or a team role (access: supervisor and up): \`me\`
159
159
  is your own verified WhatsApp, with your role on the team; one of the
160
160
  workspace's customer phones (added in the inbox, under Conversations → Try the
161
161
  agent → WhatsApp) is a customer. It stays a CLI chat: nothing goes to WhatsApp.
162
162
 
163
163
  \`export\` prints what people said and what they were answered between two
164
- dates (live unless --env says otherwise), one conversation per line as JSON,
164
+ dates (your customers', or your team's own with --team), one conversation per line as JSON,
165
165
  for reading them in bulk -- with a coding agent, say. Vatio redacts it before
166
166
  it leaves: names, emails, phone numbers and RUTs it knows are [FILTERED], and
167
167
  \`person\` stands for whoever it was without naming them. Anyone on the
@@ -169,12 +169,12 @@ workspace's team can run it, a viewer too, and every call is in the
169
169
  workspace's activity. Dates are whole days; --to defaults to now.`;
170
170
  }
171
171
 
172
- const EXPORT_USAGE = "vatio chat export --from DATE [--to DATE] [--env NAME] [--channel NAME] [--out FILE]";
172
+ const EXPORT_USAGE = "vatio chat export --from DATE [--to DATE] [--team] [--channel NAME] [--out FILE]";
173
173
 
174
174
  // One page at a time, written as it arrives: a month of a busy WhatsApp number
175
175
  // does not have to fit in memory to be read.
176
176
  async function exportChats(config, args) {
177
- const environment = takeEnv(args, { fallback: "live" });
177
+ const environment = takeSide(args, "--team");
178
178
  const from = takeValue(args, "--from");
179
179
  const to = takeValue(args, "--to");
180
180
  const channel = takeValue(args, "--channel");
@@ -620,7 +620,7 @@ async function startOver(config, options) {
620
620
  apiUrl,
621
621
  chatId: chatsFor(config, apiUrl)[options.environment] ?? null
622
622
  });
623
- console.log(`New ${options.environment} chat ${payload.chat_id} (\`vatio chat --chat ${payload.chat_id} "…"\` continues it)`);
623
+ console.log(`New chat ${payload.chat_id} (\`vatio chat --chat ${payload.chat_id} "…"\` continues it)`);
624
624
  return Number(payload.chat_id);
625
625
  }
626
626
 
@@ -1,4 +1,4 @@
1
- // push / pull / publish / rollback / status / diff.
1
+ // push / pull / publish (a notice now) / rollback / status / diff.
2
2
  //
3
3
  // Every one of them is HTTP. The workspace is parsed by the platform
4
4
  // (POST /deploy/check), so what is left here is: read the directory, send it,
@@ -7,7 +7,7 @@
7
7
  // `pull` is the exception, the one command that writes over the developer's
8
8
  // own files. It is back because the files stopped being the only writer: from
9
9
  // the Vatio MCP, in Claude or ChatGPT, people edit the agent itself, and each
10
- // edit lands in preview as a deployment of its own. What it writes is narrow
10
+ // edit is a deployment of its own. What it writes is narrow
11
11
  // on purpose (lib/pull.mjs): each tools/KEY.yml exactly as the platform holds
12
12
  // it, and only the `agent:` block of the vatio.yml already on disk, key by
13
13
  // key, because a revision keeps neither that file's comments nor `auth:` the
@@ -25,7 +25,7 @@ import { stringify as stringifyYaml } from "yaml";
25
25
 
26
26
  import { buildBundle, BundleError } from "../bundle.mjs";
27
27
  import { ApiClient, CliClient } from "../api-client.mjs";
28
- import { ConflictError, NotFoundError, UnprocessableError } from "../http.mjs";
28
+ import { ConflictError, NotFoundError } from "../http.mjs";
29
29
  import { MANIFEST_FILE } from "../workspace.mjs";
30
30
  import { PullError, planPull } from "../pull.mjs";
31
31
  import { deviceLogin } from "./auth.mjs";
@@ -132,9 +132,8 @@ export async function push(config, args) {
132
132
  // explicitly would make a bare `vatio push` and `vatio push --env preview`
133
133
  // two different requests that only happen to agree today.
134
134
  const environment = takeEnv(args, { fallback: null });
135
- // Replaces an unpublished push from another branch, or edits made outside
136
- // the files, which the platform otherwise refuses
137
- // (preview_has_unpublished_push, preview_edited_outside).
135
+ // Overwrites edits made outside the files (from the MCP or the inbox),
136
+ // which the platform otherwise refuses (preview_edited_outside).
138
137
  const force = takeFlag(args, "--force");
139
138
  const workspace = config.resolveWorkspaceRequired();
140
139
 
@@ -180,27 +179,14 @@ export async function push(config, args) {
180
179
  });
181
180
  } catch (error) {
182
181
  if (error instanceof ConflictError && error.errorKey === "preview_edited_outside") fail(editedOutsideMessage(error));
183
- if (error instanceof UnprocessableError && error.errorKey === "preview_has_unpublished_push") {
184
- fail(unpublishedPushMessage(error, gitBranch));
185
- }
186
182
  throw error;
187
183
  }
188
184
  // What the files match now, so the next push is built on it.
189
185
  config.rememberBaseDeployment({ baseUrl, workspace, deploymentId: payload.deployment_id });
190
186
 
191
- // The environment is named only when it is the answer to something: a push
192
- // that is waiting for a publish sits in preview, and that is worth saying.
193
- // One that visitors already have does not, and "to preview" there is the
194
- // line that has to be explained by hand afterwards.
195
- const outcome = payload.outcome;
196
- const landedOn = outcome && typeof outcome === "object" ? (outcome.reaches_visitors ? null : outcome.environment) : (payload.environment ?? "preview");
197
- const where = landedOn ? ` to ${landedOn}` : "";
198
- console.log(`Pushed deployment #${payload.deployment_id}${where} (git_sha=${JSON.stringify(payload.git_sha ?? null)})`);
199
- // What it means for the people talking to the agent. The environment name
200
- // answers a question nobody asked: for a draft it said "to preview" while
201
- // live was following every push, which is the single thing new developers
202
- // have to be told by hand.
203
- for (const line of consequenceLines(payload)) console.log(line);
187
+ console.log(`Pushed deployment #${payload.deployment_id} (git_sha=${JSON.stringify(payload.git_sha ?? null)})`);
188
+ // Who has it now: everyone, or the team until its tests pass.
189
+ for (const line of shippingLines(payload.shipping)) console.log(line);
204
190
  // Where to try it: the inbox's Try the agent panel for that environment.
205
191
  if (payload.share_url) console.log(`Try it: ${payload.share_url}`);
206
192
  // Mostly what the check already said: the platform loads the manifest again
@@ -209,7 +195,6 @@ export async function push(config, args) {
209
195
  if (IGNORED_BLOCK.test(warning)) ignored.push(warning);
210
196
  else console.log(` warning: ${warning}`);
211
197
  }
212
- if (payload.preview_url) console.log(`Preview: ${payload.preview_url}`);
213
198
 
214
199
  const hint = payload.first_push_hint;
215
200
  if (hint) {
@@ -221,65 +206,48 @@ export async function push(config, args) {
221
206
  printIgnored(ignored);
222
207
  }
223
208
 
224
- // The two or three lines that say who sees this push, read off the platform's
225
- // `outcome` rather than guessed from the environment name.
226
- //
227
- // A draft is the whole point: live follows preview on every push
228
- // (Vatio::Deploy::FollowPreview), so the agent is answering with this now,
229
- // and saying "pushed to preview" and nothing else is how a developer comes
230
- // to believe their work is not live when it is.
231
- function consequenceLines(payload) {
232
- const outcome = payload.outcome;
233
- // A platform older than this CLI sends no outcome; its prose notices still
209
+ // Who has a change now, read off the platform's `shipping` (Vatio::Deploy::Ship):
210
+ // everyone, or the team until the tests that pass today pass on it.
211
+ function shippingLines(shipping) {
212
+ // A platform older than this CLI sends none; its prose notices still
234
213
  // arrive and printNotices shows them.
235
- if (!outcome || typeof outcome !== "object") return [];
236
-
237
- if (outcome.reaches_visitors) {
238
- const lines = ["→ Your agent is answering with this now."];
239
- if (outcome.draft) {
240
- lines.push(
241
- " Every push reaches your app, WhatsApp and Instagram at once, until someone",
242
- " outside your team talks to it. From their first conversation on, a push waits",
243
- " for `vatio publish`."
244
- );
245
- }
246
- return lines;
247
- }
214
+ if (!shipping || typeof shipping !== "object") return [];
215
+ if (shipping.reaches_everyone || shipping.state === "live") return ["→ Everyone has it now: your app, WhatsApp and Instagram answer with it."];
248
216
 
249
- const live = outcome.live_deployment_id ? `deployment #${outcome.live_deployment_id}` : "the published version";
250
- const lines = [];
251
- if (outcome.left_draft_at) {
252
- lines.push("→ People have started talking to your agent, so a push no longer reaches them.");
253
- lines.push(` Visitors still get ${live}.`);
254
- } else {
255
- lines.push(`→ Visitors still get ${live}. This push is waiting.`);
256
- }
257
- lines.push(outcome.has_tests ? " Next: `vatio test --wait`, then `vatio publish`." : " Next: `vatio publish`.");
258
- return lines;
217
+ const by = shipping.expected_by ? `, around ${clock(shipping.expected_by)}` : "";
218
+ return [
219
+ "→ Your team has it now (`vatio chat` talks to it). Everyone gets it once the tests",
220
+ ` that pass today pass on it${by}. \`vatio status\` says where it stands.`
221
+ ];
222
+ }
223
+
224
+ function clock(iso) {
225
+ const at = new Date(iso);
226
+ return Number.isNaN(at.getTime()) ? iso : at.toLocaleTimeString([], { hour: "2-digit", minute: "2-digit" });
259
227
  }
260
228
 
261
229
  // Something the platform wants the developer to know about the command they
262
230
  // just ran -- a deprecation, usually. On stderr so scripts reading stdout keep
263
231
  // working.
264
232
  //
265
- // `outcome.supersedes` lists the ones consequenceLines already said in fewer
233
+ // `shipping.supersedes` lists the ones shippingLines already said in fewer
266
234
  // words; printing both would say it twice.
267
235
  function printNotices(payload) {
268
- const superseded = new Set(asArray(payload.outcome?.supersedes));
236
+ const superseded = new Set(asArray(payload.shipping?.supersedes ?? payload.outcome?.supersedes));
269
237
  for (const notice of asArray(payload.notices)) {
270
238
  if (superseded.has(notice)) continue;
271
239
  process.stderr.write(`\n${paint("yellow", `Notice: ${notice}`)}\n`);
272
240
  }
273
241
  }
274
242
 
275
- // Refused because preview holds edits the files have never seen: which, and
243
+ // Refused because the agent holds edits the files have never seen: which, and
276
244
  // the two ways forward. The platform's message says all of it in one line,
277
245
  // for releases that print only that; with the list to go by, this one says
278
246
  // it a line per edit instead of repeating it.
279
247
  function editedOutsideMessage(error) {
280
248
  const edits = asArray(error.body.edits);
281
249
  const count = edits.length === 1 ? "a change" : `${edits.length} changes`;
282
- const lines = edits.length === 0 ? [error.message] : [`Preview has ${count} made outside your files that this push would overwrite:`];
250
+ const lines = edits.length === 0 ? [error.message] : [`Your agent has ${count} made outside your files that this push would overwrite:`];
283
251
  for (const edit of edits) lines.push(` ${editLine(edit)}`);
284
252
  const them = edits.length === 1 ? "it" : "them";
285
253
  lines.push(
@@ -290,42 +258,6 @@ function editedOutsideMessage(error) {
290
258
  return lines.join("\n");
291
259
  }
292
260
 
293
- // Refused because preview holds a push from another branch nobody published:
294
- // whose, so the session that hit it can tell whether that work is done
295
- // without asking around. A platform older than `held` sends its own sentence.
296
- function unpublishedPushMessage(error, branch) {
297
- const held = error.body.held;
298
- if (!held || typeof held !== "object") return error.message;
299
-
300
- const yours = branch ? ` Yours is from branch ${branch}.` : "";
301
- return [
302
- "Preview holds a push from another branch that is not published:",
303
- ` ${heldLine(held)}`,
304
- "",
305
- `A push would replace it.${yours} Publish what preview holds first (\`vatio publish\`), or`,
306
- "`vatio push --force` to replace it. `vatio status` shows what preview holds at any time."
307
- ].join("\n");
308
- }
309
-
310
- // `#42 from branch feat/x, a1b2c3d plus uncommitted changes, pushed by ivan on
311
- // 2026-10-28T14:02:00Z`. Fields as AgentDeployment#held_payload and
312
- // #status_payload name them; the id is `deployment_id` in one and `id` in the
313
- // other.
314
- function heldLine(deployment) {
315
- const id = deployment.deployment_id ?? deployment.id;
316
- const parts = [`#${id}`];
317
- if (deployment.git_branch) parts[0] += ` from branch ${deployment.git_branch}`;
318
- if (deployment.source === "edit") {
319
- parts.push(`an edit made outside your files${deployment.change_summary ? ` (${deployment.change_summary})` : ""}`);
320
- }
321
- const sha = deployment.git_sha ? String(deployment.git_sha).slice(0, 7) : null;
322
- if (deployment.git_dirty === true) parts.push(`${sha ?? "no commit"} plus uncommitted changes`);
323
- else if (sha) parts.push(deployment.git_dirty === false ? `${sha}, committed` : sha);
324
- const by = deployment.created_by ? ` by ${deployment.created_by}` : "";
325
- parts.push(`${deployment.source === "edit" ? "made" : "pushed"}${by} on ${deployment.created_at}`);
326
- return parts.join(", ");
327
- }
328
-
329
261
  // `#42 by ivan@x.cl via Claude, 2026-10-16T12:00:00Z: instructions, tool my_orders`
330
262
  function editLine(edit) {
331
263
  const who = edit?.created_by ? ` by ${edit.created_by}` : "";
@@ -416,57 +348,19 @@ function refuseUnkeptChanges(root) {
416
348
  }
417
349
  }
418
350
 
351
+ // There is nothing to publish: a push reaches everyone on its own once its
352
+ // tests pass. Kept so scripts and habits that still run it learn why.
419
353
  export async function publish(config, args) {
420
- // Here `--env` names the environment being promoted, not a destination: the
421
- // destination of a publish is always live, and what goes there is preview,
422
- // with its knowledge changes.
423
- const environment = takeEnv(args, { fallback: null });
424
- // Publishes even when preview fails a report that live passes.
425
- const force = takeFlag(args, "--force");
426
- const workspace = config.resolveWorkspaceRequired();
427
- let payload;
428
- try {
429
- payload = await deployClient(config, workspace).publish({
430
- createdBy: process.env.USER ?? null,
431
- environment,
432
- force
433
- });
434
- } catch (error) {
435
- // evals_missing and evals_running already say what to run next; a
436
- // regression also needs to say which reports.
437
- if (error instanceof UnprocessableError && error.errorKey === "evals_regressed") fail(regressionsMessage(error));
438
- throw error;
439
- }
440
- const from = asArray(payload.published_from);
441
- const source = from.length > 0 ? ` from ${from.join(", ")}` : "";
442
- console.log(`Published live deployment #${payload.deployment_id}${source} (git_sha=${JSON.stringify(payload.git_sha ?? null)})`);
443
- const knowledge = asArray(payload.knowledge);
444
- if (knowledge.length > 0) console.log(`Knowledge now live: ${knowledge.join(", ")}`);
445
- printNotices(payload);
446
- }
447
-
448
- function regressionsMessage(error) {
449
- const rows = asArray(error.body.regressions);
450
- const lines = [error.message];
451
- for (const row of rows) {
452
- const untested = row.vatio_error ? " (not tested: an error on Vatio's side, not your agent)" : "";
453
- lines.push(` ${row.id} — ${row.title}${untested}`);
454
- }
455
- const broken = rows.filter((row) => !row.vatio_error);
456
- lines.push(
457
- "",
458
- broken.length > 0
459
- ? "Fix them, then `vatio push` and `vatio test --wait` again before publishing."
460
- : "Run `vatio test --wait` again, then publish.",
461
- "`vatio publish --force` publishes anyway: only if you know what you're doing."
462
- );
463
- return lines.join("\n");
354
+ takeEnv(args, { fallback: null });
355
+ takeFlag(args, "--force");
356
+ console.log("There is nothing to publish: every push reaches your team at once, and everyone once the tests");
357
+ console.log("that pass today pass on it. `vatio status` says where the newest change stands.");
464
358
  }
465
359
 
466
360
  export async function rollback(config) {
467
361
  const workspace = config.resolveWorkspaceRequired();
468
362
  const payload = await deployClient(config, workspace).rollback({ createdBy: process.env.USER ?? null });
469
- console.log(`Rolled back to deployment #${payload.deployment_id} (from #${payload.rolled_back_from_id})`);
363
+ console.log(`Everyone, your team included, is back on deployment #${payload.deployment_id} (from #${payload.rolled_back_from_id})`);
470
364
  printNotices(payload);
471
365
  }
472
366
 
@@ -476,9 +370,9 @@ export async function status(config) {
476
370
  console.log(JSON.stringify(payload, null, 2));
477
371
  printWhatsappIssue(payload.whatsapp);
478
372
 
479
- // There is one preview, so a session about to push wants to know whose work
480
- // is on it, and whether that work has gone live, without reading the JSON.
481
- printPreviewHolds(payload);
373
+ // Where the newest change stands, without reading the JSON: everyone has it,
374
+ // its tests are running, or one that passes today held it back.
375
+ printShipping(payload.shipping);
482
376
 
483
377
  // A base with content that no deployed agent reads is knowledge the agent
484
378
  // cannot reach, and nothing else says so -- it just answers without it. On
@@ -489,14 +383,14 @@ export async function status(config) {
489
383
  `reads it — add \`knowledge: [${base.name}]\` to vatio.yml and push.`
490
384
  );
491
385
  }
492
- // Edits from the Vatio MCP that preview carries, no push has written over
386
+ // Edits from the Vatio MCP that the agent carries, no push has written over
493
387
  // and these files have not pulled: the next push is refused until they are.
494
388
  const base = config.baseDeploymentFor({ baseUrl: config.resolveBaseUrl(), workspace });
495
389
  const edits = asArray(payload.preview_edited_outside_push).filter(
496
390
  (edit) => base == null || Number(edit.deployment_id) > base
497
391
  );
498
392
  if (edits.length > 0) {
499
- console.error(`Preview has ${edits.length === 1 ? "a change" : `${edits.length} changes`} made outside your files:`);
393
+ console.error(`Your agent has ${edits.length === 1 ? "a change" : `${edits.length} changes`} made outside your files:`);
500
394
  for (const edit of edits) console.error(` ${editLine(edit)}`);
501
395
  console.error(" `vatio pull` brings them into your files before your next push.");
502
396
  }
@@ -504,17 +398,28 @@ export async function status(config) {
504
398
  printImpact(payload.impact);
505
399
  }
506
400
 
507
- function printPreviewHolds(payload) {
508
- const preview = payload.preview;
509
- if (!preview || typeof preview !== "object") return;
510
-
511
- const live = payload.live;
512
- const published = preview.current_live
513
- ? "live runs it"
514
- : live?.id
515
- ? `not published: live runs #${live.id}`
516
- : "not published";
517
- console.error(`Preview holds ${heldLine(preview)}; ${published}.`);
401
+ // On stderr so piping `vatio status` into jq keeps working.
402
+ function printShipping(shipping) {
403
+ if (!shipping || typeof shipping !== "object" || shipping.state === "live") return;
404
+
405
+ const who = shipping.changed_by ? ` by ${shipping.changed_by}` : "";
406
+ if (shipping.state === "testing") {
407
+ const by = shipping.testing?.expected_by ? `, around ${clock(shipping.testing.expected_by)}` : "";
408
+ console.error(`Your team has #${shipping.newest_version}${who}; everyone gets it once its tests pass${by}.`);
409
+ return;
410
+ }
411
+ const held = shipping.held ?? {};
412
+ console.error(`Held: your team has #${shipping.newest_version}${who}, and everyone else keeps #${shipping.version}.`);
413
+ if (held.reason === "tests_capped") console.error(" Vatio could not test it: the workspace used up today's test runs.");
414
+ else if (held.reason === "error") console.error(` Vatio could not put it in place: ${held.message ?? "unknown error"}`);
415
+ else {
416
+ console.error(" These tests pass on the version everyone has and failed on it in every attempt:");
417
+ for (const test of asArray(held.tests)) {
418
+ const untested = test.vatio_error ? " (not tested: an error on Vatio's side)" : "";
419
+ console.error(` ${test.id} — ${test.title}${untested}`);
420
+ }
421
+ }
422
+ console.error(" Another push that fixes it moves it on, or `vatio test rm ID` for a test it made obsolete.");
518
423
  }
519
424
 
520
425
  // A number that looks connected while Meta refuses every send from it: first
@@ -568,7 +473,7 @@ function printImpact(impact) {
568
473
  if (asked.questions > 0) parts.push(`the agent asked your team ${asked.questions} ${asked.questions === 1 ? "time" : "times"} instead of guessing`);
569
474
  if (impact.test_replays > 0) parts.push(`Vatio replayed ${impact.test_replays} test conversations`);
570
475
  const held = impact.regressions_held ?? {};
571
- if (held.count > 0) parts.push(`the publish gate kept ${held.count} ${held.count === 1 ? "regression" : "regressions"} off live`);
476
+ if (held.count > 0) parts.push(`the tests held ${held.count} ${held.count === 1 ? "regression" : "regressions"} back from everyone`);
572
477
  const fixed = impact.reports_fixed ?? {};
573
478
  if (fixed.count > 0) {
574
479
  parts.push(`${fixed.count} ${fixed.count === 1 ? "report was" : "reports were"} fixed (median ${fixed.median_hours} h)`);
@@ -616,7 +521,7 @@ export async function diff(config, args) {
616
521
  const workspace = config.resolveWorkspaceRequired();
617
522
  // The diff comes back with the check -- one call instead of "parse here,
618
523
  // fetch there, compare with a copy of the platform's rules that may have
619
- // drifted". `--env live` is what answers "what would publishing change?"
524
+ // drifted".
620
525
  const payload = await checkWorkspace(config, workspace, { environment });
621
526
  printDiagnostics(payload);
622
527
  if (!payload.ok) fail(`diff aborted: the workspace does not load (${asArray(payload.errors).length} error(s))`);
@@ -45,8 +45,7 @@ async function show(client, workspace, name) {
45
45
  row = await client.environment(name);
46
46
  } catch (error) {
47
47
  if (error?.status !== 404) throw error;
48
- const creates = name === "live" ? "vatio publish" : "vatio push";
49
- console.log(`${name} on workspace ${workspace} does not exist yet — \`${creates}\` creates it.`);
48
+ console.log(`${name} on workspace ${workspace} does not exist yet — \`vatio push\` creates it.`);
50
49
  return;
51
50
  }
52
51
 
@@ -69,7 +69,7 @@ export async function tools(config, args) {
69
69
  const environment = takeEnv(args, { fallback: "live" });
70
70
  const period = takeValue(args, "--period");
71
71
  const json = takeFlag(args, "--json");
72
- if (args.length > 0) fail("Usage: vatio tools [--env NAME] [--period 1h|1d|7d|30d] [--json]");
72
+ if (args.length > 0) fail("Usage: vatio tools [--period 1h|1d|7d|30d] [--json]");
73
73
 
74
74
  if (json) {
75
75
  const { url, token } = workspaceBase(config);
@@ -94,8 +94,8 @@ export async function test(config, args) {
94
94
  }
95
95
 
96
96
  const TEST_ADD_USAGE =
97
- 'vatio test add "QUESTION" "WHAT IT SHOULD DO" [--as-phone me|PHONE] [--as-subject ID] [--env NAME]\n' +
98
- ' vatio test add "WHAT IT SHOULD DO" [--chat ID | --message ID] [--env NAME]';
97
+ 'vatio test add "QUESTION" "WHAT IT SHOULD DO" [--as-phone me|PHONE] [--as-subject ID]\n' +
98
+ ' vatio test add "WHAT IT SHOULD DO" [--chat ID | --message ID]';
99
99
 
100
100
  // What the agent should do when asked something, checked on every version.
101
101
  // With a question, Vatio asks it in a new chat and the test is made on that
@@ -150,7 +150,7 @@ async function addTest(config, args) {
150
150
  const judged = added.judged ?? {};
151
151
  if (judged.verdict === "pass") {
152
152
  console.log(` Passes now: ${judged.reason}`);
153
- console.log("`vatio test` replays it on every version; once live passes it, `vatio publish` refuses a version that fails it.");
153
+ console.log("`vatio test` replays it on every version; once everyone's version passes it, a change that fails it does not reach them.");
154
154
  } else if (judged.verdict === "fail") {
155
155
  console.log(` Fails now: ${judged.reason}`);
156
156
  console.log("Fix the agent, `vatio push`, then `vatio test`: `vatio test list` shows it with its replay once it has run.");
@@ -253,8 +253,8 @@ async function runTests(config, args) {
253
253
  "A test is what the agent should do when someone asks something:\n" +
254
254
  ' vatio test add "what a visitor would ask" "what the answer has to do"\n' +
255
255
  "\n" +
256
- "Then `vatio test` replays them all on every version, and `vatio publish` refuses\n" +
257
- "one that breaks them. Replies the team reports in the inbox become tests too."
256
+ "Then `vatio test` replays them all on every version, and a change that breaks one\n" +
257
+ "does not reach everyone. Replies the team reports in the inbox become tests too."
258
258
  );
259
259
  return;
260
260
  }
@@ -4,12 +4,10 @@
4
4
  // vatio.yml is a list of *names*, and a push neither fills nor empties one.
5
5
  // That is why this is a command and not part of the manifest.
6
6
  //
7
- // The entries are live. Reads and writes here are as one environment sees
8
- // them: `preview` by default, which keeps the entries it changed on top of
9
- // live and answers from them; `--env live` writes live directly, the way a
10
- // supervisor in the inbox does. `vatio publish` takes the changes live with
11
- // the agent -- `vatio kb publish` takes them alone. So: write, try it on
12
- // preview, publish.
7
+ // A write reaches your team at once and everyone once the tests that pass
8
+ // today pass with it, like every other change (the platform's Ship). Reads
9
+ // show the newest version, the team's; `--env live` reads the one everyone
10
+ // has, while a change is still on its way.
13
11
  //
14
12
  // A base holds entries, and an entry is markdown you wrote.
15
13
 
@@ -47,18 +45,13 @@ export async function kb(config, args) {
47
45
  case "rollback":
48
46
  return fail(
49
47
  "`vatio kb rollback` was removed. Restore one entry instead: `vatio kb history BASE` lists what " +
50
- "reached live, `vatio kb cat BASE ENTRY --version N > old.md` prints one, and " +
51
- "`vatio kb write BASE ENTRY old.md --env live` brings it back."
48
+ "reached everyone, `vatio kb cat BASE ENTRY --version N > old.md` prints one, and " +
49
+ "`vatio kb write BASE ENTRY old.md` brings it back."
52
50
  );
53
51
  default: fail(`Unknown kb subcommand: ${sub}\n\n${usage()}`);
54
52
  }
55
53
  }
56
54
 
57
- // `preview` when the platform chose, for messages.
58
- function envName(env) {
59
- return env ?? "preview";
60
- }
61
-
62
55
  function usage() {
63
56
  return `usage:
64
57
  vatio kb List knowledge bases
@@ -68,12 +61,11 @@ function usage() {
68
61
  vatio kb write BASE ENTRY [FILE] Write an entry, from FILE or stdin
69
62
  vatio kb cat BASE ENTRY [--version N] Print an entry's markdown, or one of its versions
70
63
  vatio kb rm-entry BASE ENTRY Delete one entry
71
- vatio kb status BASE What this environment changed that live does not have
72
- vatio kb publish BASE Take this environment's changes live, without the agent
73
- vatio kb history BASE What reached live, newest first
64
+ vatio kb status BASE What your team has that everyone does not have yet
65
+ vatio kb history BASE What reached everyone, newest first
74
66
 
75
- Entry commands, status and publish take --env preview|live; the default is
76
- preview. --env live writes live.`;
67
+ A write reaches your team at once and everyone once the tests that pass
68
+ today pass with it.`;
77
69
  }
78
70
 
79
71
  async function list({ client, workspace, env }) {
@@ -86,7 +78,7 @@ async function list({ client, workspace, env }) {
86
78
 
87
79
  console.log(`Knowledge bases on workspace ${workspace} (${bases.length}):`);
88
80
  for (const row of bases) {
89
- const pending = row.pending_changes ? ` ${row.pending_changes} unpublished in ${envName(env)}` : "";
81
+ const pending = row.pending_changes ? ` ${row.pending_changes} on their way to everyone` : "";
90
82
  console.log(
91
83
  ` ${row.name} entries=${row.entries_count} ready=${row.answerable_count}` +
92
84
  `${pending}${referenceNote(row)}`
@@ -110,7 +102,7 @@ async function show({ client, workspace, env }, name) {
110
102
  `ready=${base.answerable_count}${referenceNote(base)}`
111
103
  );
112
104
  if (base.pending_changes) {
113
- console.log(` ${base.pending_changes} change(s) in ${envName(env)} that live does not have — \`vatio kb status ${base.name}\``);
105
+ console.log(` ${base.pending_changes} change(s) only your team has yet — \`vatio kb status ${base.name}\``);
114
106
  }
115
107
 
116
108
  const entries = asArray(base.entries);
@@ -119,10 +111,10 @@ async function show({ client, workspace, env }, name) {
119
111
  return;
120
112
  }
121
113
 
122
- console.log(`\n entries, as ${envName(env)} sees them:`);
114
+ console.log("\n entries:");
123
115
  for (const entry of entries) {
124
116
  const version = entry.version ? ` v${entry.version}` : "";
125
- const unpublished = entry.published === false ? " (not live yet)" : "";
117
+ const unpublished = entry.published === false ? " (your team only, for now)" : "";
126
118
  console.log(` ${entry.name}${version} ${entry.state ?? "?"}${unpublished}`);
127
119
  }
128
120
  }
@@ -181,14 +173,12 @@ async function write({ client, workspace, env }, args) {
181
173
  fail("Nothing to write: pass a FILE, or pipe the markdown in on stdin.");
182
174
  }
183
175
 
184
- const row = await client.writeKnowledgeEntry({ base, name, content, environment: env });
176
+ const row = await client.writeKnowledgeEntry({ base, name, content });
185
177
  const version = row.version ? ` (v${row.version})` : "";
186
- if (env === "live") {
187
- console.log(`Wrote ${row.name}${version} to ${base} on workspace ${workspace}. Live answers with it now.`);
188
- return;
189
- }
190
- console.log(`Wrote ${row.name}${version} to ${base} in ${envName(env)} on workspace ${workspace}`);
191
- console.log(`${envName(env)} answers with it now; \`vatio publish\` takes it live with the agent.`);
178
+ console.log(`Wrote ${row.name}${version} to ${base} on workspace ${workspace}`);
179
+ // A platform older than this CLI sends no `shipping`.
180
+ if (row.shipping?.reaches_everyone) console.log("Everyone has it now.");
181
+ else if (row.shipping) console.log("Your team has it now; everyone gets it once the tests that pass today pass with it.");
192
182
  }
193
183
 
194
184
  // Prints exactly what the platform holds, so a diff against the file you
@@ -206,57 +196,51 @@ async function cat({ client, env }, args) {
206
196
  async function removeEntry({ client, workspace, env }, base, name) {
207
197
  if (!base || !name) fail("usage: vatio kb rm-entry BASE ENTRY");
208
198
 
209
- await client.deleteKnowledgeEntry({ base, name, environment: env });
210
- console.log(`Deleted entry ${name} from ${base} in ${envName(env)} on workspace ${workspace}`);
199
+ await client.deleteKnowledgeEntry({ base, name });
200
+ console.log(`Deleted entry ${name} from ${base} on workspace ${workspace}`);
201
+ console.log("It goes out like any change: `vatio status` says where it stands.");
211
202
  }
212
203
 
213
- // What this environment changed against live, entry by entry -- what
214
- // publishing it would do, and which entries live changed underneath.
204
+ // What the team has that everyone does not have yet, entry by entry: the
205
+ // knowledge of a change still on its way (its tests are running, or one held it).
215
206
  async function status({ client, workspace, env }, base) {
216
207
  if (!base) fail("usage: vatio kb status BASE");
217
208
 
218
209
  const payload = await client.knowledgeChanges(base, { environment: env });
219
210
  const changes = asArray(payload.data);
220
211
  if (changes.length === 0) {
221
- console.log(`${base} in ${envName(env)} on workspace ${workspace}: nothing that live does not have`);
212
+ console.log(`${base} on workspace ${workspace}: everyone has every entry your team has`);
222
213
  return;
223
214
  }
224
215
 
225
- console.log(`${base} in ${envName(env)} on workspace ${workspace}: ${changes.length} change${changes.length === 1 ? "" : "s"} live does not have`);
216
+ console.log(`${base} on workspace ${workspace}: ${changes.length} change${changes.length === 1 ? "" : "s"} only your team has yet`);
226
217
  for (const change of changes) {
227
218
  const from = change.live_version ? `v${change.live_version}` : "—";
228
219
  const to = change.version ?? change.draft_version;
229
- const conflict = change.conflict ? " CONFLICT: live changed it after you did" : "";
230
- console.log(` ${change.change.padEnd(8)} ${change.name} ${from} → v${to}${conflict}`);
231
- }
232
- if (changes.some((change) => change.conflict)) {
233
- console.log(`\nRead each conflicting entry from live (\`vatio kb cat ${base} ENTRY --env live\`), write your change on top, and it clears.`);
234
- } else {
235
- console.log("\n`vatio publish` takes them live with the agent; `vatio kb publish` takes them alone.");
220
+ console.log(` ${change.change.padEnd(8)} ${change.name} ${from} → v${to}`);
236
221
  }
222
+ console.log("\nEveryone gets them once the tests pass; `vatio status` says where that stands.");
237
223
  }
238
224
 
239
- async function publish({ client, workspace, env }, base) {
240
- if (!base) fail("usage: vatio kb publish BASE [--env NAME]");
241
-
242
- const result = await client.publishKnowledgeBase({ base, environment: env });
243
- const names = asArray(result.published);
244
- console.log(`Published ${names.length} change${names.length === 1 ? "" : "s"} to ${base} from ${envName(env)} on workspace ${workspace}: ${names.join(", ")}`);
245
- console.log("Live answers from them now.");
225
+ // There is nothing to publish: knowledge goes out with every change. Kept so
226
+ // habits that still run it learn why.
227
+ async function publish() {
228
+ console.log("There is nothing to publish: knowledge reaches your team when you write it, and everyone once the");
229
+ console.log("tests that pass today pass with it. `vatio status` says where the newest change stands.");
246
230
  }
247
231
 
248
- // Every version that reached live, newest first. Going back is writing one
232
+ // Every version that reached everyone, newest first. Going back is writing one
249
233
  // of them again.
250
234
  async function history(client, workspace, base) {
251
235
  if (!base) fail("usage: vatio kb history BASE");
252
236
 
253
237
  const versions = asArray((await client.knowledgeHistory(base)).data);
254
238
  if (versions.length === 0) {
255
- console.log(`Nothing in ${base} on workspace ${workspace} has reached live yet`);
239
+ console.log(`Nothing in ${base} on workspace ${workspace} has reached everyone yet`);
256
240
  return;
257
241
  }
258
242
 
259
- console.log(`What reached live in ${base} on workspace ${workspace}:`);
243
+ console.log(`What reached everyone in ${base} on workspace ${workspace}:`);
260
244
  for (const row of versions) {
261
245
  const who = row.author ? ` ${row.author}` : "";
262
246
  const what = row.deleted ? " deleted" : "";
@@ -1,13 +1,13 @@
1
1
  // Review terminal failures after Vatio has finished its automatic attempts.
2
2
 
3
3
  import { deployClient } from "./deploy.mjs";
4
- import { fail, takeEnv, takeFlag, takeValue } from "../support.mjs";
4
+ import { fail, takeFlag, takeSide, takeValue } from "../support.mjs";
5
5
 
6
- const USAGE = "vatio whatsapp failed [--since DATE] [--until DATE] [--error-code CODE] " +
6
+ const USAGE = "vatio whatsapp failed [--test] [--since DATE] [--until DATE] [--error-code CODE] " +
7
7
  "[--error-contains TEXT] [--before ID] [--json]";
8
8
 
9
9
  export async function messages(config, args) {
10
- const environment = takeEnv(args, { fallback: "live" });
10
+ const environment = takeSide(args, "--test");
11
11
  const json = takeFlag(args, "--json");
12
12
  const since = takeValue(args, "--since");
13
13
  const until = takeValue(args, "--until");
@@ -168,7 +168,7 @@ export async function init(config, args) {
168
168
  }
169
169
  console.log("");
170
170
  console.log("Next:");
171
- console.log(` edit ${MANIFEST_FILE}, then \`vatio push\` and \`vatio publish\``);
171
+ console.log(` edit ${MANIFEST_FILE}, then \`vatio push\``);
172
172
  console.log(` docs: ${DOCS_URL}`);
173
173
  }
174
174
 
@@ -188,8 +188,9 @@ const AGENTS_NOTE = [
188
188
  "",
189
189
  "To fix what supervisors reported and the tests that fail, take them all in",
190
190
  "one session: `vatio test list` (follow the instructions at the top of its",
191
- "output), fix, `vatio push`, `vatio test` until they pass, then",
192
- "`vatio publish`. The `vatio-improve` skill walks through it.",
191
+ "output), fix, `vatio push`, and `vatio test` until they pass: a push reaches",
192
+ "everyone once the tests that pass today pass on it. The `vatio-improve` skill",
193
+ "walks through it.",
193
194
  "`vatio test add \"QUESTION\" \"WHAT IT SHOULD DO\"` adds a test.",
194
195
  "`vatio tools --env live` shows how each tool's backend has been answering:",
195
196
  "error rate, timeouts, latency and the calls that failed.",
@@ -7,7 +7,7 @@
7
7
  import { readFileSync } from "node:fs";
8
8
 
9
9
  import { deployClient } from "./deploy.mjs";
10
- import { fail, paint, sleep, takeEnv, takeFlag, takeValue } from "../support.mjs";
10
+ import { fail, paint, sleep, takeFlag, takeSide, takeValue } from "../support.mjs";
11
11
 
12
12
  const WAIT_INTERVAL_MS = 2_000;
13
13
 
@@ -18,7 +18,7 @@ function takeAll(args, name) {
18
18
  return values;
19
19
  }
20
20
 
21
- const LIST_USAGE = "vatio whatsapp templates list [--env live] [--json]";
21
+ const LIST_USAGE = "vatio whatsapp templates list [--test-number] [--json]";
22
22
  const CREATE_USAGE = "vatio whatsapp templates create NAME --language CODE --body TEXT [--example VALUE]... " +
23
23
  "[--category utility|marketing] [--footer TEXT] [--button-url 'TEXT|URL']... [--button-example VALUE]... " +
24
24
  "[--button-phone 'TEXT|PHONE'] [--button-quick-reply TEXT]... [--json]\n" +
@@ -42,7 +42,7 @@ export async function templates(config, args) {
42
42
  args.shift();
43
43
  return deleteTemplate(config, args, json);
44
44
  }
45
- const environment = takeEnv(args, { fallback: "live" });
45
+ const environment = takeSide(args, "--test-number");
46
46
  const workspace = config.resolveWorkspaceRequired();
47
47
  const client = deployClient(config, workspace);
48
48
  const sub = args.shift() ?? "list";
@@ -58,7 +58,7 @@ export async function templates(config, args) {
58
58
  if (list.length === 0) {
59
59
  if (live && payload.whatsapp_connected === false) {
60
60
  console.log("This workspace has no WhatsApp number of its own yet. The templates you create stay on Vatio's " +
61
- "test number until you connect one, and then Vatio moves them to it: vatio whatsapp templates list --env preview");
61
+ "test number until you connect one, and then Vatio moves them to it: vatio whatsapp templates list --test-number");
62
62
  } else if (!live && payload.whatsapp_connected === true) {
63
63
  console.log("This workspace has its own WhatsApp number, so its templates are there: vatio whatsapp templates list");
64
64
  } else {
@@ -141,10 +141,10 @@ function printCreated(template, json, count) {
141
141
  `${own ? "your own number" : "Vatio's test number"}: ${template.category}, ` +
142
142
  `${count} param${count === 1 ? "" : "s"}, ${paint("cyan", template.status)}.`);
143
143
  console.log("Meta usually decides within minutes, at most 24 hours. Check with: vatio whatsapp templates list" +
144
- (own ? "" : " --env preview"));
144
+ (own ? "" : " --test-number"));
145
145
  console.log(own
146
146
  ? "Once APPROVED, your backend sends it with a live key outside the 24-hour window with:"
147
- : "Once APPROVED, a preview key sends it on Vatio's test number, to your team's verified WhatsApps and your " +
147
+ : "Once APPROVED, a test secret key sends it on Vatio's test number, to your team's verified WhatsApps and your " +
148
148
  "customer phones, outside the 24-hour window with:");
149
149
  console.log(` "template": ${JSON.stringify(template.example)}`);
150
150
  if (!own) {
@@ -201,7 +201,7 @@ async function deleteTemplate(config, args, json) {
201
201
  }
202
202
 
203
203
  export async function webhooks(config, args) {
204
- const environment = takeEnv(args, { fallback: "live" });
204
+ const environment = takeSide(args, "--test");
205
205
  const label = takeValue(args, "--label");
206
206
  const events = takeAll(args, "--event");
207
207
  const workspace = config.resolveWorkspaceRequired();
@@ -213,13 +213,13 @@ export async function webhooks(config, args) {
213
213
  const list = Array.isArray(payload.webhook_endpoints) ? payload.webhook_endpoints : [];
214
214
  if (list.length === 0) {
215
215
  console.log(`No webhook endpoints on workspace ${workspace}`);
216
- console.log(" Add one: vatio webhooks create https://your-app.com/vatio/webhooks --env live");
216
+ console.log(" Add one: vatio webhooks create https://your-app.com/vatio/webhooks");
217
217
  return;
218
218
  }
219
219
  console.log(`Webhook endpoints on workspace ${workspace} (${list.length}):`);
220
220
  for (const endpoint of list) {
221
221
  const state = endpoint.enabled ? paint("green", "enabled") : paint("red", "disabled");
222
- console.log(` #${endpoint.id} ${endpoint.environment} ${endpoint.url} ${state}`);
222
+ console.log(` #${endpoint.id} ${endpoint.environment === "preview" ? "test" : endpoint.environment} ${endpoint.url} ${state}`);
223
223
  console.log(` events: ${endpoint.events.length > 0 ? endpoint.events.join(", ") : "all"}` +
224
224
  (endpoint.consecutive_failures > 0 ? ` failing: ${endpoint.consecutive_failures} in a row` : ""));
225
225
  }
@@ -227,9 +227,9 @@ export async function webhooks(config, args) {
227
227
  }
228
228
  if (sub === "create") {
229
229
  const url = args.shift();
230
- if (!url) fail("Usage: vatio webhooks create URL [--event NAME]... [--label NAME] [--env NAME]");
230
+ if (!url) fail("Usage: vatio webhooks create URL [--event NAME]... [--label NAME] [--test]");
231
231
  const payload = await client.createWebhookEndpoint({ environment, url, events, label });
232
- console.log(`Created webhook endpoint #${payload.id} for ${environment}: ${payload.url}`);
232
+ console.log(`Created ${environment === "preview" ? "a test" : "a live"} webhook endpoint #${payload.id}: ${payload.url}`);
233
233
  console.log(` events: ${payload.events.length > 0 ? payload.events.join(", ") : "all"}`);
234
234
  console.log("");
235
235
  // Vatio signs every delivery with it; it is not shown again.
@@ -284,7 +284,7 @@ export async function webhooks(config, args) {
284
284
  return;
285
285
  }
286
286
 
287
- fail("Usage: vatio webhooks list|create URL [--event NAME]...|test ID|deliveries ID|enable ID|rm ID [--env NAME]");
287
+ fail("Usage: vatio webhooks list|create URL [--event NAME]...|test ID|deliveries ID|enable ID|rm ID [--test]");
288
288
  }
289
289
 
290
290
  function printDelivery(delivery) {
@@ -99,7 +99,7 @@ async function listSecrets(client, workspace, environment) {
99
99
 
100
100
  function secretScope({ environment, tests }) {
101
101
  if (tests) return "tests";
102
- return environment ? `only ${environment}` : "every environment";
102
+ return environment ? `only the ${environment === "preview" ? "team's" : "customers'"} version, from before` : "everywhere";
103
103
  }
104
104
 
105
105
  function takeRepeated(args, flag) {
@@ -115,7 +115,7 @@ const KINDS = ["publishable", "secret"];
115
115
  // this list is only for the help text. `team` is never given by default.
116
116
  const SCOPES = ["messages", "instagram", "chats", "team"];
117
117
  const KEYS_USAGE =
118
- "Usage: vatio keys list [--json]|create publishable|secret [--env live|preview] [--label NAME] " +
118
+ "Usage: vatio keys list [--json]|create publishable|secret [--test] [--label NAME] " +
119
119
  "[--scope NAME]... [--code CODE | --recovery-code CODE] [--json]|revoke PREFIX";
120
120
 
121
121
  // A publishable key used to take a list of the sites it worked from. It works
@@ -132,7 +132,8 @@ const NO_ORIGINS = "A publishable key works from any site, so there are no origi
132
132
  // it. A secret key carries scopes; without --scope it gets every one but
133
133
  // `team`.
134
134
  export async function keys(config, args) {
135
- const environment = environmentOption(args, "live");
135
+ const test = takeFlag(args, "--test");
136
+ const environment = environmentOption(args, test ? "preview" : "live");
136
137
  const label = takeValue(args, "--label") ?? takeValue(args, "-l");
137
138
  if (takeRepeated(args, "--origin").length > 0) fail(`--origin was removed. ${NO_ORIGINS}`);
138
139
  const scopes = takeRepeated(args, "--scope");
@@ -152,13 +153,13 @@ export async function keys(config, args) {
152
153
  }
153
154
  if (list.length === 0) {
154
155
  console.log(`No API keys on workspace ${workspace}`);
155
- console.log(" Create one: vatio keys create publishable --env live --label website");
156
- console.log(" vatio keys create secret --env live --label backend");
156
+ console.log(" Create one: vatio keys create publishable --label website");
157
+ console.log(" vatio keys create secret --label backend (--test for one that reaches only your team)");
157
158
  return;
158
159
  }
159
160
  console.log(`API keys on workspace ${workspace} (${list.length}):`);
160
161
  for (const key of list) {
161
- const parts = [key.kind, key.prefix, key.environment];
162
+ const parts = [key.kind, key.prefix, key.environment === "preview" ? "test" : key.environment];
162
163
  if (key.label) parts.push(key.label);
163
164
  if (key.managed) parts.push(`managed${key.managed_kind ? ` (${key.managed_kind})` : ""}`);
164
165
  parts.push(key.last_used_at ? `last used ${key.last_used_at}` : "never used");
@@ -174,7 +175,7 @@ export async function keys(config, args) {
174
175
  if (sub === "create") {
175
176
  const kind = args.shift();
176
177
  if (!KINDS.includes(kind)) {
177
- fail("Say which kind: vatio keys create publishable|secret [--env NAME] [--label NAME] [--scope NAME]...");
178
+ fail("Say which kind: vatio keys create publishable|secret [--test] [--label NAME] [--scope NAME]...");
178
179
  }
179
180
  if (kind === "publishable" && scopes.length > 0) {
180
181
  fail(`--scope only applies to a secret key (${SCOPES.join(", ")}).`);
@@ -193,7 +194,7 @@ export async function keys(config, args) {
193
194
  console.log(JSON.stringify({ ...payload, workspace }, null, 2));
194
195
  return;
195
196
  }
196
- console.log(`Created a ${kind} key for ${environment} on workspace ${workspace}`);
197
+ console.log(`Created a ${environment === "preview" ? "test " : ""}${kind} key on workspace ${workspace}`);
197
198
  if (kind === "publishable") console.log(" works from any site");
198
199
  if (kind === "secret") console.log(` scopes: ${asArray(payload.api_key?.scopes).join(", ")}`);
199
200
  console.log("");
package/lib/help.mjs CHANGED
@@ -21,11 +21,11 @@ command says so when the two differ. init, push, pull, diff and auth work on
21
21
  the files, so they go by the directory alone: they refuse --workspace, and a
22
22
  VATIO_WORKSPACE that names another workspace.
23
23
 
24
- Until someone outside your team talks to your agent, \`push\` is the deploy:
25
- live follows every one of them. From their first conversation on, a push waits
26
- for \`publish\`, and that is what --env NAME is about: preview is the version
27
- you are working on, live is what visitors talk to. Every push says which of
28
- the two you are in. Commands default as listed.
24
+ A push reaches your team at once (\`vatio chat\` and Try the agent talk to
25
+ it) and everyone once the tests that pass today pass on it, a few minutes
26
+ later; with no tests, at once. A test it breaks holds it back from everyone:
27
+ \`vatio status\` says which, and another push that fixes it, or removing a test
28
+ it made obsolete, moves it on. \`vatio rollback\` undoes the last change.
29
29
 
30
30
  Getting started:
31
31
  init [SLUG] [--name NAME] Create vatio.yml here, and the remote to match
@@ -54,40 +54,28 @@ the two you are in. Commands default as listed.
54
54
  share-session --never Stop coding agents from offering
55
55
 
56
56
  Deploy:
57
- push [--force] Validate the workspace, then deploy it; runs no
58
- tests (the first push signs in like \`login\`).
59
- Reaches your agent directly while the workspace
60
- is a draft, and waits in preview once people
61
- talk to it. Refused over edits made outside your
62
- files (pull them first) and over an unpublished
63
- push from another git branch; --force replaces
64
- either
65
- pull [--env NAME] [--force]
66
- Write the deployed agent into vatio.yml's agent:
57
+ push [--force] Validate the workspace, then deploy it (the first
58
+ push signs in like \`login\`): your team has it
59
+ at once, everyone once its tests pass. Refused
60
+ over edits made outside your files (pull them
61
+ first); --force overwrites them
62
+ pull [--force] Write the deployed agent into vatio.yml's agent:
67
63
  block and tools/, edits from the Vatio MCP
68
- included (default: preview). Wants vatio.yml and
69
- tools/ committed to git; --force writes anyway
70
- publish [--force] Take preview live, with its knowledge changes.
71
- Once published, refused until \`vatio test\` has
72
- tested preview's version, and while it fails a
73
- report live passes; --force publishes anyway
74
- rollback Put live back to the previous snapshot: config and knowledge
75
- status Preview and live deployment state: which one
76
- preview holds (branch, commit, uncommitted
77
- changes, who pushed it and when, published or
78
- not), the replies Vatio wrote for the agent, and
79
- your WhatsApp number when Meta refuses its sends
80
- env [preview|live] An environment: token, widget snippet, link,
81
- knowledge changes and conflicts (default: preview)
82
- env list Both environments and what each runs
83
- diff [--env NAME] What this directory would change (default: preview)
84
- --env live answers "what would publishing change?"
64
+ included. Wants vatio.yml and tools/ committed
65
+ to git; --force writes anyway
66
+ rollback Put everyone, your team included, back on the
67
+ version before the last change: config and knowledge
68
+ status Where the newest change stands (everyone has it,
69
+ its tests are running, or a test held it and
70
+ which), the replies Vatio wrote for the agent,
71
+ and your WhatsApp number when Meta refuses its sends
72
+ diff What this directory would change
85
73
  diff --stat|--name-only|--format json|--full
86
74
 
87
75
  Talk to your agent (as yourself by default — the token is the identity):
88
- chat "message" [--file PATH]... [--env NAME] [--new] [--as-phone me|PHONE]
76
+ chat "message" [--file PATH]... [--new] [--as-phone me|PHONE]
89
77
  [--as-subject ID | --visitor-token JWT]
90
- preview by default; --env live is real; --new
78
+ The newest version, the one your team has; --new
91
79
  starts over as a visitor the agent never met,
92
80
  in a new chat whose id it prints.
93
81
  --file attaches an image, PDF, text or audio file
@@ -103,23 +91,25 @@ the two you are in. Commands default as listed.
103
91
  The chat you are in, or any chat in the workspace
104
92
  (web, WhatsApp, ...): messages, tool calls, channel,
105
93
  and what was read of each file (truncated, unreadable)
106
- chat export --from DATE [--to DATE] [--env NAME] [--channel NAME] [--out FILE]
94
+ chat export --from DATE [--to DATE] [--team] [--channel NAME] [--out FILE]
107
95
  What people said and were answered between two
108
96
  dates, redacted by Vatio, one conversation per
109
- line as JSON. Default: live. Any team member,
97
+ line as JSON: your customers', or your team's own
98
+ with --team. Any team member,
110
99
  viewers included; every call is in the activity
111
100
 
112
101
  Test and improve it: what it should do, what supervisors reported, and how
113
- its tools answered (test add, test list, fix, push, test, publish):
114
- tools [--env NAME] [--period 1h|1d|7d|30d] [--json]
102
+ its tools answered (test add, test list, fix, push, test):
103
+ tools [--period 1h|1d|7d|30d] [--json]
115
104
  Each tool's calls, error rate, timeouts and
116
105
  p50/p95, then the calls that failed with what
117
- your backend answered. Default: live, 7d
118
- test [--env NAME] [--agent SLUG] [--as-subject ID | --visitor-token JWT]
119
- Test every report and test against preview
120
- (default): starts the runs on Vatio's servers,
121
- prints their ids and returns.
122
- --env live also resolves the reports it passes.
106
+ your backend answered, in your customers'
107
+ conversations. Default: 7d
108
+ test [--agent SLUG] [--as-subject ID | --visitor-token JWT]
109
+ Test every report and test against your team's
110
+ version: starts the runs on Vatio's servers,
111
+ prints their ids and returns. A run that passes
112
+ also releases a change a test held back.
123
113
  --as-subject replays every case signed in as
124
114
  that visitor (see \`vatio chat\`)
125
115
  test --wait [--timeout N] Wait for the judge and print the report; exits 1
@@ -127,7 +117,7 @@ the two you are in. Commands default as listed.
127
117
  test --show RUN_ID One run's report so far, with the replay chat of
128
118
  each case that did not pass (vatio chat show ID)
129
119
  test add "QUESTION" "WHAT IT SHOULD DO" [--as-phone me|PHONE] [--as-subject ID]
130
- Ask it in a new chat (default: preview) and keep
120
+ Ask it in a new chat and keep
131
121
  the turn as a test, judged at once
132
122
  test add "WHAT IT SHOULD DO" [--chat ID|--message ID]
133
123
  The same on a reply you already have: the agent's
@@ -143,17 +133,15 @@ the two you are in. Commands default as listed.
143
133
  kb [list] Bases, and whether a deployed agent reads each
144
134
  kb show NAME One base and its entries
145
135
  kb create NAME | rm NAME
146
- kb write BASE ENTRY [FILE] Write an entry in this environment, from FILE or stdin
136
+ kb write BASE ENTRY [FILE] Write an entry, from FILE or stdin: your team has
137
+ it at once, everyone once the tests pass
147
138
  kb cat BASE ENTRY [--version N]
148
139
  Print an entry's markdown, or one old version
149
- kb rm-entry BASE ENTRY Delete one entry in this environment
150
- kb status BASE What this environment changed that live does not
151
- have, and what live changed underneath
152
- kb publish BASE Take this environment's changes live, alone
153
- kb history BASE What reached live, newest first
154
- (entry commands take --env; --env live writes live)
140
+ kb rm-entry BASE ENTRY Delete one entry
141
+ kb status BASE What your team has that everyone does not have yet
142
+ kb history BASE What reached everyone, newest first
155
143
 
156
- Business (one value for every environment, live on save; also in the inbox,
144
+ Business (one value, everyone has it on save; also in the inbox,
157
145
  on the Web chat page):
158
146
  business [show] Name and brand, and the old business description
159
147
  if there is one
@@ -161,8 +149,8 @@ the two you are in. Commands default as listed.
161
149
  [--logo FILE | --remove-logo] [--clear-description]
162
150
  What the business does goes in agent.instructions
163
151
 
164
- Quiet hours (when the agent does not answer; one schedule for every environment,
165
- live on save; also in the inbox, under Channels):
152
+ Quiet hours (when the agent does not answer; one schedule, everyone has it on
153
+ save; also in the inbox, under Channels):
166
154
  quiet-hours [show] The weekly schedule, and whether it is silent now
167
155
  quiet-hours set --timezone ZONE --range "DAYS HH:MM-HH:MM" [--range ...]
168
156
  Replace the schedule. DAYS: mon, mon-fri, sat,sun, all
@@ -177,19 +165,22 @@ the two you are in. Commands default as listed.
177
165
  someone or changing a role stays in the inbox
178
166
 
179
167
  Credentials:
180
- secrets list|set KEY [VALUE] [--from-env [NAME]]|rm KEY [--env NAME | --tests]
168
+ secrets list|set KEY [VALUE] [--from-env [NAME]]|rm KEY [--tests]
181
169
  Without VALUE, set asks for it with the input hidden.
182
170
  --from-env takes the value from your shell or the
183
171
  .env beside the workspace, so a coding agent can set
184
172
  a secret without being shown it (NAME defaults to KEY).
185
- With --env, the value only that environment uses;
186
- otherwise the value everywhere. With --tests, the
187
- value preview and every test run use, like a staging URL
173
+ With --tests, the value your team's conversations
174
+ with the agent and every test run use, like a
175
+ staging URL; otherwise the value everywhere
188
176
  keys list [--json] API keys of both kinds: publishable (for a page or
189
177
  app, with where it was used) and secret (for your
190
178
  backend, with its scopes)
191
- keys create publishable|secret [--env NAME] [--label NAME] [--json]
179
+ keys create publishable|secret [--label NAME] [--json]
192
180
  A publishable key works from any site
181
+ keys create secret --test A secret key that reaches only your team and the
182
+ customer phones you added, through Vatio's test
183
+ number: for your backend's development and staging
193
184
  keys create secret --scope NAME... [--code CODE | --recovery-code CODE]
194
185
  What the secret key may call: messages, instagram,
195
186
  chats, team (repeatable). Without --scope, all but
@@ -199,7 +190,7 @@ the two you are in. Commands default as listed.
199
190
  auth --new-key Keypair that signs the JWT saying who a visitor is
200
191
 
201
192
  Sending from your backend (with a server key):
202
- webhooks list|create URL [--event NAME]...|test ID|deliveries ID|enable ID|rm ID
193
+ webhooks list|create URL [--event NAME]... [--test]|test ID|deliveries ID|enable ID|rm ID
203
194
  Where Vatio tells your backend what happened
204
195
 
205
196
  Contacts (privacy requests on one person; the ID is the contact's number in the inbox):
@@ -227,8 +218,9 @@ the two you are in. Commands default as listed.
227
218
  whatsapp team The team and each person's own WhatsApp: the
228
219
  phone the agent knows them by, and that reaches
229
220
  it on Vatio's number
230
- whatsapp templates [list] [--env live]
231
- The number's templates and the "template" to send
221
+ whatsapp templates [list] [--test-number]
222
+ The number's templates and the "template" to send;
223
+ --test-number lists those on Vatio's test number
232
224
  whatsapp templates create NAME --language CODE --body TEXT [--example VALUE]...
233
225
  [--category utility|marketing] [--footer TEXT]
234
226
  [--button-url 'TEXT|URL']... [--button-example VALUE]...
@@ -240,10 +232,11 @@ the two you are in. Commands default as listed.
240
232
  on Vatio's test number until you connect one
241
233
  whatsapp templates rm NAME [--language CODE] | sync
242
234
  Delete one at Meta; pull back ones made elsewhere
243
- whatsapp failed [--since DATE] [--until DATE] [--error-code CODE]
235
+ whatsapp failed [--test] [--since DATE] [--until DATE] [--error-code CODE]
244
236
  [--error-contains TEXT] [--before ID]
245
237
  Messages Vatio gave up retrying, with your
246
- external_ref (default: live)
238
+ external_ref; --test for what your test secret
239
+ key sent
247
240
 
248
241
  Channels:
249
242
  instagram The same, for Instagram
@@ -251,6 +244,10 @@ the two you are in. Commands default as listed.
251
244
  Everything else:
252
245
  config show|get KEY|set KEY VALUE|unset KEY
253
246
  Keys: base_url, token
247
+ env [list] The version your team has and the one everyone
248
+ has, with the deployment each runs
249
+ publish Nothing to do: a push reaches everyone once its
250
+ tests pass. Prints that and exits 0, for scripts
254
251
 
255
252
  Global flag: --workspace SLUG names the workspace (not for init, push, pull,
256
253
  diff, auth)
package/lib/support.mjs CHANGED
@@ -47,6 +47,15 @@ export function takeEnv(args, { fallback = null } = {}) {
47
47
  return environment !== undefined ? environment : fallback;
48
48
  }
49
49
 
50
+ // The side a command reads or acts on, said plainly: `flag` (--team, --test,
51
+ // --test-number) names the team's or the test side, which the platform still
52
+ // calls preview. `--env NAME` from before still works.
53
+ export function takeSide(args, flag, { fallback = "live" } = {}) {
54
+ const environment = takeEnv(args, { fallback: null });
55
+ const flagged = takeFlag(args, flag);
56
+ return environment ?? (flagged ? "preview" : fallback);
57
+ }
58
+
50
59
  export function takeFlag(args, name) {
51
60
  const index = args.indexOf(name);
52
61
  if (index === -1) return false;
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@vatio-ai/cli",
3
- "version": "0.131.0",
3
+ "version": "0.133.0",
4
4
  "description": "Vatio CLI — deploy and manage Vatio agent workspaces",
5
5
  "keywords": [
6
6
  "vatio",