peakurl 0.1.2 → 0.3.0

package/README.md

@@ -20,7 +20,7 @@ Sign in with your PeakURL API key:
 
 ```bash
 peakurl login \
-    --base-url https://peakurl.org \
+    --base-url https://example.com/api/v1 \
     --api-key 0123456789abcdef0123456789abcdef0123456789abcdef
 ```
 
@@ -34,34 +34,42 @@ peakurl create \
 
 peakurl list
 peakurl whoami
+peakurl status
+peakurl logout
 ```
 
 ## Authentication
 
 The CLI uses PeakURL bearer API keys and validates them against `GET /api/v1/users/me` before saving credentials.
 
-- `--base-url` accepts either the site root, such as `https://peakurl.org`, or the API base URL, such as `https://peakurl.org/api/v1`
+- `--base-url` expects the explicit API base URL, such as `https://example.com/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:
 
 ```bash
-export PEAKURL_BASE_URL=https://peakurl.org
+export PEAKURL_BASE_URL=https://example.com/api/v1
 export PEAKURL_API_KEY=0123456789abcdef0123456789abcdef0123456789abcdef
 ```
 
 ## Commands
 
-| Command                        | Description                                                |
-| ------------------------------ | ---------------------------------------------------------- |
-| `peakurl login`                | Validate and save your PeakURL credentials.                |
-| `peakurl whoami`               | Show the current authenticated account.                    |
-| `peakurl create <url>`         | Create a new short link.                                   |
-| `peakurl list`                 | List links in your account.                                |
-| `peakurl get <id-or-alias>`    | Fetch a single link by ID or alias.                        |
-| `peakurl delete <id-or-alias>` | Delete a link by ID or alias.                              |
-| `peakurl update`               | Show the latest available CLI version and install command. |
+| Command                        | Description                                                 |
+| ------------------------------ | ----------------------------------------------------------- |
+| `peakurl login`                | Validate and save your PeakURL credentials.                 |
+| `peakurl whoami`               | Show the current authenticated account.                     |
+| `peakurl logout`               | Remove saved local CLI credentials.                         |
+| `peakurl status`               | Show the current system status snapshot for the site.       |
+| `peakurl create <url>`         | Create a new short link.                                    |
+| `peakurl import <file>`        | Import links from a local CSV, JSON, or XML file.           |
+| `peakurl export`               | Export accessible links as CSV, JSON, or XML.               |
+| `peakurl list`                 | List links in your account.                                 |
+| `peakurl get <id-or-alias>`    | Fetch a single link by ID or alias.                         |
+| `peakurl delete <id-or-alias>` | Delete a link by ID or alias.                               |
+| `peakurl webhook <subcommand>` | List, create, delete, and inspect supported webhook events. |
+| `peakurl update`               | Show the latest available CLI version and install command.  |
 
 ## Examples
 
@@ -88,6 +96,28 @@ Inspect a link:
 peakurl get example
 ```
 
+Log out from saved local credentials:
+
+```bash
+peakurl logout
+```
+
+Show the current system status:
+
+```bash
+peakurl status
+```
+
+The status command calls `GET /api/v1/system/status` and prints summary, checks, plus site, server, database, storage, mail, location, and data tables when that information is available.
+
+This route typically requires admin access on the PeakURL install.
+
+If you need the raw payload:
+
+```bash
+peakurl status --json
+```
+
 Delete a link:
 
 ```bash
@@ -96,6 +126,55 @@ peakurl delete example
 
 When `delete` receives an alias or short code, the CLI resolves it to the underlying PeakURL row ID before deleting it.
 
+Import links from a local file:
+
+```bash
+peakurl import ./links.csv
+```
+
+The import command accepts dashboard-style CSV, JSON, and XML files, normalizes them locally, and sends the API-native `urls` array to `POST /api/v1/urls/bulk`.
+
+Export links as CSV:
+
+```bash
+peakurl export --format csv
+```
+
+Write the exported JSON snapshot to stdout:
+
+```bash
+peakurl export --format json --stdout
+```
+
+List configured webhooks:
+
+```bash
+peakurl webhook list
+```
+
+Create a webhook:
+
+```bash
+peakurl webhook create \
+    https://example.com/api/webhooks/peakurl \
+    --event link.clicked \
+    --event link.created
+```
+
+The create command prints the signing secret once, so save it before closing the terminal output.
+
+List supported webhook events:
+
+```bash
+peakurl webhook events
+```
+
+Delete a webhook:
+
+```bash
+peakurl webhook delete webhook_123
+```
+
 Check the latest available CLI version:
 
 ```bash
@@ -126,6 +205,23 @@ 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/>