peakurl 0.1.0 → 0.1.2

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 PeakURL Command-Line Interface and Abd Ur Rehman
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE 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. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,12 +1,14 @@
-# PeakURL CLI
+# PeakURL - Command-Line Interface
 
-`peakurl` is the official command-line interface for PeakURL.
+The official command-line interface for PeakURL.
 
-It gives you a fast way to create, inspect, list, and remove short links from the terminal while keeping default output readable for humans and optional `--json` output friendly for scripts.
+Use `peakurl` to create short links, inspect existing links, and manage your PeakURL account from the terminal.
+
+Learn more in the full CLI docs: <https://peakurl.org/docs/cli>
 
 ## Install
 
-Requirements: Node.js 20 or later.
+Node.js 20 or later is required.
 
 ```bash
 npm install -g peakurl
@@ -14,22 +16,35 @@ npm install -g peakurl
 
 ## Quick Start
 
+Sign in with your PeakURL API key:
+
+```bash
+peakurl login \
+    --base-url https://peakurl.org \
+    --api-key 0123456789abcdef0123456789abcdef0123456789abcdef
+```
+
+Create and review a short link:
+
 ```bash
-peakurl login --base-url https://peakurl.org --api-key 0123456789abcdef0123456789abcdef0123456789abcdef
-peakurl create https://example.com/articles/launch --alias launch --title "Launch Post"
+peakurl create \
+    https://example.com/articles/launch \
+    --alias launch \
+    --title "Launch Post"
+
 peakurl list
 peakurl whoami
 ```
 
 ## Authentication
 
-The CLI uses PeakURL bearer API keys and validates them with `GET /api/v1/users/me` before storing them.
+The CLI uses PeakURL bearer API keys and validates them against `GET /api/v1/users/me` before saving credentials.
 
-- `--base-url` accepts either the site root such as `https://peakurl.org` or the API base URL such as `https://peakurl.org/api/v1`
+- `--base-url` accepts either the site root, such as `https://peakurl.org`, or the API base URL, such as `https://peakurl.org/api/v1`
 - API keys are opaque 48-character hex tokens
-- credentials are stored in the standard per-user config location for `peakurl`
+- Credentials are stored in the standard per-user config location for `peakurl`
 
-For CI and automation, you can also use environment variables:
+For CI or automation, you can also authenticate with environment variables:
 
 ```bash
 export PEAKURL_BASE_URL=https://peakurl.org
@@ -38,32 +53,33 @@ export PEAKURL_API_KEY=0123456789abcdef0123456789abcdef0123456789abcdef
 
 ## Commands
 
-| Command                        | Description                                 |
-| ------------------------------ | ------------------------------------------- |
-| `peakurl login`                | Validate and save your PeakURL credentials. |
-| `peakurl whoami`               | Show the current authenticated account.     |
-| `peakurl create <url>`         | Create a new short link.                    |
-| `peakurl list`                 | List links in your account.                 |
-| `peakurl get <id-or-alias>`    | Fetch a single link by ID or alias.         |
-| `peakurl delete <id-or-alias>` | Delete a link by ID or alias.               |
-
-## Common Flags
-
-- `--json` prints machine-readable JSON output
-- `--quiet` minimizes output for scripts
+| Command                        | Description                                                |
+| ------------------------------ | ---------------------------------------------------------- |
+| `peakurl login`                | Validate and save your PeakURL credentials.                |
+| `peakurl whoami`               | Show the current authenticated account.                    |
+| `peakurl create <url>`         | Create a new short link.                                   |
+| `peakurl list`                 | List links in your account.                                |
+| `peakurl get <id-or-alias>`    | Fetch a single link by ID or alias.                        |
+| `peakurl delete <id-or-alias>` | Delete a link by ID or alias.                              |
+| `peakurl update`               | Show the latest available CLI version and install command. |
 
 ## Examples
 
 Create a short link:
 
 ```bash
-peakurl create https://example.com --alias example --title "Example"
+peakurl create \
+    https://example.com \
+    --alias example \
+    --title "Example"
 ```
 
 List links as JSON:
 
 ```bash
-peakurl list --limit 10 --json
+peakurl list \
+    --limit 10 \
+    --json
 ```
 
 Inspect a link:
@@ -80,9 +96,40 @@ peakurl delete example
 
 When `delete` receives an alias or short code, the CLI resolves it to the underlying PeakURL row ID before deleting it.
 
+Check the latest available CLI version:
+
+```bash
+peakurl update --check
+```
+
+Show the recommended install command:
+
+```bash
+peakurl update
+```
+
+Install the latest version manually:
+
+```bash
+npm install -g peakurl@latest
+```
+
+Disable update notices in the current shell:
+
+```bash
+export PEAKURL_DISABLE_UPDATE_CHECK=1
+```
+
+## Output
+
+- Human-readable output is the default
+- `--json` prints machine-readable JSON where supported
+- `--quiet` minimizes output for scripts
+
 ## Links
 
-- Website: https://peakurl.org/
-- API docs: https://peakurl.org/docs/api
-- npm package: https://www.npmjs.com/package/peakurl
-- Issues: https://github.com/PeakURL/PeakURL-CLI/issues
+- Website: <https://peakurl.org/>
+- CLI docs: <https://peakurl.org/docs/cli>
+- API docs: <https://peakurl.org/docs/api>
+- npm package: <https://www.npmjs.com/package/peakurl>
+- Issues: <https://github.com/PeakURL/PeakURL-CLI/issues>

package/bin/peakurl.js

@@ -13,7 +13,7 @@ var CliError = class extends Error {
     this.exitCode = exitCode;
   }
 };
-function toCliError(error) {
+function wrapCliError(error) {
   if (error instanceof CliError) {
     return error;
   }
@@ -24,6 +24,14 @@ function toCliError(error) {
 }
 
 // src/lib/url.ts
+function validateHttpUrl(parsed, label) {
+  if (parsed.protocol !== "http:" && parsed.protocol !== "https:") {
+    throw new CliError(`${label} must use http or https.`);
+  }
+  if (parsed.username || parsed.password) {
+    throw new CliError(`${label} must not include embedded credentials.`);
+  }
+}
 function normalizeBaseUrl(value) {
   const input = value.trim();
   if (!input) {
@@ -35,9 +43,7 @@ function normalizeBaseUrl(value) {
   } catch {
     throw new CliError(`Invalid base URL: ${value}`);
   }
-  if (parsed.protocol !== "http:" && parsed.protocol !== "https:") {
-    throw new CliError("PeakURL base URLs must use http or https.");
-  }
+  validateHttpUrl(parsed, "PeakURL base URL");
   parsed.hash = "";
   parsed.search = "";
   const pathname = parsed.pathname.replace(/\/+$/, "");
@@ -62,8 +68,13 @@ function normalizeDestinationUrl(value) {
     throw new CliError("A destination URL is required.");
   }
   try {
-    return new URL(input).toString();
-  } catch {
+    const parsed = new URL(input);
+    validateHttpUrl(parsed, "Destination URL");
+    return parsed.toString();
+  } catch (error) {
+    if (error instanceof CliError) {
+      throw error;
+    }
     throw new CliError(`Invalid destination URL: ${value}`);
   }
 }
@@ -234,9 +245,18 @@ import { chmod, mkdir, readFile, writeFile } from "fs/promises";
 import { dirname, join } from "path";
 import envPaths from "env-paths";
 var CONFIG_FILENAME = "config.json";
+var STATE_FILENAME = "state.json";
 function defaultConfigPath() {
   return join(envPaths("peakurl", { suffix: "" }).config, CONFIG_FILENAME);
 }
+function defaultStatePath() {
+  return join(envPaths("peakurl", { suffix: "" }).config, STATE_FILENAME);
+}
+async function prepareFileDirectory(filePath) {
+  const directory = dirname(filePath);
+  await mkdir(directory, { recursive: true, mode: 448 });
+  return directory;
+}
 var ConfigStore = class {
   filePath;
   /**
@@ -292,8 +312,7 @@ var ConfigStore = class {
    * @param config Normalized credential set to write.
    */
   async save(config) {
-    const directory = dirname(this.filePath);
-    await mkdir(directory, { recursive: true, mode: 448 });
+    const directory = await prepareFileDirectory(this.filePath);
     await writeFile(this.filePath, `${JSON.stringify(config, null, 2)}
 `, {
       mode: 384
@@ -305,6 +324,51 @@ var ConfigStore = class {
     }
   }
 };
+var StateStore = class {
+  filePath;
+  /**
+   * Creates a state store bound to one on-disk file.
+   *
+   * @param filePath Optional override used by tests or advanced callers.
+   */
+  constructor(filePath = defaultStatePath()) {
+    this.filePath = filePath;
+  }
+  /**
+   * Loads cached state from disk.
+   *
+   * Missing or invalid files are treated as empty state because the CLI can
+   * always recompute update metadata on the next successful network check.
+   *
+   * @returns Parsed state object or an empty object.
+   */
+  async load() {
+    try {
+      const content = await readFile(this.filePath, "utf8");
+      const parsed = JSON.parse(content);
+      return parsed && typeof parsed === "object" ? parsed : {};
+    } catch {
+      return {};
+    }
+  }
+  /**
+   * Persists cached state to disk.
+   *
+   * @param state State payload to save.
+   */
+  async save(state) {
+    const directory = await prepareFileDirectory(this.filePath);
+    await writeFile(this.filePath, `${JSON.stringify(state, null, 2)}
+`, {
+      mode: 384
+    });
+    try {
+      await chmod(directory, 448);
+      await chmod(this.filePath, 384);
+    } catch {
+    }
+  }
+};
 
 // src/lib/auth.ts
 function resolveLoginConfig(input, env) {
@@ -335,20 +399,126 @@ async function resolveStoredConfig(env, store = new ConfigStore()) {
   };
 }
 
+// src/lib/output.ts
+function writeStdout(message = "") {
+  process.stdout.write(`${message}
+`);
+}
+function writeStderr(message = "") {
+  process.stderr.write(`${message}
+`);
+}
+function writeNoticeBox(title, lines, target = "stderr") {
+  const contentLines = lines.length > 0 ? lines : [""];
+  const width = Math.max(
+    title.length,
+    ...contentLines.map((line) => line.length)
+  );
+  const stream = target === "stdout" ? process.stdout : process.stderr;
+  const useTuiBox = stream.isTTY;
+  const border = useTuiBox ? {
+    topLeft: "\u250C",
+    topRight: "\u2510",
+    bottomLeft: "\u2514",
+    bottomRight: "\u2518",
+    horizontal: "\u2500",
+    vertical: "\u2502",
+    separatorLeft: "\u251C",
+    separatorRight: "\u2524"
+  } : {
+    topLeft: "+",
+    topRight: "+",
+    bottomLeft: "+",
+    bottomRight: "+",
+    horizontal: "-",
+    vertical: "|",
+    separatorLeft: "+",
+    separatorRight: "+"
+  };
+  const topBorder = `${border.topLeft}${border.horizontal.repeat(width + 2)}${border.topRight}`;
+  const separator = `${border.separatorLeft}${border.horizontal.repeat(width + 2)}${border.separatorRight}`;
+  const bottomBorder = `${border.bottomLeft}${border.horizontal.repeat(width + 2)}${border.bottomRight}`;
+  const writeLine = target === "stdout" ? writeStdout : writeStderr;
+  writeLine(topBorder);
+  writeLine(`${border.vertical} ${title.padEnd(width)} ${border.vertical}`);
+  writeLine(separator);
+  for (const line of contentLines) {
+    writeLine(
+      `${border.vertical} ${line.padEnd(width)} ${border.vertical}`
+    );
+  }
+  writeLine(bottomBorder);
+}
+function formatTable(headers, rows, target = "stdout") {
+  const stream = target === "stdout" ? process.stdout : process.stderr;
+  const useTuiBox = stream.isTTY;
+  const border = useTuiBox ? {
+    topLeft: "\u250C",
+    topRight: "\u2510",
+    bottomLeft: "\u2514",
+    bottomRight: "\u2518",
+    horizontal: "\u2500",
+    vertical: "\u2502",
+    separatorLeft: "\u251C",
+    separatorRight: "\u2524",
+    topJunction: "\u252C",
+    middleJunction: "\u253C",
+    bottomJunction: "\u2534"
+  } : {
+    topLeft: "+",
+    topRight: "+",
+    bottomLeft: "+",
+    bottomRight: "+",
+    horizontal: "-",
+    vertical: "|",
+    separatorLeft: "+",
+    separatorRight: "+",
+    topJunction: "+",
+    middleJunction: "+",
+    bottomJunction: "+"
+  };
+  const widths = headers.map(
+    (header, index) => Math.max(
+      header.length,
+      ...rows.map((row) => (row[index] ?? "").length)
+    )
+  );
+  const formatTableBorder = (left, join2, right) => `${left}${widths.map((width) => border.horizontal.repeat(width + 2)).join(join2)}${right}`;
+  const formatTableRow = (cells) => `${border.vertical}${cells.map((cell, index) => ` ${(cell ?? "").padEnd(widths[index])} `).join(border.vertical)}${border.vertical}`;
+  return [
+    formatTableBorder(border.topLeft, border.topJunction, border.topRight),
+    formatTableRow(headers),
+    formatTableBorder(
+      border.separatorLeft,
+      border.middleJunction,
+      border.separatorRight
+    ),
+    ...rows.map(formatTableRow),
+    formatTableBorder(
+      border.bottomLeft,
+      border.bottomJunction,
+      border.bottomRight
+    )
+  ].join("\n");
+}
+function writeJson(value) {
+  writeStdout(JSON.stringify(value, null, 2));
+}
+
 // src/lib/links.ts
 var LIST_KEYS = ["urls", "items", "results"];
-function asRecord(value) {
+function objectValue(value) {
   return value && typeof value === "object" && !Array.isArray(value) ? value : null;
 }
-function readString(value) {
+function stringValue(value) {
   return typeof value === "string" && value.trim() ? value.trim() : void 0;
 }
-function readNumber(value) {
+function numberValue(value) {
   return typeof value === "number" && Number.isFinite(value) ? value : void 0;
 }
-function firstString(link, keys) {
+function pickString(link, keys) {
   for (const key of keys) {
-    const value = readString(link[key]);
+    const value = stringValue(link[key]);
     if (value) {
       return value;
     }
@@ -359,31 +529,31 @@ function truncate(value, maxLength) {
   return value.length > maxLength ? `${value.slice(0, maxLength - 1)}\u2026` : value;
 }
 function extractListMeta(data) {
-  const record = asRecord(data);
+  const record = objectValue(data);
   if (!record) {
     return null;
   }
-  const meta = asRecord(record.meta);
+  const meta = objectValue(record.meta);
   if (meta) {
     return {
-      page: readNumber(meta.page),
-      limit: readNumber(meta.limit),
-      totalItems: readNumber(meta.totalItems),
-      totalPages: readNumber(meta.totalPages)
+      page: numberValue(meta.page),
+      limit: numberValue(meta.limit),
+      totalItems: numberValue(meta.totalItems),
+      totalPages: numberValue(meta.totalPages)
     };
   }
   return {
-    page: readNumber(record.page),
-    limit: readNumber(record.limit),
-    totalItems: readNumber(record.total),
-    totalPages: readNumber(record.totalPages)
+    page: numberValue(record.page),
+    limit: numberValue(record.limit),
+    totalItems: numberValue(record.total),
+    totalPages: numberValue(record.totalPages)
   };
 }
 function extractLinks(data) {
   if (Array.isArray(data)) {
     return data;
   }
-  const record = asRecord(data);
+  const record = objectValue(data);
   if (record) {
     for (const key of LIST_KEYS) {
       const value = record[key];
@@ -395,16 +565,16 @@ function extractLinks(data) {
   return [];
 }
 function getLinkId(link) {
-  return firstString(link, ["id", "_id", "urlId"]) || (link.id !== void 0 ? String(link.id) : void 0);
+  return pickString(link, ["id", "_id", "urlId"]) || (link.id !== void 0 ? String(link.id) : void 0);
 }
 function getLinkAlias(link) {
-  return firstString(link, ["alias", "shortCode", "slug", "code"]);
+  return pickString(link, ["alias", "shortCode", "slug", "code"]);
 }
 function getLinkShortUrl(link) {
-  return firstString(link, ["shortUrl", "shortLink", "shortURL", "url"]);
+  return pickString(link, ["shortUrl", "shortLink", "shortURL", "url"]);
 }
 function getLinkDestination(link) {
-  return firstString(link, [
+  return pickString(link, [
     "destinationUrl",
     "originalUrl",
     "targetUrl",
@@ -420,14 +590,14 @@ function formatLinkDetails(link) {
     ["Alias", getLinkAlias(link)],
     ["Short URL", getLinkShortUrl(link)],
     ["Destination", getLinkDestination(link)],
-    ["Title", readString(link.title)],
-    ["Status", readString(link.status)],
+    ["Title", stringValue(link.title)],
+    ["Status", stringValue(link.status)],
     [
       "Clicks",
-      readNumber(link.clicks) === void 0 ? void 0 : String(link.clicks)
+      numberValue(link.clicks) === void 0 ? void 0 : String(link.clicks)
     ],
-    ["Created", readString(link.createdAt)],
-    ["Updated", readString(link.updatedAt)]
+    ["Created", stringValue(link.createdAt)],
+    ["Updated", stringValue(link.updatedAt)]
   ].filter((entry) => Boolean(entry[1]));
   return lines.map(([label, value]) => `${label}: ${value}`).join("\n");
 }
@@ -435,23 +605,15 @@ function formatLinksTable(links) {
   if (links.length === 0) {
     return "No links found.";
   }
-  const headers = ["ID", "ALIAS", "SHORT URL", "DESTINATION", "STATUS"];
+  const headers = ["ID", "Alias", "Short URL", "Destination", "Status"];
   const rows = links.map((link) => [
     truncate(getLinkId(link) || "-", 18),
-    truncate(getLinkAlias(link) || "-", 18),
+    truncate(getLinkAlias(link) || "-", 12),
     truncate(getLinkShortUrl(link) || "-", 36),
     truncate(getLinkDestination(link) || "-", 52),
-    truncate(readString(link.status) || "-", 12)
+    truncate(stringValue(link.status) || "-", 12)
   ]);
-  const widths = headers.map(
-    (header, index) => Math.max(header.length, ...rows.map((row) => row[index].length))
-  );
-  const renderRow = (row) => row.map((cell, index) => cell.padEnd(widths[index])).join("  ");
-  return [
-    renderRow(headers),
-    renderRow(widths.map((width) => "-".repeat(width))),
-    ...rows.map(renderRow)
-  ].join("\n");
+  return formatTable(headers, rows);
 }
 function formatListSummary(data, count) {
   const meta = extractListMeta(data);
@@ -467,19 +629,6 @@ function formatListSummary(data, count) {
   return `${count} link${count === 1 ? "" : "s"} returned.`;
 }
 
-// src/lib/output.ts
-function writeStdout(message = "") {
-  process.stdout.write(`${message}
-`);
-}
-function writeStderr(message = "") {
-  process.stderr.write(`${message}
-`);
-}
-function writeJson(value) {
-  writeStdout(JSON.stringify(value, null, 2));
-}
-
 // src/commands/create.ts
 function normalizeExpiresAt(value) {
   if (!value) {
@@ -585,22 +734,22 @@ async function listCommand(options) {
 }
 
 // src/lib/users.ts
-function readString2(value) {
+function stringValue2(value) {
   return typeof value === "string" && value.trim() ? value.trim() : void 0;
 }
 function getUserLabel(user) {
-  const fullName = [readString2(user.firstName), readString2(user.lastName)].filter(Boolean).join(" ");
-  return fullName || readString2(user.username) || readString2(user.email) || String(user.id ?? "unknown");
+  const fullName = [stringValue2(user.firstName), stringValue2(user.lastName)].filter(Boolean).join(" ");
+  return fullName || stringValue2(user.username) || stringValue2(user.email) || String(user.id ?? "unknown");
 }
 function getQuietUserValue(user) {
-  return readString2(user.username) || readString2(user.email) || String(user.id ?? "");
+  return stringValue2(user.username) || stringValue2(user.email) || String(user.id ?? "");
 }
 function formatUserDetails(user) {
   const lines = [
     ["Name", getUserLabel(user)],
-    ["Username", readString2(user.username)],
-    ["Email", readString2(user.email)],
-    ["Role", readString2(user.role)],
+    ["Username", stringValue2(user.username)],
+    ["Email", stringValue2(user.email)],
+    ["Role", stringValue2(user.role)],
     ["ID", user.id === void 0 ? void 0 : String(user.id)]
   ].filter((entry) => Boolean(entry[1]));
   return lines.map(([label, value]) => `${label}: ${value}`).join("\n");
@@ -612,7 +761,7 @@ async function loginCommand(options) {
   const client = new PeakUrlApiClient(credentials);
   const response = await client.whoami();
   await new ConfigStore().save(credentials);
-  const payload = {
+  const responseBody = {
     success: true,
     message: `Saved credentials for ${credentials.baseUrl}.`,
     data: {
@@ -622,7 +771,7 @@ async function loginCommand(options) {
     timestamp: response.timestamp
   };
   if (options.json) {
-    writeJson(payload);
+    writeJson(responseBody);
     return;
   }
   if (options.quiet) {
@@ -633,6 +782,256 @@ async function loginCommand(options) {
   writeStdout(formatUserDetails(response.data));
 }
 
+// src/lib/update.ts
+var PACKAGE_NAME = "peakurl";
+var DEFAULT_REGISTRY_URL = "https://registry.npmjs.org";
+var CACHE_TTL_MS = 1e3 * 60 * 60 * 12;
+var NOTICE_TTL_MS = 1e3 * 60 * 60 * 24;
+function parseTime(value) {
+  if (!value) {
+    return null;
+  }
+  const parsed = Date.parse(value);
+  return Number.isNaN(parsed) ? null : parsed;
+}
+function getRegistryBaseUrl(env) {
+  const candidate = env.PEAKURL_NPM_REGISTRY_URL?.trim();
+  if (!candidate) {
+    return DEFAULT_REGISTRY_URL;
+  }
+  try {
+    const parsed = new URL(candidate);
+    if (parsed.protocol !== "http:" && parsed.protocol !== "https:" || parsed.username || parsed.password) {
+      return DEFAULT_REGISTRY_URL;
+    }
+    return candidate;
+  } catch {
+    return DEFAULT_REGISTRY_URL;
+  }
+}
+function normalizeRegistryUrl(registryUrl) {
+  return registryUrl.replace(/\/+$/, "");
+}
+function parseSemver(version) {
+  const match = /^(\d+)\.(\d+)\.(\d+)(?:-([0-9A-Za-z.-]+))?(?:\+[0-9A-Za-z.-]+)?$/.exec(
+    version
+  );
+  if (!match) {
+    return null;
+  }
+  return {
+    major: Number.parseInt(match[1], 10),
+    minor: Number.parseInt(match[2], 10),
+    patch: Number.parseInt(match[3], 10),
+    prerelease: match[4] ? match[4].split(".") : []
+  };
+}
+function comparePrerelease(left, right) {
+  if (left.length === 0 && right.length === 0) {
+    return 0;
+  }
+  if (left.length === 0) {
+    return 1;
+  }
+  if (right.length === 0) {
+    return -1;
+  }
+  const length = Math.max(left.length, right.length);
+  for (let index = 0; index < length; index += 1) {
+    const leftPart = left[index];
+    const rightPart = right[index];
+    if (leftPart === void 0) {
+      return -1;
+    }
+    if (rightPart === void 0) {
+      return 1;
+    }
+    const leftNumber = /^\d+$/.test(leftPart) ? Number.parseInt(leftPart, 10) : null;
+    const rightNumber = /^\d+$/.test(rightPart) ? Number.parseInt(rightPart, 10) : null;
+    if (leftNumber !== null && rightNumber !== null) {
+      if (leftNumber !== rightNumber) {
+        return leftNumber > rightNumber ? 1 : -1;
+      }
+      continue;
+    }
+    if (leftNumber !== null) {
+      return -1;
+    }
+    if (rightNumber !== null) {
+      return 1;
+    }
+    if (leftPart !== rightPart) {
+      return leftPart > rightPart ? 1 : -1;
+    }
+  }
+  return 0;
+}
+function compareSemver(left, right) {
+  const parsedLeft = parseSemver(left);
+  const parsedRight = parseSemver(right);
+  if (!parsedLeft || !parsedRight) {
+    return left.localeCompare(right, void 0, { numeric: true });
+  }
+  if (parsedLeft.major !== parsedRight.major) {
+    return parsedLeft.major > parsedRight.major ? 1 : -1;
+  }
+  if (parsedLeft.minor !== parsedRight.minor) {
+    return parsedLeft.minor > parsedRight.minor ? 1 : -1;
+  }
+  if (parsedLeft.patch !== parsedRight.patch) {
+    return parsedLeft.patch > parsedRight.patch ? 1 : -1;
+  }
+  return comparePrerelease(parsedLeft.prerelease, parsedRight.prerelease);
+}
+function getUpdateInstallCommand() {
+  return `npm install -g ${PACKAGE_NAME}@latest`;
+}
+async function fetchLatestPackageVersion(env) {
+  const registryUrl = normalizeRegistryUrl(getRegistryBaseUrl(env));
+  const url = `${registryUrl}/${PACKAGE_NAME}/latest`;
+  const controller = new AbortController();
+  const timeout = setTimeout(() => controller.abort(), 2e3);
+  try {
+    const response = await fetch(url, {
+      headers: {
+        accept: "application/json"
+      },
+      signal: controller.signal
+    });
+    if (!response.ok) {
+      return null;
+    }
+    const payload = await response.json();
+    return typeof payload.version === "string" ? payload.version : null;
+  } catch {
+    return null;
+  } finally {
+    clearTimeout(timeout);
+  }
+}
+async function getCachedUpdateState(store) {
+  const state = await store.load();
+  return state.update ?? {};
+}
+async function saveUpdateState(store, update) {
+  const state = await store.load();
+  await store.save({
+    ...state,
+    update
+  });
+}
+async function getLatestPackageVersion(env, options) {
+  const store = options?.store ?? new StateStore();
+  const updateState = await getCachedUpdateState(store);
+  const lastCheckedAt = parseTime(updateState.lastCheckedAt);
+  const now = Date.now();
+  if (!options?.forceRefresh && updateState.latestVersion && lastCheckedAt !== null && now - lastCheckedAt < CACHE_TTL_MS) {
+    return updateState.latestVersion;
+  }
+  const latestVersion = await fetchLatestPackageVersion(env);
+  if (!latestVersion) {
+    return updateState.latestVersion ?? null;
+  }
+  await saveUpdateState(store, {
+    ...updateState,
+    latestVersion,
+    lastCheckedAt: new Date(now).toISOString()
+  });
+  return latestVersion;
+}
+async function getUpdateStatus(currentVersion, env, options) {
+  const resolvedLatestVersion = await getLatestPackageVersion(env, {
+    forceRefresh: options?.forceRefresh,
+    store: options?.store
+  });
+  if (!resolvedLatestVersion && options?.forceRefresh) {
+    throw new CliError(
+      `Could not reach the npm registry to check the latest ${PACKAGE_NAME} version.`
+    );
+  }
+  const latestVersion = resolvedLatestVersion ?? currentVersion;
+  return {
+    currentVersion,
+    latestVersion,
+    isOutdated: compareSemver(currentVersion, latestVersion) < 0,
+    installCommand: getUpdateInstallCommand()
+  };
+}
+function writeUpdateNotice(status) {
+  writeNoticeBox("Update Available", [
+    `${PACKAGE_NAME} ${status.currentVersion} -> ${status.latestVersion}`,
+    `Run: ${status.installCommand}`
+  ]);
+}
+async function maybeShowUpdateNotice(options) {
+  if (options.env.PEAKURL_DISABLE_UPDATE_CHECK === "1" || options.commandName === "update" || options.options?.json || options.options?.quiet) {
+    return;
+  }
+  if (options.env.PEAKURL_FORCE_UPDATE_NOTICE !== "1" && !process.stderr.isTTY) {
+    return;
+  }
+  const store = new StateStore();
+  const updateState = await getCachedUpdateState(store);
+  const status = await getUpdateStatus(options.currentVersion, options.env, {
+    store
+  });
+  if (!status.isOutdated) {
+    return;
+  }
+  const lastNotifiedAt = parseTime(updateState.lastNotifiedAt);
+  const alreadyNotifiedForVersion = updateState.lastNotifiedVersion === status.latestVersion;
+  if (alreadyNotifiedForVersion && lastNotifiedAt !== null && Date.now() - lastNotifiedAt < NOTICE_TTL_MS) {
+    return;
+  }
+  await saveUpdateState(store, {
+    ...updateState,
+    lastNotifiedAt: (/* @__PURE__ */ new Date()).toISOString(),
+    lastNotifiedVersion: status.latestVersion
+  });
+  writeUpdateNotice(status);
+}
+
+// src/commands/update.ts
+async function updateCommand(options, currentVersion) {
+  const status = await getUpdateStatus(currentVersion, process.env, {
+    forceRefresh: true
+  });
+  const responseBody = {
+    success: true,
+    message: status.isOutdated ? `A newer PeakURL CLI version is available (${status.latestVersion}).` : `PeakURL CLI ${status.currentVersion} is up to date.`,
+    data: {
+      currentVersion: status.currentVersion,
+      latestVersion: status.latestVersion,
+      isOutdated: status.isOutdated,
+      installCommand: status.installCommand,
+      checkOnly: Boolean(options.check)
+    },
+    timestamp: (/* @__PURE__ */ new Date()).toISOString()
+  };
+  if (options.json) {
+    writeJson(responseBody);
+    return;
+  }
+  if (!status.isOutdated) {
+    if (!options.quiet) {
+      writeStdout(`PeakURL CLI ${status.currentVersion} is up to date.`);
+    }
+    return;
+  }
+  if (options.quiet) {
+    writeStdout(status.installCommand);
+    return;
+  }
+  writeNoticeBox(
+    "Update Available",
+    [
+      `peakurl ${status.currentVersion} -> ${status.latestVersion}`,
+      `Run: ${status.installCommand}`
+    ],
+    "stdout"
+  );
+}
+
 // src/commands/whoami.ts
 async function whoamiCommand(options) {
   const config = await resolveStoredConfig(process.env);
@@ -661,7 +1060,7 @@ function parsePositiveInteger(label) {
     return parsed;
   };
 }
-async function readVersion() {
+async function getCliVersion() {
   const packageJson = new URL("../package.json", import.meta.url);
   const content = await readFile2(packageJson, "utf8");
   const parsed = JSON.parse(content);
@@ -669,7 +1068,8 @@ async function readVersion() {
 }
 async function main() {
   const program = new Command();
-  program.name("peakurl").description("PeakURL command-line interface").version(await readVersion()).showHelpAfterError().showSuggestionAfterError().addHelpText(
+  const version = await getCliVersion();
+  program.name("peakurl").description("PeakURL command-line interface").version(version).showHelpAfterError().showSuggestionAfterError().addHelpText(
     "after",
     `
 Examples:
@@ -677,9 +1077,19 @@ Examples:
   peakurl whoami --json
   peakurl create https://example.com --alias example
   peakurl list --limit 10
+  peakurl update --check
   peakurl get example
   peakurl delete example --quiet`
   ).exitOverride();
+  program.hook("preAction", async (_command, actionCommand) => {
+    const options = actionCommand.optsWithGlobals();
+    await maybeShowUpdateNotice({
+      currentVersion: version,
+      commandName: actionCommand.name(),
+      options,
+      env: process.env
+    });
+  });
   program.command("login").description(
     "Save PeakURL credentials after verifying them with GET /users/me."
   ).option(
@@ -694,13 +1104,19 @@ Examples:
   program.command("list").description("List PeakURL short links.").option("--page <number>", "Page number", parsePositiveInteger("page")).option("--limit <number>", "Page size", parsePositiveInteger("limit")).option("--search <query>", "Search term").option("--sort-by <field>", "Sort field").option("--sort-order <order>", "Sort order, for example asc or desc").option("--json", "Print machine-readable output").option("--quiet", "Print a minimal per-link value").action(listCommand);
   program.command("get").description("Fetch a single PeakURL short link by id or alias.").argument("<id-or-alias>", "Link identifier or alias").option("--json", "Print machine-readable output").option("--quiet", "Print only the short URL").action(getCommand);
   program.command("delete").description("Delete a PeakURL short link by id or alias.").argument("<id-or-alias>", "Link identifier or alias").option("--json", "Print machine-readable output").option("--quiet", "Suppress success output").action(deleteCommand);
+  program.command("update").description(
+    "Check for a newer CLI version and print the npm command to install it."
+  ).option(
+    "--check",
+    "Alias for checking update status without changing anything"
+  ).option("--json", "Print machine-readable output").option("--quiet", "Print minimal output").action((options) => updateCommand(options, version));
   try {
     await program.parseAsync(process.argv);
   } catch (error) {
     if (error instanceof CommanderError) {
       process.exit(error.exitCode);
     }
-    const cliError = toCliError(error);
+    const cliError = wrapCliError(error);
     writeStderr(cliError.message);
     process.exit(cliError.exitCode);
   }

package/package.json

@@ -1,12 +1,25 @@
 {
     "name": "peakurl",
-    "version": "0.1.0",
-    "description": "PeakURL command-line interface",
-    "homepage": "https://peakurl.org/",
+    "version": "0.1.2",
+    "description": "Official CLI for creating, listing, and managing PeakURL short links from the terminal",
+    "homepage": "https://peakurl.org",
+    "bugs": {
+        "url": "https://github.com/PeakURL/PeakURL-CLI/issues"
+    },
     "repository": {
         "type": "git",
         "url": "git+https://github.com/PeakURL/PeakURL-CLI.git"
     },
+    "keywords": [
+        "peakurl",
+        "url shortener",
+        "short links",
+        "link shortening",
+        "cli",
+        "command line",
+        "terminal",
+        "productivity"
+    ],
     "type": "module",
     "bin": {
         "peakurl": "bin/peakurl.js"
@@ -22,7 +35,7 @@
         "dev": "tsx src/index.ts",
         "format": "prettier --write .",
         "format:check": "prettier --check .",
-        "test": "tsx --test test/*.test.ts",
+        "test": "npm run build && tsx --test test/*.test.ts",
         "typecheck": "tsc --noEmit",
         "prepare": "npm run build"
     },