npm - vellum-cli - Versions diffs - 0.3.3 → 0.3.5 - Mend

vellum-cli 0.3.3 → 0.3.5

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.

Files changed (3) hide show

package/README.md CHANGED Viewed

@@ -8,14 +8,16 @@ Vellum server.
 ```bash
 # one-off, no install
 npx vellum-cli push --help
+bunx vellum-cli push --help          # or with Bun
 # or install the `vellum` command globally
-npm i -g vellum-cli
+npm i -g vellum-cli                  # npm
+bun add -g vellum-cli                # Bun
 vellum push --help
 ```
-Requires Node 18+. The package is self-contained (`@vellum/core` is bundled in),
-so it has no runtime dependencies.
+Requires Node 18+ (or Bun). The package is self-contained (`@vellum/core` is
+bundled in), so it has no runtime dependencies.
 ## Authentication
@@ -39,11 +41,9 @@ 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`)         |
-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.
+The CLI always uses the stored `vellum login` token. Commands are scoped to
+the logged-in page owner; the CLI does not accept the shared server API key.
 ## Commands
@@ -55,7 +55,7 @@ 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
-stdin. Pass `--page-id <id>` to append a new version to an existing page.
+stdin. Pass `--page-id <PAGE_ID>` to append a new version to an existing page.
 ```bash
 # new page from a file
@@ -65,11 +65,19 @@ vellum push artifact.html
 echo '<!doctype html><h1>Hello</h1>' | vellum push
 # add a version to an existing page, print raw JSON
-vellum push artifact.html --page-id pg_123 --json
+vellum push artifact.html --page-id <PAGE_ID> --json
 ```
 On success it prints the new version number, the human view URL, and the raw
-URL. With `--json` it prints the server's `CreateVersionResponse` verbatim.
+URL. With `--json` it prints the server's `CreateVersionResponse` verbatim;
+that response's `id` is the version id. The page id is the `pg_...` value in
+the view URL (`/p/<PAGE_ID>`) or from `vellum list`.
+### `vellum list`
+List the artifacts owned by your logged-in identity. By default only live pages
+are shown; pass `--archived` for archived-only or `--all` for both (archived
+pages are marked `*`). `--json` prints the raw response.
 ### `vellum markup <page-id>`
@@ -79,15 +87,22 @@ the highlight. Without `--version`, the page's current version is used.
 ```bash
 # anchor a note to a passage
-vellum markup pg_123 --quote "Q3 dashboard" --body "tighten this headline"
+vellum markup <PAGE_ID> --quote "Q3 dashboard" --body "tighten this headline"
 # pipe the note in on stdin instead of --body
-echo "tighten this headline" | vellum markup pg_123 --quote "Q3 dashboard"
+echo "tighten this headline" | vellum markup <PAGE_ID> --quote "Q3 dashboard"
 ```
 The CLI checks the quote is anchorable before posting; pass `--force` to post
 anyway, or `--json` for the raw response.
+### `vellum archive <page-id>` / `vellum unarchive <page-id>`
+Archive hides a page from the gallery and makes it read-only; the bytes,
+versions, comments, and URLs stay intact, but new versions and comments are
+paused until you unarchive. Unarchive restores it to live. Page owner only.
+`--json` prints the raw response.
 ### `vellum whoami`
 Show the identity the CLI is authenticated as for a server.
@@ -96,6 +111,10 @@ Show the identity the CLI is authenticated as for a server.
 Revoke this machine's stored token server-side and forget it locally.
+### `vellum version`
+Print the installed CLI version.
 ## Development
 From the repo root, Bun runs the TypeScript source directly (no build):

package/dist/index.js CHANGED Viewed

@@ -15,13 +15,10 @@ 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 (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).`);
+  throw new ConfigError(`Not logged in to ${baseUrl}. Run \`vellum login\`.`);
 }
 function storePath() {
   const xdg = process.env.XDG_CONFIG_HOME;
@@ -111,7 +108,8 @@ class VellumClient {
     });
     if (!res.ok)
       await this.fail(res);
-    return await res.json();
+    const body = await res.json();
+    return { ...body, created: res.status === 201 };
   }
   async getPage(pageId) {
     const res = await this.fetchImpl(`${this.baseUrl}/v1/pages/${encodeURIComponent(pageId)}`, { headers: this.authHeaders() });
@@ -204,12 +202,11 @@ Usage:
   vellum ${verb} <page-id> [options]
 ${verb === "archive" ? `Archiving keeps the bytes, versions, comments, and URLs intact — new
-versions and comments are paused until you unarchive. Owner/admin only.` : `Unarchiving restores the page to the gallery and re-opens it for new
-versions and comments. Owner/admin only.`}
+versions and comments are paused until you unarchive. Page owner only.` : `Unarchiving restores the page to the gallery and re-opens it for new
+versions and comments. Page owner only.`}
 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`;
 }
@@ -219,7 +216,6 @@ async function run(verb, argv) {
     allowPositionals: true,
     options: {
       url: { type: "string" },
-      "api-key": { type: "string" },
       json: { type: "boolean", default: false },
       help: { type: "boolean", short: "h", default: false }
     }
@@ -235,7 +231,7 @@ async function run(verb, argv) {
     console.error(help(verb));
     return 1;
   }
-  const flags = { url: values.url, apiKey: values["api-key"] };
+  const flags = { url: values.url };
   const baseUrl = resolveBaseUrl(flags);
   const credential = await resolveCredential(flags, baseUrl);
   const client2 = new VellumClient({ baseUrl, ...credential });
@@ -249,7 +245,11 @@ async function run(verb, argv) {
     return 0;
   } catch (err) {
     if (err instanceof VellumApiError && err.status === 401) {
-      console.error(`Error: ${verb} requires the owner API key. Set VELLUM_API_KEY or pass --api-key.`);
+      console.error(`Error: not logged in. Run \`vellum login\` as the page owner.`);
+      return 1;
+    }
+    if (err instanceof VellumApiError && err.status === 403) {
+      console.error(`Error: you don't own ${pageId}, so you can't ${verb} it.`);
       return 1;
     }
     if (err instanceof VellumApiError && err.status === 404) {
@@ -273,15 +273,13 @@ var HELP = `vellum list — list your artifacts
 Usage:
   vellum list [options]
-Lists the pages you own (log in with \`vellum login\`). With the owner API key
-(VELLUM_API_KEY / --api-key) it lists every page. By default only live pages are
-shown; use --archived for archived-only, or --all for both.
+Lists the pages you own (log in with \`vellum login\`). By default only live
+pages are shown; use --archived for archived-only, or --all for both.
 Options:
   --archived         Show only archived pages
   --all              Show both live and archived pages
   --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`;
 function cell(value, width) {
@@ -309,7 +307,6 @@ async function listCommand(argv) {
       archived: { type: "boolean", default: false },
       all: { type: "boolean", default: false },
       url: { type: "string" },
-      "api-key": { type: "string" },
       json: { type: "boolean", default: false },
       help: { type: "boolean", short: "h", default: false }
     }
@@ -318,7 +315,7 @@ async function listCommand(argv) {
     console.log(HELP);
     return 0;
   }
-  const flags = { url: values.url, apiKey: values["api-key"] };
+  const flags = { url: values.url };
   const baseUrl = resolveBaseUrl(flags);
   const credential = await resolveCredential(flags, baseUrl);
   const client2 = new VellumClient({ baseUrl, ...credential });
@@ -344,7 +341,7 @@ ${pages.length} page${pages.length === 1 ? "" : "s"}${suffix}`);
     return 0;
   } catch (err) {
     if (err instanceof VellumApiError && err.status === 401) {
-      console.error("Error: not authenticated. Run `vellum login` (or set VELLUM_API_KEY / pass --api-key).");
+      console.error("Error: not authenticated. Run `vellum login` as the page owner.");
       return 1;
     }
     throw err;
@@ -485,7 +482,6 @@ Options:
   --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() {
@@ -519,7 +515,6 @@ async function markupCommand(argv) {
       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 }
     }
@@ -553,7 +548,7 @@ async function markupCommand(argv) {
       return 1;
     }
   }
-  const flags = { url: values.url, apiKey: values["api-key"] };
+  const flags = { url: values.url };
   const baseUrl = resolveBaseUrl(flags);
   const credential = await resolveCredential(flags, baseUrl);
   const client2 = new VellumClient({ baseUrl, ...credential });
@@ -590,6 +585,10 @@ async function markupCommand(argv) {
 // src/commands/push.ts
 import { readFile as readFile2 } from "node:fs/promises";
 import { parseArgs as parseArgs6 } from "node:util";
+function formatPush(res) {
+  const head = res.created ? `✓ v${res.version_number} created` : `↺ identical to v${res.version_number} — no new version`;
+  return [head, `  view: ${res.view_url}`, `  raw:  ${res.raw_url}`];
+}
 var HELP5 = `vellum push — create a Vellum artifact from HTML
 Usage:
@@ -599,7 +598,6 @@ Usage:
 Options:
   --page-id <id>     Append a new version to an existing page
   --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 readStdin2() {
@@ -615,7 +613,6 @@ async function pushCommand(argv) {
     options: {
       "page-id": { type: "string" },
       url: { type: "string" },
-      "api-key": { type: "string" },
       json: { type: "boolean", default: false },
       help: { type: "boolean", short: "h", default: false }
     }
@@ -630,7 +627,7 @@ async function pushCommand(argv) {
     console.error("Error: no HTML provided (empty file or stdin).");
     return 1;
   }
-  const flags = { url: values.url, apiKey: values["api-key"] };
+  const flags = { url: values.url };
   const baseUrl = resolveBaseUrl(flags);
   const credential = await resolveCredential(flags, baseUrl);
   const client2 = new VellumClient({ baseUrl, ...credential });
@@ -638,16 +635,15 @@ async function pushCommand(argv) {
   if (values.json) {
     console.log(JSON.stringify(res, null, 2));
   } else {
-    console.log(`✓ v${res.version_number} created`);
-    console.log(`  view: ${res.view_url}`);
-    console.log(`  raw:  ${res.raw_url}`);
+    for (const line of formatPush(res))
+      console.log(line);
   }
   return 0;
 }
 // package.json
 var package_default = {
   name: "vellum-cli",
-  version: "0.3.3",
+  version: "0.3.5",
   description: "The vellum CLI — publish agent-authored HTML artifacts to a Vellum server.",
   type: "module",
   license: "MIT",
@@ -701,14 +697,12 @@ Usage:
 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 } = parseArgs7({
     args: argv,
     options: {
       url: { type: "string" },
-      "api-key": { type: "string" },
       help: { type: "boolean", short: "h", default: false }
     }
   });
@@ -717,11 +711,7 @@ async function whoamiCommand(argv) {
     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 credential = await resolveCredential({ url: values.url }, baseUrl);
   const client2 = new VellumClient({ baseUrl, token: credential.token });
   const { email } = await client2.whoami();
   console.log(`${email ?? "(no email on record)"} — ${baseUrl}`);
@@ -739,7 +729,7 @@ Commands:
   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)
-  list      List your artifacts (owner/admin only)
+  list      List artifacts owned by your logged-in identity
   markup    Pin a comment to a passage of a document
   archive   Archive a page (read-only, hidden from the gallery)
   unarchive Restore an archived page to live

package/package.json CHANGED Viewed

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