@relaypdf/cli

Official CLI and stdio MCP server for RelayPDF.

HTML to PDFs without the struggle. Browser login for coding agents, then the same public API as REST: HTML / Markdown / URL / templates → PDF, Office convert, PDF tools, barcodes, zip, jobs.

• Docs: relaypdf.com/docs/cli · MCP
• npm: @relaypdf/cli
• Support: [email protected]

Requires Node.js 20+.

Do not ask a human to paste an API key. Run relaypdf setup (or login) and have them click Approve in the browser.

Installation

npm install -g @relaypdf/cli
relaypdf --help

Or without a global install:

npx @relaypdf/[email protected] --help
npx @relaypdf/cli setup --env .env.local

pnpm add -g @relaypdf/cli

Version: relaypdf 0.1.7 (--version).

Base URL

| | Default | |--|---------| | API | https://api.relaypdf.com | | Dashboard | https://relaypdf.com |

Override with RELAYPDF_BASE_URL / RELAYPDF_APP_URL, or --app / --api on login.

Authentication

Device login opens /cli/authorize. On approve, the CLI stores a CLI YYYY-MM-DD key.

| Command | What it does | |---------|----------------| | relaypdf login [--app <url>] [--no-open] | Browser device login | | relaypdf setup [--env <file>] | Login if needed, write env file mode 0600 | | relaypdf env write [file] | Write stored key into an env file | | relaypdf whoami [--json] | Email and masked key prefix (never the secret) | | relaypdf logout | Delete stored credentials |

Credentials: ~/.config/relaypdf/credentials.json (mode 0600). Override directory with RELAYPDF_CONFIG_DIR. Override key with RELAYPDF_API_KEY (never print it).

npx @relaypdf/cli login
npx @relaypdf/cli setup --env .env.local
npx @relaypdf/cli whoami --json

Local dashboard + API:

RELAYPDF_APP_URL=http://localhost:3000 \
RELAYPDF_BASE_URL=http://localhost:8787 \
npx @relaypdf/cli login

Revoke the key anytime at Dashboard → API keys.

Definitions

Same as the API: prepaid wallet (millicents; 1 = $0.001), published templates, async jobs, 24-hour files. Failed commands are not billed.

Rate limiting

Trial 20/min, funded 60/min, burst 5/10s. 429 is not billed.

Document commands

Uses RELAYPDF_API_KEY or the stored key. --html / --markdown may be markup, a file path, or - (stdin). --json prints metadata (never the API key). --out - writes bytes to stdout (not with --json). --async returns a job id. --response url returns a 24-hour download URL.

| Command | REST | Description | |---------|------|-------------| | relaypdf pdf --html … --out file.pdf | POST /v1/pdf | HTML → PDF | | relaypdf pdf --url https://… --out file.pdf | POST /v1/pdf | URL → PDF | | relaypdf pdf --markdown … --out file.pdf | POST /v1/pdf | Markdown → PDF | | relaypdf pdf --template <id\|slug> --data file.json --out file.pdf | POST /v1/pdf | Published template → PDF | | relaypdf image --url … --out shot.png [--full-page] | POST /v1/images | Screenshot | | relaypdf convert <file> --to pdf --out file.pdf | POST /v1/convert | LibreOffice / Office | | relaypdf merge a.pdf b.pdf --out pack.pdf | POST /v1/pdf/merge | Merge PDFs | | relaypdf extract file.pdf --pages 1-3 --out excerpt.pdf | POST /v1/pdf/extract | Extract pages | | relaypdf protect file.pdf --password <secret> --out locked.pdf | POST /v1/pdf/protect | Password-protect | | relaypdf unlock file.pdf --password <secret> --out open.pdf | POST /v1/pdf/unlock | Remove password | | relaypdf raster file.pdf --pages 1 --out page.png | POST /v1/pdf/raster | PDF → image | | relaypdf from-images a.png b.jpg --out scans.pdf | POST /v1/pdf/from-images | Images → PDF | | relaypdf stamp file.pdf --text DRAFT --out stamped.pdf | POST /v1/pdf/stamp | Watermark | | relaypdf rotate file.pdf --degrees 90 --out rotated.pdf | POST /v1/pdf/rotate | Rotate | | relaypdf delete-pages file.pdf --pages 2 --out trimmed.pdf | POST /v1/pdf/delete-pages | Delete pages | | relaypdf compress file.pdf --out small.pdf | POST /v1/pdf/compress | Optimize | | relaypdf info file.pdf | POST /v1/pdf/info | Metadata JSON | | relaypdf text file.pdf | POST /v1/pdf/text | Text layer | | relaypdf data file.pdf [--schema schema.json] [--ocr] | POST /v1/pdf/data | Schema extract or Markdown | | relaypdf form-fields file.pdf | POST /v1/pdf/form/fields | AcroForm names | | relaypdf form-fill file.pdf --fields '{"Name":"Jane"}' --out filled.pdf | POST /v1/pdf/form/fill | Fill form | | relaypdf barcode --type qr --data 'https://relaypdf.com' --out qr.png | POST /v1/barcodes | Barcode / QR | | relaypdf zip a.pdf b.pdf --out bundle.zip | POST /v1/zip | Zip files | | relaypdf templates list | GET /v1/templates | List drafts | | relaypdf templates gallery | GET /v1/templates/gallery | Stock layouts | | relaypdf templates create --name Invoice --html invoice.html --data sample.json | POST /v1/templates | Create draft | | relaypdf templates publish <id> | POST /v1/templates/:id/publish | Publish | | relaypdf webhooks list | GET /v1/webhooks | List signed endpoints | | relaypdf webhooks create --url https://… [--events job.completed,job.failed] | POST /v1/webhooks | Create; secret once; cap 25; not billed | | relaypdf webhooks delete <id> | DELETE /v1/webhooks/:id | Unsubscribe | | relaypdf jobs get <id> | GET /v1/jobs/:id | Poll job | | relaypdf jobs wait <id> [--out file] | GET /v1/jobs/:id | Wait + optional download | | relaypdf health | GET /health | Liveness | | relaypdf mcp | — | Stdio MCP server |

npx @relaypdf/cli pdf --html invoice.html --out invoice.pdf
npx @relaypdf/cli pdf --url https://example.com --out page.pdf
npx @relaypdf/cli pdf --template invoice --data sample.json --out invoice.pdf
cat body.html | npx @relaypdf/cli pdf --html - --out invoice.pdf
npx @relaypdf/cli convert letter.docx --to pdf --out letter.pdf
npx @relaypdf/cli merge cover.pdf body.pdf --out pack.pdf
npx @relaypdf/cli stamp in.pdf --text DRAFT --out stamped.pdf
npx @relaypdf/cli jobs wait <id> --out done.pdf

MCP

Hosted Streamable HTTP (Claude, Relevance, remote Cursor): POST https://api.relaypdf.com/mcp with Authorization: Bearer. See relaypdf.com/docs/mcp. Generating tools return a 24-hour URL.

Local stdio (this package):

npx @relaypdf/cli mcp

Uses the same stored key as CLI commands. Do not log HTML or file contents. Binary tools require out (a filesystem path); bytes are not returned over MCP. The data tool returns JSON inline.

Cursor / Claude Desktop

{
  "mcpServers": {
    "relaypdf": {
      "command": "npx",
      "args": ["-y", "@relaypdf/cli", "mcp"]
    }
  }
}

Recommended: npx @relaypdf/cli setup first so the user approves browser auth.

Tools

| Tool | REST | Notes | |------|------|--------| | pdf | POST /v1/pdf | html / url / markdown / templateId + templateData; out; async | | image | POST /v1/images | html or url; fullPage; type | | convert | POST /v1/convert | Office file path; to | | merge | POST /v1/pdf/merge | File paths | | extract | POST /v1/pdf/extract | pages | | protect | POST /v1/pdf/protect | Password | | unlock | POST /v1/pdf/unlock | Password | | raster | POST /v1/pdf/raster | Pages → PNG/JPEG | | from_images | POST /v1/pdf/from-images | PNG/JPEG paths | | stamp | POST /v1/pdf/stamp | Text watermark | | rotate | POST /v1/pdf/rotate | degrees | | delete_pages | POST /v1/pdf/delete-pages | pages | | compress | POST /v1/pdf/compress | Optimize | | info | POST /v1/pdf/info | Metadata | | text | POST /v1/pdf/text | Text layer | | form_fields | POST /v1/pdf/form/fields | Field names | | form_fill | POST /v1/pdf/form/fill | fields object | | barcode | POST /v1/barcodes | type, text/data | | zip | POST /v1/zip | Named files | | templates_list | GET /v1/templates | Drafts | | templates_gallery | GET /v1/templates/gallery | Stock layouts | | templates_create | POST /v1/templates | Draft | | templates_publish | POST /v1/templates/:id/publish | Publish | | webhooks_list | GET /v1/webhooks | List signed endpoints | | webhooks_create | POST /v1/webhooks | HTTPS URL; secret once | | webhooks_delete | DELETE /v1/webhooks/:id | Unsubscribe | | jobs_get | GET /v1/jobs/:id | Poll | | jobs_wait | GET /v1/jobs/:id | Wait | | health | GET /health | Liveness |

Errors and billing

Same RelayPDFError codes as @relaypdf/sdk: unauthorized, payment_required, rate_limited, convert_unavailable, … Failed jobs are not billed. Launch HTML PDF is $0.015; convert $0.04; tools $0.005. See wallet docs.

Environment

| Variable | Purpose | |----------|---------| | RELAYPDF_API_KEY | Override stored key | | RELAYPDF_BASE_URL | API origin | | RELAYPDF_APP_URL | Dashboard origin for login | | RELAYPDF_CONFIG_DIR | Credential directory |

Related packages

| Package | Role | |---------|------| | @relaypdf/sdk | Node / TypeScript SDK (this CLI depends on it) | | relaypdf | Python SDK | | PHP / C# / Java SDKs | sdks/php, sdks/dotnet, sdks/java in this repo | | n8n-nodes-relaypdf | n8n community node |

License

MIT. Strategic Products LLC, d/b/a RelayPDF.