peakurl 0.1.2 → 0.2.0

package/README.md

@@ -34,6 +34,7 @@ peakurl create \
 
 peakurl list
 peakurl whoami
+peakurl logout
 ```
 
 ## Authentication
@@ -43,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:
 
@@ -57,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.                        |
@@ -88,6 +91,12 @@ Inspect a link:
 peakurl get example
 ```
 
+Log out from saved local credentials:
+
+```bash
+peakurl logout
+```
+
 Delete a link:
 
 ```bash

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 wrapCliError(error) {
+function ensureCliError(error) {
   if (error instanceof CliError) {
     return error;
   }
@@ -80,18 +82,18 @@ function normalizeDestinationUrl(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.
    *
@@ -131,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.
@@ -191,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) {
@@ -224,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."
       );
@@ -241,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 prepareFileDirectory(filePath) {
+async function ensureParentDir(filePath) {
   const directory = dirname(filePath);
   await mkdir(directory, { recursive: true, mode: 448 });
   return directory;
@@ -264,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;
   }
   /**
@@ -312,7 +305,7 @@ var ConfigStore = class {
    * @param config Normalized credential set to write.
    */
   async save(config) {
-    const directory = await prepareFileDirectory(this.filePath);
+    const directory = await ensureParentDir(this.filePath);
     await writeFile(this.filePath, `${JSON.stringify(config, null, 2)}
 `, {
       mode: 384
@@ -323,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;
@@ -331,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;
   }
   /**
@@ -357,7 +373,7 @@ var StateStore = class {
    * @param state State payload to save.
    */
   async save(state) {
-    const directory = await prepareFileDirectory(this.filePath);
+    const directory = await ensureParentDir(this.filePath);
     await writeFile(this.filePath, `${JSON.stringify(state, null, 2)}
 `, {
       mode: 384
@@ -371,7 +387,16 @@ var StateStore = class {
 };
 
 // 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) {
@@ -384,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),
@@ -507,18 +532,18 @@ function writeJson(value) {
 
 // src/lib/links.ts
 var LIST_KEYS = ["urls", "items", "results"];
-function objectValue(value) {
+function asObject(value) {
   return value && typeof value === "object" && !Array.isArray(value) ? value : null;
 }
-function stringValue(value) {
+function asString(value) {
   return typeof value === "string" && value.trim() ? value.trim() : void 0;
 }
-function numberValue(value) {
+function asNumber(value) {
   return typeof value === "number" && Number.isFinite(value) ? value : void 0;
 }
-function pickString(link, keys) {
+function pickText(link, keys) {
   for (const key of keys) {
-    const value = stringValue(link[key]);
+    const value = asString(link[key]);
     if (value) {
       return value;
     }
@@ -528,32 +553,32 @@ function pickString(link, keys) {
 function truncate(value, maxLength) {
   return value.length > maxLength ? `${value.slice(0, maxLength - 1)}\u2026` : value;
 }
-function extractListMeta(data) {
-  const record = objectValue(data);
+function getListMeta(data) {
+  const record = asObject(data);
   if (!record) {
     return null;
   }
-  const meta = objectValue(record.meta);
+  const meta = asObject(record.meta);
   if (meta) {
     return {
-      page: numberValue(meta.page),
-      limit: numberValue(meta.limit),
-      totalItems: numberValue(meta.totalItems),
-      totalPages: numberValue(meta.totalPages)
+      page: asNumber(meta.page),
+      limit: asNumber(meta.limit),
+      totalItems: asNumber(meta.totalItems),
+      totalPages: asNumber(meta.totalPages)
     };
   }
   return {
-    page: numberValue(record.page),
-    limit: numberValue(record.limit),
-    totalItems: numberValue(record.total),
-    totalPages: numberValue(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 = objectValue(data);
+  const record = asObject(data);
   if (record) {
     for (const key of LIST_KEYS) {
       const value = record[key];
@@ -565,16 +590,16 @@ function extractLinks(data) {
   return [];
 }
 function getLinkId(link) {
-  return pickString(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 pickString(link, ["alias", "shortCode", "slug", "code"]);
+  return pickText(link, ["alias", "shortCode", "slug", "code"]);
 }
 function getLinkShortUrl(link) {
-  return pickString(link, ["shortUrl", "shortLink", "shortURL", "url"]);
+  return pickText(link, ["shortUrl", "shortLink", "shortURL", "url"]);
 }
 function getLinkDestination(link) {
-  return pickString(link, [
+  return pickText(link, [
     "destinationUrl",
     "originalUrl",
     "targetUrl",
@@ -590,14 +615,14 @@ function formatLinkDetails(link) {
     ["Alias", getLinkAlias(link)],
     ["Short URL", getLinkShortUrl(link)],
     ["Destination", getLinkDestination(link)],
-    ["Title", stringValue(link.title)],
-    ["Status", stringValue(link.status)],
+    ["Title", asString(link.title)],
+    ["Status", asString(link.status)],
     [
       "Clicks",
-      numberValue(link.clicks) === void 0 ? void 0 : String(link.clicks)
+      asNumber(link.clicks) === void 0 ? void 0 : String(link.clicks)
     ],
-    ["Created", stringValue(link.createdAt)],
-    ["Updated", stringValue(link.updatedAt)]
+    ["Created", asString(link.createdAt)],
+    ["Updated", asString(link.updatedAt)]
   ].filter((entry) => Boolean(entry[1]));
   return lines.map(([label, value]) => `${label}: ${value}`).join("\n");
 }
@@ -611,12 +636,12 @@ function formatLinksTable(links) {
     truncate(getLinkAlias(link) || "-", 12),
     truncate(getLinkShortUrl(link) || "-", 36),
     truncate(getLinkDestination(link) || "-", 52),
-    truncate(stringValue(link.status) || "-", 12)
+    truncate(asString(link.status) || "-", 12)
   ]);
   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.`;
   }
@@ -629,159 +654,6 @@ function formatListSummary(data, count) {
   return `${count} link${count === 1 ? "" : "s"} returned.`;
 }
 
-// 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 stringValue2(value) {
-  return typeof value === "string" && value.trim() ? value.trim() : void 0;
-}
-function getUserLabel(user) {
-  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 stringValue2(user.username) || stringValue2(user.email) || String(user.id ?? "");
-}
-function formatUserDetails(user) {
-  const lines = [
-    ["Name", getUserLabel(user)],
-    ["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");
-}
-
-// 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 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 ${getUserLabel(response.data)}`);
-  writeStdout(formatUserDetails(response.data));
-}
-
 // src/lib/update.ts
 var PACKAGE_NAME = "peakurl";
 var DEFAULT_REGISTRY_URL = "https://registry.npmjs.org";
@@ -886,7 +758,7 @@ function compareSemver(left, right) {
 function getUpdateInstallCommand() {
   return `npm install -g ${PACKAGE_NAME}@latest`;
 }
-async function fetchLatestPackageVersion(env) {
+async function fetchLatestVersion(env) {
   const registryUrl = normalizeRegistryUrl(getRegistryBaseUrl(env));
   const url = `${registryUrl}/${PACKAGE_NAME}/latest`;
   const controller = new AbortController();
@@ -909,7 +781,7 @@ async function fetchLatestPackageVersion(env) {
     clearTimeout(timeout);
   }
 }
-async function getCachedUpdateState(store) {
+async function getUpdateState(store) {
   const state = await store.load();
   return state.update ?? {};
 }
@@ -920,15 +792,15 @@ async function saveUpdateState(store, update) {
     update
   });
 }
-async function getLatestPackageVersion(env, options) {
+async function loadLatestVersion(env, options) {
   const store = options?.store ?? new StateStore();
-  const updateState = await getCachedUpdateState(store);
+  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;
   }
-  const latestVersion = await fetchLatestPackageVersion(env);
+  const latestVersion = await fetchLatestVersion(env);
   if (!latestVersion) {
     return updateState.latestVersion ?? null;
   }
@@ -940,7 +812,7 @@ async function getLatestPackageVersion(env, options) {
   return latestVersion;
 }
 async function getUpdateStatus(currentVersion, env, options) {
-  const resolvedLatestVersion = await getLatestPackageVersion(env, {
+  const resolvedLatestVersion = await loadLatestVersion(env, {
     forceRefresh: options?.forceRefresh,
     store: options?.store
   });
@@ -957,13 +829,13 @@ async function getUpdateStatus(currentVersion, env, options) {
     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;
   }
@@ -971,7 +843,7 @@ async function maybeShowUpdateNotice(options) {
     return;
   }
   const store = new StateStore();
-  const updateState = await getCachedUpdateState(store);
+  const updateState = await getUpdateState(store);
   const status = await getUpdateStatus(options.currentVersion, options.env, {
     store
   });
@@ -988,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
@@ -1034,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) {
@@ -1075,6 +1138,7 @@ async function main() {
 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
@@ -1083,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,
@@ -1097,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(
@@ -1116,8 +1181,13 @@ Examples:
     if (error instanceof CommanderError) {
       process.exit(error.exitCode);
     }
-    const cliError = wrapCliError(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.2",
+    "version": "0.2.0",
     "description": "Official CLI for creating, listing, and managing PeakURL short links from the terminal",
     "homepage": "https://peakurl.org",
     "bugs": {