peakurl 0.1.1 → 0.2.0

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,9 +1,11 @@
-# PeakURL CLI
+# PeakURL - Command-Line Interface
 
 The official command-line interface for PeakURL.
 
 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
 
 Node.js 20 or later is required.
@@ -32,6 +34,7 @@ peakurl create \
 
 peakurl list
 peakurl whoami
+peakurl logout
 ```
 
 ## Authentication
@@ -41,6 +44,7 @@ The CLI uses PeakURL bearer API keys and validates them against `GET /api/v1/use
 - `--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`
+- `peakurl logout` removes the saved config file, but shell environment variables still override auth if they are set
 
 For CI or automation, you can also authenticate with environment variables:
 
@@ -55,6 +59,7 @@ export PEAKURL_API_KEY=0123456789abcdef0123456789abcdef0123456789abcdef
 | ------------------------------ | ---------------------------------------------------------- |
 | `peakurl login`                | Validate and save your PeakURL credentials.                |
 | `peakurl whoami`               | Show the current authenticated account.                    |
+| `peakurl logout`               | Remove saved local CLI credentials.                        |
 | `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.                        |
@@ -86,6 +91,12 @@ Inspect a link:
 peakurl get example
 ```
 
+Log out from saved local credentials:
+
+```bash
+peakurl logout
+```
+
 Delete a link:
 
 ```bash
@@ -127,6 +138,7 @@ export PEAKURL_DISABLE_UPDATE_CHECK=1
 ## Links
 
 - 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

@@ -7,13 +7,15 @@ import { Command, CommanderError, InvalidArgumentError } from "commander";
 // src/lib/errors.ts
 var CliError = class extends Error {
   exitCode;
+  kind;
   constructor(message, exitCode = 1, options) {
     super(message, options);
     this.name = "CliError";
     this.exitCode = exitCode;
+    this.kind = options?.kind;
   }
 };
-function toCliError(error) {
+function ensureCliError(error) {
   if (error instanceof CliError) {
     return error;
   }
@@ -24,6 +26,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 +45,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,25 +70,30 @@ 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}`);
   }
 }
 
 // src/api/client.ts
-function isEnvelope(value) {
+function isApiResponse(value) {
   return Boolean(
     value && typeof value === "object" && "success" in value && "message" in value && "timestamp" in value
   );
 }
-function formatNetworkError(baseUrl, error) {
+function networkError(baseUrl, error) {
   if (error instanceof Error && error.message) {
     return `Could not reach PeakURL at ${baseUrl}. ${error.message}`;
   }
   return `Could not reach PeakURL at ${baseUrl}.`;
 }
-var PeakUrlApiClient = class {
+var ApiClient = class {
   /**
    * Creates a client bound to one resolved credential set.
    *
@@ -120,12 +133,7 @@ var PeakUrlApiClient = class {
    * @returns API response envelope containing list data.
    */
   listUrls(query) {
-    return this.request(
-      "GET",
-      "urls",
-      void 0,
-      query
-    );
+    return this.request("GET", "urls", void 0, query);
   }
   /**
    * Loads a single short URL by identifier or alias.
@@ -180,13 +188,9 @@ var PeakUrlApiClient = class {
         body: body ? JSON.stringify(body) : void 0
       });
     } catch (error) {
-      throw new CliError(
-        formatNetworkError(this.config.baseUrl, error),
-        1,
-        {
-          cause: error instanceof Error ? error : void 0
-        }
-      );
+      throw new CliError(networkError(this.config.baseUrl, error), 1, {
+        cause: error instanceof Error ? error : void 0
+      });
     }
     const rawText = await response.text();
     if (!rawText) {
@@ -213,7 +217,7 @@ var PeakUrlApiClient = class {
       }
       throw new CliError("PeakURL returned an invalid JSON response.");
     }
-    if (!isEnvelope(parsed)) {
+    if (!isApiResponse(parsed)) {
       throw new CliError(
         "PeakURL returned an unexpected response envelope."
       );
@@ -230,18 +234,18 @@ var PeakUrlApiClient = class {
 };
 
 // src/config/store.ts
-import { chmod, mkdir, readFile, writeFile } from "fs/promises";
+import { chmod, mkdir, readFile, unlink, 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() {
+function getConfigPath() {
   return join(envPaths("peakurl", { suffix: "" }).config, CONFIG_FILENAME);
 }
-function defaultStatePath() {
+function getStatePath() {
   return join(envPaths("peakurl", { suffix: "" }).config, STATE_FILENAME);
 }
-async function ensureParentDirectory(filePath) {
+async function ensureParentDir(filePath) {
   const directory = dirname(filePath);
   await mkdir(directory, { recursive: true, mode: 448 });
   return directory;
@@ -253,7 +257,7 @@ var ConfigStore = class {
    *
    * @param filePath Optional override used by tests or advanced callers.
    */
-  constructor(filePath = defaultConfigPath()) {
+  constructor(filePath = getConfigPath()) {
     this.filePath = filePath;
   }
   /**
@@ -301,7 +305,7 @@ var ConfigStore = class {
    * @param config Normalized credential set to write.
    */
   async save(config) {
-    const directory = await ensureParentDirectory(this.filePath);
+    const directory = await ensureParentDir(this.filePath);
     await writeFile(this.filePath, `${JSON.stringify(config, null, 2)}
 `, {
       mode: 384
@@ -312,6 +316,29 @@ var ConfigStore = class {
     } catch {
     }
   }
+  /**
+   * Removes the stored credential file.
+   *
+   * @returns `true` when a saved config file existed and was removed.
+   * @throws {CliError} When the file exists but cannot be removed.
+   */
+  async clear() {
+    try {
+      await unlink(this.filePath);
+      return true;
+    } catch (error) {
+      if (error instanceof Error && "code" in error && typeof error.code === "string" && error.code === "ENOENT") {
+        return false;
+      }
+      throw new CliError(
+        `Could not remove PeakURL config at ${this.filePath}.`,
+        1,
+        {
+          cause: error instanceof Error ? error : void 0
+        }
+      );
+    }
+  }
 };
 var StateStore = class {
   filePath;
@@ -320,7 +347,7 @@ var StateStore = class {
    *
    * @param filePath Optional override used by tests or advanced callers.
    */
-  constructor(filePath = defaultStatePath()) {
+  constructor(filePath = getStatePath()) {
     this.filePath = filePath;
   }
   /**
@@ -346,16 +373,30 @@ var StateStore = class {
    * @param state State payload to save.
    */
   async save(state) {
-    await ensureParentDirectory(this.filePath);
+    const directory = await ensureParentDir(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) {
+var AUTH_REQUIRED_MESSAGE = "PeakURL credentials are not configured.";
+function authRows() {
+  return [
+    ["Reason", AUTH_REQUIRED_MESSAGE],
+    ["Command", "peakurl login"],
+    ["Flags", "--base-url <url> --api-key <key>"],
+    ["Env", "PEAKURL_BASE_URL, PEAKURL_API_KEY"]
+  ];
+}
+function getLoginConfig(input, env) {
   const baseUrl = input.baseUrl?.trim() || env.PEAKURL_BASE_URL?.trim();
   const apiKey = input.apiKey?.trim() || env.PEAKURL_API_KEY?.trim();
   if (!baseUrl || !apiKey) {
@@ -368,14 +409,14 @@ function resolveLoginConfig(input, env) {
     apiKey
   };
 }
-async function resolveStoredConfig(env, store = new ConfigStore()) {
+async function getAuthConfig(env, store = new ConfigStore()) {
   const saved = await store.load();
   const baseUrl = env.PEAKURL_BASE_URL?.trim() || saved?.baseUrl;
   const apiKey = env.PEAKURL_API_KEY?.trim() || saved?.apiKey;
   if (!baseUrl || !apiKey) {
-    throw new CliError(
-      "PeakURL credentials are not configured. Run `peakurl login --base-url ... --api-key ...` or set PEAKURL_BASE_URL and PEAKURL_API_KEY."
-    );
+    throw new CliError(AUTH_REQUIRED_MESSAGE, 1, {
+      kind: "auth_required"
+    });
   }
   return {
     baseUrl: normalizeBaseUrl(baseUrl),
@@ -383,20 +424,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 asObject(value) {
   return value && typeof value === "object" && !Array.isArray(value) ? value : null;
 }
-function readString(value) {
+function asString(value) {
   return typeof value === "string" && value.trim() ? value.trim() : void 0;
 }
-function readNumber(value) {
+function asNumber(value) {
   return typeof value === "number" && Number.isFinite(value) ? value : void 0;
 }
-function firstString(link, keys) {
+function pickText(link, keys) {
   for (const key of keys) {
-    const value = readString(link[key]);
+    const value = asString(link[key]);
     if (value) {
       return value;
     }
@@ -406,32 +553,32 @@ function firstString(link, keys) {
 function truncate(value, maxLength) {
   return value.length > maxLength ? `${value.slice(0, maxLength - 1)}\u2026` : value;
 }
-function extractListMeta(data) {
-  const record = asRecord(data);
+function getListMeta(data) {
+  const record = asObject(data);
   if (!record) {
     return null;
   }
-  const meta = asRecord(record.meta);
+  const meta = asObject(record.meta);
   if (meta) {
     return {
-      page: readNumber(meta.page),
-      limit: readNumber(meta.limit),
-      totalItems: readNumber(meta.totalItems),
-      totalPages: readNumber(meta.totalPages)
+      page: asNumber(meta.page),
+      limit: asNumber(meta.limit),
+      totalItems: asNumber(meta.totalItems),
+      totalPages: asNumber(meta.totalPages)
     };
   }
   return {
-    page: readNumber(record.page),
-    limit: readNumber(record.limit),
-    totalItems: readNumber(record.total),
-    totalPages: readNumber(record.totalPages)
+    page: asNumber(record.page),
+    limit: asNumber(record.limit),
+    totalItems: asNumber(record.total),
+    totalPages: asNumber(record.totalPages)
   };
 }
 function extractLinks(data) {
   if (Array.isArray(data)) {
     return data;
   }
-  const record = asRecord(data);
+  const record = asObject(data);
   if (record) {
     for (const key of LIST_KEYS) {
       const value = record[key];
@@ -443,16 +590,16 @@ function extractLinks(data) {
   return [];
 }
 function getLinkId(link) {
-  return firstString(link, ["id", "_id", "urlId"]) || (link.id !== void 0 ? String(link.id) : void 0);
+  return pickText(link, ["id", "_id", "urlId"]) || (link.id !== void 0 ? String(link.id) : void 0);
 }
 function getLinkAlias(link) {
-  return firstString(link, ["alias", "shortCode", "slug", "code"]);
+  return pickText(link, ["alias", "shortCode", "slug", "code"]);
 }
 function getLinkShortUrl(link) {
-  return firstString(link, ["shortUrl", "shortLink", "shortURL", "url"]);
+  return pickText(link, ["shortUrl", "shortLink", "shortURL", "url"]);
 }
 function getLinkDestination(link) {
-  return firstString(link, [
+  return pickText(link, [
     "destinationUrl",
     "originalUrl",
     "targetUrl",
@@ -468,14 +615,14 @@ function formatLinkDetails(link) {
     ["Alias", getLinkAlias(link)],
     ["Short URL", getLinkShortUrl(link)],
     ["Destination", getLinkDestination(link)],
-    ["Title", readString(link.title)],
-    ["Status", readString(link.status)],
+    ["Title", asString(link.title)],
+    ["Status", asString(link.status)],
     [
       "Clicks",
-      readNumber(link.clicks) === void 0 ? void 0 : String(link.clicks)
+      asNumber(link.clicks) === void 0 ? void 0 : String(link.clicks)
     ],
-    ["Created", readString(link.createdAt)],
-    ["Updated", readString(link.updatedAt)]
+    ["Created", asString(link.createdAt)],
+    ["Updated", asString(link.updatedAt)]
   ].filter((entry) => Boolean(entry[1]));
   return lines.map(([label, value]) => `${label}: ${value}`).join("\n");
 }
@@ -483,26 +630,18 @@ 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(asString(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);
+  const meta = getListMeta(data);
   if (!meta) {
     return `${count} link${count === 1 ? "" : "s"} returned.`;
   }
@@ -515,227 +654,32 @@ 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 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 writeJson(value) {
-  writeStdout(JSON.stringify(value, null, 2));
-}
-
-// src/commands/create.ts
-function normalizeExpiresAt(value) {
-  if (!value) {
-    return void 0;
-  }
-  if (Number.isNaN(Date.parse(value))) {
-    throw new CliError(`Invalid expiration timestamp: ${value}`);
-  }
-  return value;
-}
-async function createCommand(destinationUrl, options) {
-  const config = await resolveStoredConfig(process.env);
-  const response = await new PeakUrlApiClient(config).createUrl({
-    destinationUrl: normalizeDestinationUrl(destinationUrl),
-    ...options.alias ? { alias: options.alias } : {},
-    ...options.title ? { title: options.title } : {},
-    ...options.password ? { password: options.password } : {},
-    ...options.status ? { status: options.status } : {},
-    ...options.expiresAt ? { expiresAt: normalizeExpiresAt(options.expiresAt) } : {},
-    ...options.utmSource ? { utmSource: options.utmSource } : {},
-    ...options.utmMedium ? { utmMedium: options.utmMedium } : {},
-    ...options.utmCampaign ? { utmCampaign: options.utmCampaign } : {},
-    ...options.utmTerm ? { utmTerm: options.utmTerm } : {},
-    ...options.utmContent ? { utmContent: options.utmContent } : {}
-  });
-  if (options.json) {
-    writeJson(response);
-    return;
-  }
-  if (options.quiet) {
-    writeStdout(getQuietLinkValue(response.data));
-    return;
-  }
-  writeStdout(response.message);
-  writeStdout(formatLinkDetails(response.data));
-}
-
-// src/commands/delete.ts
-async function deleteCommand(idOrAlias, options) {
-  const config = await resolveStoredConfig(process.env);
-  const client = new PeakUrlApiClient(config);
-  const lookupResponse = await client.getUrl(idOrAlias);
-  const resolvedId = getLinkId(lookupResponse.data);
-  if (!resolvedId) {
-    throw new CliError(
-      "PeakURL returned a link record without an ID, so the CLI cannot delete it safely."
-    );
-  }
-  const response = await client.deleteUrl(resolvedId);
-  if (options.json) {
-    writeJson(response);
-    return;
-  }
-  if (options.quiet) {
-    return;
-  }
-  writeStdout(response.message);
-}
-
-// src/commands/get.ts
-async function getCommand(idOrAlias, options) {
-  const config = await resolveStoredConfig(process.env);
-  const response = await new PeakUrlApiClient(config).getUrl(idOrAlias);
-  if (options.json) {
-    writeJson(response);
-    return;
-  }
-  if (options.quiet) {
-    writeStdout(getQuietLinkValue(response.data));
-    return;
-  }
-  writeStdout(response.message);
-  writeStdout(formatLinkDetails(response.data));
-}
-
-// src/commands/list.ts
-async function listCommand(options) {
-  const config = await resolveStoredConfig(process.env);
-  const response = await new PeakUrlApiClient(config).listUrls({
-    page: options.page,
-    limit: options.limit,
-    search: options.search,
-    sortBy: options.sortBy,
-    sortOrder: options.sortOrder
-  });
-  const links = extractLinks(response.data);
-  if (options.json) {
-    writeJson(response);
-    return;
-  }
-  if (options.quiet) {
-    for (const link of links) {
-      const value = getQuietLinkValue(link);
-      if (value) {
-        writeStdout(value);
-      }
-    }
-    return;
-  }
-  writeStdout(response.message);
-  writeStdout(formatLinksTable(links));
-  writeStdout(formatListSummary(response.data, links.length));
-}
-
-// src/lib/users.ts
-function readString2(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");
-}
-function getQuietUserValue(user) {
-  return readString2(user.username) || readString2(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)],
-    ["ID", user.id === void 0 ? void 0 : String(user.id)]
-  ].filter((entry) => Boolean(entry[1]));
-  return lines.map(([label, value]) => `${label}: ${value}`).join("\n");
-}
-
-// src/commands/login.ts
-async function loginCommand(options) {
-  const credentials = resolveLoginConfig(options, process.env);
-  const client = new PeakUrlApiClient(credentials);
-  const response = await client.whoami();
-  await new ConfigStore().save(credentials);
-  const payload = {
-    success: true,
-    message: `Saved credentials for ${credentials.baseUrl}.`,
-    data: {
-      baseUrl: credentials.baseUrl,
-      user: response.data
-    },
-    timestamp: response.timestamp
-  };
-  if (options.json) {
-    writeJson(payload);
-    return;
-  }
-  if (options.quiet) {
-    return;
-  }
-  writeStdout(`Saved credentials for ${credentials.baseUrl}`);
-  writeStdout(`Authenticated as ${getUserLabel(response.data)}`);
-  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 readTimestamp(value) {
+function parseTime(value) {
   if (!value) {
     return null;
   }
   const parsed = Date.parse(value);
   return Number.isNaN(parsed) ? null : parsed;
 }
-function getRegistryUrl(env) {
-  return env.PEAKURL_NPM_REGISTRY_URL?.trim() || DEFAULT_REGISTRY_URL;
+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(/\/+$/, "");
@@ -811,11 +755,11 @@ function compareSemver(left, right) {
   }
   return comparePrerelease(parsedLeft.prerelease, parsedRight.prerelease);
 }
-function getInstallCommand() {
+function getUpdateInstallCommand() {
   return `npm install -g ${PACKAGE_NAME}@latest`;
 }
 async function fetchLatestVersion(env) {
-  const registryUrl = normalizeRegistryUrl(getRegistryUrl(env));
+  const registryUrl = normalizeRegistryUrl(getRegistryBaseUrl(env));
   const url = `${registryUrl}/${PACKAGE_NAME}/latest`;
   const controller = new AbortController();
   const timeout = setTimeout(() => controller.abort(), 2e3);
@@ -837,7 +781,7 @@ async function fetchLatestVersion(env) {
     clearTimeout(timeout);
   }
 }
-async function loadLatestVersionFromState(store) {
+async function getUpdateState(store) {
   const state = await store.load();
   return state.update ?? {};
 }
@@ -848,10 +792,10 @@ async function saveUpdateState(store, update) {
     update
   });
 }
-async function resolveLatestVersion(env, options) {
+async function loadLatestVersion(env, options) {
   const store = options?.store ?? new StateStore();
-  const updateState = await loadLatestVersionFromState(store);
-  const lastCheckedAt = readTimestamp(updateState.lastCheckedAt);
+  const updateState = await getUpdateState(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;
@@ -868,7 +812,7 @@ async function resolveLatestVersion(env, options) {
   return latestVersion;
 }
 async function getUpdateStatus(currentVersion, env, options) {
-  const resolvedLatestVersion = await resolveLatestVersion(env, {
+  const resolvedLatestVersion = await loadLatestVersion(env, {
     forceRefresh: options?.forceRefresh,
     store: options?.store
   });
@@ -882,16 +826,16 @@ async function getUpdateStatus(currentVersion, env, options) {
     currentVersion,
     latestVersion,
     isOutdated: compareSemver(currentVersion, latestVersion) < 0,
-    installCommand: getInstallCommand()
+    installCommand: getUpdateInstallCommand()
   };
 }
-function writeUpdateNotice(status) {
+function showUpdateNotice(status) {
   writeNoticeBox("Update Available", [
     `${PACKAGE_NAME} ${status.currentVersion} -> ${status.latestVersion}`,
     `Run: ${status.installCommand}`
   ]);
 }
-async function maybeShowUpdateNotice(options) {
+async function checkUpdates(options) {
   if (options.env.PEAKURL_DISABLE_UPDATE_CHECK === "1" || options.commandName === "update" || options.options?.json || options.options?.quiet) {
     return;
   }
@@ -899,14 +843,14 @@ async function maybeShowUpdateNotice(options) {
     return;
   }
   const store = new StateStore();
-  const updateState = await loadLatestVersionFromState(store);
+  const updateState = await getUpdateState(store);
   const status = await getUpdateStatus(options.currentVersion, options.env, {
     store
   });
   if (!status.isOutdated) {
     return;
   }
-  const lastNotifiedAt = readTimestamp(updateState.lastNotifiedAt);
+  const lastNotifiedAt = parseTime(updateState.lastNotifiedAt);
   const alreadyNotifiedForVersion = updateState.lastNotifiedVersion === status.latestVersion;
   if (alreadyNotifiedForVersion && lastNotifiedAt !== null && Date.now() - lastNotifiedAt < NOTICE_TTL_MS) {
     return;
@@ -916,7 +860,198 @@ async function maybeShowUpdateNotice(options) {
     lastNotifiedAt: (/* @__PURE__ */ new Date()).toISOString(),
     lastNotifiedVersion: status.latestVersion
   });
-  writeUpdateNotice(status);
+  showUpdateNotice(status);
+}
+
+// src/lib/users.ts
+function text(value) {
+  return typeof value === "string" && value.trim() ? value.trim() : void 0;
+}
+function userLabel(user) {
+  const fullName = [text(user.firstName), text(user.lastName)].filter((value) => Boolean(value)).join(" ");
+  return fullName || text(user.username) || text(user.email) || String(user.id ?? "unknown");
+}
+function userValue(user) {
+  return text(user.username) || text(user.email) || String(user.id ?? "");
+}
+function userTable(user) {
+  const rows = [
+    ["Name", userLabel(user)],
+    ["Username", text(user.username)],
+    ["Email", text(user.email)],
+    ["Role", text(user.role)],
+    ["ID", user.id === void 0 ? void 0 : String(user.id)]
+  ].filter((entry) => Boolean(entry[1]));
+  if (rows.length === 0) {
+    return "No user fields returned.";
+  }
+  return formatTable(["Field", "Value"], rows);
+}
+
+// src/commands/create.ts
+function normalizeExpiresAt(value) {
+  if (!value) {
+    return void 0;
+  }
+  if (Number.isNaN(Date.parse(value))) {
+    throw new CliError(`Invalid expiration timestamp: ${value}`);
+  }
+  return value;
+}
+async function createCommand(destinationUrl, options) {
+  const config = await getAuthConfig(process.env);
+  const response = await new ApiClient(config).createUrl({
+    destinationUrl: normalizeDestinationUrl(destinationUrl),
+    ...options.alias ? { alias: options.alias } : {},
+    ...options.title ? { title: options.title } : {},
+    ...options.password ? { password: options.password } : {},
+    ...options.status ? { status: options.status } : {},
+    ...options.expiresAt ? { expiresAt: normalizeExpiresAt(options.expiresAt) } : {},
+    ...options.utmSource ? { utmSource: options.utmSource } : {},
+    ...options.utmMedium ? { utmMedium: options.utmMedium } : {},
+    ...options.utmCampaign ? { utmCampaign: options.utmCampaign } : {},
+    ...options.utmTerm ? { utmTerm: options.utmTerm } : {},
+    ...options.utmContent ? { utmContent: options.utmContent } : {}
+  });
+  if (options.json) {
+    writeJson(response);
+    return;
+  }
+  if (options.quiet) {
+    writeStdout(getQuietLinkValue(response.data));
+    return;
+  }
+  writeStdout(response.message);
+  writeStdout(formatLinkDetails(response.data));
+}
+
+// src/commands/delete.ts
+async function deleteCommand(idOrAlias, options) {
+  const config = await getAuthConfig(process.env);
+  const client = new ApiClient(config);
+  const lookupResponse = await client.getUrl(idOrAlias);
+  const resolvedId = getLinkId(lookupResponse.data);
+  if (!resolvedId) {
+    throw new CliError(
+      "PeakURL returned a link record without an ID, so the CLI cannot delete it safely."
+    );
+  }
+  const response = await client.deleteUrl(resolvedId);
+  if (options.json) {
+    writeJson(response);
+    return;
+  }
+  if (options.quiet) {
+    return;
+  }
+  writeStdout(response.message);
+}
+
+// src/commands/get.ts
+async function getCommand(idOrAlias, options) {
+  const config = await getAuthConfig(process.env);
+  const response = await new ApiClient(config).getUrl(idOrAlias);
+  if (options.json) {
+    writeJson(response);
+    return;
+  }
+  if (options.quiet) {
+    writeStdout(getQuietLinkValue(response.data));
+    return;
+  }
+  writeStdout(response.message);
+  writeStdout(formatLinkDetails(response.data));
+}
+
+// src/commands/list.ts
+async function listCommand(options) {
+  const config = await getAuthConfig(process.env);
+  const response = await new ApiClient(config).listUrls({
+    page: options.page,
+    limit: options.limit,
+    search: options.search,
+    sortBy: options.sortBy,
+    sortOrder: options.sortOrder
+  });
+  const links = extractLinks(response.data);
+  if (options.json) {
+    writeJson(response);
+    return;
+  }
+  if (options.quiet) {
+    for (const link of links) {
+      const value = getQuietLinkValue(link);
+      if (value) {
+        writeStdout(value);
+      }
+    }
+    return;
+  }
+  writeStdout(response.message);
+  writeStdout(formatLinksTable(links));
+  writeStdout(formatListSummary(response.data, links.length));
+}
+
+// src/commands/login.ts
+async function loginCommand(options) {
+  const credentials = getLoginConfig(options, process.env);
+  const client = new ApiClient(credentials);
+  const response = await client.whoami();
+  await new ConfigStore().save(credentials);
+  const responseBody = {
+    success: true,
+    message: `Saved credentials for ${credentials.baseUrl}.`,
+    data: {
+      baseUrl: credentials.baseUrl,
+      user: response.data
+    },
+    timestamp: response.timestamp
+  };
+  if (options.json) {
+    writeJson(responseBody);
+    return;
+  }
+  if (options.quiet) {
+    return;
+  }
+  writeStdout(`Saved credentials for ${credentials.baseUrl}`);
+  writeStdout(`Authenticated as ${userLabel(response.data)}`);
+  writeStdout(userTable(response.data));
+}
+
+// src/commands/logout.ts
+function hasEnvConfig(env) {
+  return Boolean(env.PEAKURL_BASE_URL?.trim() || env.PEAKURL_API_KEY?.trim());
+}
+async function logoutCommand(options) {
+  const store = new ConfigStore();
+  const saved = await store.load();
+  const removed = await store.clear();
+  const envConfig = hasEnvConfig(process.env);
+  const message = removed && saved?.baseUrl ? `Logged out. Removed saved credentials for ${saved.baseUrl}.` : removed ? "Logged out. Removed saved PeakURL credentials." : "Already logged out. No saved PeakURL credentials were found.";
+  const responseBody = {
+    success: true,
+    message,
+    data: {
+      removed,
+      baseUrl: saved?.baseUrl,
+      envCredentialsActive: envConfig
+    },
+    timestamp: (/* @__PURE__ */ new Date()).toISOString()
+  };
+  if (options.json) {
+    writeJson(responseBody);
+    return;
+  }
+  if (options.quiet) {
+    return;
+  }
+  writeStdout(message);
+  if (envConfig) {
+    writeStdout(
+      "Environment credentials in PEAKURL_BASE_URL or PEAKURL_API_KEY still apply in this shell."
+    );
+  }
 }
 
 // src/commands/update.ts
@@ -924,7 +1059,7 @@ async function updateCommand(options, currentVersion) {
   const status = await getUpdateStatus(currentVersion, process.env, {
     forceRefresh: true
   });
-  const payload = {
+  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: {
@@ -937,7 +1072,7 @@ async function updateCommand(options, currentVersion) {
     timestamp: (/* @__PURE__ */ new Date()).toISOString()
   };
   if (options.json) {
-    writeJson(payload);
+    writeJson(responseBody);
     return;
   }
   if (!status.isOutdated) {
@@ -962,22 +1097,22 @@ async function updateCommand(options, currentVersion) {
 
 // src/commands/whoami.ts
 async function whoamiCommand(options) {
-  const config = await resolveStoredConfig(process.env);
-  const response = await new PeakUrlApiClient(config).whoami();
+  const config = await getAuthConfig(process.env);
+  const response = await new ApiClient(config).whoami();
   if (options.json) {
     writeJson(response);
     return;
   }
   if (options.quiet) {
-    writeStdout(getQuietUserValue(response.data));
+    writeStdout(userValue(response.data));
     return;
   }
   writeStdout(response.message);
-  writeStdout(formatUserDetails(response.data));
+  writeStdout(userTable(response.data));
 }
 
 // src/index.ts
-function parsePositiveInteger(label) {
+function parseNumber(label) {
   return (value) => {
     const parsed = Number.parseInt(value, 10);
     if (!Number.isInteger(parsed) || parsed <= 0) {
@@ -988,7 +1123,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);
@@ -996,13 +1131,14 @@ async function readVersion() {
 }
 async function main() {
   const program = new Command();
-  const version = await readVersion();
+  const version = await getCliVersion();
   program.name("peakurl").description("PeakURL command-line interface").version(version).showHelpAfterError().showSuggestionAfterError().addHelpText(
     "after",
     `
 Examples:
   peakurl login --base-url https://peakurl.org --api-key 0123456789abcdef0123456789abcdef0123456789abcdef
   peakurl whoami --json
+  peakurl logout
   peakurl create https://example.com --alias example
   peakurl list --limit 10
   peakurl update --check
@@ -1011,7 +1147,7 @@ Examples:
   ).exitOverride();
   program.hook("preAction", async (_command, actionCommand) => {
     const options = actionCommand.optsWithGlobals();
-    await maybeShowUpdateNotice({
+    await checkUpdates({
       currentVersion: version,
       commandName: actionCommand.name(),
       options,
@@ -1025,11 +1161,12 @@ Examples:
     "PeakURL base URL, for example https://peakurl.org"
   ).option("--api-key <token>", "PeakURL API key to store").option("--json", "Print machine-readable output").option("--quiet", "Suppress success output").action(loginCommand);
   program.command("whoami").description("Show the current authenticated PeakURL user.").option("--json", "Print machine-readable output").option("--quiet", "Print a minimal identity value").action(whoamiCommand);
+  program.command("logout").description("Remove saved PeakURL credentials from this device.").option("--json", "Print machine-readable output").option("--quiet", "Suppress success output").action(logoutCommand);
   program.command("create").description("Create a PeakURL short link.").argument("<url>", "Destination URL to shorten").option("--alias <alias>", "Custom alias for the short link").option("--title <title>", "Title to store with the short link").option("--password <password>", "Password-protect the short link").option(
     "--status <status>",
     "Link status, for example active or paused"
   ).option("--expires-at <iso>", "Expiration timestamp in ISO-8601 format").option("--utm-source <value>", "UTM source").option("--utm-medium <value>", "UTM medium").option("--utm-campaign <value>", "UTM campaign").option("--utm-term <value>", "UTM term").option("--utm-content <value>", "UTM content").option("--json", "Print machine-readable output").option("--quiet", "Print only the created short URL").action(createCommand);
-  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("list").description("List PeakURL short links.").option("--page <number>", "Page number", parseNumber("page")).option("--limit <number>", "Page size", parseNumber("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(
@@ -1044,8 +1181,13 @@ Examples:
     if (error instanceof CommanderError) {
       process.exit(error.exitCode);
     }
-    const cliError = toCliError(error);
-    writeStderr(cliError.message);
+    const cliError = ensureCliError(error);
+    if (cliError.kind === "auth_required") {
+      writeStderr("Not logged in.");
+      writeStderr(formatTable(["Field", "Value"], authRows(), "stderr"));
+    } else {
+      writeStderr(cliError.message);
+    }
     process.exit(cliError.exitCode);
   }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "peakurl",
-    "version": "0.1.1",
+    "version": "0.2.0",
     "description": "Official CLI for creating, listing, and managing PeakURL short links from the terminal",
     "homepage": "https://peakurl.org",
     "bugs": {