@vatio-ai/cli 0.130.0 → 0.132.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
 
@@ -73,20 +84,20 @@ init [SLUG] Create vatio.yml here, and the remote to match
73
84
  login | logout Authorize this machine in a browser, or revoke and forget it
74
85
  doctor Node, config, workspace and token status
75
86
 
76
- push Validate the workspace, then update preview
77
- pull [--env NAME] Write the deployed agent back into vatio.yml and tools/
78
- publish Take preview live, once `vatio test` has tested it
79
- diff [--env NAME] What this directory would change
80
- status Preview and live deployment state
81
- rollback Restore the previous live deployment
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
82
93
 
83
- chat "message" [--env NAME] [--new]
94
+ chat "message" [--new]
84
95
  Talk to your own agent; the token is the identity
85
96
  chat show [CHAT_ID] [--json]
86
97
  The chat you are in, or any chat in the workspace, with its tool calls
87
98
 
88
99
  flags Every open report from the inbox, for your coding agent to fix
89
- test Test every report against preview, in the background
100
+ test Test every report against your team's version, in the background
90
101
  test --wait Wait for the report; exits 1 if a case fails
91
102
  tools [--env NAME] How each tool's backend has been answering
92
103
 
@@ -94,7 +105,7 @@ kb list|show|create|rm Knowledge bases
94
105
  kb write|cat|rm-entry Entries, from a file or stdin
95
106
 
96
107
  secrets list|set|rm Credentials your tools read
97
- 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)
98
109
  auth --new-key Keypair that signs the visitor's JWT
99
110
 
100
111
  whatsapp | instagram Set up in the inbox; prints the link
@@ -103,9 +114,6 @@ docs [--save [PATH]] The whole developer contract
103
114
  config show|set|unset base_url and token, per developer
104
115
  ```
105
116
 
106
- `--env NAME` targets an environment: `preview`, the next version, or `live`,
107
- what visitors talk to.
108
-
109
117
  Run `npx @vatio-ai/cli help` for the whole surface, and see
110
118
  [vatio.ai/docs](https://vatio.ai/docs) for the platform.
111
119
 
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)}`);
@@ -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();
@@ -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
 
@@ -111,13 +112,13 @@ export async function chat(config, args) {
111
112
 
112
113
  export function chatHelp() {
113
114
  return `Usage:
114
- 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}
115
116
  vatio chat --chat CHAT_ID "message" [--file PATH]...
116
117
  vatio chat show [CHAT_ID] [--env NAME] [--last N] [--json]
117
118
  ${EXPORT_USAGE}
118
119
 
119
- --env picks the deployment that answers: preview (default) or live. A chat
120
- 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.
121
122
 
122
123
  --file PATH attaches a file to the message, as a visitor would from the web:
123
124
  up to four, 8 MB each, images, PDFs, text files or audio. The message may be
@@ -145,13 +146,15 @@ 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
 
154
- \`--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
155
158
  need $contact.phone_number or a team role (access: supervisor and up): \`me\`
156
159
  is your own verified WhatsApp, with your role on the team; one of the
157
160
  workspace's customer phones (added in the inbox, under Conversations → Try the
@@ -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 {
@@ -610,7 +620,7 @@ async function startOver(config, options) {
610
620
  apiUrl,
611
621
  chatId: chatsFor(config, apiUrl)[options.environment] ?? null
612
622
  });
613
- 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)`);
614
624
  return Number(payload.chat_id);
615
625
  }
616
626