@vatio-ai/cli 0.37.2

package/LICENSE.txt

@@ -0,0 +1,16 @@
+Copyright (c) 2026 Urcalab. All rights reserved.
+
+This software (the "Vatio CLI") is distributed solely for the purpose
+of installing, running, and interacting with the Vatio platform at
+https://vatio.ai and its APIs.
+
+Permission is granted to install and use the Vatio CLI as distributed,
+for that purpose. Redistribution, modification, reverse engineering,
+sublicensing, or any use of this software independent of the Vatio
+platform is not permitted without prior written permission from
+Urcalab.
+
+THIS SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, AND
+NONINFRINGEMENT.

package/README.md

@@ -0,0 +1,61 @@
+# @vatio-ai/cli
+
+The CLI for [Vatio](https://vatio.ai) — deploy and manage AI agent workspaces.
+
+```bash
+npx @vatio-ai/cli init my-agent
+npx @vatio-ai/cli push
+```
+
+No runtime to install first: if you have Node, you have this.
+
+The package is `@vatio-ai/cli`; the command it installs is `vatio`. So
+`npm install -g @vatio-ai/cli` gives you `vatio push`, and `npx @vatio-ai/cli push`
+is the same thing without installing anything.
+
+## What a workspace is
+
+A directory with a `vatio.yml` in it. That file says which Vatio workspace the
+directory deploys to, what the agent does, and how the widget looks; `tools/`,
+`lib/` and `auth/` next to it are plain JavaScript the agent runs.
+
+Nothing constrains where that directory lives — an agent can sit inside the
+repository of the backend it calls, and every command except `init` finds it by
+walking up from the current directory. There is no `--workspace` flag.
+
+## Commands
+
+```
+init [SLUG] [--name NAME]   Create vatio.yml here, and the remote to match
+login [--base-url URL]      Authorize this machine in a browser
+push [--env NAME]           Validate the workspace, then update a preview
+publish [--env NAME]        Promote a preview to live
+diff [--env NAME]           What this directory would change
+status                      Preview and live deployment state
+rollback                    Restore the previous live deployment
+tools check                 Validate the workspace against Vatio's contracts
+secrets list|set|rm         Credentials your tools read as ctx.env
+tokens list|create|revoke   Publishable tokens for the widget and the SDK
+widget [--env NAME]         What the platform enforces, and the tokens there are
+config show|set|unset       base_url and token, per developer
+doctor                      Node, config, workspace and token status
+```
+
+`--env NAME` targets a deployment: `live`, `preview`, or a named preview like
+`pr-42`.
+
+Run `npx @vatio-ai/cli help` for the whole surface, and see
+[vatio.ai/docs](https://vatio.ai/docs) for the platform.
+
+## Where your credentials live
+
+`~/.vatio/config.json`, or `$VATIO_HOME/config.json` — per developer, never
+inside a repository. `VATIO_BASE_URL` and `VATIO_TOKEN` override it for one
+command, which is what CI should use.
+
+## Where the rules live
+
+Whether a workspace is valid is answered by Vatio, not by this package: `push`
+and `tools check` send the directory and read the result back. So the rules that
+judge your workspace are always the deployed ones, and this CLI never has to be
+upgraded to understand a new one.

package/bin/vatio.mjs

@@ -0,0 +1,132 @@
+#!/usr/bin/env node
+// The Vatio CLI, as an npm package: `npx vatio push`.
+//
+// Same platform, same API, same ~/.vatio/config.json as the Ruby CLI that
+// `curl … /install.sh | bash` puts on a machine. Either can drive a workspace,
+// and a developer who logged in with one is logged in for the other -- the
+// credential belongs to their home directory, not to a client.
+//
+// This exists because Node is the runtime this audience already has and Ruby
+// is the one some of them do not. Nothing about the contract moved: the
+// workspace is parsed by the platform, so a client is HTTP and a terminal.
+
+import { Config, ConfigError } from "../lib/config.mjs";
+import { HttpError, UnauthorizedError, ForbiddenError, NotFoundError } from "../lib/http.mjs";
+import { UserError, fail } from "../lib/support.mjs";
+import { helpText } from "../lib/help.mjs";
+import { login, logout } from "../lib/commands/auth.mjs";
+import { configCommand, doctor, init, version } from "../lib/commands/misc.mjs";
+import { diff, publish, push, rollback, status, toolsCheck } from "../lib/commands/deploy.mjs";
+import { secrets, tokens, widget } from "../lib/commands/workspace-admin.mjs";
+import { chat } from "../lib/commands/chat.mjs";
+import { kb } from "../lib/commands/knowledge.mjs";
+import { instagram, whatsapp } from "../lib/commands/channels.mjs";
+import { docs, issue } from "../lib/commands/support-commands.mjs";
+import { mcp } from "../lib/commands/mcp.mjs";
+
+// Two commands that existed and are gone, answered by name rather than as
+// unknown: one was removed from the product, the other is what npm does.
+const RETIRED = {
+  pull: "was removed: a deployed manifest only ever comes from a push, so it could never\n" +
+    "hand back anything your repository did not already have. Use `vatio diff --env live`,\n" +
+    "or read the manifest at GET /api/v1/:slug/deploy/manifest.",
+  update: "is npm's job now: `npx vatio@latest` always runs the current release, and\n" +
+    "`npm install -g vatio@latest` updates a global install."
+};
+
+async function main(argv) {
+  const args = argv.slice(2);
+  const command = args.shift();
+  const config = new Config({ startDir: process.cwd() });
+
+  switch (command) {
+    case "version":
+    case "--version":
+    case "-v":
+      return version();
+    case "doctor":
+      return doctor(config);
+    case "login":
+      return await login(config, args);
+    case "logout":
+      return logout(config);
+    case "config":
+      return configCommand(config, args);
+    case "init":
+      return await init(config, args);
+    case "push":
+      return await push(config, args);
+    case "publish":
+      return await publish(config, args);
+    case "rollback":
+      return await rollback(config);
+    case "status":
+      return await status(config);
+    case "diff":
+      return await diff(config, args);
+    case "tools":
+      return await toolsCheck(config, args);
+    case "tokens":
+      return await tokens(config, args);
+    case "widget":
+      return await widget(config, args);
+    case "chat":
+      return await chat(config, args);
+    case "kb":
+      return await kb(config, args);
+    case "secrets":
+      return await secrets(config, args);
+    case "whatsapp":
+      return await whatsapp(config, args);
+    case "instagram":
+      return await instagram(config, args);
+    case "docs":
+      return await docs(config, args);
+    case "issue":
+      return await issue(config, args);
+    case "mcp":
+      return await mcp(config);
+    case "help":
+    case "-h":
+    case "--help":
+    case undefined:
+      return console.log(helpText());
+    default:
+      if (RETIRED[command]) fail(`\`vatio ${command}\` ${RETIRED[command]}`);
+      fail(`Unknown command: ${command}\n\n${helpText()}`);
+  }
+}
+
+
+main(process.argv).catch((error) => {
+  if (error instanceof UserError || error instanceof ConfigError) {
+    console.error(error.message);
+    process.exit(1);
+  }
+  if (error instanceof UnauthorizedError) {
+    console.error("Authentication failed (401). Run `vatio login`.");
+    if (error.requestId) console.error(`request_id=${error.requestId}`);
+    process.exit(1);
+  }
+  if (error instanceof ForbiddenError) {
+    console.error("Access denied (403). Your token cannot access this workspace.");
+    if (error.requestId) console.error(`request_id=${error.requestId}`);
+    process.exit(1);
+  }
+  if (error instanceof NotFoundError) {
+    console.error(
+      "Remote resource not found (404). Check the workspace slug; `vatio push` creates a missing remote automatically."
+    );
+    if (error.requestId) console.error(`request_id=${error.requestId}`);
+    process.exit(1);
+  }
+  if (error instanceof HttpError) {
+    console.error(error.message);
+    if (error.requestId) console.error(`request_id=${error.requestId}`);
+    process.exit(1);
+  }
+  // Anything left is a bug in this CLI rather than something the developer
+  // did, so it keeps its stack: that is what makes it reportable.
+  console.error(error?.stack ?? String(error));
+  process.exit(1);
+});

package/lib/api-client.mjs

@@ -0,0 +1,286 @@
+// Everything the CLI can ask of one workspace: /api/v1/:slug/*.
+//
+// One class rather than a client per surface. They share a host, a token and an
+// error contract, and splitting them only ever meant passing the same three
+// things around four times.
+
+import { HttpClient } from "./http.mjs";
+
+const encode = (value) => encodeURIComponent(String(value));
+
+export class ApiClient extends HttpClient {
+  // --- deploy ---------------------------------------------------------
+
+  deployStatus() {
+    return this.get("/deploy/status");
+  }
+
+  deployedManifest({ environment = "live" } = {}) {
+    return this.get("/deploy/manifest", { environment });
+  }
+
+  // Validation without deploying: send the directory, get back the manifest it
+  // builds, its errors and warnings, and the diff against `environment`. A
+  // workspace that fails to validate is a normal 200 with ok:false -- only a
+  // bundle the platform cannot read at all raises.
+  check({ files, environment = null }) {
+    const body = { files };
+    if (environment) body.environment = environment;
+    return this.post("/deploy/check", body);
+  }
+
+  pushPreview({ manifest, gitSha = null, createdBy = null, environment = null }) {
+    const body = { manifest };
+    if (gitSha) body.git_sha = gitSha;
+    if (createdBy) body.created_by = createdBy;
+    if (environment) body.environment = environment;
+    return this.put("/deploy/preview", body);
+  }
+
+  publish({ createdBy = null, environment = null } = {}) {
+    const body = {};
+    if (createdBy) body.created_by = createdBy;
+    if (environment) body.environment = environment;
+    return this.post("/deploy/publish", body);
+  }
+
+  rollback({ createdBy = null } = {}) {
+    const body = {};
+    if (createdBy) body.created_by = createdBy;
+    return this.post("/deploy/rollback", body);
+  }
+
+  revisions() {
+    return this.get("/deploy/revisions");
+  }
+
+  revision(id) {
+    return this.get(`/deploy/revisions/${encode(id)}`);
+  }
+
+  // --- secrets --------------------------------------------------------
+
+  listSecrets() {
+    return this.get("/deploy/secrets");
+  }
+
+  upsertSecret({ key, value }) {
+    return this.put(`/deploy/secrets/${encode(key)}`, { value });
+  }
+
+  deleteSecret({ key }) {
+    return this.delete(`/deploy/secrets/${encode(key)}`);
+  }
+
+  // --- knowledge bases ------------------------------------------------
+
+  knowledgeBases() {
+    return this.get("/knowledge_bases");
+  }
+
+  knowledgeBase(name) {
+    return this.get(`/knowledge_bases/${encode(name)}`);
+  }
+
+  createKnowledgeBase(name) {
+    return this.post("/knowledge_bases", { name });
+  }
+
+  deleteKnowledgeBase(name) {
+    return this.delete(`/knowledge_bases/${encode(name)}`);
+  }
+
+  addKnowledgeCrawl({ base, name, siteUrl, includes = [], excludes = [] }) {
+    return this.post(`/knowledge_bases/${encode(base)}/sources`, {
+      name,
+      site_url: siteUrl,
+      include: includes,
+      exclude: excludes
+    });
+  }
+
+  // The file's bytes travel in the body: the platform chunks and embeds, and
+  // it is the only copy there will be.
+  uploadKnowledgeDocument({ base, filename, content }) {
+    return this.post(`/knowledge_bases/${encode(base)}/sources`, { filename, content });
+  }
+
+  deleteKnowledgeSource({ base, name }) {
+    return this.delete(`/knowledge_bases/${encode(base)}/sources/${encode(name)}`);
+  }
+
+  reindexKnowledgeSource({ base, name }) {
+    return this.post(`/knowledge_bases/${encode(base)}/sources/${encode(name)}/reindex`, {});
+  }
+
+  // --- publishable tokens and the widget ------------------------------
+
+  listPublishableTokens() {
+    return this.get("/publishable_tokens");
+  }
+
+  createPublishableToken({ environment, label = null }) {
+    const body = { environment };
+    if (String(label ?? "").trim() !== "") body.label = String(label).trim();
+    return this.post("/publishable_tokens", body);
+  }
+
+  revokePublishableToken({ prefix }) {
+    return this.delete(`/publishable_tokens/${encode(prefix)}`);
+  }
+
+  widget() {
+    return this.get("/widget");
+  }
+
+  // --- the shared WhatsApp preview ------------------------------------
+
+  listTestPhoneNumbers() {
+    return this.get("/test_phone_numbers");
+  }
+
+  addTestPhoneNumber({ phoneNumber }) {
+    return this.post("/test_phone_numbers", { phone_number: phoneNumber });
+  }
+
+  verifyTestPhoneNumber({ phoneNumber, code }) {
+    return this.post(`/test_phone_numbers/${waId(phoneNumber)}/verify`, { code });
+  }
+
+  resendTestPhoneNumberCode({ phoneNumber }) {
+    return this.post(`/test_phone_numbers/${waId(phoneNumber)}/resend`, {});
+  }
+
+  removeTestPhoneNumber({ phoneNumber }) {
+    return this.delete(`/test_phone_numbers/${waId(phoneNumber)}`);
+  }
+
+  // --- the workspace's own WhatsApp number ----------------------------
+
+  whatsappAccount() {
+    return this.get("/whatsapp_account");
+  }
+
+  // Mints the URL for Meta's Embedded Signup and returns it; it connects
+  // nothing on its own. Same shape as instagramConnectLink.
+  whatsappConnectLink() {
+    return this.post("/whatsapp_account", {});
+  }
+
+  checkWhatsappAccount() {
+    return this.post("/whatsapp_account/check", {});
+  }
+
+  activateWhatsappAccount() {
+    return this.post("/whatsapp_account/activate", {});
+  }
+
+  deactivateWhatsappAccount() {
+    return this.post("/whatsapp_account/deactivate", {});
+  }
+
+  disconnectWhatsappAccount() {
+    return this.delete("/whatsapp_account");
+  }
+
+  // --- Instagram ------------------------------------------------------
+
+  instagramAccount() {
+    return this.get("/instagram_account");
+  }
+
+  instagramConnectLink() {
+    return this.post("/instagram_account", {});
+  }
+
+  checkInstagramAccount() {
+    return this.post("/instagram_account/check", {});
+  }
+
+  disconnectInstagramAccount() {
+    return this.delete("/instagram_account");
+  }
+
+  listTestInstagramAccounts() {
+    return this.get("/test_instagram_accounts");
+  }
+
+  // Declares which Instagram account you mean. The code comes later, by DM,
+  // once that account writes to the shared preview -- Instagram will not let
+  // Vatio message an account that has not messaged it first.
+  addTestInstagramAccount({ username }) {
+    return this.post("/test_instagram_accounts", { username });
+  }
+
+  // Addressed by the code alone: the workspace is already in the path and the
+  // code is the only value the developer has in hand.
+  verifyTestInstagramAccount({ code }) {
+    return this.post("/test_instagram_accounts/verify", { code });
+  }
+
+  showTestInstagramAccount(id) {
+    return this.get(`/test_instagram_accounts/${encode(id)}`);
+  }
+
+  resendTestInstagramAccountCode(id) {
+    return this.post(`/test_instagram_accounts/${encode(id)}/resend_otp`, {});
+  }
+
+  removeTestInstagramAccount(id) {
+    return this.delete(`/test_instagram_accounts/${encode(id)}`);
+  }
+
+  // --- chats ----------------------------------------------------------
+
+  createChat({ environment }) {
+    return this.post("/chats", { environment });
+  }
+
+  resetChat({ chatId, environment }) {
+    return this.post(`/chats/${encode(chatId)}/reset`, { environment });
+  }
+
+  showChat({ chatId, view = "visitor" }) {
+    return this.get(`/chats/${encode(chatId)}`, { view });
+  }
+
+  chatMessages({ chatId, view = "visitor", after = null, limit = null }) {
+    const params = { view };
+    if (after) params.after = after;
+    if (limit) params.limit = limit;
+    return this.get(`/chats/${encode(chatId)}/messages`, params);
+  }
+
+  sendChatMessage({ chatId, content }) {
+    return this.post(`/chats/${encode(chatId)}/messages`, { content });
+  }
+
+  destroyChat({ chatId }) {
+    return this.delete(`/chats/${encode(chatId)}`);
+  }
+}
+
+// /cli/* -- not workspace-scoped, so it takes the bare host.
+export class CliClient extends HttpClient {
+  listWorkspaces() {
+    return this.get("/cli/workspaces");
+  }
+
+  createWorkspace({ slug, name = null }) {
+    const body = { slug };
+    if (String(name ?? "").trim() !== "") body.name = String(name).trim();
+    return this.post("/cli/workspaces", body);
+  }
+
+  async workspaceExists(slug) {
+    const payload = await this.listWorkspaces();
+    const workspaces = Array.isArray(payload.workspaces) ? payload.workspaces : [];
+    return workspaces.some((workspace) => String(workspace.slug) === String(slug));
+  }
+}
+
+// The path carries the digits: "+" and spaces do not survive a URL, and the
+// digits are what the API stores as `wa_id`.
+function waId(phoneNumber) {
+  return String(phoneNumber ?? "").replace(/\D/g, "");
+}

package/lib/bundle.mjs

@@ -0,0 +1,90 @@
+// The workspace directory as the bytes that go on the wire, for
+// POST /api/v1/:slug/deploy/check. The port of cli/lib/workspace_bundle.rb.
+//
+// There is deliberately no list here of "the files a manifest reads". That list
+// *is* the contract -- `widget.logo` and `identity.public_key` name files from
+// inside vatio.yml -- and a client that knew it would be a client that needs a
+// release every time the answer changes. So this walks what is on disk, skips
+// what is plainly not workspace source, and lets the platform decide what
+// matters.
+
+import { readFileSync, readdirSync, statSync } from "node:fs";
+import { join, relative, sep } from "node:path";
+
+// Mirrors what /deploy/check enforces. Checked here as well so an oversized
+// workspace fails in the terminal rather than after the upload.
+export const MAX_FILES = 500;
+export const MAX_FILE_BYTES = 2 * 1024 * 1024;
+export const MAX_TOTAL_BYTES = 8 * 1024 * 1024;
+// Hidden entries are skipped wholesale, which is what keeps `.env` and `.git/`
+// out of an upload without having to name either.
+export const SKIP_DIRECTORIES = new Set(["node_modules", "tmp", "log"]);
+
+export class BundleError extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "BundleError";
+  }
+}
+
+export function buildBundle(root) {
+  if (!isDirectory(root)) throw new BundleError(`not a directory: ${root}`);
+
+  const files = [];
+  let total = 0;
+
+  for (const path of walk(root)) {
+    // Posix separators on the wire: the platform materializes these into a
+    // directory and a Windows client must not send backslashes for it to
+    // refuse.
+    const relativePath = relative(root, path).split(sep).join("/");
+    const bytes = readFileSync(path);
+
+    if (bytes.byteLength > MAX_FILE_BYTES) {
+      throw new BundleError(`${relativePath} is ${bytes.byteLength} bytes; the limit is ${MAX_FILE_BYTES}`);
+    }
+
+    total += bytes.byteLength;
+    if (total > MAX_TOTAL_BYTES) throw new BundleError(`the workspace is over ${MAX_TOTAL_BYTES} bytes`);
+    if (files.length >= MAX_FILES) throw new BundleError(`the workspace has more than ${MAX_FILES} files`);
+
+    files.push(entryFor(relativePath, bytes));
+  }
+
+  if (files.length === 0) throw new BundleError("the workspace is empty");
+  return files;
+}
+
+function* walk(dir) {
+  const children = readdirSync(dir, { withFileTypes: true }).sort((a, b) => (a.name < b.name ? -1 : 1));
+  for (const child of children) {
+    if (child.name.startsWith(".")) continue;
+
+    const path = join(dir, child.name);
+    if (child.isDirectory()) {
+      if (SKIP_DIRECTORIES.has(child.name)) continue;
+      yield* walk(path);
+    } else if (child.isFile()) {
+      yield path;
+    }
+  }
+}
+
+// Text travels as text so a diff of the request is readable and a logo does not
+// corrupt on the way. Anything that is not valid UTF-8 -- a png, a compiled
+// asset someone left in the directory -- goes as base64.
+function entryFor(path, bytes) {
+  const text = bytes.toString("utf8");
+  if (!text.includes("�") && !text.includes("\0") && Buffer.compare(Buffer.from(text, "utf8"), bytes) === 0) {
+    return { path, content: text, encoding: "utf-8" };
+  }
+  return { path, content: bytes.toString("base64"), encoding: "base64" };
+}
+
+function isDirectory(path) {
+  try {
+    return statSync(path).isDirectory();
+  } catch {
+    return false;
+  }
+}

package/lib/commands/auth.mjs

@@ -0,0 +1,64 @@
+// login / logout, and the device-code dance they share with `init`.
+
+import { DeviceAuthClient, ExpiredError, PendingError } from "../device-auth.mjs";
+import { DEFAULT_BASE_URL } from "../config.mjs";
+import { fail, openBrowser, sleep, takeValue } from "../support.mjs";
+
+// A token is minted by a human approving a code in a browser, not by anything
+// the CLI can do on its own. That is the whole point: a secret this CLI holds
+// was authorized by someone who was there.
+export async function deviceLogin({ baseUrl, message }) {
+  const resolved = String(baseUrl || process.env.VATIO_BASE_URL || DEFAULT_BASE_URL).replace(/\/$/, "");
+  const client = new DeviceAuthClient({ baseUrl: resolved });
+
+  console.log(message);
+  const auth = await client.start();
+  const deviceCode = auth.device_code;
+  const userCode = auth.user_code;
+  const verificationUri = auth.verification_uri_complete ?? auth.verification_uri;
+  const interval = Number(auth.interval ?? 5);
+  const expiresIn = Number(auth.expires_in ?? 900);
+  if (!deviceCode || !verificationUri) fail("The platform did not return a device code");
+
+  console.log("");
+  console.log(`Open: ${verificationUri}`);
+  console.log(`Code: ${userCode}`);
+  console.log("");
+  openBrowser(verificationUri);
+
+  const deadline = Date.now() + expiresIn * 1000;
+  for (;;) {
+    if (Date.now() > deadline) fail("Timed out waiting for authorization");
+    try {
+      const result = await client.poll({ deviceCode });
+      return {
+        token: result.token,
+        baseUrl: String(result.base_url ?? "").trim() || resolved
+      };
+    } catch (error) {
+      if (error instanceof PendingError) {
+        await sleep(interval * 1000);
+        continue;
+      }
+      if (error instanceof ExpiredError) fail("The code expired. Run `vatio login` again.");
+      throw error;
+    }
+  }
+}
+
+export async function login(config, args) {
+  const baseUrl = takeValue(args, "--base-url");
+  const { token, baseUrl: resolved } = await deviceLogin({
+    baseUrl,
+    message: "Starting device authorization for Vatio CLI…"
+  });
+
+  config.writeAuth({ baseUrl: resolved, token });
+  console.log(`Logged in to ${resolved}`);
+  console.log(`Token saved to ${config.configPath}`);
+}
+
+export function logout(config) {
+  config.clearToken();
+  console.log(`Removed the token from ${config.configPath}`);
+}