# Command line

The `watermark` command runs the Watermark API from a terminal, a shell script or a CI job. It waits for each request, downloads the result, and with `--json` prints output that scripts and AI agents can read.

## Install

Run it once without installing anything (Node.js 18 or newer):

```bash
npx @watermark/cli --version
```

Or install it, so `watermark` is on your path:

```bash
npm install -g @watermark/cli
```

On macOS or Linux with Homebrew:

```bash
brew install watermarkws/tap/watermark
```

It has no dependencies besides Node.js. Check the install with `watermark --version`.

## Set your key

Create a key at [watermark.ws/developers](https://watermark.ws/developers) and export it. A `wm_test_…` key is free and returns real results.

```bash
export WATERMARK_API_KEY=wm_test_…
```

`--api-key` on a single command works too, but leaves the key in your shell history.

## Watermark an image

```console
$ watermark 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
Request 1234 (images/process): succeeded
Result: {"width":1600,"height":1067,"format":"WEBP","size":183021}
File: https://… (link valid until 2026-10-18T15:00:04Z)
Saved to photo.webp
Price: $0.002000
```

The command waits for the request to finish (up to `--timeout`, 300 seconds), and `--out` downloads the result. The source must be a public `http` or `https` URL.

## Operations

Each `--op` is one operation, and they run in the order you give them:

```text
--op type:param=value,param=value
```

Numbers and `true`/`false` are sent as such; everything else as text. For anything awkward to write that way, pass the whole list as JSON:

```bash
watermark image process https://example.com/photo.jpg \
  --ops-json '[{"type":"filter","name":"nashville","strength":50},{"type":"compress","quality":70}]'
```

`watermark operations image` (or `video`, `document`) lists every operation and its parameters, read live from the API. The [Operations](https://api.watermark.ws/docs/operations.md) page shows each with a picture.

## More examples

### Watermark every page of a PDF

```bash
watermark document process https://example.com/contract.pdf \
  --op watermark:image_url=https://example.com/logo.png,x=148,y=712,diagonal_lines_color=#c0392b,diagonal_lines_opacity=35 \
  --out contract-watermarked.pdf
```

### Watermark the first minute of a video

```console
$ watermark video process https://example.com/clip.mp4 \
    --op resize:width=1280,height=720 \
    --op watermark:image_url=https://example.com/logo.png,x=32,y=32 \
    --max-duration 60 --out clip.mp4
Request 1240: processing 45%
```

Video requests report their progress while they run.

### Save one frame, or one page

```bash
watermark video screenshot https://example.com/clip.mp4 --seconds 3 --out poster.jpg
watermark document snapshot https://example.com/contract.pdf --page 1 --format png --out page-1.png
```

### Start now, collect later

```bash
watermark image process https://example.com/photo.jpg --op grayscale --no-wait --json | jq .id
watermark request get 1234
```

### A whole list of files

```bash
mkdir -p out
while read -r url; do
  watermark image process "$url" \
    --op watermark:image_url=https://example.com/logo.png,x=40,y=40 \
    --customer cus_42 --out "out/$(basename "$url")"
done < urls.txt
```

### Read a file's details in a script

```bash
width=$(watermark image read https://example.com/photo.jpg --json | jq '.result.data.width')
```

## For scripts and AI agents

- `--json` prints the request exactly as the API returns it, and nothing else on stdout. Progress goes to stderr.
- The exit code says what happened:

| 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 and server errors are retried twice with the same `Idempotency-Key`. Pass `--idempotency-key` to make a retry of the whole command safe too.

## Commands

```text
watermark image process <url> --op <operation> [--op ...] [--format webp] [--out file]
watermark image read <url>
watermark video process <url> --op <operation> [--max-duration 30] [--out file]
watermark video read <url>
watermark video screenshot <url> --seconds 5 [--format png] [--out file]
watermark document process <url> --op <operation> [--max-pages 10] [--out file]
watermark document read <url>
watermark document snapshot <url> [--page 1] [--format png] [--out file]
watermark request get <id>
watermark request abort <id>
watermark requests [--limit 20]
watermark account
watermark usage [--from 2026-10-01] [--to 2026-10-31] [--group-by day|endpoint|customer|status]
watermark operations [image|video|document]
```

| Option | What it does |
| --- | --- |
| `--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. |
| `--format <format>` | The output format, such as `webp` or `png`. |
| `--webhook <url>` | Post the finished request here. |
| `--customer <id>` | Your own reference for who the request is for. |
| `--metadata key=value` | Repeatable. Returned with the request. |
| `--idempotency-key <key>` | Make a retry of this command safe. |
| `--json` | Print JSON only. |
| `--api-key <key>` | Or set `WATERMARK_API_KEY`. |
| `--base-url <url>` | Or set `WATERMARK_API_URL`. Default `https://api.watermark.ws`. |

## Source

MIT licensed, on GitHub at [watermarkws/watermark-cli](https://github.com/watermarkws/watermark-cli).