peakurl 0.0.1 → 0.0.2

package/README.md

@@ -0,0 +1,113 @@
+# PeakURL CLI
+
+`peakurl` is the official command-line interface for PeakURL.
+
+## Install
+
+```bash
+npm install -g peakurl
+```
+
+The npm package name is unscoped and the executable is also `peakurl`.
+
+## Authentication
+
+The CLI uses a PeakURL API key and validates it with `GET /api/v1/users/me` before storing it.
+PeakURL API keys are opaque 48-character hex bearer tokens, for example `0123456789abcdef0123456789abcdef0123456789abcdef`.
+The CLI accepts either the site root URL such as `https://peakurl.org` or the dashboard-exposed API base URL such as `https://peakurl.org/api/v1`.
+
+```bash
+peakurl login --base-url https://peakurl.org --api-key 0123456789abcdef0123456789abcdef0123456789abcdef
+```
+
+You can also provide credentials through environment variables, which is useful in CI:
+
+```bash
+export PEAKURL_BASE_URL=https://peakurl.org
+export PEAKURL_API_KEY=0123456789abcdef0123456789abcdef0123456789abcdef
+```
+
+Stored credentials live in the OS-standard per-user config directory for `peakurl`.
+
+## Commands
+
+### `peakurl login`
+
+```bash
+peakurl login --base-url https://peakurl.org --api-key 0123456789abcdef0123456789abcdef0123456789abcdef
+```
+
+### `peakurl whoami`
+
+```bash
+peakurl whoami
+peakurl whoami --json
+```
+
+### `peakurl create <url>`
+
+```bash
+peakurl create https://example.com/articles/launch --alias launch --title "Launch Post"
+peakurl create https://example.com --json
+```
+
+### `peakurl list`
+
+```bash
+peakurl list
+peakurl list --search launch --limit 10 --json
+```
+
+### `peakurl get <id-or-alias>`
+
+```bash
+peakurl get launch
+peakurl get 681f3b63e7e44c0a1e83aa11 --json
+```
+
+### `peakurl delete <id-or-alias>`
+
+```bash
+peakurl delete launch
+peakurl delete 681f3b63e7e44c0a1e83aa11 --quiet
+```
+
+When you pass an alias or short code to `delete`, the CLI resolves it to the
+stable PeakURL row ID first because the current backend delete route operates on
+IDs.
+
+## Flags
+
+Common flags:
+
+- `--json` prints machine-readable output.
+- `--quiet` prints minimal output for scripts.
+
+Create flags:
+
+- `--alias`
+- `--title`
+- `--password`
+- `--status`
+- `--expires-at`
+- `--utm-source`
+- `--utm-medium`
+- `--utm-campaign`
+- `--utm-term`
+- `--utm-content`
+
+List flags:
+
+- `--page`
+- `--limit`
+- `--search`
+- `--sort-by`
+- `--sort-order`
+
+## Development
+
+```bash
+npm install
+npm run typecheck
+npm test
+```

package/dist/index.js

@@ -0,0 +1,708 @@
+#!/usr/bin/env node
+
+// src/index.ts
+import { readFile as readFile2 } from "fs/promises";
+import { Command, CommanderError, InvalidArgumentError } from "commander";
+
+// src/lib/errors.ts
+var CliError = class extends Error {
+  exitCode;
+  constructor(message, exitCode = 1, options) {
+    super(message, options);
+    this.name = "CliError";
+    this.exitCode = exitCode;
+  }
+};
+function toCliError(error) {
+  if (error instanceof CliError) {
+    return error;
+  }
+  if (error instanceof Error) {
+    return new CliError(error.message, 1, { cause: error });
+  }
+  return new CliError("Unexpected error.");
+}
+
+// src/lib/url.ts
+function normalizeBaseUrl(value) {
+  const input = value.trim();
+  if (!input) {
+    throw new CliError("A PeakURL base URL is required.");
+  }
+  let parsed;
+  try {
+    parsed = new URL(input);
+  } 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.");
+  }
+  parsed.hash = "";
+  parsed.search = "";
+  const pathname = parsed.pathname.replace(/\/+$/, "");
+  const installPath = pathname.replace(/\/api\/v1$/i, "");
+  return installPath ? `${parsed.origin}${installPath}` : parsed.origin;
+}
+function buildApiUrl(baseUrl, path, query) {
+  const cleanBaseUrl = normalizeBaseUrl(baseUrl);
+  const cleanPath = path.replace(/^\/+/, "");
+  const url = new URL(`api/v1/${cleanPath}`, `${cleanBaseUrl}/`);
+  for (const [key, value] of Object.entries(query ?? {})) {
+    if (value === void 0 || value === "") {
+      continue;
+    }
+    url.searchParams.set(key, String(value));
+  }
+  return url.toString();
+}
+function normalizeDestinationUrl(value) {
+  const input = value.trim();
+  if (!input) {
+    throw new CliError("A destination URL is required.");
+  }
+  try {
+    return new URL(input).toString();
+  } catch {
+    throw new CliError(`Invalid destination URL: ${value}`);
+  }
+}
+
+// src/api/client.ts
+function isEnvelope(value) {
+  return Boolean(
+    value && typeof value === "object" && "success" in value && "message" in value && "timestamp" in value
+  );
+}
+function formatNetworkError(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 {
+  /**
+   * Creates a client bound to one resolved credential set.
+   *
+   * @param config Normalized base URL plus bearer API key.
+   */
+  constructor(config) {
+    this.config = config;
+  }
+  config;
+  /**
+   * Loads the currently authenticated user.
+   *
+   * PeakURL accepts bearer API keys on `GET /users/me`, which is also the
+   * CLI login verification flow.
+   *
+   * @returns API response envelope containing the authenticated user.
+   */
+  whoami() {
+    return this.request("GET", "users/me");
+  }
+  /**
+   * Creates a short URL.
+   *
+   * @param payload Request body accepted by `POST /api/v1/urls`.
+   * @returns API response envelope containing the created link.
+   */
+  createUrl(payload) {
+    return this.request("POST", "urls", payload);
+  }
+  /**
+   * Lists short URLs with optional pagination and filtering.
+   *
+   * The current PeakURL app returns `{ items, meta }` under `data`, but the
+   * CLI keeps a slightly broader compatibility type for future-proofing.
+   *
+   * @param query Optional query-string values.
+   * @returns API response envelope containing list data.
+   */
+  listUrls(query) {
+    return this.request(
+      "GET",
+      "urls",
+      void 0,
+      query
+    );
+  }
+  /**
+   * Loads a single short URL by identifier or alias.
+   *
+   * PeakURL resolves IDs, short codes, and aliases through the same route.
+   *
+   * @param idOrAlias Link identifier, short code, or alias.
+   * @returns API response envelope containing the resolved link.
+   */
+  getUrl(idOrAlias) {
+    return this.request(
+      "GET",
+      `urls/${encodeURIComponent(idOrAlias)}`
+    );
+  }
+  /**
+   * Deletes a short URL by its stable row ID.
+   *
+   * The current PeakURL backend delete route expects the row ID. The CLI can
+   * still accept an alias at the command layer by resolving it first.
+   *
+   * @param id Stable link row ID.
+   * @returns API response envelope containing the deletion result.
+   */
+  deleteUrl(id) {
+    return this.request(
+      "DELETE",
+      `urls/${encodeURIComponent(id)}`
+    );
+  }
+  /**
+   * Performs one authenticated API request and normalizes the response.
+   *
+   * @param method HTTP method to send.
+   * @param path Route path relative to `/api/v1`.
+   * @param body Optional JSON body.
+   * @param query Optional query-string values.
+   * @returns Parsed PeakURL response envelope.
+   * @throws {CliError} When the network request fails or the API returns an error.
+   */
+  async request(method, path, body, query) {
+    const url = buildApiUrl(this.config.baseUrl, path, query);
+    let response;
+    try {
+      response = await fetch(url, {
+        method,
+        headers: {
+          Accept: "application/json",
+          Authorization: `Bearer ${this.config.apiKey}`,
+          ...body ? { "Content-Type": "application/json" } : {}
+        },
+        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
+        }
+      );
+    }
+    const rawText = await response.text();
+    if (!rawText) {
+      if (!response.ok) {
+        throw new CliError(
+          `PeakURL request failed with HTTP ${response.status}.`
+        );
+      }
+      return {
+        success: true,
+        message: "Request completed.",
+        data: void 0,
+        timestamp: (/* @__PURE__ */ new Date()).toISOString()
+      };
+    }
+    let parsed;
+    try {
+      parsed = JSON.parse(rawText);
+    } catch {
+      if (!response.ok) {
+        throw new CliError(
+          `PeakURL request failed with HTTP ${response.status}.`
+        );
+      }
+      throw new CliError("PeakURL returned an invalid JSON response.");
+    }
+    if (!isEnvelope(parsed)) {
+      throw new CliError(
+        "PeakURL returned an unexpected response envelope."
+      );
+    }
+    if (!response.ok || !parsed.success) {
+      const statusCode = response.status === 401 ? 2 : 1;
+      throw new CliError(
+        parsed.message || `PeakURL request failed with HTTP ${response.status}.`,
+        statusCode
+      );
+    }
+    return parsed;
+  }
+};
+
+// src/config/store.ts
+import { chmod, mkdir, readFile, writeFile } from "fs/promises";
+import { dirname, join } from "path";
+import envPaths from "env-paths";
+var CONFIG_FILENAME = "config.json";
+function defaultConfigPath() {
+  return join(envPaths("peakurl", { suffix: "" }).config, CONFIG_FILENAME);
+}
+var ConfigStore = class {
+  filePath;
+  /**
+   * Creates a config store bound to one on-disk file.
+   *
+   * @param filePath Optional override used by tests or advanced callers.
+   */
+  constructor(filePath = defaultConfigPath()) {
+    this.filePath = filePath;
+  }
+  /**
+   * Loads the stored credential set from disk.
+   *
+   * Missing files are treated as "not configured yet" instead of as hard
+   * errors so first-run CLI flows remain clean.
+   *
+   * @returns Stored config or `null` when the file does not exist.
+   * @throws {CliError} When the file exists but is unreadable or invalid.
+   */
+  async load() {
+    try {
+      const content = await readFile(this.filePath, "utf8");
+      const parsed = JSON.parse(content);
+      if (typeof parsed.baseUrl !== "string" || typeof parsed.apiKey !== "string") {
+        throw new CliError(`Invalid config file: ${this.filePath}`);
+      }
+      return {
+        baseUrl: parsed.baseUrl,
+        apiKey: parsed.apiKey
+      };
+    } catch (error) {
+      if (error instanceof Error && "code" in error && typeof error.code === "string" && error.code === "ENOENT") {
+        return null;
+      }
+      if (error instanceof CliError) {
+        throw error;
+      }
+      throw new CliError(
+        `Could not read PeakURL config at ${this.filePath}.`,
+        1,
+        {
+          cause: error instanceof Error ? error : void 0
+        }
+      );
+    }
+  }
+  /**
+   * Persists one credential set to disk with restrictive file permissions.
+   *
+   * The chmod step is best-effort because Windows and some filesystems do not
+   * expose POSIX permission bits in the same way as Unix-like systems.
+   *
+   * @param config Normalized credential set to write.
+   */
+  async save(config) {
+    const directory = dirname(this.filePath);
+    await mkdir(directory, { recursive: true, mode: 448 });
+    await writeFile(this.filePath, `${JSON.stringify(config, null, 2)}
+`, {
+      mode: 384
+    });
+    try {
+      await chmod(directory, 448);
+      await chmod(this.filePath, 384);
+    } catch {
+    }
+  }
+};
+
+// src/lib/auth.ts
+function resolveLoginConfig(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) {
+    throw new CliError(
+      "Missing credentials. Provide --base-url and --api-key, or set PEAKURL_BASE_URL and PEAKURL_API_KEY."
+    );
+  }
+  return {
+    baseUrl: normalizeBaseUrl(baseUrl),
+    apiKey
+  };
+}
+async function resolveStoredConfig(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."
+    );
+  }
+  return {
+    baseUrl: normalizeBaseUrl(baseUrl),
+    apiKey
+  };
+}
+
+// src/lib/links.ts
+var LIST_KEYS = ["urls", "items", "results"];
+function asRecord(value) {
+  return value && typeof value === "object" && !Array.isArray(value) ? value : null;
+}
+function readString(value) {
+  return typeof value === "string" && value.trim() ? value.trim() : void 0;
+}
+function readNumber(value) {
+  return typeof value === "number" && Number.isFinite(value) ? value : void 0;
+}
+function firstString(link, keys) {
+  for (const key of keys) {
+    const value = readString(link[key]);
+    if (value) {
+      return value;
+    }
+  }
+  return void 0;
+}
+function truncate(value, maxLength) {
+  return value.length > maxLength ? `${value.slice(0, maxLength - 1)}\u2026` : value;
+}
+function extractListMeta(data) {
+  const record = asRecord(data);
+  if (!record) {
+    return null;
+  }
+  const meta = asRecord(record.meta);
+  if (meta) {
+    return {
+      page: readNumber(meta.page),
+      limit: readNumber(meta.limit),
+      totalItems: readNumber(meta.totalItems),
+      totalPages: readNumber(meta.totalPages)
+    };
+  }
+  return {
+    page: readNumber(record.page),
+    limit: readNumber(record.limit),
+    totalItems: readNumber(record.total),
+    totalPages: readNumber(record.totalPages)
+  };
+}
+function extractLinks(data) {
+  if (Array.isArray(data)) {
+    return data;
+  }
+  const record = asRecord(data);
+  if (record) {
+    for (const key of LIST_KEYS) {
+      const value = record[key];
+      if (Array.isArray(value)) {
+        return value;
+      }
+    }
+  }
+  return [];
+}
+function getLinkId(link) {
+  return firstString(link, ["id", "_id", "urlId"]) || (link.id !== void 0 ? String(link.id) : void 0);
+}
+function getLinkAlias(link) {
+  return firstString(link, ["alias", "shortCode", "slug", "code"]);
+}
+function getLinkShortUrl(link) {
+  return firstString(link, ["shortUrl", "shortLink", "shortURL", "url"]);
+}
+function getLinkDestination(link) {
+  return firstString(link, [
+    "destinationUrl",
+    "originalUrl",
+    "targetUrl",
+    "destination"
+  ]);
+}
+function getQuietLinkValue(link) {
+  return getLinkShortUrl(link) || getLinkAlias(link) || getLinkId(link) || "";
+}
+function formatLinkDetails(link) {
+  const lines = [
+    ["ID", getLinkId(link)],
+    ["Alias", getLinkAlias(link)],
+    ["Short URL", getLinkShortUrl(link)],
+    ["Destination", getLinkDestination(link)],
+    ["Title", readString(link.title)],
+    ["Status", readString(link.status)],
+    [
+      "Clicks",
+      readNumber(link.clicks) === void 0 ? void 0 : String(link.clicks)
+    ],
+    ["Created", readString(link.createdAt)],
+    ["Updated", readString(link.updatedAt)]
+  ].filter((entry) => Boolean(entry[1]));
+  return lines.map(([label, value]) => `${label}: ${value}`).join("\n");
+}
+function formatLinksTable(links) {
+  if (links.length === 0) {
+    return "No links found.";
+  }
+  const headers = ["ID", "ALIAS", "SHORT URL", "DESTINATION", "STATUS"];
+  const rows = links.map((link) => [
+    truncate(getLinkId(link) || "-", 18),
+    truncate(getLinkAlias(link) || "-", 18),
+    truncate(getLinkShortUrl(link) || "-", 36),
+    truncate(getLinkDestination(link) || "-", 52),
+    truncate(readString(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");
+}
+function formatListSummary(data, count) {
+  const meta = extractListMeta(data);
+  if (!meta) {
+    return `${count} link${count === 1 ? "" : "s"} returned.`;
+  }
+  const total = meta.totalItems;
+  const page = meta.page;
+  const totalPages = meta.totalPages;
+  if (total !== void 0 && page !== void 0 && totalPages !== void 0) {
+    return `Page ${page} of ${totalPages}. ${total} total link${total === 1 ? "" : "s"}.`;
+  }
+  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) {
+    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/commands/whoami.ts
+async function whoamiCommand(options) {
+  const config = await resolveStoredConfig(process.env);
+  const response = await new PeakUrlApiClient(config).whoami();
+  if (options.json) {
+    writeJson(response);
+    return;
+  }
+  if (options.quiet) {
+    writeStdout(getQuietUserValue(response.data));
+    return;
+  }
+  writeStdout(response.message);
+  writeStdout(formatUserDetails(response.data));
+}
+
+// src/index.ts
+function parsePositiveInteger(label) {
+  return (value) => {
+    const parsed = Number.parseInt(value, 10);
+    if (!Number.isInteger(parsed) || parsed <= 0) {
+      throw new InvalidArgumentError(
+        `${label} must be a positive integer.`
+      );
+    }
+    return parsed;
+  };
+}
+async function readVersion() {
+  const packageJson = new URL("../package.json", import.meta.url);
+  const content = await readFile2(packageJson, "utf8");
+  const parsed = JSON.parse(content);
+  return parsed.version || "0.0.0";
+}
+async function main() {
+  const program = new Command();
+  program.name("peakurl").description("PeakURL command-line interface").version(await readVersion()).showHelpAfterError().showSuggestionAfterError().addHelpText(
+    "after",
+    `
+Examples:
+  peakurl login --base-url https://peakurl.org --api-key 0123456789abcdef0123456789abcdef0123456789abcdef
+  peakurl whoami --json
+  peakurl create https://example.com --alias example
+  peakurl list --limit 10
+  peakurl get example
+  peakurl delete example --quiet`
+  ).exitOverride();
+  program.command("login").description(
+    "Save PeakURL credentials after verifying them with GET /users/me."
+  ).option(
+    "--base-url <url>",
+    "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("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("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);
+  try {
+    await program.parseAsync(process.argv);
+  } catch (error) {
+    if (error instanceof CommanderError) {
+      process.exit(error.exitCode);
+    }
+    const cliError = toCliError(error);
+    writeStderr(cliError.message);
+    process.exit(cliError.exitCode);
+  }
+}
+void main();

package/package.json

@@ -1,9 +1,36 @@
 {
     "name": "peakurl",
-    "version": "0.0.1",
-    "description": "PeakURL CLI",
+    "version": "0.0.2",
+    "description": "PeakURL command-line interface",
+    "type": "module",
     "bin": {
-        "peakurl": "./index.js"
+        "peakurl": "dist/index.js"
+    },
+    "files": [
+        "dist"
+    ],
+    "engines": {
+        "node": ">=20"
+    },
+    "scripts": {
+        "build": "tsup src/index.ts --format esm --target node20 --clean",
+        "dev": "tsx src/index.ts",
+        "format": "prettier --write .",
+        "format:check": "prettier --check .",
+        "test": "tsx --test test/**/*.test.ts",
+        "typecheck": "tsc --noEmit",
+        "prepare": "npm run build"
+    },
+    "dependencies": {
+        "commander": "^14.0.0",
+        "env-paths": "^3.0.0"
+    },
+    "devDependencies": {
+        "@types/node": "^24.0.0",
+        "prettier": "^3.6.2",
+        "tsup": "^8.5.0",
+        "tsx": "^4.20.6",
+        "typescript": "^5.9.3"
     },
     "license": "MIT"
 }

package/index.js

@@ -1,3 +0,0 @@
-#!/usr/bin/env node
-
-console.log("PeakURL CLI coming soon 🚀");