peakurl 0.3.0 → 0.3.2

package/README.md

@@ -1,5 +1,7 @@
 # PeakURL - Command-Line Interface
 
+![PeakURL CLI](https://github.com/PeakURL/PeakURL/blob/main/.github/images/peakurl-cli.jpg?raw=1)
+
 The official command-line interface for PeakURL.
 
 Use `peakurl` to create short links, inspect existing links, and manage your PeakURL account from the terminal.
@@ -11,7 +13,7 @@ Learn more in the full CLI docs: <https://peakurl.org/docs/cli>
 Node.js 20 or later is required.
 
 ```bash
-npm install -g peakurl
+npm i -g peakurl
 ```
 
 ## Quick Start
@@ -190,7 +192,7 @@ peakurl update
 Install the latest version manually:
 
 ```bash
-npm install -g peakurl@latest
+npm i -g peakurl@latest
 ```
 
 Disable update notices in the current shell:
@@ -205,27 +207,10 @@ export PEAKURL_DISABLE_UPDATE_CHECK=1
 - `--json` prints machine-readable JSON where supported
 - `--quiet` minimizes output for scripts
 
-If you run an authenticated command before logging in, the CLI explains what to do next and shows the command to retry:
-
-```text
-Authentication required.
-PeakURL could not find credentials for this command.
-Use one of the first two steps below, then run the last command.
-+---------------------------+-----------------------------------------------------+-----------------------------------------+
-| Step                      | Command                                             | Notes                                   |
-+---------------------------+-----------------------------------------------------+-----------------------------------------+
-| Save credentials          | peakurl login --base-url https://example.com/api/v1 | Regular use on this machine             |
-|                           | --api-key YOUR_API_KEY                              |                                         |
-| Set environment variables | PEAKURL_BASE_URL=https://example.com/api/v1         | CI, scripts, or one-off use             |
-|                           | PEAKURL_API_KEY=YOUR_API_KEY                        |                                         |
-| Then run                  | peakurl whoami                                      | After completing one of the steps above |
-+---------------------------+-----------------------------------------------------+-----------------------------------------+
-```
-
 ## 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>
+- Issues: <https://github.com/PeakURL/CLI/issues>

package/bin/peakurl.js

@@ -1539,7 +1539,7 @@ function compareSemver(left, right) {
   return comparePrerelease(parsedLeft.prerelease, parsedRight.prerelease);
 }
 function getUpdateInstallCommand() {
-  return `npm install -g ${PACKAGE_NAME}@latest`;
+  return `npm i -g ${PACKAGE_NAME}@latest`;
 }
 async function fetchLatestVersion(env) {
   const registryUrl = normalizeRegistryUrl(getRegistryBaseUrl(env));
@@ -2168,6 +2168,17 @@ function parseNumber(label) {
     return parsed;
   };
 }
+function addExamples(command, lines) {
+  return command.addHelpText(
+    "after",
+    `
+Examples:
+${lines.map((line) => `  ${line}`).join("\n")}
+
+Documentation:
+  https://peakurl.org/docs/cli`
+  );
+}
 async function getCliVersion() {
   const packageJson = new URL("../package.json", import.meta.url);
   const content = await readFile3(packageJson, "utf8");
@@ -2190,23 +2201,26 @@ function getRetryCommandName(argv) {
 async function main() {
   const program = new Command();
   const version = await getCliVersion();
-  program.name("peakurl").description("PeakURL command-line interface").version(version).showHelpAfterError().showSuggestionAfterError().addHelpText(
+  program.name("peakurl").description("Manage your PeakURL site from the terminal.").helpOption("-h, --help", "Show help").helpCommand("help [command]", "Show help for a command").version(version, "-V, --version", "Show CLI version").showHelpAfterError().showSuggestionAfterError().addHelpText(
     "after",
     `
-Examples:
-  peakurl login --base-url https://example.com/api/v1 --api-key 0123456789abcdef0123456789abcdef0123456789abcdef
-  peakurl whoami --json
-  peakurl logout
+Get Started:
+  peakurl login --base-url https://example.com/api/v1 --api-key YOUR_API_KEY
+  peakurl whoami
+  peakurl create https://example.com/docs --alias docs
+
+Common Commands:
   peakurl status
-  peakurl create https://example.com --alias example
+  peakurl list --limit 10
   peakurl import ./links.csv
   peakurl export --format csv
-  peakurl list --limit 10
   peakurl webhook list
-  peakurl webhook create https://example.com/api/webhooks/peakurl --event link.clicked
   peakurl update --check
-  peakurl get example
-  peakurl delete example --quiet`
+
+Documentation:
+  https://peakurl.org/docs/cli
+
+Run 'peakurl <command> --help' for command-specific flags and examples.`
   ).exitOverride();
   program.hook("preAction", async (_command, actionCommand) => {
     const options = actionCommand.optsWithGlobals();
@@ -2217,43 +2231,120 @@ Examples:
       env: process.env
     });
   });
-  program.command("login").description(
-    "Save PeakURL credentials after verifying them with GET /users/me."
-  ).option(
-    "--base-url <url>",
-    "PeakURL API base URL, for example https://example.com/api/v1"
-  ).option("--api-key <token>", "PeakURL API key to store").option("--json", "Print machine-readable output").option("--quiet", "Suppress success output").action(login);
-  program.command("whoami").description("Show the current authenticated PeakURL user.").option("--json", "Print machine-readable output").option("--quiet", "Print a minimal identity value").action(whoami);
-  program.command("logout").description("Remove saved PeakURL credentials from this device.").option("--json", "Print machine-readable output").option("--quiet", "Suppress success output").action(logout);
-  program.command("status").description("Show the current PeakURL system status snapshot.").option("--json", "Print machine-readable output").option("--quiet", "Print only the overall health value").action(status);
-  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(createLink);
-  program.command("import").description(
-    "Import multiple short links from a local CSV, JSON, or XML file."
-  ).argument("<file>", "Path to the import file").option("--format <format>", "File format: csv, json, or xml").option("--json", "Print machine-readable output").option("--quiet", "Print only the created short URLs").action(importLinks);
-  program.command("export").description(
-    "Export accessible links as a local CSV, JSON, or XML file."
-  ).option("--format <format>", "File format: csv, json, or xml").option("--output <path>", "Write the export to a specific file").option("--stdout", "Write the raw export content to stdout").option("--search <query>", "Search term").option("--sort-by <field>", "Sort field").option("--sort-order <order>", "Sort order, for example asc or desc").option("--quiet", "Print only the saved export path").action(exportLinks);
-  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(listLinks);
-  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(getLink);
-  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(deleteLink);
-  program.command("update").description(
-    "Check for a newer CLI version and print the npm command to install it."
-  ).option(
-    "--check",
-    "Alias for checking update status without changing anything"
-  ).option("--json", "Print machine-readable output").option("--quiet", "Print minimal output").action((options) => checkUpdate(options, version));
-  const webhook = program.command("webhook").alias("webhooks").description("Manage outbound webhook integrations.");
-  webhook.command("list").description("List outbound webhooks.").option("--json", "Print machine-readable output").option("--quiet", "Print minimal webhook identifiers").action(listWebhooks);
-  webhook.command("create").description("Create an outbound webhook.").argument("<url>", "Webhook endpoint URL").option(
-    "--event <event>",
-    "Webhook event id, for example link.clicked",
-    parseWebhookEvents
-  ).option("--json", "Print machine-readable output").option("--quiet", "Print only the created webhook ID").action(createWebhook);
-  webhook.command("delete").description("Delete an outbound webhook by id.").argument("<id>", "Webhook identifier").option("--json", "Print machine-readable output").option("--quiet", "Suppress success output").action(deleteWebhook);
-  webhook.command("events").description("List the webhook events supported by the CLI.").option("--json", "Print machine-readable output").option("--quiet", "Print only event ids").action(listWebhookEvents);
+  addExamples(
+    program.command("login").summary("Save API credentials").description(
+      "Save PeakURL credentials after verifying them with GET /users/me."
+    ).helpOption("-h, --help", "Show help").option(
+      "--base-url <url>",
+      "PeakURL API base URL, for example https://example.com/api/v1"
+    ).option("--api-key <token>", "PeakURL API key to store").option("--json", "Print machine-readable output").option("--quiet", "Suppress success output").action(login),
+    [
+      "peakurl login --base-url https://example.com/api/v1 --api-key YOUR_API_KEY",
+      "peakurl login --json"
+    ]
+  );
+  addExamples(
+    program.command("whoami").summary("Show the current account").description("Show the current authenticated PeakURL user.").helpOption("-h, --help", "Show help").option("--json", "Print machine-readable output").option("--quiet", "Print a minimal identity value").action(whoami),
+    ["peakurl whoami", "peakurl whoami --json"]
+  );
+  addExamples(
+    program.command("logout").summary("Remove saved credentials").description("Remove saved PeakURL credentials from this device.").helpOption("-h, --help", "Show help").option("--json", "Print machine-readable output").option("--quiet", "Suppress success output").action(logout),
+    ["peakurl logout", "peakurl logout --json"]
+  );
+  addExamples(
+    program.command("status").summary("Show site system status").description("Show the current PeakURL system status snapshot.").helpOption("-h, --help", "Show help").option("--json", "Print machine-readable output").option("--quiet", "Print only the overall health value").action(status),
+    ["peakurl status", "peakurl status --json", "peakurl status --quiet"]
+  );
+  addExamples(
+    program.command("create").summary("Create a short link").description("Create a PeakURL short link.").helpOption("-h, --help", "Show help").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(createLink),
+    [
+      "peakurl create https://example.com/docs --alias docs",
+      'peakurl create https://example.com/launch --title "Launch Page"',
+      "peakurl create https://example.com --json"
+    ]
+  );
+  addExamples(
+    program.command("import").summary("Import links from a file").description(
+      "Import multiple short links from a local CSV, JSON, or XML file."
+    ).helpOption("-h, --help", "Show help").argument("<file>", "Path to the import file").option("--format <format>", "File format: csv, json, or xml").option("--json", "Print machine-readable output").option("--quiet", "Print only the created short URLs").action(importLinks),
+    ["peakurl import ./links.csv", "peakurl import ./links.xml --json"]
+  );
+  addExamples(
+    program.command("export").summary("Export links to a file").description(
+      "Export accessible links as a local CSV, JSON, or XML file."
+    ).helpOption("-h, --help", "Show help").option("--format <format>", "File format: csv, json, or xml").option("--output <path>", "Write the export to a specific file").option("--stdout", "Write the raw export content to stdout").option("--search <query>", "Search term").option("--sort-by <field>", "Sort field").option(
+      "--sort-order <order>",
+      "Sort order, for example asc or desc"
+    ).option("--quiet", "Print only the saved export path").action(exportLinks),
+    [
+      "peakurl export --format csv",
+      "peakurl export --format json --stdout",
+      "peakurl export --format xml --output ./backups/links.xml"
+    ]
+  );
+  addExamples(
+    program.command("list").summary("List short links").description("List PeakURL short links.").helpOption("-h, --help", "Show help").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(listLinks),
+    [
+      "peakurl list",
+      "peakurl list --limit 25 --page 1",
+      "peakurl list --search launch --json"
+    ]
+  );
+  addExamples(
+    program.command("get").summary("Show one short link").description("Fetch a single PeakURL short link by id or alias.").helpOption("-h, --help", "Show help").argument("<id-or-alias>", "Link identifier or alias").option("--json", "Print machine-readable output").option("--quiet", "Print only the short URL").action(getLink),
+    ["peakurl get docs", "peakurl get url_123 --json"]
+  );
+  addExamples(
+    program.command("delete").summary("Delete one short link").description("Delete a PeakURL short link by id or alias.").helpOption("-h, --help", "Show help").argument("<id-or-alias>", "Link identifier or alias").option("--json", "Print machine-readable output").option("--quiet", "Suppress success output").action(deleteLink),
+    ["peakurl delete docs", "peakurl delete url_123 --quiet"]
+  );
+  addExamples(
+    program.command("update").summary("Check for CLI updates").description(
+      "Check for a newer CLI version and print the npm command to install it."
+    ).helpOption("-h, --help", "Show help").option(
+      "--check",
+      "Alias for checking update status without changing anything"
+    ).option("--json", "Print machine-readable output").option("--quiet", "Print minimal output").action((options) => checkUpdate(options, version)),
+    ["peakurl update", "peakurl update --check", "peakurl update --json"]
+  );
+  const webhook = program.command("webhook").alias("webhooks").summary("Manage webhooks").helpOption("-h, --help", "Show help").description("Manage outbound webhook integrations.");
+  addExamples(webhook, [
+    "peakurl webhook list",
+    "peakurl webhook create https://example.com/api/webhooks/peakurl --event link.clicked",
+    "peakurl webhook events"
+  ]);
+  addExamples(
+    webhook.command("list").summary("List webhooks").description("List outbound webhooks.").helpOption("-h, --help", "Show help").option("--json", "Print machine-readable output").option("--quiet", "Print minimal webhook identifiers").action(listWebhooks),
+    ["peakurl webhook list", "peakurl webhook list --json"]
+  );
+  addExamples(
+    webhook.command("create").summary("Create a webhook").description("Create an outbound webhook.").helpOption("-h, --help", "Show help").argument("<url>", "Webhook endpoint URL").option(
+      "--event <event>",
+      "Webhook event id, for example link.clicked",
+      parseWebhookEvents
+    ).option("--json", "Print machine-readable output").option("--quiet", "Print only the created webhook ID").action(createWebhook),
+    [
+      "peakurl webhook create https://example.com/api/webhooks/peakurl --event link.clicked",
+      "peakurl webhook create https://example.com/api/webhooks/peakurl --event link.clicked --event link.created"
+    ]
+  );
+  addExamples(
+    webhook.command("delete").summary("Delete a webhook").description("Delete an outbound webhook by id.").helpOption("-h, --help", "Show help").argument("<id>", "Webhook identifier").option("--json", "Print machine-readable output").option("--quiet", "Suppress success output").action(deleteWebhook),
+    ["peakurl webhook delete webhook_123"]
+  );
+  addExamples(
+    webhook.command("events").summary("List supported events").description("List the webhook events supported by the CLI.").helpOption("-h, --help", "Show help").option("--json", "Print machine-readable output").option("--quiet", "Print only event ids").action(listWebhookEvents),
+    ["peakurl webhook events", "peakurl webhook events --json"]
+  );
   try {
     await program.parseAsync(process.argv);
   } catch (error) {

package/package.json

@@ -1,14 +1,14 @@
 {
     "name": "peakurl",
-    "version": "0.3.0",
+    "version": "0.3.2",
     "description": "Official CLI for creating, listing, and managing PeakURL short links from the terminal",
     "homepage": "https://peakurl.org",
     "bugs": {
-        "url": "https://github.com/PeakURL/PeakURL-CLI/issues"
+        "url": "https://github.com/PeakURL/CLI/issues"
     },
     "repository": {
         "type": "git",
-        "url": "git+https://github.com/PeakURL/PeakURL-CLI.git"
+        "url": "git+https://github.com/PeakURL/CLI.git"
     },
     "keywords": [
         "peakurl",