@vatio-ai/cli 0.46.0 → 0.47.1

package/README.md

@@ -1,44 +1,86 @@
 # @vatio-ai/cli
 
-The CLI for [Vatio](https://vatio.ai) — deploy and manage AI agent workspaces.
+The CLI for [Vatio](https://vatio.ai) — a production runtime for
+customer-facing AI agents. Describe an agent in one `vatio.yml` and deploy it to
+web chat, WhatsApp and Instagram; Vatio runs the conversation, the contacts, the
+identity, the safeguards and the handoff to a human.
 
 ```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.
+No runtime to install first: if you have Node 20 or newer, 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.
 
+## If you are a coding agent
+
+```bash
+vatio mcp     # MCP over stdio
+vatio docs    # the whole developer contract as markdown, live from Vatio
+```
+
+`vatio mcp` is the short path: it hands you the contract and the deploy commands
+over MCP, with no browser step. Failing that, `vatio docs` prints the same
+contract that [docs.vatio.ai/docs.md](https://docs.vatio.ai/docs.md) serves, and
+`vatio docs --save` writes it next to the workspace.
+
+Don't guess `vatio.yml` keys. Unknown root keys fail validation, and the rules
+that judge a workspace live on the server — so the printed contract is the
+current one by construction.
+
 ## 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.
+A directory with a `vatio.yml` in it:
+
+```text
+support-agent/
+  vatio.yml          # required: the agent, its tools, its knowledge
+  tools/*.yml        # one HTTP request each, described in YAML
+  identity.pub       # public key that verifies the JWT saying who a visitor is
+```
 
-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.
+Only create the files you need. 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
+init [SLUG]                 Create vatio.yml here, and the remote to match
+login | logout              Authorize this machine in a browser, or forget it
+doctor                      Node, config, workspace and token status
+
 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
+
+chat "message" [--env NAME] Talk to your own agent; the token is the identity
+chat transcript|debug|reset|destroy
+
+kb list|show|create|rm       Knowledge bases
+kb write|cat|rm-entry        Entries, from a file or stdin
+kb follow|unfollow|refresh   Read a site into a base, nightly
+
+secrets list|set|rm          Credentials your tools read
+tokens list|create|revoke    Publishable tokens for the widget and the SDK
+widget [--env NAME]          What the platform enforces, and the tokens there are
+auth --new-key               Keypair that signs the visitor's JWT
+
+whatsapp ...                 Shared preview number, or your own business number
+instagram ...                Shared sandbox, or your own account
+
+docs [--save [PATH]]         The whole developer contract
+mcp                          Speak MCP over stdio, for a coding agent
+issue "what should change"   Send a change request, workspace attached
+config show|set|unset        base_url and token, per developer
 ```
 
 `--env NAME` targets a deployment: `live`, `preview`, or a named preview like

package/lib/commands/auth.mjs

@@ -2,17 +2,19 @@
 
 import { DeviceAuthClient, ExpiredError, PendingError } from "../device-auth.mjs";
 import { DEFAULT_BASE_URL } from "../config.mjs";
-import { fail, openBrowser, sleep, takeValue } from "../support.mjs";
+import { ask, 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 }) {
+// A token is minted by a human approving it in a browser, never by the CLI
+// alone. The email turns that approval into a link we mail, which is what lets
+// somebody with no account finish it; typing nothing falls back to the URL.
+export async function deviceLogin({ baseUrl, message, email }) {
   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 address = String(email ?? (await ask("Your email (we send you a link): "))).trim();
+
+  const auth = await client.start({ email: address });
   const deviceCode = auth.device_code;
   const userCode = auth.user_code;
   const verificationUri = auth.verification_uri_complete ?? auth.verification_uri;
@@ -21,10 +23,16 @@ export async function deviceLogin({ baseUrl, message }) {
   if (!deviceCode || !verificationUri) fail("The platform did not return a device code");
 
   console.log("");
-  console.log(`Open: ${verificationUri}`);
-  console.log(`Code: ${userCode}`);
+  if (auth.email_sent) {
+    console.log(`We emailed ${address} a link.`);
+    console.log(`This terminal is ${userCode} — check it matches before you approve.`);
+  } else {
+    console.log(`Open: ${verificationUri}`);
+    console.log(`Code: ${userCode}`);
+    openBrowser(verificationUri);
+  }
   console.log("");
-  openBrowser(verificationUri);
+  console.log("Waiting…");
 
   const deadline = Date.now() + expiresIn * 1000;
   for (;;) {

package/lib/commands/deploy.mjs

@@ -17,8 +17,20 @@ import { stringify as stringifyYaml } from "yaml";
 import { buildBundle, BundleError } from "../bundle.mjs";
 import { ApiClient, CliClient } from "../api-client.mjs";
 import { NotFoundError } from "../http.mjs";
+import { deviceLogin } from "./auth.mjs";
 import { detectGitSha, fail, takeEnv, takeFlag, takeValue } from "../support.mjs";
 
+// The first command that makes something exist on a server, so the first one
+// that needs to know whose it is.
+export async function ensureAuthorized(config) {
+  if (config.resolveToken()) return;
+
+  const auth = await deviceLogin({ message: "Before I can push this, I need to know whose it is." });
+  config.writeAuth({ baseUrl: auth.baseUrl, token: auth.token });
+  console.log(`Token saved to ${config.configPath}`);
+  console.log("");
+}
+
 export function deployClient(config, workspace) {
   const base = config.resolveBaseUrl();
   if (!base) fail("VATIO_BASE_URL is required (env or `vatio config set base_url …`)");
@@ -91,6 +103,8 @@ export async function push(config, args) {
   const environment = takeEnv(args, { fallback: null });
   const workspace = config.resolveWorkspaceRequired();
 
+  await ensureAuthorized(config);
+
   // The remote has to exist before the workspace can be checked: the slug is in
   // the URL of the call that checks it. It is created unnamed -- the push a few
   // lines down applies `business.name` from the manifest anyway.
@@ -121,7 +135,7 @@ export async function push(config, args) {
   for (const warning of asArray(payload.warnings)) console.log(`  warning: ${warning}`);
   if (payload.preview_url) console.log(`Preview: ${payload.preview_url}`);
 
-  const hint = payload.whatsapp_preview_hint;
+  const hint = payload.first_push_hint;
   if (hint) {
     console.log("");
     console.log(hint.message);

package/lib/commands/misc.mjs

@@ -8,7 +8,6 @@ import { KEYS, SLUG_FORMAT } from "../config.mjs";
 import { MANIFEST_FILE, manifestPath } from "../workspace.mjs";
 import { VERSION } from "../version.mjs";
 import { fail, takeValue } from "../support.mjs";
-import { deviceLogin } from "./auth.mjs";
 import { workspacesClient } from "./deploy.mjs";
 
 export const DOCS_URL = "https://docs.vatio.ai";
@@ -81,7 +80,9 @@ export function configCommand(config, args) {
 // the point of the file is that an agent can live inside the repository of the
 // backend it calls, not in a separate folder of agents.
 export async function init(config, args) {
-  const baseUrl = takeValue(args, "--base-url");
+  // Still accepted and still ignored here -- `vatio login` owns --base-url,
+  // and swallowing it keeps it out of the slug below.
+  takeValue(args, "--base-url");
   const name = takeValue(args, "--name");
 
   const target = process.cwd();
@@ -100,25 +101,19 @@ export async function init(config, args) {
     fail(`Invalid slug "${slug}" (use lowercase letters, numbers, hyphens)`);
   }
 
-  // Logging in first means the remote is created against a base_url the
-  // developer has actually authorized, and a fresh machine gets through
-  // `vatio init` in one command instead of two.
-  if (!config.resolveToken()) {
-    const auth = await deviceLogin({ baseUrl, message: "Starting device authorization for Vatio CLI…" });
-    config.writeAuth({ baseUrl: auth.baseUrl, token: auth.token });
-    console.log(`Token saved to ${config.configPath}`);
-    console.log("");
+  // No login here: identity is what `push` needs, because `push` is the first
+  // thing that makes something run on a server. This writes a file.
+  const authorized = Boolean(config.resolveToken());
+  if (authorized) {
+    const clients = workspacesClient(config);
+    if (!(await clients.workspaceExists(slug))) await clients.createWorkspace({ slug, name });
   }
 
-  const clients = workspacesClient(config);
-  const created = !(await clients.workspaceExists(slug));
-  if (created) await clients.createWorkspace({ slug, name });
-
   const manifest = join(target, MANIFEST_FILE);
   writeFileSync(manifest, starterManifest(slug, name));
 
-  console.log(`${created ? "Created" : "Linked"} remote workspace ${slug}`);
   console.log(`Wrote ${manifest}`);
+  if (!authorized) console.log(`Local only for now — \`vatio push\` is what creates ${slug} on the platform.`);
   console.log("");
   console.log("Next:");
   console.log(`  edit ${MANIFEST_FILE}, then \`vatio push\` and \`vatio publish\``);

package/lib/device-auth.mjs

@@ -15,8 +15,12 @@ export class DeviceAuthClient {
     this.baseUrl = String(baseUrl ?? "").replace(/\/$/, "");
   }
 
-  start() {
-    return this.#post("/cli/device_authorizations", {});
+  // With an `email` the platform mails the approval link; without one the
+  // response is exactly what it always was.
+  start({ email } = {}) {
+    const body = {};
+    if (String(email ?? "").trim() !== "") body.email = String(email).trim();
+    return this.#post("/cli/device_authorizations", body);
   }
 
   poll({ deviceCode }) {

package/lib/support.mjs

@@ -104,3 +104,17 @@ export function openBrowser(url) {
 export function sleep(ms) {
   return new Promise((resolve) => setTimeout(resolve, ms));
 }
+
+// Returns "" with nothing attached to stdin, so an agent running `vatio push`
+// in a pipeline falls back to the URL instead of hanging on a prompt.
+export async function ask(question) {
+  if (!process.stdin.isTTY) return "";
+
+  const { createInterface } = await import("node:readline/promises");
+  const rl = createInterface({ input: process.stdin, output: process.stdout });
+  try {
+    return (await rl.question(question)).trim();
+  } finally {
+    rl.close();
+  }
+}

package/package.json

@@ -1,8 +1,14 @@
 {
   "name": "@vatio-ai/cli",
-  "version": "0.46.0",
+  "version": "0.47.1",
   "description": "Vatio CLI — deploy and manage Vatio agent workspaces",
-  "keywords": ["vatio", "agent", "ai", "cli", "deploy"],
+  "keywords": [
+    "vatio",
+    "agent",
+    "ai",
+    "cli",
+    "deploy"
+  ],
   "homepage": "https://vatio.ai",
   "bugs": "https://docs.vatio.ai",
   "license": "SEE LICENSE IN LICENSE.txt",