vellum-cli 0.1.0 → 0.2.0

package/README.md

@@ -17,17 +17,41 @@ vellum push --help
 Requires Node 18+. The package is self-contained (`@vellum/core` is bundled in),
 so it has no runtime dependencies.
 
+## Authentication
+
+The normal path is `vellum login`, which signs you in through your browser and
+stores a per-user token under `~/.config/vellum/config.json`
+(`$XDG_CONFIG_HOME` is honored). After that, commands authenticate as you with
+no further setup.
+
+```bash
+vellum login            # opens the browser, approve, done
+vellum whoami           # who am I logged in as?
+vellum logout           # revoke + forget this machine's token
+```
+
 ## Configuration
 
-Connection settings come from flags, falling back to env vars:
+`--url` defaults to the hosted instance (`https://vellumai.app`); override it
+for self-hosted servers. Connection settings come from flags, falling back to
+env vars:
+
+| Flag         | Env var          | Description                                  |
+| ------------ | ---------------- | -------------------------------------------- |
+| `--url`      | `VELLUM_URL`     | Server base URL (default `https://vellumai.app`) |
+| `--api-key`  | `VELLUM_API_KEY` | Shared owner/agent key (`X-Api-Key`)         |
 
-| Flag         | Env var          | Description                  |
-| ------------ | ---------------- | ---------------------------- |
-| `--url`      | `VELLUM_URL`     | Server base URL              |
-| `--api-key`  | `VELLUM_API_KEY` | Shared API key (`X-Api-Key`) |
+Credential precedence for a write: an explicit `--api-key`/`VELLUM_API_KEY`
+(the shared owner key, e.g. for agents/CI) wins; otherwise the stored
+`vellum login` token is used.
 
 ## Commands
 
+### `vellum login`
+
+Authenticate this machine. Opens the browser to approve, polls until you do,
+then stores the token. `--no-browser` just prints the URL to open manually.
+
 ### `vellum push [file]`
 
 Create an artifact from HTML. Reads from `<file>` if given, otherwise from

package/dist/index.js

@@ -1,22 +1,67 @@
 #!/usr/bin/env node
 
 // src/config.ts
+import { mkdir, readFile, writeFile } from "node:fs/promises";
+import { homedir } from "node:os";
+import { dirname, join } from "node:path";
+var DEFAULT_URL = "https://vellumai.app";
+
 class ConfigError extends Error {
 }
-function resolveConfig(flags) {
-  const baseUrl = flags.url ?? process.env.VELLUM_URL;
+function normalizeUrl(url) {
+  return url.replace(/\/+$/, "");
+}
+function resolveBaseUrl(flags) {
+  return normalizeUrl(flags.url ?? process.env.VELLUM_URL ?? DEFAULT_URL);
+}
+async function resolveCredential(flags, baseUrl) {
   const apiKey = flags.apiKey ?? process.env.VELLUM_API_KEY;
-  if (!baseUrl) {
-    throw new ConfigError("Missing server URL. Pass --url or set VELLUM_URL.");
-  }
-  if (!apiKey) {
-    throw new ConfigError("Missing API key. Pass --api-key or set VELLUM_API_KEY.");
+  if (apiKey)
+    return { apiKey };
+  const token = await loadToken(baseUrl);
+  if (token)
+    return { token };
+  throw new ConfigError(`Not logged in to ${baseUrl}. Run \`vellum login\` (or set VELLUM_API_KEY / pass --api-key).`);
+}
+function storePath() {
+  const xdg = process.env.XDG_CONFIG_HOME;
+  const base = xdg && xdg.trim().length > 0 ? xdg : join(homedir(), ".config");
+  return join(base, "vellum", "config.json");
+}
+async function readStore() {
+  try {
+    const raw = await readFile(storePath(), "utf8");
+    const parsed = JSON.parse(raw);
+    return { servers: parsed.servers ?? {} };
+  } catch {
+    return { servers: {} };
   }
-  return { baseUrl, apiKey };
+}
+async function writeStore(store) {
+  const path = storePath();
+  await mkdir(dirname(path), { recursive: true });
+  await writeFile(path, `${JSON.stringify(store, null, 2)}
+`, { mode: 384 });
+}
+async function loadToken(baseUrl) {
+  const store = await readStore();
+  return store.servers[normalizeUrl(baseUrl)]?.token;
+}
+async function saveToken(baseUrl, token, email) {
+  const store = await readStore();
+  store.servers[normalizeUrl(baseUrl)] = { token, email };
+  await writeStore(store);
+}
+async function clearToken(baseUrl) {
+  const store = await readStore();
+  const key = normalizeUrl(baseUrl);
+  const existing = store.servers[key]?.token;
+  delete store.servers[key];
+  await writeStore(store);
+  return existing;
 }
 
-// src/commands/push.ts
-import { readFile } from "node:fs/promises";
+// src/commands/login.ts
 import { parseArgs } from "node:util";
 // ../core/src/client.ts
 class VellumApiError extends Error {
@@ -33,12 +78,25 @@ class VellumApiError extends Error {
 class VellumClient {
   baseUrl;
   apiKey;
+  token;
   fetchImpl;
   constructor(opts) {
     this.baseUrl = opts.baseUrl.replace(/\/+$/, "");
     this.apiKey = opts.apiKey;
+    this.token = opts.token;
     this.fetchImpl = opts.fetch ?? globalThis.fetch;
   }
+  authHeaders() {
+    if (this.token)
+      return { Authorization: `Bearer ${this.token}` };
+    if (this.apiKey)
+      return { "X-Api-Key": this.apiKey };
+    return {};
+  }
+  async fail(res) {
+    const code = await res.clone().json().then((b) => b.error).catch(() => res.statusText);
+    throw new VellumApiError(res.status, code);
+  }
   async createPage(html, opts = {}) {
     const url = new URL(`${this.baseUrl}/v1/pages`);
     if (opts.pageId)
@@ -47,19 +105,168 @@ class VellumClient {
       method: "POST",
       headers: {
         "Content-Type": "text/html; charset=utf-8",
-        "X-Api-Key": this.apiKey
+        ...this.authHeaders()
       },
       body: html
     });
-    if (!res.ok) {
-      const code = await res.json().then((b) => b.error).catch(() => res.statusText);
-      throw new VellumApiError(res.status, code);
-    }
+    if (!res.ok)
+      await this.fail(res);
     return await res.json();
   }
+  async startCliAuth() {
+    const res = await this.fetchImpl(`${this.baseUrl}/v1/cli/auth/start`, {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: "{}"
+    });
+    if (!res.ok)
+      await this.fail(res);
+    return await res.json();
+  }
+  async pollCliAuth(deviceCode) {
+    const res = await this.fetchImpl(`${this.baseUrl}/v1/cli/auth/poll`, {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({ device_code: deviceCode })
+    });
+    if (!res.ok)
+      await this.fail(res);
+    return await res.json();
+  }
+  async whoami() {
+    const res = await this.fetchImpl(`${this.baseUrl}/v1/cli/whoami`, {
+      headers: this.authHeaders()
+    });
+    if (!res.ok)
+      await this.fail(res);
+    return await res.json();
+  }
+  async logout() {
+    const res = await this.fetchImpl(`${this.baseUrl}/v1/cli/auth/logout`, {
+      method: "POST",
+      headers: this.authHeaders()
+    });
+    if (!res.ok)
+      await this.fail(res);
+  }
+}
+// src/util/open.ts
+import { spawn } from "node:child_process";
+function openBrowser(url) {
+  const platform = process.platform;
+  const [cmd, args] = platform === "darwin" ? ["open", [url]] : platform === "win32" ? ["cmd", ["/c", "start", "", url]] : ["xdg-open", [url]];
+  try {
+    const child = spawn(cmd, args, {
+      stdio: "ignore",
+      detached: true
+    });
+    child.on("error", () => {});
+    child.unref();
+  } catch {}
+}
+
+// src/commands/login.ts
+var HELP = `vellum login — authenticate this machine to a Vellum server
+
+Opens your browser to approve a CLI login, then stores a token under
+~/.config/vellum/config.json so future commands authenticate as you.
+
+Usage:
+  vellum login [options]
+
+Options:
+  --url <url>        Server base URL          (env: VELLUM_URL)
+  --no-browser       Don't auto-open the browser; just print the URL
+  -h, --help         Show this help`;
+var sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+async function loginCommand(argv) {
+  const { values } = parseArgs({
+    args: argv,
+    options: {
+      url: { type: "string" },
+      "no-browser": { type: "boolean", default: false },
+      help: { type: "boolean", short: "h", default: false }
+    }
+  });
+  if (values.help) {
+    console.log(HELP);
+    return 0;
+  }
+  const baseUrl = resolveBaseUrl({ url: values.url });
+  const client2 = new VellumClient({ baseUrl });
+  const start = await client2.startCliAuth();
+  console.log(`
+To authorize this CLI, visit:
+`);
+  console.log(`  ${start.verification_uri_complete}
+`);
+  console.log(`and confirm the code:  ${start.user_code}
+`);
+  if (!values["no-browser"]) {
+    openBrowser(start.verification_uri_complete);
+    console.log(`(Opening your browser…)
+`);
+  }
+  process.stdout.write("Waiting for approval");
+  const deadline = Date.now() + start.expires_in * 1000;
+  const intervalMs = Math.max(1, start.interval) * 1000;
+  while (Date.now() < deadline) {
+    await sleep(intervalMs);
+    process.stdout.write(".");
+    const res = await client2.pollCliAuth(start.device_code);
+    if (res.status === "complete") {
+      await saveToken(baseUrl, res.token, res.email);
+      console.log(`
+
+✓ Logged in to ${baseUrl}${res.email ? ` as ${res.email}` : ""}.`);
+      return 0;
+    }
+    if (res.status === "expired")
+      break;
+  }
+  console.error("\n\nError: login request expired. Run `vellum login` again.");
+  return 1;
+}
+
+// src/commands/logout.ts
+import { parseArgs as parseArgs2 } from "node:util";
+var HELP2 = `vellum logout — remove this machine's stored CLI token
+
+Usage:
+  vellum logout [options]
+
+Options:
+  --url <url>        Server base URL          (env: VELLUM_URL)
+  -h, --help         Show this help`;
+async function logoutCommand(argv) {
+  const { values } = parseArgs2({
+    args: argv,
+    options: {
+      url: { type: "string" },
+      help: { type: "boolean", short: "h", default: false }
+    }
+  });
+  if (values.help) {
+    console.log(HELP2);
+    return 0;
+  }
+  const baseUrl = resolveBaseUrl({ url: values.url });
+  const token = await clearToken(baseUrl);
+  if (!token) {
+    console.log(`Not logged in to ${baseUrl}.`);
+    return 0;
+  }
+  try {
+    await new VellumClient({ baseUrl, token }).logout();
+  } catch {}
+  console.log(`✓ Logged out of ${baseUrl}.`);
+  return 0;
 }
+
 // src/commands/push.ts
-var HELP = `vellum push — create a Vellum artifact from HTML
+import { readFile as readFile2 } from "node:fs/promises";
+import { parseArgs as parseArgs3 } from "node:util";
+var HELP3 = `vellum push — create a Vellum artifact from HTML
 
 Usage:
   vellum push <file.html> [options]
@@ -78,7 +285,7 @@ async function readStdin() {
   return Buffer.concat(chunks).toString("utf8");
 }
 async function pushCommand(argv) {
-  const { values, positionals } = parseArgs({
+  const { values, positionals } = parseArgs3({
     args: argv,
     allowPositionals: true,
     options: {
@@ -90,20 +297,19 @@ async function pushCommand(argv) {
     }
   });
   if (values.help) {
-    console.log(HELP);
+    console.log(HELP3);
     return 0;
   }
   const file = positionals[0];
-  const html = file ? await readFile(file, "utf8") : await readStdin();
+  const html = file ? await readFile2(file, "utf8") : await readStdin();
   if (!html.trim()) {
     console.error("Error: no HTML provided (empty file or stdin).");
     return 1;
   }
-  const { baseUrl, apiKey } = resolveConfig({
-    url: values.url,
-    apiKey: values["api-key"]
-  });
-  const client2 = new VellumClient({ baseUrl, apiKey });
+  const flags = { url: values.url, apiKey: values["api-key"] };
+  const baseUrl = resolveBaseUrl(flags);
+  const credential = await resolveCredential(flags, baseUrl);
+  const client2 = new VellumClient({ baseUrl, ...credential });
   const res = await client2.createPage(html, { pageId: values["page-id"] });
   if (values.json) {
     console.log(JSON.stringify(res, null, 2));
@@ -115,30 +321,72 @@ async function pushCommand(argv) {
   return 0;
 }
 
+// src/commands/whoami.ts
+import { parseArgs as parseArgs4 } from "node:util";
+var HELP4 = `vellum whoami — show the identity the CLI is authenticated as
+
+Usage:
+  vellum whoami [options]
+
+Options:
+  --url <url>        Server base URL          (env: VELLUM_URL)
+  --api-key <key>    Shared API key           (env: VELLUM_API_KEY)
+  -h, --help         Show this help`;
+async function whoamiCommand(argv) {
+  const { values } = parseArgs4({
+    args: argv,
+    options: {
+      url: { type: "string" },
+      "api-key": { type: "string" },
+      help: { type: "boolean", short: "h", default: false }
+    }
+  });
+  if (values.help) {
+    console.log(HELP4);
+    return 0;
+  }
+  const baseUrl = resolveBaseUrl({ url: values.url });
+  const credential = await resolveCredential({ url: values.url, apiKey: values["api-key"] }, baseUrl);
+  if ("apiKey" in credential) {
+    console.log(`Authenticated to ${baseUrl} with a shared API key (owner).`);
+    return 0;
+  }
+  const client2 = new VellumClient({ baseUrl, token: credential.token });
+  const { email } = await client2.whoami();
+  console.log(`${email ?? "(no email on record)"} — ${baseUrl}`);
+  return 0;
+}
+
 // src/index.ts
-var HELP2 = `vellum — CLI for the Vellum artifact store
+var HELP5 = `vellum — CLI for the Vellum artifact store
 
 Usage:
   vellum <command> [options]
 
 Commands:
+  login     Authenticate this machine (opens your browser)
+  logout    Remove this machine's stored CLI token
+  whoami    Show the identity the CLI is authenticated as
   push      Create an artifact (page) from HTML (file or stdin)
 
 Run 'vellum <command> --help' for command-specific options.`;
 var commands = {
+  login: loginCommand,
+  logout: logoutCommand,
+  whoami: whoamiCommand,
   push: pushCommand
 };
 async function main() {
   const [, , cmd, ...rest] = process.argv;
   if (!cmd || cmd === "-h" || cmd === "--help" || cmd === "help") {
-    console.log(HELP2);
+    console.log(HELP5);
     return cmd ? 0 : 1;
   }
   const handler = commands[cmd];
   if (!handler) {
     console.error(`Unknown command: ${cmd}
 `);
-    console.error(HELP2);
+    console.error(HELP5);
     return 1;
   }
   return handler(rest);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "vellum-cli",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "The vellum CLI — publish agent-authored HTML artifacts to a Vellum server.",
   "type": "module",
   "license": "MIT",