@watermarkws/cli 0.0.0-stage → 0.1.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Much Media Inc.
+
+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,3 +1,81 @@
-# Temporary Holding Version
+# Watermark CLI
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Watermark, resize and convert images, videos and PDFs from the command line with the [Watermark API](https://api.watermark.ws/docs). Built for people and for AI agents: `--json` prints machine-readable output and exit codes mean something.
+
+```bash
+export WATERMARK_API_KEY=wm_test_…   # https://watermark.ws/developers
+npx @watermarkws/cli image process https://example.com/photo.jpg \
+  --op resize:width=1600,height=1600 \
+  --op watermark:image_url=https://example.com/logo.png,x=40,y=40 \
+  --format webp --out photo.webp
+```
+
+Node 18+, no dependencies.
+
+## Install
+
+```bash
+brew install watermarkws/tap/watermark   # Homebrew, macOS and Linux
+npm install -g @watermarkws/cli          # npm
+```
+
+Either way the command is `watermark`. Homebrew brings its own Node; `npx @watermarkws/cli` runs it without installing.
+
+## Commands
+
+```
+watermark image process <source> --op <operation> [--op ...] [--format webp] [--out file]
+watermark image read <source> [--level]   # --level also finds the angle that levels a tilted horizon
+watermark image create --width 1200 --height 300 --op 'text:text=Hi,font=inter-bold,size=96' --op trim --out logo.png
+watermark video process <source> --op <operation> [--max-duration 30] [--out file]
+watermark video read <source> | watermark video screenshot <source> --seconds 5
+watermark document process <source> --op <operation> [--max-pages 10] [--out file]
+watermark document read <source> | watermark document snapshot <source> --page 1
+watermark request get <id> | watermark request abort <id>
+watermark requests [--before <id>] | watermark account | watermark usage --group-by endpoint [--customer <id>]
+watermark upload photo.heic | watermark upload get|delete <upl_id>
+watermark file get|delete <file_id>
+watermark storage list | connect --bucket b --region us-east-1 --role-arn <arn> --prefix in/ [--read true|false] [--write true|false] | get|verify|disconnect <stg_id>
+watermark storage update <stg_id> --prefix photos/ --prefix archive/ [--read true|false] [--write true|false]   # the whole new list; checked before it is kept
+watermark events --since 2026-10-13T15:00:00Z
+watermark fonts
+watermark operations image
+```
+
+Processing commands wait for the request to finish (up to `--timeout`, default 300 seconds) unless `--no-wait` is given; `--out` downloads the result.
+
+Operations run in order: `--op type:param=value,param=value`, or all at once with `--ops-json '[{"type":"resize","width":800,"height":600}]'`. `watermark operations` lists them all.
+
+More than one file from a request, each with its own operations and format: `--outputs-json '[{"name":"large","format":"webp"},{"name":"thumb","operations":[{"type":"resize","width":200,"height":200}]}]'`.
+
+Other options: `--webhook <url>`, `--event <type>` (repeatable, such as `request.progress`), `--customer <id>`, `--metadata key=value`, `--idempotency-key <key>`, `--json`, `--api-key`, `--base-url` (or `WATERMARK_API_URL`).
+
+A source is a public http(s) URL, a local file (uploaded first), an upload
+(`upl_…`), a file an earlier request kept (`file_…`), or an object in a
+connected bucket (`stg_7a:path/to/key`).
+
+## Errors
+
+The CLI passes every error code through as the API sends it: `Error 422 validation_failed: …`, with every invalid field below it, or with `--json` the whole error object (`type`, `code`, `message`, `param`, `request_id`, `errors`, and the `permissions_policy` a storage change whose check failed needs). The codes are listed at https://api.watermark.ws/docs/errors.md.
+
+## Exit codes
+
+| Code | Meaning |
+| --- | --- |
+| 0 | Succeeded (or queued, with `--no-wait`). |
+| 1 | The API refused the call, or the request failed or was aborted. The error code is printed. |
+| 2 | The command was used wrongly. |
+
+Rate limits (429) and server errors are retried twice with the same `Idempotency-Key`, so a retry never runs a request twice.
+
+## For AI agents
+
+`SKILL.md` is an [Agent Skill](https://agentskills.io) for this CLI: when to use it, the commands, the output shape, exit codes and the rules an agent should follow (ask before a big batch, never paste file bytes). Save it as `.claude/skills/watermark/SKILL.md` in a project for Claude Code, or paste it into any agent's instructions. The API's own guide for agents, with its MCP server and plain HTTP, is at https://api.watermark.ws/docs/agents.md.
+
+## Development
+
+```bash
+npm test
+```
+
+`test/spec-coverage.test.js` holds the CLI to the API's OpenAPI spec: every endpoint has a command, every parameter is sent, and the spec is the one in `spec/openapi.json`, whose sha256 is in `spec.sha`. It reads the spec from `WATERMARK_API_SPEC` (a path or URL), else `../watermark-api`, else `spec/openapi.json`. When the API changes, update the CLI, then run `npm run spec:refresh` to record the new spec as checked.

package/SKILL.md

@@ -0,0 +1,106 @@
+---
+name: watermark
+description: Watermark, resize, crop, convert and stamp text on images, videos and PDF or Word documents with the Watermark API from the shell, through the `watermark` CLI. Use it when a user wants a logo or text placed on files, a batch of photos resized or converted (JPEG, PNG, WebP, HEIC, camera RAW and more), a video watermarked or trimmed to a preview, a frame or a page saved as an image, or every page of a PDF stamped while it stays a PDF. Sources can be public URLs, local files (uploaded automatically) or files an earlier request made. Needs a WATERMARK_API_KEY from https://watermark.ws/developers.
+---
+
+# Watermark CLI
+
+The `watermark` command sends a file and a list of operations to the Watermark API, waits for the result and downloads it. Use it instead of a local image library for batches, video, PDF/DOCX, camera formats (HEIC, CR3, NEF, ARW, DNG), text in real fonts, and when the result should be a link the user can download.
+
+## Install and set the key
+
+```bash
+npm install -g @watermarkws/cli          # or: brew install watermarkws/tap/watermark
+npx @watermarkws/cli --version           # or run it once without installing (Node 18+)
+export WATERMARK_API_KEY=wm_test_…       # keys: https://watermark.ws/developers
+```
+
+`wm_test_…` keys are free and return real results within small limits (10 requests a minute, 100 a day, sources up to 10 MB, no video). `wm_live_…` keys spend the account's prepaid credit. If the user has no key, send them to https://watermark.ws/developers; new accounts start with $1 of free credit.
+
+## Core commands
+
+A `<source>` is a public http(s) URL, a local file path (uploaded first, automatically), an upload id `upl_…`, a file an earlier request made `file_…`, or `stg_7a:path/key` in a connected bucket. Operations run in the order given: `--op type:param=value,param=value`; numbers and `true`/`false` are typed, everything else is text.
+
+```bash
+watermark image process photo.jpg --op resize:width=1600,height=1600 --op watermark:image_url=https://example.com/logo.png,x=40,y=40 --format webp --out photo.webp
+watermark image read photo.jpg --json                       # width, height, format; add --level for the angle that levels the horizon
+watermark image create --width 1200 --height 300 --op 'text:text=Lena Hart,font=inter-bold,size=96,color=#202020,position=center' --op trim --format png --out logo.png
+watermark video process clip.mp4 --op watermark:image_url=https://example.com/logo.png,x=24,y=24 --max-duration 30 --out preview.mp4
+watermark video screenshot clip.mp4 --seconds 5 --format png --out frame.png
+watermark document process contract.pdf --op watermark:image_url=https://example.com/stamp.png,x=20,y=230 --out contract-stamped.pdf
+watermark document snapshot contract.pdf --page 1 --format png --out page-1.png
+watermark operations image                                   # every operation and parameter, live from the API (also video, document)
+watermark fonts                                              # font names a text operation accepts
+watermark request get 1234                                   # follow a request started with --no-wait
+watermark account                                            # balance and limits
+```
+
+Useful options on processing commands: `--out <file>` (wait, then download), `--no-wait` (print the queued request and return), `--timeout <seconds>` (default 300), `--format <fmt>`, `--ops-json '[…]'` instead of `--op`, `--max-duration <s>` (video), `--max-pages <n>` (documents), `--customer <id>`, `--metadata key=value`, `--json`.
+
+Operations that exist: images `resize`, `crop`, `rotate`, `flip`, `grayscale`, `border`, `watermark`, `thumbnail`, `compress`, `sepia`, `exposure`, `filter`, `remove_background`, `orient`, `text`, `trim`, `color`, `frame`, `protect`, `shave`, `line`, `adjust`, `color_profile`; videos `resize`, `crop`, `rotate`, `flip`, `grayscale`, `border`, `watermark`; documents `watermark` only (an image on every page; make a text stamp with `image create` first). `watermark` takes `image_url` or `image` (a `file_…` id), `x`, `y` from the top left, `tile_spacing_x`/`tile_spacing_y` to repeat it, `diagonal_lines_color`/`diagonal_lines_opacity`. Run `watermark operations image` before using a parameter you are not sure of.
+
+## A folder of files
+
+Prepare the watermark once and reuse its `file_…` id; one request per file after that.
+
+```bash
+logo=$(watermark image process logo.png --op orient --format png --json | jq -r '.result.files[0].id')
+mkdir -p out
+for f in photos/*; do
+  name=$(basename "${f%.*}")
+  watermark image process "$f" --op resize:width=1600,height=1600 --op "watermark:image=$logo,x=40,y=40" --format webp --out "out/$name.webp"
+done
+```
+
+Stamp text across every page of a PDF: make the stamp, then watermark the document with it.
+
+```bash
+stamp=$(watermark image create --width 800 --height 800 --op 'text:text=CONFIDENTIAL,font=inter-bold,size=80,color=#c0392b,opacity=35,position=center,rotation=-30' --op trim --format png --json | jq -r '.result.files[0].id')
+watermark document process contract.pdf --op "watermark:image=$stamp,x=20,y=230" --out contract-confidential.pdf
+```
+
+## Output and exit codes
+
+With `--json`, stdout is only the finished request as the API returns it (progress goes to stderr):
+
+```json
+{"id": 1234, "object": "request", "endpoint": "images/process", "status": "succeeded",
+ "result": {"data": {"width": 1600, "height": 1067, "format": "WEBP"},
+            "files": [{"id": "file_…", "url": "https://…", "url_expires_at": "2026-10-18T15:00:04Z", "format": "webp", "size": 183021}]},
+ "price": {"amount": "0.002000", "currency": "usd"}, "saved_to": "photo.webp"}
+```
+
+A failed request has `"status": "failed"` and `error.code` / `error.message`. An API error with `--json` prints `{"error": {"status": 422, "type": "…", "code": "…", "message": "…", "errors": {…}}}` on stdout. Without `--json`, the result is human-readable lines (`Request 1234 (images/process): succeeded`, `File: https://…`, `Saved to …`, `Price: $0.002000`).
+
+| Exit | Meaning |
+| --- | --- |
+| 0 | The request succeeded (or was queued, with `--no-wait`). |
+| 1 | The API refused the call, or the request failed or was aborted. The error code is printed. |
+| 2 | The command was used wrongly (bad source, missing `--op`, unknown command). |
+
+## Rules
+
+- Never paste file contents or base64 into a command; give the path and the CLI uploads it. Never ask the user to host a local file first.
+- Credit is prepaid and every finished request is charged ($0.002 an image, $0.004 a document page, $0.02 a started minute of video). Before more than about 20 files, a video over about 10 minutes, or a document with hundreds of pages, tell the user the cost and ask.
+- Failed and aborted requests are free; fix the cause (the message names the field) and run again. Rate limits and server errors are retried by the CLI itself.
+- Always pass `--out` when the user wants the file, and `--json` when a script reads the result. Download links in `result.files[].url` last 7 days; `watermark file get <file_id>` gives a fresh one while the file is kept.
+- Video needs a live key on an account that has bought credit; a test key gets `402 paid_account_required`.
+- Check a file before guessing parameters: `watermark image read`, `watermark video read` and `watermark document read` give dimensions, duration and page count.
+
+## Common errors
+
+| Error | Fix |
+| --- | --- |
+| `Set WATERMARK_API_KEY or pass --api-key`, `401 missing_api_key`, `401 invalid_api_key` | No key, or a wrong or revoked key. Export `WATERMARK_API_KEY` from https://watermark.ws/developers. |
+| `402 insufficient_credits` | The account has no credit left. Buy credit at https://watermark.ws/developers. |
+| `402 paid_account_required` | Video, or writing to your own storage, needs an account that has bought credit; a test key cannot. |
+| `422 validation_failed` | A parameter is wrong; the invalid fields are listed under the message. Check `watermark operations <media>`. |
+| `429 rate_limited` / `429 concurrency_limited` | Too many requests a minute, or too many running at once. The CLI retries twice; otherwise wait and run fewer in parallel. |
+| `is not a URL, an id, stg_…:key, or a file here` | The source path does not exist or is not a file. |
+| `Request … was still processing after 300 seconds` | A long video. Rerun with `--timeout 1800`, or `--no-wait` and later `watermark request get <id>`. |
+
+## More
+
+- Agent guide, with MCP server, HTTP and worked examples: https://api.watermark.ws/docs/agents.md
+- Every operation and parameter: https://api.watermark.ws/docs/operations.md
+- Every command and option: `watermark --help`, or https://api.watermark.ws/docs/cli.md

package/bin/watermark.js

@@ -0,0 +1,5 @@
+#!/usr/bin/env node
+import { main } from '../src/cli.js';
+
+main(process.argv.slice(2), { env: process.env, stdout: process.stdout, stderr: process.stderr })
+  .then((code) => { process.exitCode = code; });

package/package.json

@@ -1,6 +1,30 @@
 {
   "name": "@watermarkws/cli",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.1",
+  "description": "Watermark, resize and convert images, videos and PDFs from the command line with the Watermark API.",
+  "type": "module",
+  "bin": {
+    "watermark": "bin/watermark.js"
+  },
+  "files": ["bin", "src", "README.md", "SKILL.md", "LICENSE"],
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "test": "node --test test/",
+    "spec:refresh": "node scripts/refresh-spec.js"
+  },
+  "keywords": ["watermark", "image", "video", "pdf", "cli", "api"],
+  "homepage": "https://api.watermark.ws/docs",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/watermarkws/watermark-cli.git"
+  },
+  "bugs": {
+    "url": "https://github.com/watermarkws/watermark-cli/issues"
+  },
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/src/api.js

@@ -0,0 +1,123 @@
+// A small client for the Watermark API: the key, JSON, typed errors, and
+// retries for 429 (after Retry-After), 5xx and dropped connections, with an
+// Idempotency-Key on every POST so a retried POST never runs twice.
+
+export const VERSION = '0.1.1';
+
+export class ApiError extends Error {
+  constructor(status, error = {}) {
+    super(error.message || `The API answered ${status}.`);
+    this.status = status;
+    this.type = error.type || 'server_error';
+    this.code = error.code || 'unknown';
+    this.param = error.param;
+    this.requestId = error.request_id;
+    this.errors = error.errors;
+    // The whole error object as the API sent it, with the fields some errors
+    // add, such as a storage change's permissions_policy.
+    this.error = error;
+  }
+}
+
+export class Api {
+  constructor({ apiKey, baseUrl = 'https://api.watermark.ws', fetch = globalThis.fetch, sleep, maxRetries = 2 }) {
+    if (!apiKey) {
+      throw new Error('Set WATERMARK_API_KEY or pass --api-key. Get a key at https://watermark.ws/developers');
+    }
+    this.apiKey = apiKey;
+    this.baseUrl = baseUrl.replace(/\/+$/, '');
+    this.fetch = fetch;
+    this.sleep = sleep || ((ms) => new Promise((resolve) => setTimeout(resolve, ms)));
+    this.maxRetries = maxRetries;
+  }
+
+  async request(method, path, { body, query, idempotencyKey } = {}) {
+    const url = new URL(this.baseUrl + path);
+    for (const [key, value] of Object.entries(query || {})) {
+      if (value !== undefined && value !== null) url.searchParams.set(key, String(value));
+    }
+
+    const headers = {
+      Authorization: `Bearer ${this.apiKey}`,
+      Accept: 'application/json',
+      'User-Agent': `watermark-cli/${VERSION} node/${process.versions.node}`,
+    };
+    if (body !== undefined) headers['Content-Type'] = 'application/json';
+    if (method === 'POST') headers['Idempotency-Key'] = idempotencyKey || crypto.randomUUID();
+
+    for (let attempt = 0; ; attempt++) {
+      let response;
+      try {
+        response = await this.fetch(url, { method, headers, body: body === undefined ? undefined : JSON.stringify(body) });
+      } catch (error) {
+        if (attempt >= this.maxRetries) throw error;
+        await this.sleep(500 * 2 ** attempt);
+        continue;
+      }
+
+      if ((response.status === 429 || response.status >= 500) && attempt < this.maxRetries) {
+        const retryAfter = Number(response.headers.get('retry-after'));
+        await this.sleep(Number.isFinite(retryAfter) && retryAfter > 0 ? Math.min(retryAfter, 60) * 1000 : 500 * 2 ** attempt);
+        continue;
+      }
+
+      const text = await response.text();
+      const json = text ? JSON.parse(text) : {};
+      if (response.status >= 400) throw new ApiError(response.status, json.error);
+      return json;
+    }
+  }
+
+  // Wait for a request to be succeeded, failed or aborted. Each call asks the
+  // API to hold the response until the request finishes (up to 25 seconds),
+  // so the result comes back as soon as it is ready.
+  async wait(id, { timeoutMs = 300_000, intervalMs = 1000, onProgress } = {}) {
+    const started = Date.now();
+    for (;;) {
+      const hold = Math.max(0, Math.min(25, Math.floor((timeoutMs - (Date.now() - started)) / 1000)));
+      const before = Date.now();
+      const request = await this.request('GET', `/v1/requests/${id}`, { query: { wait: hold || undefined } });
+      if (['succeeded', 'failed', 'aborted'].includes(request.status)) return request;
+      if (onProgress) onProgress(request);
+      if (Date.now() - started >= timeoutMs) {
+        throw new Error(`Request ${id} was still ${request.status} after ${Math.round(timeoutMs / 1000)} seconds.`);
+      }
+      if (hold > 0 && Date.now() - before >= (hold - 1) * 1000) continue;
+      await this.sleep(intervalMs);
+      intervalMs = Math.min(5000, intervalMs * 1.5);
+    }
+  }
+
+  // Make an upload for a local file and PUT the file to its URL. Its id is
+  // then a request's source.
+  async upload(path, { readFile, contentType } = {}) {
+    const bytes = await readFile(path);
+    const filename = path.split(/[\\/]/).pop();
+    const type = contentType || contentTypeOf(filename);
+    const upload = await this.request('POST', '/v1/uploads', { body: { filename, size: bytes.length, content_type: type } });
+
+    const response = await this.fetch(upload.upload.url, {
+      method: 'PUT',
+      headers: upload.upload.headers || { 'Content-Type': type },
+      body: bytes,
+    });
+    if (!response.ok) throw new Error(`Sending ${filename} failed: HTTP ${response.status}.`);
+
+    return upload;
+  }
+}
+
+const CONTENT_TYPES = {
+  jpg: 'image/jpeg', jpeg: 'image/jpeg', png: 'image/png', gif: 'image/gif', webp: 'image/webp', avif: 'image/avif',
+  heic: 'image/heic', heif: 'image/heif', tif: 'image/tiff', tiff: 'image/tiff',
+  bmp: 'image/bmp', svg: 'image/svg+xml', psd: 'image/vnd.adobe.photoshop',
+  cr2: 'image/x-canon-cr2', cr3: 'image/x-canon-cr3', nef: 'image/x-nikon-nef', arw: 'image/x-sony-arw',
+  dng: 'image/x-adobe-dng', raf: 'image/x-fuji-raf', orf: 'image/x-olympus-orf', rw2: 'image/x-panasonic-rw2',
+  mp4: 'video/mp4', mov: 'video/quicktime', m4v: 'video/x-m4v', webm: 'video/webm', mkv: 'video/x-matroska',
+  avi: 'video/x-msvideo', flv: 'video/x-flv', wmv: 'video/x-ms-wmv', mpg: 'video/mpeg',
+  pdf: 'application/pdf', docx: 'application/vnd.openxmlformats-officedocument.wordprocessingml.document',
+};
+
+export function contentTypeOf(filename) {
+  return CONTENT_TYPES[(filename.split('.').pop() || '').toLowerCase()] || 'application/octet-stream';
+}

package/src/cli.js

@@ -0,0 +1,407 @@
+import { readFile, stat, writeFile } from 'node:fs/promises';
+import { Api, ApiError, VERSION } from './api.js';
+
+const HELP = `watermark: the Watermark API from the command line (https://api.watermark.ws/docs)
+
+Usage:
+  watermark image process <source> --op <operation> [--op ...] [--format webp] [--out file]
+  watermark image read <source> [--level]
+  watermark image create --width 1200 --height 300 [--background "#ffffff"] --op <operation> [--out file]
+  watermark video process <source> --op <operation> [--max-duration 30] [--out file]
+  watermark video read <source>
+  watermark video screenshot <source> --seconds 5 [--format png] [--out file]
+  watermark document process <source> --op <operation> [--max-pages 10] [--out file]
+  watermark document read <source>
+  watermark document snapshot <source> [--page 1] [--format png] [--out file]
+  watermark request get <id> | watermark request abort <id>
+  watermark requests [--limit 20] [--before <id>]
+  watermark upload <file> | watermark upload get|delete <upl_id>
+  watermark file get|delete <file_id>
+  watermark storage list | get|verify|disconnect <stg_id>
+  watermark storage connect --bucket <name> --region <region> --role-arn <arn> --prefix in/ [--prefix ...] [--read true|false] [--write true|false]
+  watermark storage update <stg_id> [--prefix in/ ...] [--read true|false] [--write true|false]
+  watermark events --since 2026-10-13T15:00:00Z [--limit 100]
+  watermark fonts
+  watermark account
+  watermark usage [--from 2026-10-01] [--to 2026-10-31] [--group-by day|endpoint|customer|status] [--customer <id>]
+  watermark operations [image|video|document]
+
+A source is a public http(s) URL, a local file (uploaded first), an upload
+(upl_…), a file an earlier request kept (file_…), or an object in a
+connected bucket (stg_7a:path/to/key).
+
+Operations (repeat --op; they run in order):
+  --op resize:width=800,height=600
+  --op grayscale
+  --op watermark:image_url=https://example.com/logo.png,x=40,y=40
+  --ops-json '[{"type":"resize","width":800,"height":600}]'
+  See: watermark operations image
+
+  More than one file from a request, each with its own operations and format:
+  --outputs-json '[{"name":"large","format":"webp"},{"name":"thumb","operations":[{"type":"resize","width":200,"height":200}]}]'
+
+Options:
+  --out <file>            Wait, then download the result to this file.
+  --no-wait               Return as soon as the request is queued.
+  --timeout <seconds>     How long to wait (default 300).
+  --webhook <url>         Post the finished request here.
+  --event <type>          The webhook events to send (repeatable), such as request.progress.
+  --customer <id>         Your own reference for who the request is for.
+  --metadata key=value    Repeatable.
+  --idempotency-key <k>   Make a retry of this command safe.
+  --json                  Print JSON only (for scripts and AI agents).
+  --api-key <key>         Or set WATERMARK_API_KEY.
+  --base-url <url>        Or set WATERMARK_API_URL (default https://api.watermark.ws).
+  --version               Print the version.
+`;
+
+const MEDIA = { image: 'images', images: 'images', video: 'videos', videos: 'videos', document: 'documents', documents: 'documents', pdf: 'documents' };
+const ACTIONS = {
+  images: ['process', 'read', 'create'],
+  videos: ['process', 'read', 'screenshot'],
+  documents: ['process', 'read', 'snapshot'],
+};
+const REPEATABLE = new Set(['op', 'metadata', 'prefix', 'event']);
+const FLAGS = new Set(['json', 'no-wait', 'help', 'version', 'level']);
+
+// Parse argv into positionals and options; repeatable options collect arrays.
+export function parseArgs(argv) {
+  const positionals = [];
+  const options = { op: [], metadata: [], prefix: [], event: [] };
+
+  for (let i = 0; i < argv.length; i++) {
+    const arg = argv[i];
+    if (!arg.startsWith('--')) {
+      positionals.push(arg);
+      continue;
+    }
+    let [name, value] = arg.slice(2).split(/=(.*)/s, 2);
+    if (FLAGS.has(name)) {
+      options[name] = true;
+      continue;
+    }
+    if (value === undefined) {
+      value = argv[++i];
+      if (value === undefined) throw new UsageError(`--${name} needs a value.`);
+    }
+    if (REPEATABLE.has(name)) options[name].push(value);
+    else options[name] = value;
+  }
+
+  return { positionals, options };
+}
+
+// "resize:width=800,height=600" -> {type: "resize", width: 800, height: 600}
+export function parseOperation(text) {
+  const [type, rest] = text.split(/:(.*)/s, 2);
+  if (!/^[a-z_]+$/.test(type)) throw new UsageError(`"${text}" is not an operation: use type:param=value,...`);
+
+  const operation = { type };
+  for (const pair of (rest || '').split(',').filter(Boolean)) {
+    const [key, value] = pair.split(/=(.*)/s, 2);
+    if (value === undefined) throw new UsageError(`"${pair}" in --op ${type} needs a value: param=value.`);
+    operation[key.trim()] = typedValue(value.trim());
+  }
+  return operation;
+}
+
+function typedValue(value) {
+  if (value === 'true') return true;
+  if (value === 'false') return false;
+  if (/^-?\d+(\.\d+)?$/.test(value)) return Number(value);
+  return value;
+}
+
+class UsageError extends Error {}
+
+export async function main(argv, { env = {}, stdout, stderr, fetch, sleep } = {}) {
+  const print = (text) => stdout.write(text + '\n');
+  const fail = (text) => stderr.write(text + '\n');
+
+  let parsed;
+  try {
+    parsed = parseArgs(argv);
+  } catch (error) {
+    fail(error.message);
+    return 2;
+  }
+  const { positionals, options } = parsed;
+
+  if (options.version) {
+    print(`watermark ${VERSION}`);
+    return 0;
+  }
+
+  if (options.help || positionals.length === 0) {
+    print(HELP);
+    return positionals.length === 0 && !options.help ? 2 : 0;
+  }
+
+  const json = Boolean(options.json);
+  const output = (value, human) => print(json ? JSON.stringify(value, null, 2) : human(value));
+
+  try {
+    const api = new Api({
+      apiKey: options['api-key'] || env.WATERMARK_API_KEY,
+      baseUrl: options['base-url'] || env.WATERMARK_API_URL || 'https://api.watermark.ws',
+      fetch,
+      sleep,
+    });
+
+    const [command, ...rest] = positionals;
+
+    if (MEDIA[command]) {
+      return await runMedia(api, MEDIA[command], rest, options, { output, print, json, fetch: fetch || globalThis.fetch });
+    }
+
+    switch (command) {
+      case 'request': {
+        const [action, id] = rest;
+        if (!['get', 'abort'].includes(action) || !/^\d+$/.test(id || '')) throw new UsageError('Usage: watermark request get|abort <id>');
+        const request = await api.request(action === 'get' ? 'GET' : 'POST', `/v1/requests/${id}${action === 'abort' ? '/abort' : ''}`);
+        output(request, describeRequest);
+        return request.status === 'failed' ? 1 : 0;
+      }
+      case 'requests': {
+        const list = await api.request('GET', '/v1/requests', { query: { limit: options.limit, before: options.before } });
+        output(list, (value) => value.data.map((request) => `${request.id}\t${request.endpoint}\t${request.status}\t${request.created_at}`).join('\n') || 'No requests yet.');
+        return 0;
+      }
+      case 'account': {
+        const account = await api.request('GET', '/v1/account');
+        output(account, (value) => [
+          `${value.name} (${value.tier}${value.livemode === false ? ', test key' : ''})`,
+          `Balance: $${value.balance.amount}`,
+          value.limits ? `Limits: ${value.limits.requests_per_minute} requests a minute, sources up to ${Math.round(value.limits.max_source_bytes / 1048576)} MB` : '',
+        ].filter(Boolean).join('\n'));
+        return 0;
+      }
+      case 'usage': {
+        const usage = await api.request('GET', '/v1/usage', { query: { from: options.from, to: options.to, group_by: options['group-by'], customer: options.customer } });
+        output(usage, (value) => [`${value.group_by}\trequests\tfailed\tspent`, ...value.data.map((row) => `${row[value.group_by]}\t${row.requests}\t${row.failed}\t$${row.spent}`)].join('\n'));
+        return 0;
+      }
+      case 'operations': {
+        const catalog = await api.request('GET', '/v1/operations');
+        const media = rest[0] ? { image: 'image', images: 'image', video: 'video', videos: 'video', document: 'document', documents: 'document' }[rest[0]] : null;
+        const selected = media ? { [media]: catalog.data[media] } : catalog.data;
+        output(selected, (value) => Object.entries(value).map(([name, entry]) => [
+          `${name} (formats: ${entry.formats.join(', ')})`,
+          ...Object.entries(entry.operations).map(([type, operation]) => `  ${type}: ${operation.description}\n${Object.entries(operation.params).map(([param, info]) => `      ${param}${info.required ? ' (required)' : ''}: ${info.description}`).join('\n')}`),
+        ].join('\n')).join('\n\n'));
+        return 0;
+      }
+      case 'upload': {
+        const [action, id] = rest;
+        if (['get', 'delete'].includes(action)) {
+          if (!/^upl_[A-Za-z0-9]{22}$/.test(id || '')) throw new UsageError('Usage: watermark upload get|delete <upl_id>');
+          output(await api.request(action === 'get' ? 'GET' : 'DELETE', `/v1/uploads/${id}`), describeUpload);
+          return 0;
+        }
+        if (!action) throw new UsageError('Usage: watermark upload <file>');
+        output(await api.upload(action, { readFile }), describeUpload);
+        return 0;
+      }
+      case 'file': {
+        const [action, id] = rest;
+        if (!['get', 'delete'].includes(action) || !/^file_[A-Za-z0-9]{22}$/.test(id || '')) throw new UsageError('Usage: watermark file get|delete <file_id>');
+        output(await api.request(action === 'get' ? 'GET' : 'DELETE', `/v1/files/${id}`), describeFile);
+        return 0;
+      }
+      case 'storage': {
+        const [action, id] = rest;
+        if (action === 'list' || !action) {
+          output(await api.request('GET', '/v1/storage'), (value) => value.data.map(describeStorage).join('\n\n') || 'No storage connections.');
+          return 0;
+        }
+        if (action === 'connect') {
+          if (!options.bucket || !options.region || !options['role-arn'] || !options.prefix.length) throw new UsageError('Usage: watermark storage connect --bucket <name> --region <region> --role-arn <arn> --prefix in/ [--prefix ...] [--read true|false] [--write true|false]');
+          const body = { provider: 's3', bucket: options.bucket, region: options.region, role_arn: options['role-arn'], prefixes: options.prefix, ...storageSwitches(options) };
+          output(await api.request('POST', '/v1/storage', { body }), describeStorage);
+          return 0;
+        }
+        if (action === 'update') {
+          const usage = 'Usage: watermark storage update <stg_id> [--prefix in/ ...] [--read true|false] [--write true|false]';
+          if (!/^stg_[0-9a-z]{1,12}$/.test(id || '')) throw new UsageError(usage);
+          const body = storageSwitches(options);
+          if (options.prefix.length) body.prefixes = options.prefix;
+          if (!Object.keys(body).length) throw new UsageError(usage);
+          output(await api.request('PATCH', `/v1/storage/${id}`, { body }), describeStorage);
+          return 0;
+        }
+        if (!['get', 'verify', 'disconnect'].includes(action) || !/^stg_[0-9a-z]{1,12}$/.test(id || '')) throw new UsageError('Usage: watermark storage list | get|verify|disconnect <stg_id> | connect ... | update ...');
+        const method = { get: 'GET', verify: 'POST', disconnect: 'DELETE' }[action];
+        const storage = await api.request(method, `/v1/storage/${id}${action === 'verify' ? '/verify' : ''}`);
+        output(storage, describeStorage);
+        return action === 'verify' && storage.status !== 'verified' ? 1 : 0;
+      }
+      case 'events': {
+        if (!options.since) throw new UsageError('Usage: watermark events --since 2026-10-13T15:00:00Z [--limit 100]');
+        const events = await api.request('GET', '/v1/events', { query: { since: options.since, limit: options.limit } });
+        output(events, (value) => [
+          ...value.data.map((event) => `${new Date(event.created * 1000).toISOString()}\t${event.type}\trequest ${event.data?.id}`),
+          value.has_more ? `More: watermark events --since ${new Date(value.data.at(-1).created * 1000).toISOString()}` : '',
+        ].filter(Boolean).join('\n') || 'No events since then.');
+        return 0;
+      }
+      case 'fonts': {
+        const fonts = await api.request('GET', '/v1/fonts');
+        output(fonts, (value) => value.data.map((font) => `${font.name}\t${[font.family, font.style].filter(Boolean).join(' ')}`).join('\n'));
+        return 0;
+      }
+      default:
+        throw new UsageError(`Unknown command "${command}". Run watermark --help.`);
+    }
+  } catch (error) {
+    if (error instanceof UsageError) {
+      fail(error.message);
+      return 2;
+    }
+    if (error instanceof ApiError) {
+      if (json) print(JSON.stringify({ error: { ...error.error, status: error.status, type: error.type, code: error.code, message: error.message } }, null, 2));
+      else fail(describeError(error));
+      return 1;
+    }
+    fail(error.message);
+    return 1;
+  }
+}
+
+async function runMedia(api, media, [action, source], options, { output, print, json, fetch }) {
+  if (!ACTIONS[media].includes(action)) throw new UsageError(`Usage: watermark ${media.replace(/s$/, '')} ${ACTIONS[media].join('|')} <source>`);
+
+  const body = {};
+
+  if (action === 'create') {
+    if (!options.width || !options.height) throw new UsageError('watermark image create needs --width and --height.');
+    body.width = Number(options.width);
+    body.height = Number(options.height);
+    if (options.background) body.background = options.background;
+  } else {
+    body.source = await resolveSource(api, source);
+  }
+
+  if (options.level) {
+    if (media !== 'images' || action !== 'read') throw new UsageError('--level is for watermark image read.');
+    body.level = true;
+  }
+
+  if (action === 'process' || action === 'create') {
+    const operations = options['ops-json'] ? JSON.parse(options['ops-json']) : options.op.map(parseOperation);
+    if (operations.length === 0) throw new UsageError('Give at least one --op (see: watermark operations).');
+    body.operations = operations;
+  }
+  if (options['outputs-json']) body.outputs = JSON.parse(options['outputs-json']);
+  if (options.format) body.output = { format: options.format };
+  else if (action === 'create' && options.out) body.output = { format: options.out.split('.').pop().toLowerCase() };
+  if (options.seconds !== undefined) body.seconds = Number(options.seconds);
+  if (action === 'screenshot' && body.seconds === undefined) throw new UsageError('A screenshot needs --seconds.');
+  if (options.page !== undefined) body.page = Number(options.page);
+  if (options['max-duration'] !== undefined) body.max_duration = Number(options['max-duration']);
+  if (options['max-pages'] !== undefined) body.max_pages = Number(options['max-pages']);
+  if (options.webhook) body.webhook_url = options.webhook;
+  if (options.event.length) body.events = options.event;
+  if (options.customer) body.customer = options.customer;
+  if (options.metadata.length) {
+    body.metadata = Object.fromEntries(options.metadata.map((pair) => {
+      const [key, value] = pair.split(/=(.*)/s, 2);
+      if (value === undefined) throw new UsageError(`--metadata needs key=value, got "${pair}".`);
+      return [key, value];
+    }));
+  }
+
+  let request = await api.request('POST', `/v1/${media}/${action}`, { body, idempotencyKey: options['idempotency-key'] });
+
+  if (!options['no-wait']) {
+    request = await api.wait(request.id, {
+      timeoutMs: Number(options.timeout || 300) * 1000,
+      onProgress: json ? undefined : (current) => process.stderr.write(`Request ${current.id}: ${current.status}${current.progress !== undefined ? ` ${current.progress}%` : ''}\r`),
+    });
+  }
+
+  if (options.out && request.status === 'succeeded') {
+    const url = request.result?.files?.[0]?.url;
+    if (!url) throw new Error(`Request ${request.id} made no file to download.`);
+    const response = await fetch(url);
+    if (!response.ok) throw new Error(`Downloading the result failed: HTTP ${response.status}.`);
+    await writeFile(options.out, Buffer.from(await response.arrayBuffer()));
+    request = { ...request, saved_to: options.out };
+  }
+
+  output(request, describeRequest);
+
+  return request.status === 'failed' || request.status === 'aborted' ? 1 : 0;
+}
+
+// A source as the API takes it: a URL, an id, a storage object, or a local
+// file, which is uploaded first.
+async function resolveSource(api, source) {
+  if (!source) throw new UsageError('Give a source: a URL, a local file, upl_…, file_… or stg_…:key.');
+  if (/^https?:\/\//.test(source) || /^(upl|file)_[A-Za-z0-9]{22}$/.test(source)) return source;
+
+  const object = source.match(/^(stg_[0-9a-z]{1,12}):(.+)$/s);
+  if (object) return { storage: object[1], key: object[2] };
+
+  const local = await stat(source).catch(() => null);
+  if (!local?.isFile()) throw new UsageError(`"${source}" is not a URL, an id, stg_…:key, or a file here.`);
+
+  const upload = await api.upload(source, { readFile });
+  return upload.id;
+}
+
+// --read and --write as the API takes them, for connecting or changing storage.
+function storageSwitches(options) {
+  const switches = {};
+  for (const field of ['read', 'write']) {
+    if (options[field] === undefined) continue;
+    if (!['true', 'false'].includes(options[field])) throw new UsageError(`--${field} takes true or false.`);
+    switches[field] = options[field] === 'true';
+  }
+  return switches;
+}
+
+// An API error for people: the code to branch on, every invalid field, and
+// the permissions policy a storage change whose check failed needs.
+function describeError(error) {
+  const lines = [`Error ${error.status} ${error.code}: ${error.message}${error.param ? ` (${error.param})` : ''}`];
+  for (const [field, messages] of Object.entries(error.errors || {})) {
+    lines.push(`  ${field}: ${[].concat(messages).join(' ')}`);
+  }
+  if (error.error.permissions_policy) {
+    lines.push(`The role needs this permissions policy:\n${JSON.stringify(error.error.permissions_policy, null, 2)}`);
+  }
+  return lines.join('\n');
+}
+
+function describeUpload(upload) {
+  return `Upload ${upload.id} (${upload.filename}): ${upload.status}${upload.expires_at ? `, until ${upload.expires_at}` : ''}`;
+}
+
+function describeFile(file) {
+  const lines = [`File ${file.id} (${file.name}, ${file.format}, ${file.size} bytes)`];
+  if (file.url) lines.push(`Download: ${file.url} (until ${file.url_expires_at})`);
+  if (file.destination) lines.push(`Written to: ${file.destination.storage ? `${file.destination.storage}:${file.destination.key}` : 'your URL'}`);
+  if (file.deleted_at && !file.url) lines.push(`Deleted ${file.deleted_at}`);
+  return lines.join('\n');
+}
+
+function describeStorage(storage) {
+  const lines = [`${storage.id}: s3://${storage.bucket} (${storage.region}), ${storage.status}`];
+  if (storage.prefixes?.length) lines.push(`Prefixes: ${storage.prefixes.join(', ')}`);
+  if (storage.status !== 'verified' && storage.trust_policy) lines.push(`Create the role with the trust_policy and permissions_policy shown with --json (external id ${storage.external_id}), then run: watermark storage verify ${storage.id}`);
+  if (storage.last_error) lines.push(`Problem: ${storage.last_error}`);
+  return lines.join('\n');
+}
+
+function describeRequest(request) {
+  const lines = [`Request ${request.id} (${request.endpoint}): ${request.status}`];
+  if (request.status === 'failed' && request.error) lines.push(`Error ${request.error.code}: ${request.error.message}`);
+  if (request.result?.data) lines.push(`Result: ${JSON.stringify(request.result.data)}`);
+  for (const file of request.result?.files || []) {
+    if (file.destination) lines.push(`File: written to ${file.destination.storage ? `${file.destination.storage}:${file.destination.key}` : 'your URL'}`);
+    else lines.push(file.url ? `File: ${file.url} (link valid until ${file.url_expires_at})` : 'File: made, but no download link is available right now; fetch the request again.');
+  }
+  if (request.saved_to) lines.push(`Saved to ${request.saved_to}`);
+  if (request.price) lines.push(`Price: $${request.price.amount}`);
+  return lines.join('\n');
+}