Skip to content
rounder

The CLI

roundertools runs the site's tools from a terminal. Each command is the tool's address on the site:roundertools compress-pdf is roundertools.com/compress-pdf. Nothing to install with npx;npm install -g roundertools keeps it around.

terminal
npx roundertools compress-pdf report.pdf --target 1mb
npx roundertools merge-pdf a.pdf b.pdf c.pdf -o merged.pdf
npx roundertools image-converter "photos/*.png" --to webp -o webp/
npx roundertools png-to-jpg scan.png               # the site's preset pages work as commands
npx roundertools video-compressor clip.mov --target 25mb
cat in.pdf | npx roundertools compress-pdf - -o - > out.pdf
terminal
npx roundertools list              # every tool
npx roundertools help compress-pdf  # its options, examples and preset names
npx roundertools doctor             # Node, ffmpeg and canvas: what's installed

Files in, files out

  • Inputs are files, globs (quoted, so they work the same on Windows), folders with --recursive, or - for stdin.
  • Results go next to each input with the site's names (report-compressed.pdf), into a folder with -o out/, to one file with -o name.pdf, or to stdout with -o -.
  • It never replaces a file: a clash gets report-compressed (2).pdf. --overwrite allows replacing outputs; inputs are never replaced.
  • Batches keep going when one file fails, and say which at the end. -j 4 runs four files at a time.
  • Passwords can come from ROUNDERTOOLS_PASSWORD, so they stay out of your shell history.

For scripts and AI agents

--json prints one JSON document when it's done; --ndjson streams progress, result and error lines as they happen. Neither ever prompts.

--json
{ "schema": 1, "ok": true, "tool": "compress-pdf", "version": "0.1.0",
  "results": [{ "input": "/work/report.pdf", "output": "/work/report-compressed.pdf",
                "bytesIn": 3375514, "bytesOut": 118735, "ratio": 0.035,
                "meta": { "kept": false, "images": { "found": 4, "replaced": 3 } }, "warnings": [] }],
  "errors": [], "durationMs": 1012, "web": "https://roundertools.com/compress-pdf" }

The npm package also ships an Agent Skill (skill/SKILL.md) that tells coding agents how to use it. Drop it into your agent's skills folder and it costs no context until it's needed.

Exit codes

  • 0 every input worked
  • 1 the tool failed (a damaged file, an unsupported format, an existing output)
  • 2 usage: an unknown tool, flag or option value
  • 3 some inputs worked and some failed; the rest were written
  • 4 a dependency is missing (ffmpeg, @napi-rs/canvas)
  • 5 a size target was missed, with --strict (without it, the smallest result is written and noted)
  • 6 a password is needed or wrong
  • 130 interrupted with Ctrl+C; nothing half-written is left behind

Video and audio

The video and audio commands run the ffmpeg already on your computer, found on your PATH or atROUNDERTOOLS_FFMPEG. Without one they exit with code 4 and a link toffmpeg.org. roundertools doctor shows what it found.

try