@vatio-ai/cli 0.129.0 → 0.131.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
@@ -2,25 +2,31 @@
2
2
 
3
3
  The CLI for [Vatio](https://vatio.ai), which gives the app you're building with
4
4
  a coding agent — Claude Code, Cursor or Codex — an AI agent that knows the app
5
- and its users. Your coding agent writes the agent into your project and drives
6
- this CLI; Vatio runs the conversations, with your users signed in, an inbox for
7
- your team, handoff to a person, and the replies your team reports turned into
8
- tests.
5
+ and its users. Vatio runs the conversations, with your users signed in, an
6
+ inbox for your team, handoff to a person, and the replies your team reports
7
+ turned into tests.
9
8
 
10
9
  ## Start here
11
10
 
12
- In your app's project:
11
+ Your coding agent builds and tests the agent through the
12
+ [Vatio MCP](https://vatio.ai/docs/mcp), with nothing in your repository. In
13
+ your app's project:
13
14
 
14
15
  ```bash
15
16
  npx @vatio-ai/skills
16
17
  ```
17
18
 
18
- Then, in Claude Code, run `/vatio-init` (in Cursor or Codex, ask it to use
19
- vatio-init). It reads your app, asks only what the code can't answer, and
20
- pushes a preview for you to try. Then ask your coding agent to put the agent
21
- in your web, iOS, Android or Flutter app. See the [docs](https://vatio.ai/docs/).
19
+ It adds the skills and the MCP to the project. Then, in Claude Code, run
20
+ `/vatio-init` (in Cursor or Codex, ask it to use vatio-init). It reads your
21
+ app, asks only what the code can't answer, builds the agent, writes its tests
22
+ and puts it in your web, iOS, Android or Flutter app. See the
23
+ [docs](https://vatio.ai/docs/).
22
24
 
23
- ## By hand
25
+ This CLI is for a team that keeps the agent as files (`vatio.yml`), and for
26
+ what the MCP leaves to a terminal: `vatio feedback`, `vatio share-session`
27
+ and `vatio docs`.
28
+
29
+ ## As files
24
30
 
25
31
  ```bash
26
32
  npx @vatio-ai/cli init my-agent
@@ -63,8 +69,13 @@ support-agent/
63
69
 
64
70
  Only create the files you need. Nothing constrains where that directory lives —
65
71
  an agent can sit inside the repository of the backend it calls, and every
66
- command except `init` finds it by walking up from the current directory. There
67
- is no `--workspace` flag.
72
+ command except `init` finds it by walking up from the current directory.
73
+
74
+ A workspace with no `vatio.yml`, built through the Vatio MCP, is named with
75
+ `--workspace SLUG` or `VATIO_WORKSPACE` instead, and either wins over a
76
+ `vatio.yml`. `init`, `push`, `pull`, `diff` and `auth` work on the files, so
77
+ they go by the directory alone and refuse `--workspace`. See
78
+ [Choosing the workspace](https://vatio.ai/docs/cli/#choosing-the-workspace).
68
79
 
69
80
  ## Commands
70
81
 
package/bin/vatio.mjs CHANGED
@@ -4,7 +4,7 @@
4
4
  // The workspace is parsed by the platform, so a client is HTTP and a
5
5
  // terminal; the credential lives in ~/.vatio/config.json.
6
6
 
7
- import { Config, ConfigError } from "../lib/config.mjs";
7
+ import { Config, ConfigError, WORKSPACE_ENV, takeWorkspaceFlag } from "../lib/config.mjs";
8
8
  import { CliOutdatedError, HttpError, UnauthorizedError, ForbiddenError, NotFoundError } from "../lib/http.mjs";
9
9
  import { UserError, fail } from "../lib/support.mjs";
10
10
  import { helpText } from "../lib/help.mjs";
@@ -37,18 +37,27 @@ const RETIRED = {
37
37
  "https://github.com/vatio-ai/cli/issues (or sdk, ios, ruby under github.com/vatio-ai).",
38
38
  widget: "was removed: `vatio env` prints the snippet and its token, and the look is edited in\n" +
39
39
  "the inbox, under Channels → Widget.",
40
- mcp: "was removed. Point your coding agent at `vatio docs --save` and let it run the CLI.",
40
+ mcp: "was removed: the Vatio MCP is https://vatio.ai/mcp, and `npx @vatio-ai/skills` adds it to a project.",
41
41
  update: "is npm's job: `npx @vatio-ai/cli@latest` always runs the current release, and\n" +
42
42
  "`npm install -g @vatio-ai/cli@latest` updates a global install.\n" +
43
43
  "`vatio changelog` says which release is current and what it changed.",
44
44
  propose: "was removed in 0.71.0. Test with `vatio test` and publish with `vatio publish`."
45
45
  };
46
46
 
47
+ // The commands that read or write the workspace's files. They take the
48
+ // workspace from the directory's vatio.yml and nothing else (lib/config.mjs
49
+ // says why), so --workspace, or a VATIO_WORKSPACE naming another workspace,
50
+ // is refused before they start.
51
+ const DIRECTORY_COMMANDS = new Set(["init", "push", "pull", "diff", "auth"]);
52
+
47
53
  const config = new Config({ startDir: process.cwd() });
54
+ let invoked;
48
55
 
49
56
  async function main(argv) {
50
57
  const args = argv.slice(2);
58
+ config.workspaceFlag = takeWorkspaceFlag(args);
51
59
  const command = args.shift();
60
+ invoked = command;
52
61
  beginRun(command, args);
53
62
  const updateCheck = startUpdateCheck(command);
54
63
  await run(command, args);
@@ -63,6 +72,7 @@ async function run(command, args) {
63
72
  if (command !== undefined && (args.includes("--help") || args.includes("-h"))) {
64
73
  return console.log(command === "chat" ? chatHelp() : helpText());
65
74
  }
75
+ if (DIRECTORY_COMMANDS.has(command)) config.bindToDirectory(command);
66
76
 
67
77
  switch (command) {
68
78
  case "version":
@@ -138,7 +148,8 @@ async function run(command, args) {
138
148
  return console.log(helpText());
139
149
  default:
140
150
  if (RETIRED[command]) fail(`\`vatio ${command}\` ${RETIRED[command]}`);
141
- fail(unknownCommandMessage(command, args));
151
+ // The flag rides along into the command it suggests.
152
+ fail(unknownCommandMessage(command, config.workspaceFlag === null ? args : [...args, "--workspace", config.workspaceFlag]));
142
153
  }
143
154
  }
144
155
 
@@ -168,8 +179,11 @@ function printError(error) {
168
179
  return printTrailer(error);
169
180
  }
170
181
  if (error instanceof NotFoundError) {
182
+ const named = { "--workspace": "passed to --workspace", [WORKSPACE_ENV]: `in ${WORKSPACE_ENV}` }[config.workspaceSource()];
171
183
  console.error(
172
- "Remote resource not found (404). Check the workspace slug; `vatio push` creates a missing remote automatically."
184
+ named
185
+ ? `Remote resource not found (404). Check the workspace slug ${named}; \`vatio whoami\` lists the workspaces this machine reaches.`
186
+ : "Remote resource not found (404). Check the workspace slug; `vatio push` creates a missing remote automatically."
173
187
  );
174
188
  return printTrailer(error);
175
189
  }
@@ -198,7 +212,7 @@ function printTrailer(error) {
198
212
  // Said to coding agents only: a person at a terminal has better ways to
199
213
  // complain, and does not need the line on every typo.
200
214
  function suggestFeedback() {
201
- if (!telemetryEnabled() || !isCodingAgent() || ["feedback", "share-session"].includes(process.argv[2])) return;
215
+ if (!telemetryEnabled() || !isCodingAgent() || ["feedback", "share-session"].includes(invoked)) return;
202
216
  console.error(
203
217
  '\nIf this has you stuck, tell the Vatio team: vatio feedback "what you were trying to do and what got in the way"'
204
218
  );
@@ -208,17 +208,13 @@ export class ApiClient extends HttpClient {
208
208
  // `scopes` (a secret key's) left null takes the platform's default: every
209
209
  // scope but `team`. `confirmation` is { code } or { recovery_code }, which a
210
210
  // `team` key needs.
211
- createApiKey({ kind, environment, label = null, allowedOrigins = [], scopes = null, confirmation = {} }) {
211
+ createApiKey({ kind, environment, label = null, scopes = null, confirmation = {} }) {
212
212
  const body = { kind, environment, ...confirmation };
213
213
  if (String(label ?? "").trim() !== "") body.label = String(label).trim();
214
- if (allowedOrigins.length > 0) body.allowed_origins = allowedOrigins;
215
214
  if (Array.isArray(scopes) && scopes.length > 0) body.scopes = scopes;
216
215
  return this.post("/api_keys", body);
217
216
  }
218
217
 
219
- setApiKeyOrigins({ prefix, allowedOrigins }) {
220
- return this.patch(`/api_keys/${encode(prefix)}`, { allowed_origins: allowedOrigins });
221
- }
222
218
 
223
219
  revokeApiKey({ prefix }) {
224
220
  return this.delete(`/api_keys/${encode(prefix)}`);
@@ -5,7 +5,7 @@
5
5
  // vatio.ai/workspaces is only for a server too old to send the link, and
6
6
  // redirects to the inbox.
7
7
 
8
- import { deployClient } from "./deploy.mjs";
8
+ import { deployClient, whatsappIssueLines } from "./deploy.mjs";
9
9
  import { messages } from "./messages.mjs";
10
10
  import { withSecondFactor } from "./team.mjs";
11
11
  import { templates } from "./webhooks.mjs";
@@ -55,10 +55,10 @@ export async function whatsapp(config, args = []) {
55
55
  }
56
56
  case "check": {
57
57
  // The number's two-step verification PIN registers it on the Cloud API
58
- // again first: the fix for 133010, not registered.
58
+ // first: the fix for an issue of kind not_registered.
59
59
  const pin = takeValue(args, "--pin");
60
60
  if (args.length) fail(WHATSAPP_USAGE);
61
- if (pin !== null && !/^\d{6}$/.test(pin)) fail("--pin is the number's two-step verification PIN: 6 digits.");
61
+ if (pin !== null && !/^\d{6}$/.test(pin)) fail("--pin is the number's two-step verification PIN: 6 digits. A number with none takes them as its PIN.");
62
62
  const number = await client().checkWhatsapp(pin);
63
63
  printNumber(number, { json, checked: true });
64
64
  // A check that leaves Meta refusing every send did not pass.
@@ -172,7 +172,8 @@ function printNumber(number, { json = false, checked = false } = {}) {
172
172
  if (json) return console.log(JSON.stringify(number, null, 2));
173
173
  const name = number.number ?? "Your number";
174
174
  if (number.issue) {
175
- printIssue(name, number.issue);
175
+ console.log("");
176
+ for (const line of whatsappIssueLines(name, number.issue)) console.log(line);
176
177
  } else {
177
178
  const live = number.live
178
179
  ? paint("green", "live: the agent answers everyone who writes")
@@ -186,12 +187,3 @@ function printNumber(number, { json = false, checked = false } = {}) {
186
187
  if (number.failed_deliveries) console.log(` ${number.failed_deliveries} failed deliveries: vatio whatsapp failed`);
187
188
  }
188
189
 
189
- // Meta refuses every send from the number, and the server API refuses your
190
- // backend's messages with 409 whatsapp_number_unhealthy until a check passes.
191
- function printIssue(name, issue) {
192
- const code = issue.code ? ` (Meta ${issue.code})` : "";
193
- console.log(`\n${name}: ${paint("red", `NOT SENDING since ${issue.since}${code}`)}`);
194
- if (issue.message) console.log(` Meta: ${issue.message}`);
195
- console.log(` Fix: ${issue.fix}`);
196
- console.log(" Until a check passes, POST /messages answers 409 whatsapp_number_unhealthy and the agent's replies do not go out.");
197
- }
@@ -14,10 +14,11 @@
14
14
  // already hold (lib/visitor-identity.mjs, Vatio::Preview::Tester).
15
15
 
16
16
  import { randomBytes } from "node:crypto";
17
- import { appendFileSync, existsSync, readFileSync, renameSync, rmSync, statSync, writeFileSync } from "node:fs";
17
+ import { appendFileSync, existsSync, mkdirSync, readFileSync, renameSync, rmSync, statSync, writeFileSync } from "node:fs";
18
18
  import { basename, dirname, join } from "node:path";
19
19
 
20
20
  import { ApiClient } from "../api-client.mjs";
21
+ import { configHome } from "../config.mjs";
21
22
  import { fail, sleep, takeAll, takeEnv, takeFlag, takeValue } from "../support.mjs";
22
23
  import { IDENTITY_FLAGS_USAGE, takeIdentity, tokenFor } from "../visitor-identity.mjs";
23
24
 
@@ -145,9 +146,11 @@ way it does the widget's. --visitor-token JWT (or VATIO_VISITOR_TOKEN) brings a
145
146
  token you signed elsewhere.
146
147
  A chat as someone else starts over; the same person continues it.
147
148
 
148
- The open chat per deployment is remembered in ${STATE_FILE}, so a second
149
- \`vatio chat\` continues the first. \`--new\` starts over as a visitor the
150
- workspace has never met, sends the message to that new chat and prints its id.
149
+ The open chat per deployment is remembered in ${STATE_FILE} beside vatio.yml
150
+ (in ~/.vatio/chats/SLUG.json for a workspace named with --workspace or
151
+ VATIO_WORKSPACE), so a second \`vatio chat\` continues the first. \`--new\`
152
+ starts over as a visitor the workspace has never met, sends the message to
153
+ that new chat and prints its id.
151
154
  \`--chat CHAT_ID\` continues that chat, whatever ${STATE_FILE} says: for
152
155
  conversations running side by side, each command names its own.
153
156
 
@@ -222,8 +225,14 @@ function client(config, options) {
222
225
  return new ApiClient({ baseUrl: apiUrl, token });
223
226
  }
224
227
 
228
+ // The chats are remembered beside vatio.yml. A workspace named by --workspace
229
+ // or VATIO_WORKSPACE has no directory here to keep them in, so its are in the
230
+ // CLI's home, one file per workspace, rather than in whatever directory the
231
+ // command ran in.
225
232
  function statePath(config) {
226
- return join(config.workspaceRootRequired(), STATE_FILE);
233
+ const root = config.workspaceDirectory();
234
+ if (root) return join(root, STATE_FILE);
235
+ return join(configHome(), "chats", `${config.resolveWorkspaceRequired()}.json`);
227
236
  }
228
237
 
229
238
  function loadState(config) {
@@ -270,6 +279,7 @@ function rememberChat(config, { apiUrl, environment, chatId, subject = null }) {
270
279
  // never gets half a file. The temporary name starts with a dot, which keeps
271
280
  // it out of a push.
272
281
  function writeAtomically(path, content) {
282
+ mkdirSync(dirname(path), { recursive: true });
273
283
  const temporary = join(dirname(path), `.${basename(path)}.${process.pid}.${randomBytes(4).toString("hex")}.tmp`);
274
284
  writeFileSync(temporary, content);
275
285
  try {
@@ -522,10 +522,30 @@ function printPreviewHolds(payload) {
522
522
  function printWhatsappIssue(whatsapp) {
523
523
  const issue = whatsapp?.issue;
524
524
  if (!issue) return;
525
+ for (const line of whatsappIssueLines(`WhatsApp ${whatsapp.number ?? "number"}`, issue)) console.error(line);
526
+ }
527
+
528
+ // The number's issue as `vatio whatsapp` and `vatio status` say it, and as the
529
+ // inbox's WhatsApp page and the MCP's get_whatsapp do. Not registered is also
530
+ // where a number lands the moment it is first connected, so it reads as that
531
+ // step, and its fix already says what Meta said.
532
+ export function whatsappIssueLines(name, issue) {
533
+ const until = "POST /messages answers 409 whatsapp_number_unhealthy and the agent's replies do not go out.";
534
+ if (issue.kind === "not_registered") {
535
+ return [
536
+ `${name}: ${paint("red", "NOT REGISTERED on the WhatsApp Cloud API: register it so it can send")}`,
537
+ ` Fix: ${issue.fix}`,
538
+ " Register it: vatio whatsapp check --pin PIN",
539
+ ` Until then, ${until}`,
540
+ ];
541
+ }
525
542
  const code = issue.code ? ` (Meta ${issue.code})` : "";
526
- console.error(`WhatsApp ${whatsapp.number ?? "number"} is NOT SENDING since ${issue.since}${code}: ${issue.message ?? ""}`);
527
- console.error(` Fix: ${issue.fix}`);
528
- console.error(" Until a check passes (vatio whatsapp check), POST /messages answers 409 whatsapp_number_unhealthy.");
543
+ return [
544
+ `${name}: ${paint("red", `NOT SENDING since ${issue.since}${code}`)}`,
545
+ ...(issue.message ? [` Meta: ${issue.message}`] : []),
546
+ ` Fix: ${issue.fix}`,
547
+ ` Until a check passes (vatio whatsapp check), ${until}`,
548
+ ];
529
549
  }
530
550
 
531
551
  // What Vatio did for this workspace in the last 30 days, in one line a
@@ -35,7 +35,8 @@ export async function doctor(config) {
35
35
  } catch (error) {
36
36
  console.log(`Workspace: unreadable — ${error.message}`);
37
37
  }
38
- if (slug) console.log(`Workspace: ${slug}`);
38
+ const source = config.workspaceSource();
39
+ if (slug) console.log(`Workspace: ${slug}${source === MANIFEST_FILE ? "" : ` (from ${source})`}`);
39
40
  const token = config.resolveToken();
40
41
  console.log(`Token: ${token ? "configured" : "missing — run `vatio login`"}`);
41
42
  if (token) console.log(`Account: ${await accountLine(config)}`);
@@ -60,9 +61,15 @@ export async function whoami(config) {
60
61
  slug = null;
61
62
  }
62
63
  if (slug && !slugs.includes(slug)) {
64
+ const source = config.workspaceSource();
63
65
  console.log("");
64
- console.log(`This directory's workspace, ${slug}, is not one of them: it does not exist yet (\`vatio push\` ` +
65
- "creates it) or belongs to another account (`vatio login` with that account's email or sign-in).");
66
+ if (source === MANIFEST_FILE) {
67
+ console.log(`This directory's workspace, ${slug}, is not one of them: it does not exist yet (\`vatio push\` ` +
68
+ "creates it) or belongs to another account (`vatio login` with that account's email or sign-in).");
69
+ } else {
70
+ console.log(`The workspace ${source} names, ${slug}, is not one of them: check the slug, or it belongs to ` +
71
+ "another account (`vatio login` with that account's email or sign-in).");
72
+ }
66
73
  }
67
74
  }
68
75
 
@@ -299,7 +299,12 @@ export async function shareSession(config, args) {
299
299
  if (transcript.startedAt) form.set("started_at", transcript.startedAt);
300
300
  if (transcript.endedAt) form.set("ended_at", transcript.endedAt);
301
301
  if (feedback) form.set("feedback", feedback);
302
- const workspace = config.resolveWorkspace();
302
+ let workspace = null;
303
+ try {
304
+ workspace = config.resolveWorkspace();
305
+ } catch {
306
+ // A VATIO_WORKSPACE or vatio.yml that names no workspace is no reason to send nothing.
307
+ }
303
308
  if (workspace) form.set("workspace", workspace);
304
309
 
305
310
  let response;
@@ -1,6 +1,6 @@
1
1
  // secrets / keys — the things a workspace has that its manifest deliberately
2
- // does not carry. A secret is a credential, and so are the API keys (publishable,
3
- // with the origins it accepts, and secret); none of them is in vatio.yml.
2
+ // does not carry. A secret is a credential, and so are the API keys (publishable
3
+ // and secret); none of them is in vatio.yml.
4
4
 
5
5
  import { existsSync, readFileSync, realpathSync } from "node:fs";
6
6
  import { join } from "node:path";
@@ -102,11 +102,6 @@ function secretScope({ environment, tests }) {
102
102
  return environment ? `only ${environment}` : "every environment";
103
103
  }
104
104
 
105
- // Repeatable: `--origin https://a.com --origin https://b.com`.
106
- function takeOrigins(args) {
107
- return takeRepeated(args, "--origin");
108
- }
109
-
110
105
  function takeRepeated(args, flag) {
111
106
  const values = [];
112
107
  for (let value = takeValue(args, flag); value !== null; value = takeValue(args, flag)) {
@@ -120,11 +115,17 @@ const KINDS = ["publishable", "secret"];
120
115
  // this list is only for the help text. `team` is never given by default.
121
116
  const SCOPES = ["messages", "instagram", "chats", "team"];
122
117
  const KEYS_USAGE =
123
- "Usage: vatio keys list [--json]|create publishable|secret [--env live|preview] [--label NAME] [--origin URL]... " +
124
- "[--scope NAME]... [--code CODE | --recovery-code CODE] [--json]|origins PREFIX URL...|revoke PREFIX";
118
+ "Usage: vatio keys list [--json]|create publishable|secret [--env live|preview] [--label NAME] " +
119
+ "[--scope NAME]... [--code CODE | --recovery-code CODE] [--json]|revoke PREFIX";
120
+
121
+ // A publishable key used to take a list of the sites it worked from. It works
122
+ // from any site now, so there is nothing to set, and saying so beats an
123
+ // unknown flag.
124
+ const NO_ORIGINS = "A publishable key works from any site, so there are no origins to set. " +
125
+ "`vatio keys list` shows where each key has been used.";
125
126
 
126
127
  // API keys, of two kinds. A publishable key is for a page or an app: public by
127
- // design, accepted only from the origins it lists. A secret key is for the
128
+ // design, working from any site. A secret key is for the
128
129
  // developer's own backend (to have the agent write to a contact first, read a
129
130
  // chat, keep the team): it never goes in a page or an app, and unlike the
130
131
  // CLI's own token it belongs to the workspace, so it outlives whoever created
@@ -133,7 +134,7 @@ const KEYS_USAGE =
133
134
  export async function keys(config, args) {
134
135
  const environment = environmentOption(args, "live");
135
136
  const label = takeValue(args, "--label") ?? takeValue(args, "-l");
136
- const origins = takeOrigins(args);
137
+ if (takeRepeated(args, "--origin").length > 0) fail(`--origin was removed. ${NO_ORIGINS}`);
137
138
  const scopes = takeRepeated(args, "--scope");
138
139
  const code = takeValue(args, "--code");
139
140
  const recoveryCode = takeValue(args, "--recovery-code");
@@ -151,7 +152,7 @@ export async function keys(config, args) {
151
152
  }
152
153
  if (list.length === 0) {
153
154
  console.log(`No API keys on workspace ${workspace}`);
154
- console.log(" Create one: vatio keys create publishable --env live --origin https://your-site.com");
155
+ console.log(" Create one: vatio keys create publishable --env live --label website");
155
156
  console.log(" vatio keys create secret --env live --label backend");
156
157
  return;
157
158
  }
@@ -162,7 +163,10 @@ export async function keys(config, args) {
162
163
  if (key.managed) parts.push(`managed${key.managed_kind ? ` (${key.managed_kind})` : ""}`);
163
164
  parts.push(key.last_used_at ? `last used ${key.last_used_at}` : "never used");
164
165
  console.log(` ${parts.filter(Boolean).join(" ")}`);
165
- if (key.kind === "publishable") console.log(` origins: ${originsLine(key.allowed_origins)}`);
166
+ if (key.kind === "publishable") {
167
+ const seen = asArray(key.seen_origins).map((row) => row.origin);
168
+ console.log(` used from: ${seen.length > 0 ? seen.join(", ") : "nowhere yet"}`);
169
+ }
166
170
  if (key.kind === "secret") console.log(` scopes: ${asArray(key.scopes).join(", ") || "none"}`);
167
171
  }
168
172
  return;
@@ -170,10 +174,7 @@ export async function keys(config, args) {
170
174
  if (sub === "create") {
171
175
  const kind = args.shift();
172
176
  if (!KINDS.includes(kind)) {
173
- fail("Say which kind: vatio keys create publishable|secret [--env NAME] [--label NAME] [--origin URL]... [--scope NAME]...");
174
- }
175
- if (kind === "secret" && origins.length > 0) {
176
- fail("--origin only applies to a publishable key. A secret key is for your backend and has no origins.");
177
+ fail("Say which kind: vatio keys create publishable|secret [--env NAME] [--label NAME] [--scope NAME]...");
177
178
  }
178
179
  if (kind === "publishable" && scopes.length > 0) {
179
180
  fail(`--scope only applies to a secret key (${SCOPES.join(", ")}).`);
@@ -182,7 +183,6 @@ export async function keys(config, args) {
182
183
  kind,
183
184
  environment,
184
185
  label,
185
- allowedOrigins: kind === "publishable" ? origins : [],
186
186
  scopes: kind === "secret" && scopes.length > 0 ? scopes : null,
187
187
  code,
188
188
  recoveryCode
@@ -194,7 +194,7 @@ export async function keys(config, args) {
194
194
  return;
195
195
  }
196
196
  console.log(`Created a ${kind} key for ${environment} on workspace ${workspace}`);
197
- if (kind === "publishable") console.log(` origins: ${originsLine(payload.api_key?.allowed_origins)}`);
197
+ if (kind === "publishable") console.log(" works from any site");
198
198
  if (kind === "secret") console.log(` scopes: ${asArray(payload.api_key?.scopes).join(", ")}`);
199
199
  console.log("");
200
200
  // Shown in full exactly once: the platform stores a digest, so this is the
@@ -221,13 +221,7 @@ export async function keys(config, args) {
221
221
  }
222
222
  return;
223
223
  }
224
- if (sub === "origins") {
225
- const prefix = args.shift();
226
- if (!prefix) fail("Usage: vatio keys origins PREFIX [URL...] (no URL clears the list)");
227
- const payload = await client.setApiKeyOrigins({ prefix, allowedOrigins: args.splice(0) });
228
- console.log(`Origins for ${prefix}: ${originsLine(payload.api_key?.allowed_origins)}`);
229
- return;
230
- }
224
+ if (sub === "origins") fail(`\`vatio keys origins\` was removed. ${NO_ORIGINS}`);
231
225
  if (sub === "revoke") {
232
226
  const prefix = args.shift();
233
227
  if (!prefix) fail("Usage: vatio keys revoke PREFIX");
@@ -317,13 +311,9 @@ function readLocalEnv(config, name) {
317
311
  const exported = process.env[name];
318
312
  if (exported !== undefined && exported !== "") return exported;
319
313
 
320
- const roots = [];
321
- try {
322
- roots.push(config.workspaceRootRequired());
323
- } catch {
324
- // No workspace yet: the cwd is still worth reading.
325
- }
326
- roots.push(process.cwd());
314
+ // With no workspace directory -- none yet, or a workspace named by
315
+ // --workspace that has none here -- the cwd is still worth reading.
316
+ const roots = [config.workspaceDirectory(), process.cwd()].filter(Boolean);
327
317
 
328
318
  const seen = [];
329
319
  for (const root of roots) {
@@ -394,10 +384,6 @@ function valueIn(text, name) {
394
384
  const UNTERMINATED = Symbol("unterminated");
395
385
 
396
386
  // An empty list is not "anywhere": only Vatio's own pages can use the key.
397
- function originsLine(origins) {
398
- const list = asArray(origins);
399
- return list.length > 0 ? list.join(", ") : "none (add one with `vatio keys origins PREFIX URL`)";
400
- }
401
387
 
402
388
  function asArray(value) {
403
389
  return Array.isArray(value) ? value : [];
package/lib/config.mjs CHANGED
@@ -7,9 +7,16 @@
7
7
  // credential -- the developer's home does.
8
8
  //
9
9
  // Two scopes, as before: credentials are per developer and live here; workspace
10
- // identity is per directory and lives in that workspace's own vatio.yml. There
11
- // is no --workspace flag, because the slug is a property of the directory, and
12
- // reading it anywhere else is how a push lands in the wrong workspace.
10
+ // identity is per directory and lives in that workspace's own vatio.yml.
11
+ //
12
+ // A workspace built through the Vatio MCP has no vatio.yml, and the commands
13
+ // that only talk to the platform (`vatio status`, `vatio business`, `vatio
14
+ // keys`...) are as useful to it as to one kept as files. So `--workspace SLUG`
15
+ // and VATIO_WORKSPACE name a workspace too, ahead of the vatio.yml. The
16
+ // commands that read or write the workspace's files (init, push, pull, diff,
17
+ // auth --new-key) still go by the directory alone and refuse both: for them
18
+ // the slug is a property of the files, and reading it anywhere else is how a
19
+ // push lands in the wrong workspace.
13
20
 
14
21
  import { chmodSync, existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
15
22
  import { homedir } from "node:os";
@@ -18,6 +25,7 @@ import { dirname, join, resolve } from "node:path";
18
25
  import { MANIFEST_FILE, SLUG_FORMAT, findWorkspaceRoot, manifestPath, workspaceSlug, workspacesBelow } from "./workspace.mjs";
19
26
 
20
27
  export const KEYS = ["base_url", "token"];
28
+ export const WORKSPACE_ENV = "VATIO_WORKSPACE";
21
29
  export const DEFAULT_BASE_URL = "https://vatio.ai";
22
30
  // `as`, `channel` and `from` configured a simulated visitor for `vatio chat`.
23
31
  // That simulation is gone from the platform, so they are refused as keys and
@@ -36,12 +44,43 @@ export function configHome() {
36
44
  return override === "" ? join(homedir(), ".vatio") : resolve(override);
37
45
  }
38
46
 
47
+ // `--workspace SLUG` or `--workspace=SLUG`, wherever it is on the command line,
48
+ // taken out of `args` before anything reads the command: it means the same for
49
+ // every command, and none of them should take it for a message or a value.
50
+ export function takeWorkspaceFlag(args) {
51
+ let found = null;
52
+ for (let i = 0; i < args.length; ) {
53
+ let value;
54
+ if (args[i] === "--workspace") {
55
+ value = args[i + 1];
56
+ if (value === undefined || value.startsWith("-")) value = "";
57
+ args.splice(i, value === "" ? 1 : 2);
58
+ } else if (args[i].startsWith("--workspace=")) {
59
+ value = args[i].slice("--workspace=".length);
60
+ args.splice(i, 1);
61
+ } else {
62
+ i += 1;
63
+ continue;
64
+ }
65
+ if (value.trim() === "") throw new ConfigError("--workspace needs the workspace's slug: --workspace SLUG");
66
+ if (found !== null && found !== value) throw new ConfigError(`--workspace is given twice (${found}, ${value}): name one workspace.`);
67
+ found = value;
68
+ }
69
+ return found;
70
+ }
71
+
39
72
  export class Config {
73
+ #differenceSaid = false;
74
+
40
75
  constructor({ startDir = process.cwd() } = {}) {
41
76
  this.startDir = resolve(startDir);
42
77
  this.configPath = join(configHome(), "config.json");
43
78
  this.workspaceRoot = findWorkspaceRoot(this.startDir);
44
79
  this.legacyKeysRemoved = [];
80
+ // `--workspace`'s value, which bin/vatio.mjs takes out of the arguments.
81
+ this.workspaceFlag = null;
82
+ // Set for a command that works on the files (bindToDirectory).
83
+ this.directoryCommand = null;
45
84
  }
46
85
 
47
86
  load() {
@@ -103,12 +142,67 @@ export class Config {
103
142
  return presence(process.env.VATIO_TOKEN) ?? presence(this.load().token);
104
143
  }
105
144
 
106
- // One source, always: the manifest of the workspace the cwd is in.
107
- resolveWorkspace() {
145
+ // --workspace, then VATIO_WORKSPACE, then the manifest of the workspace the
146
+ // cwd is in. `quiet` keeps a vatio.yml that names another workspace from
147
+ // being mentioned, for a caller that is not running the command.
148
+ resolveWorkspace({ quiet = false } = {}) {
149
+ const named = this.namedWorkspace();
150
+ if (!named) return this.directoryWorkspace();
151
+ if (!quiet) this.#sayWhenDirectoryDiffers(named);
152
+ return named.slug;
153
+ }
154
+
155
+ // The `workspace:` of the vatio.yml at or above the cwd.
156
+ directoryWorkspace() {
108
157
  if (!this.workspaceRoot) return null;
109
158
  return presence(workspaceSlug(this.workspaceRoot))?.toLowerCase() ?? null;
110
159
  }
111
160
 
161
+ // The workspace named without a vatio.yml, and by what; null when neither
162
+ // the flag nor the variable is given. A slug that is not one is refused
163
+ // here, where it can still be a sentence rather than a 404.
164
+ namedWorkspace() {
165
+ const flagged = this.workspaceFlag !== null;
166
+ const value = flagged ? this.workspaceFlag : presence(process.env[WORKSPACE_ENV]);
167
+ if (value === null) return null;
168
+
169
+ const source = flagged ? "--workspace" : WORKSPACE_ENV;
170
+ const slug = value.trim().toLowerCase();
171
+ if (!SLUG_FORMAT.test(slug)) {
172
+ throw new ConfigError(
173
+ `${source} ${JSON.stringify(value)} is not a workspace slug (lowercase letters, numbers, hyphens). ` +
174
+ "`vatio whoami` lists the workspaces this machine reaches."
175
+ );
176
+ }
177
+ return { slug, source };
178
+ }
179
+
180
+ // What named the workspace, for a message that has to say so.
181
+ workspaceSource() {
182
+ if (this.workspaceFlag !== null) return "--workspace";
183
+ if (presence(process.env[WORKSPACE_ENV])) return WORKSPACE_ENV;
184
+ return this.workspaceRoot ? MANIFEST_FILE : null;
185
+ }
186
+
187
+ // For a command that reads or writes the workspace's files, called before it
188
+ // does anything. The flag is refused outright; VATIO_WORKSPACE only when it
189
+ // names a workspace other than the directory's, since an app's own config
190
+ // reads the same variable and having it exported should not stop a push.
191
+ bindToDirectory(command) {
192
+ this.directoryCommand = command;
193
+ const [takes, there] =
194
+ command === "init"
195
+ ? [`writes ${MANIFEST_FILE} here and takes the workspace from its SLUG argument`, ""]
196
+ : [`works from the directory that holds ${MANIFEST_FILE} and takes the workspace from it`, " there"];
197
+ const refusal = `\`vatio ${command}\` ${takes}`;
198
+ if (this.workspaceFlag !== null) throw new ConfigError(`${refusal}: run it${there} without --workspace.`);
199
+
200
+ const named = presence(process.env[WORKSPACE_ENV]);
201
+ if (named !== null && named.toLowerCase() !== this.#directorySlugOrNull()) {
202
+ throw new ConfigError(`${refusal}, not from ${WORKSPACE_ENV} (${named}): run it${there} with ${WORKSPACE_ENV} unset.`);
203
+ }
204
+ }
205
+
112
206
  resolveWorkspaceRequired() {
113
207
  const slug = this.resolveWorkspace();
114
208
  if (slug) return slug;
@@ -124,14 +218,64 @@ export class Config {
124
218
  }
125
219
 
126
220
  workspaceRootRequired() {
221
+ const named = this.namedWorkspace();
222
+ if (named && named.slug !== this.#directorySlugOrNull()) {
223
+ throw new ConfigError(
224
+ `This works on the workspace's files, and ${named.source} names ${named.slug}, which has none here: ` +
225
+ `run it from the directory whose ${MANIFEST_FILE} says \`workspace: ${named.slug}\`, without ${named.source}.`
226
+ );
227
+ }
127
228
  if (this.workspaceRoot) return this.workspaceRoot;
229
+
128
230
  const below = workspacesBelow(this.startDir);
129
- throw new ConfigError(
130
- `Not inside a Vatio workspace (no ${MANIFEST_FILE} found walking up from ${this.startDir}).\n` +
131
- (below.length > 0
132
- ? `There is one in ${below.map((dir) => `./${dir}`).join(", ")}: run it from there (\`cd ${below[0]}\`).`
133
- : "Run `vatio init SLUG` here to create one.")
134
- );
231
+ const lines = [`Not inside a Vatio workspace (no ${MANIFEST_FILE} found walking up from ${this.startDir}).`];
232
+ if (below.length > 0) {
233
+ lines.push(`There is one in ${below.map((dir) => `./${dir}`).join(", ")}: run it from there (\`cd ${below[0]}\`).`);
234
+ }
235
+ // Only a command that takes --workspace is told about it.
236
+ if (this.directoryCommand) {
237
+ if (below.length === 0) lines.push("Run `vatio init SLUG` here to create one.");
238
+ } else {
239
+ lines.push(
240
+ `A workspace with no ${MANIFEST_FILE}, built through the Vatio MCP, is named with --workspace SLUG ` +
241
+ `(\`vatio whoami\` lists yours)${below.length === 0 ? "; `vatio init SLUG` starts one kept as files here" : ""}.`
242
+ );
243
+ }
244
+ throw new ConfigError(lines.join("\n"));
245
+ }
246
+
247
+ // The directory that holds the addressed workspace's files, or null: a
248
+ // workspace named by --workspace or VATIO_WORKSPACE has one here only when
249
+ // the vatio.yml here names it too. For what may sit beside vatio.yml without
250
+ // being required (identity.pem, .env, the chat state), so it never throws.
251
+ workspaceDirectory() {
252
+ if (!this.workspaceRoot) return null;
253
+ let named;
254
+ try {
255
+ named = this.namedWorkspace();
256
+ } catch {
257
+ return null;
258
+ }
259
+ if (!named) return this.workspaceRoot;
260
+ return named.slug === this.#directorySlugOrNull() ? this.workspaceRoot : null;
261
+ }
262
+
263
+ #directorySlugOrNull() {
264
+ try {
265
+ return this.directoryWorkspace();
266
+ } catch {
267
+ return null;
268
+ }
269
+ }
270
+
271
+ // Said once, on stderr, so that a vatio.yml naming another workspace is
272
+ // never a surprise: the named one wins.
273
+ #sayWhenDirectoryDiffers(named) {
274
+ if (this.#differenceSaid) return;
275
+ const here = this.#directorySlugOrNull();
276
+ if (here === null || here === named.slug) return;
277
+ this.#differenceSaid = true;
278
+ console.error(`vatio: using workspace ${named.slug} from ${named.source}, not ${here} from ${this.manifestPath()}`);
135
279
  }
136
280
 
137
281
  manifestPath() {
@@ -243,7 +387,9 @@ export class Config {
243
387
  );
244
388
  }
245
389
  if (normalized === "workspace") {
246
- throw new ConfigError(`the workspace is named by \`workspace:\` in ${MANIFEST_FILE}, never by config`);
390
+ throw new ConfigError(
391
+ `the workspace is named by \`workspace:\` in ${MANIFEST_FILE}, or by --workspace or ${WORKSPACE_ENV}, never by config`
392
+ );
247
393
  }
248
394
  if (REMOVED_KEYS.includes(normalized)) {
249
395
  throw new ConfigError(
package/lib/help.mjs CHANGED
@@ -8,9 +8,18 @@ export function helpText() {
8
8
 
9
9
  (installed globally with \`npm i -g @vatio-ai/cli\`, the command is just \`vatio\`)
10
10
 
11
- A workspace is any directory with a vatio.yml. Every command except init reads
12
- \`workspace:\` from the vatio.yml at or above the cwd — there is no --workspace
13
- flag, the directory decides.
11
+ To build and test an agent from a coding agent, connect the Vatio MCP
12
+ (https://vatio.ai/mcp) instead: \`npx @vatio-ai/skills\` adds it to the
13
+ project, then /vatio-init. Vatio holds the agent, and nothing goes in your
14
+ repository. The CLI is for a team that keeps the agent as files.
15
+
16
+ A workspace is any directory with a vatio.yml: commands read \`workspace:\`
17
+ from the vatio.yml at or above the cwd. --workspace SLUG (anywhere on the
18
+ command line) or VATIO_WORKSPACE names one instead, such as a workspace built
19
+ through the MCP, which has no vatio.yml; it wins over a vatio.yml, and the
20
+ command says so when the two differ. init, push, pull, diff and auth work on
21
+ the files, so they go by the directory alone: they refuse --workspace, and a
22
+ VATIO_WORKSPACE that names another workspace.
14
23
 
15
24
  Until someone outside your team talks to your agent, \`push\` is the deploy:
16
25
  live follows every one of them. From their first conversation on, a push waits
@@ -177,17 +186,15 @@ the two you are in. Commands default as listed.
177
186
  otherwise the value everywhere. With --tests, the
178
187
  value preview and every test run use, like a staging URL
179
188
  keys list [--json] API keys of both kinds: publishable (for a page or
180
- app) and secret (for your backend, with its scopes)
181
- keys create publishable|secret [--env NAME] [--label NAME] [--origin URL]... [--json]
182
- --origin only for a publishable key
189
+ app, with where it was used) and secret (for your
190
+ backend, with its scopes)
191
+ keys create publishable|secret [--env NAME] [--label NAME] [--json]
192
+ A publishable key works from any site
183
193
  keys create secret --scope NAME... [--code CODE | --recovery-code CODE]
184
194
  What the secret key may call: messages, instagram,
185
195
  chats, team (repeatable). Without --scope, all but
186
196
  team. team (add people to the team) is the owner's,
187
197
  with a code from their authenticator app
188
- keys origins PREFIX URL...
189
- The origins a publishable key is accepted from
190
- (replaces the list)
191
198
  keys revoke PREFIX
192
199
  auth --new-key Keypair that signs the JWT saying who a visitor is
193
200
 
@@ -210,8 +217,9 @@ the two you are in. Commands default as listed.
210
217
  whatsapp live on|off Answer everyone who writes, or nobody
211
218
  whatsapp check [--pin PIN] Check the number with Meta and re-subscribe it;
212
219
  a pass clears its problem. --pin (its 6-digit
213
- two-step verification PIN) registers it on the
214
- Cloud API again first: the fix for 133010
220
+ two-step verification PIN, or the one it takes
221
+ when it has none) registers it on the Cloud API
222
+ first: the fix for a number not registered
215
223
  whatsapp disconnect [--yes]
216
224
  whatsapp invite EMAIL [--code CODE]
217
225
  Ask whoever manages the number to connect it:
@@ -244,8 +252,11 @@ the two you are in. Commands default as listed.
244
252
  config show|get KEY|set KEY VALUE|unset KEY
245
253
  Keys: base_url, token
246
254
 
247
- Environment: VATIO_BASE_URL, VATIO_TOKEN, VATIO_HOME, VATIO_NO_UPDATE_NOTIFIER,
248
- VATIO_TELEMETRY=0 (see vatio.ai/docs/cli/workspace#telemetry)
255
+ Global flag: --workspace SLUG names the workspace (not for init, push, pull,
256
+ diff, auth)
257
+
258
+ Environment: VATIO_BASE_URL, VATIO_TOKEN, VATIO_WORKSPACE, VATIO_HOME,
259
+ VATIO_NO_UPDATE_NOTIFIER, VATIO_TELEMETRY=0 (see vatio.ai/docs/cli/workspace#telemetry)
249
260
 
250
261
  Docs: https://vatio.ai/docs
251
262
  `;
package/lib/telemetry.mjs CHANGED
@@ -206,7 +206,7 @@ async function post(config, body, { strict = false } = {}) {
206
206
  headers,
207
207
  body: JSON.stringify({
208
208
  ...body,
209
- workspace: safely(() => config.resolveWorkspace())
209
+ workspace: safely(() => config.resolveWorkspace({ quiet: true }))
210
210
  }),
211
211
  signal: AbortSignal.timeout(strict ? 10_000 : REPORT_TIMEOUT_MS)
212
212
  });
@@ -87,8 +87,8 @@ function loadKey(config, keyFile) {
87
87
  } else if (process.env[KEY_ENV]) {
88
88
  pem = process.env[KEY_ENV];
89
89
  } else {
90
- const path = join(config.workspaceRootRequired(), KEY_FILE);
91
- if (existsSync(path)) pem = readFileSync(path, "utf8");
90
+ const root = config.workspaceDirectory();
91
+ if (root && existsSync(join(root, KEY_FILE))) pem = readFileSync(join(root, KEY_FILE), "utf8");
92
92
  }
93
93
  if (pem === null) {
94
94
  fail(
@@ -107,8 +107,10 @@ function loadKey(config, keyFile) {
107
107
  // Vatio verifies with the algorithm the manifest declares, never the token's
108
108
  // own header, so a token signed with another one would simply not verify.
109
109
  function declaredAlgorithm(config) {
110
+ const root = config.workspaceDirectory();
111
+ if (!root) return null;
110
112
  try {
111
- const manifest = parseYaml(readFileSync(join(config.workspaceRootRequired(), MANIFEST_FILE), "utf8"));
113
+ const manifest = parseYaml(readFileSync(join(root, MANIFEST_FILE), "utf8"));
112
114
  const algorithm = String(manifest?.auth?.algorithm ?? "").trim().toUpperCase();
113
115
  return ALGORITHMS.includes(algorithm) ? algorithm : null;
114
116
  } catch {
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@vatio-ai/cli",
3
- "version": "0.129.0",
3
+ "version": "0.131.0",
4
4
  "description": "Vatio CLI — deploy and manage Vatio agent workspaces",
5
5
  "keywords": [
6
6
  "vatio",