vellum-cli 0.1.0 → 0.3.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/comments.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,506 @@ 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 getPage(pageId) {
+    const res = await this.fetchImpl(`${this.baseUrl}/v1/pages/${encodeURIComponent(pageId)}`, { headers: this.authHeaders() });
+    if (!res.ok)
+      await this.fail(res);
+    return await res.json();
+  }
+  async createComment(pageId, opts) {
+    const res = await this.fetchImpl(`${this.baseUrl}/v1/pages/${encodeURIComponent(pageId)}/comments`, {
+      method: "POST",
+      headers: { "Content-Type": "application/json", ...this.authHeaders() },
+      body: JSON.stringify({
+        version_id: opts.versionId,
+        body: opts.body,
+        anchor: opts.anchor,
+        parent_id: opts.parentId
+      })
+    });
+    if (!res.ok)
+      await this.fail(res);
+    return await res.json();
+  }
+  async listComments(pageId, opts = {}) {
+    const url = new URL(`${this.baseUrl}/v1/pages/${encodeURIComponent(pageId)}/comments`);
+    if (opts.versionId)
+      url.searchParams.set("version_id", opts.versionId);
+    const res = await this.fetchImpl(url, { headers: this.authHeaders() });
+    if (!res.ok)
+      await this.fail(res);
+    return await res.json();
+  }
+  async resolveComment(commentId) {
+    const res = await this.fetchImpl(`${this.baseUrl}/v1/comments/${encodeURIComponent(commentId)}/resolve`, { method: "POST", headers: this.authHeaders() });
+    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/commands/comments.ts
+var HELP = `vellum comments — list the comments on a document
+
+Usage:
+  vellum comments <page-id> [options]
+
+Reads are public, so no login is required. Comments print as threads; replies
+are indented under their parent.
+
+Options:
+  --open             Show only unresolved threads
+  --version <id>     Only comments anchored to this version id
+  --url <url>        Server base URL          (env: VELLUM_URL)
+  --json             Print the raw JSON response
+  -h, --help         Show this help`;
+var truncate = (s, n) => s.length > n ? `${s.slice(0, n - 1)}…` : s;
+var oneLine = (s) => s.replace(/\s+/g, " ").trim();
+function printComment(c, indent) {
+  const who = c.author_email ?? c.author_name ?? "(unknown)";
+  const state = c.resolved ? "resolved" : "open";
+  console.log(`${indent}${c.id}  [${state}]  ${who}`);
+  if (c.anchor?.exact) {
+    console.log(`${indent}  on “${truncate(oneLine(c.anchor.exact), 70)}”`);
+  }
+  console.log(`${indent}  ${truncate(oneLine(c.body), 100)}`);
+  for (const reply of c.replies ?? []) {
+    printComment(reply, `${indent}    `);
+  }
+}
+async function commentsCommand(argv) {
+  const { values, positionals } = parseArgs({
+    args: argv,
+    allowPositionals: true,
+    options: {
+      open: { type: "boolean", default: false },
+      version: { type: "string" },
+      url: { type: "string" },
+      json: { type: "boolean", default: false },
+      help: { type: "boolean", short: "h", default: false }
+    }
+  });
+  if (values.help) {
+    console.log(HELP);
+    return 0;
+  }
+  const pageId = positionals[0];
+  if (!pageId) {
+    console.error(`Error: missing <page-id>.
+`);
+    console.error(HELP);
+    return 1;
+  }
+  const baseUrl = resolveBaseUrl({ url: values.url });
+  const client2 = new VellumClient({ baseUrl });
+  let comments = await client2.listComments(pageId, {
+    versionId: values.version
+  });
+  if (values.open)
+    comments = comments.filter((c) => !c.resolved);
+  if (values.json) {
+    console.log(JSON.stringify(comments, null, 2));
+    return 0;
+  }
+  if (comments.length === 0) {
+    console.log(values.open ? "No open comments." : "No comments.");
+    return 0;
+  }
+  for (const c of comments)
+    printComment(c, "");
+  return 0;
+}
+
+// src/commands/get.ts
+import { parseArgs as parseArgs2 } from "node:util";
+var HELP2 = `vellum get — print a document's raw HTML
+
+Usage:
+  vellum get <page-id> [options]
+
+Reads are public, so no login is required. Without --version, the page's
+current version is printed.
+
+Options:
+  --version <n>      Print a specific version number (default: current)
+  --url <url>        Server base URL          (env: VELLUM_URL)
+  -h, --help         Show this help`;
+function resolveVersion(page, requested) {
+  if (requested != null) {
+    return page.versions.find((v) => v.version_number === requested) ?? null;
+  }
+  const current = page.current_version_id ? page.versions.find((v) => v.id === page.current_version_id) : undefined;
+  return current ?? page.versions[page.versions.length - 1] ?? null;
 }
+async function getCommand(argv) {
+  const { values, positionals } = parseArgs2({
+    args: argv,
+    allowPositionals: true,
+    options: {
+      version: { type: "string" },
+      url: { type: "string" },
+      help: { type: "boolean", short: "h", default: false }
+    }
+  });
+  if (values.help) {
+    console.log(HELP2);
+    return 0;
+  }
+  const pageId = positionals[0];
+  if (!pageId) {
+    console.error(`Error: missing <page-id>.
+`);
+    console.error(HELP2);
+    return 1;
+  }
+  let version;
+  if (values.version != null) {
+    version = Number.parseInt(values.version, 10);
+    if (!Number.isInteger(version) || version < 1) {
+      console.error("Error: --version must be a positive integer.");
+      return 1;
+    }
+  }
+  const baseUrl = resolveBaseUrl({ url: values.url });
+  const client2 = new VellumClient({ baseUrl });
+  const page = await client2.getPage(pageId);
+  const target = resolveVersion(page, version);
+  if (!target) {
+    console.error(version != null ? `Error: page has no version ${version}.` : "Error: page has no versions.");
+    return 1;
+  }
+  const res = await fetch(target.raw_url);
+  if (!res.ok) {
+    console.error(`Error: could not fetch raw HTML (${res.status}).`);
+    return 1;
+  }
+  process.stdout.write(await res.text());
+  return 0;
+}
+
+// src/commands/login.ts
+import { parseArgs as parseArgs3 } from "node:util";
+
+// 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 HELP3 = `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 } = parseArgs3({
+    args: argv,
+    options: {
+      url: { type: "string" },
+      "no-browser": { type: "boolean", default: false },
+      help: { type: "boolean", short: "h", default: false }
+    }
+  });
+  if (values.help) {
+    console.log(HELP3);
+    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 parseArgs4 } from "node:util";
+var HELP4 = `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 } = parseArgs4({
+    args: argv,
+    options: {
+      url: { type: "string" },
+      help: { type: "boolean", short: "h", default: false }
+    }
+  });
+  if (values.help) {
+    console.log(HELP4);
+    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/markup.ts
+import { parseArgs as parseArgs5 } from "node:util";
+var HELP5 = `vellum markup — pin a comment to a passage of a document
+
+Usage:
+  vellum markup <page-id> --quote "<text>" --body "<note>" [options]
+  echo "<note>" | vellum markup <page-id> --quote "<text>"
+
+The --quote text must appear verbatim in the document; the viewer highlights it
+and links the highlight to your note. Without --version, the page's current
+version is used.
+
+Options:
+  --quote <text>     Passage to mark up (must match the document text)
+  --body <note>      Your note (or pipe it via stdin)
+  --version <n>      Pin to a specific version number (default: current)
+  --force            Post even if the quote isn't found in the version
+  --url <url>        Server base URL          (env: VELLUM_URL)
+  --api-key <key>    Shared API key           (env: VELLUM_API_KEY)
+  --json             Print the raw JSON response
+  -h, --help         Show this help`;
+async function readStdin() {
+  const chunks = [];
+  for await (const chunk of process.stdin)
+    chunks.push(chunk);
+  return Buffer.concat(chunks).toString("utf8");
+}
+function resolveVersion2(page, requested) {
+  if (requested != null) {
+    return page.versions.find((v) => v.version_number === requested) ?? null;
+  }
+  const current = page.current_version_id ? page.versions.find((v) => v.id === page.current_version_id) : undefined;
+  return current ?? page.versions[page.versions.length - 1] ?? null;
+}
+function extractText(html) {
+  return html.replace(/<script\b[^>]*>[\s\S]*?<\/script>/gi, "").replace(/<style\b[^>]*>[\s\S]*?<\/style>/gi, "").replace(/<[^>]+>/g, "").replace(/&nbsp;/g, " ").replace(/&amp;/g, "&").replace(/&lt;/g, "<").replace(/&gt;/g, ">").replace(/&quot;/g, '"').replace(/&#39;/g, "'");
+}
+var collapse = (s) => s.replace(/\s+/g, " ").trim();
+function quoteIsAnchorable(html, quote) {
+  const text = extractText(html);
+  return text.includes(quote) || collapse(text).includes(collapse(quote));
+}
+async function markupCommand(argv) {
+  const { values, positionals } = parseArgs5({
+    args: argv,
+    allowPositionals: true,
+    options: {
+      quote: { type: "string" },
+      body: { type: "string" },
+      version: { type: "string" },
+      force: { type: "boolean", default: false },
+      url: { type: "string" },
+      "api-key": { type: "string" },
+      json: { type: "boolean", default: false },
+      help: { type: "boolean", short: "h", default: false }
+    }
+  });
+  if (values.help) {
+    console.log(HELP5);
+    return 0;
+  }
+  const pageId = positionals[0];
+  if (!pageId) {
+    console.error(`Error: missing <page-id>.
+`);
+    console.error(HELP5);
+    return 1;
+  }
+  const quote = (values.quote ?? "").trim();
+  if (!quote) {
+    console.error("Error: --quote is required (the passage to mark up).");
+    return 1;
+  }
+  const body = (values.body ?? await readStdin()).trim();
+  if (!body) {
+    console.error("Error: no note provided (pass --body or pipe it via stdin).");
+    return 1;
+  }
+  let version;
+  if (values.version != null) {
+    version = Number.parseInt(values.version, 10);
+    if (!Number.isInteger(version) || version < 1) {
+      console.error("Error: --version must be a positive integer.");
+      return 1;
+    }
+  }
+  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 page = await client2.getPage(pageId);
+  const target = resolveVersion2(page, version);
+  if (!target) {
+    console.error(version != null ? `Error: page has no version ${version}.` : "Error: page has no versions to mark up.");
+    return 1;
+  }
+  if (!values.force) {
+    const html = await fetch(target.raw_url).then((r) => r.ok ? r.text() : "");
+    if (!quoteIsAnchorable(html, quote)) {
+      console.error(`Error: --quote was not found in v${target.version_number}; the highlight
+` + "       would not appear. Check the wording, or pass --force to post anyway.");
+      return 1;
+    }
+  }
+  const anchor = { type: "text-quote", exact: quote };
+  const comment = await client2.createComment(pageId, {
+    versionId: target.id,
+    body,
+    anchor
+  });
+  if (values.json) {
+    console.log(JSON.stringify(comment, null, 2));
+  } else {
+    console.log("✓ markup added");
+    console.log(`  on:   “${quote.length > 80 ? `${quote.slice(0, 79)}…` : quote}”`);
+    console.log(`  view: ${page.view_url}`);
+  }
+  return 0;
+}
+
+// src/commands/open.ts
+import { parseArgs as parseArgs6 } from "node:util";
+var HELP6 = `vellum open — print (and open) a document's view URL
+
+Usage:
+  vellum open <page-id> [options]
+
+Options:
+  --no-browser       Just print the URL; don't open the browser
+  --url <url>        Server base URL          (env: VELLUM_URL)
+  -h, --help         Show this help`;
+async function openCommand(argv) {
+  const { values, positionals } = parseArgs6({
+    args: argv,
+    allowPositionals: true,
+    options: {
+      "no-browser": { type: "boolean", default: false },
+      url: { type: "string" },
+      help: { type: "boolean", short: "h", default: false }
+    }
+  });
+  if (values.help) {
+    console.log(HELP6);
+    return 0;
+  }
+  const pageId = positionals[0];
+  if (!pageId) {
+    console.error(`Error: missing <page-id>.
+`);
+    console.error(HELP6);
+    return 1;
+  }
+  const baseUrl = resolveBaseUrl({ url: values.url });
+  const page = await new VellumClient({ baseUrl }).getPage(pageId);
+  console.log(page.view_url);
+  if (!values["no-browser"])
+    openBrowser(page.view_url);
+  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 parseArgs7 } from "node:util";
+var HELP7 = `vellum push — create a Vellum artifact from HTML
 
 Usage:
   vellum push <file.html> [options]
@@ -71,14 +616,14 @@ Options:
   --api-key <key>    Shared API key           (env: VELLUM_API_KEY)
   --json             Print the raw JSON response
   -h, --help         Show this help`;
-async function readStdin() {
+async function readStdin2() {
   const chunks = [];
   for await (const chunk of process.stdin)
     chunks.push(chunk);
   return Buffer.concat(chunks).toString("utf8");
 }
 async function pushCommand(argv) {
-  const { values, positionals } = parseArgs({
+  const { values, positionals } = parseArgs7({
     args: argv,
     allowPositionals: true,
     options: {
@@ -90,20 +635,19 @@ async function pushCommand(argv) {
     }
   });
   if (values.help) {
-    console.log(HELP);
+    console.log(HELP7);
     return 0;
   }
   const file = positionals[0];
-  const html = file ? await readFile(file, "utf8") : await readStdin();
+  const html = file ? await readFile2(file, "utf8") : await readStdin2();
   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 +659,218 @@ async function pushCommand(argv) {
   return 0;
 }
 
+// src/commands/reply.ts
+import { parseArgs as parseArgs8 } from "node:util";
+var HELP8 = `vellum reply — reply to a comment thread
+
+Usage:
+  vellum reply <page-id> <comment-id> --body "<note>"
+  echo "<note>" | vellum reply <page-id> <comment-id>
+
+The reply is threaded under <comment-id> and inherits the parent's version.
+Run \`vellum comments <page-id>\` to find the page and comment ids.
+
+Options:
+  --body <note>      Your reply (or pipe it via stdin)
+  --url <url>        Server base URL          (env: VELLUM_URL)
+  --api-key <key>    Shared API key           (env: VELLUM_API_KEY)
+  --json             Print the raw JSON response
+  -h, --help         Show this help`;
+async function readStdin3() {
+  const chunks = [];
+  for await (const chunk of process.stdin)
+    chunks.push(chunk);
+  return Buffer.concat(chunks).toString("utf8");
+}
+function flatten(comments) {
+  const out = [];
+  const walk = (c) => {
+    out.push(c);
+    for (const reply of c.replies ?? [])
+      walk(reply);
+  };
+  for (const c of comments)
+    walk(c);
+  return out;
+}
+async function replyCommand(argv) {
+  const { values, positionals } = parseArgs8({
+    args: argv,
+    allowPositionals: true,
+    options: {
+      body: { type: "string" },
+      url: { type: "string" },
+      "api-key": { type: "string" },
+      json: { type: "boolean", default: false },
+      help: { type: "boolean", short: "h", default: false }
+    }
+  });
+  if (values.help) {
+    console.log(HELP8);
+    return 0;
+  }
+  const [pageId, commentId] = positionals;
+  if (!pageId || !commentId) {
+    console.error("Error: usage is `vellum reply <page-id> <comment-id>`.\n");
+    console.error(HELP8);
+    return 1;
+  }
+  const body = (values.body ?? await readStdin3()).trim();
+  if (!body) {
+    console.error("Error: no note provided (pass --body or pipe it via stdin).");
+    return 1;
+  }
+  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 parent = flatten(await client2.listComments(pageId)).find((c) => c.id === commentId);
+  if (!parent) {
+    console.error(`Error: no comment ${commentId} on page ${pageId}.`);
+    return 1;
+  }
+  if (!parent.version_id) {
+    console.error("Error: parent comment has no version to reply on.");
+    return 1;
+  }
+  const reply = await client2.createComment(pageId, {
+    versionId: parent.version_id,
+    body,
+    parentId: commentId
+  });
+  if (values.json) {
+    console.log(JSON.stringify(reply, null, 2));
+  } else {
+    console.log(`✓ replied to ${commentId}`);
+  }
+  return 0;
+}
+
+// src/commands/resolve.ts
+import { parseArgs as parseArgs9 } from "node:util";
+var HELP9 = `vellum resolve — mark a comment as resolved
+
+Usage:
+  vellum resolve <comment-id> [options]
+
+Options:
+  --url <url>        Server base URL          (env: VELLUM_URL)
+  --api-key <key>    Shared API key           (env: VELLUM_API_KEY)
+  --json             Print the raw JSON response
+  -h, --help         Show this help`;
+async function resolveCommand(argv) {
+  const { values, positionals } = parseArgs9({
+    args: argv,
+    allowPositionals: true,
+    options: {
+      url: { type: "string" },
+      "api-key": { type: "string" },
+      json: { type: "boolean", default: false },
+      help: { type: "boolean", short: "h", default: false }
+    }
+  });
+  if (values.help) {
+    console.log(HELP9);
+    return 0;
+  }
+  const commentId = positionals[0];
+  if (!commentId) {
+    console.error(`Error: missing <comment-id>.
+`);
+    console.error(HELP9);
+    return 1;
+  }
+  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 comment = await client2.resolveComment(commentId);
+  if (values.json) {
+    console.log(JSON.stringify(comment, null, 2));
+  } else {
+    console.log(`✓ resolved ${comment.id}`);
+  }
+  return 0;
+}
+
+// src/commands/whoami.ts
+import { parseArgs as parseArgs10 } from "node:util";
+var HELP10 = `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 } = parseArgs10({
+    args: argv,
+    options: {
+      url: { type: "string" },
+      "api-key": { type: "string" },
+      help: { type: "boolean", short: "h", default: false }
+    }
+  });
+  if (values.help) {
+    console.log(HELP10);
+    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 HELP11 = `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)
+  get       Print a document's raw HTML
+  open      Print (and open) a document's view URL
+  markup    Pin a comment to a passage of a document
+  comments  List the comments on a document
+  reply     Reply to a comment thread
+  resolve   Mark a comment as resolved
 
 Run 'vellum <command> --help' for command-specific options.`;
 var commands = {
-  push: pushCommand
+  login: loginCommand,
+  logout: logoutCommand,
+  whoami: whoamiCommand,
+  push: pushCommand,
+  get: getCommand,
+  open: openCommand,
+  markup: markupCommand,
+  comments: commentsCommand,
+  reply: replyCommand,
+  resolve: resolveCommand
 };
 async function main() {
   const [, , cmd, ...rest] = process.argv;
   if (!cmd || cmd === "-h" || cmd === "--help" || cmd === "help") {
-    console.log(HELP2);
+    console.log(HELP11);
     return cmd ? 0 : 1;
   }
   const handler = commands[cmd];
   if (!handler) {
     console.error(`Unknown command: ${cmd}
 `);
-    console.error(HELP2);
+    console.error(HELP11);
     return 1;
   }
   return handler(rest);

package/package.json

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