Command line

Run the document lifecycle from your terminal

Validate PDFs, send envelopes, follow status, download signed documents, and forward real webhook events to localhost. No tunnel and no runtime dependencies.

View npm package REST API reference

Install and verify

npm install -g @zsign/cli
zsign help

Requires Node.js 18 or newer. You can also run any command with npx @zsign/cli.

Quickstart

From PDF to completed envelope

The CLI is intentionally thin. Field syntax, pricing, and document behavior stay defined by the API so terminal and HTTP integrations cannot drift apart.

Connect an account

Create an account and store its API key, or provide an existing key with ZSIGN_API_KEY.

zsign init --email you@example.com

Validate before sending

Find field tags, parties, and syntax errors without a credential or credit charge.

zsign lint contract.pdf

Send the envelope

Map every party in the PDF to a recipient. A successful send spends one credit. `zsign send` is always sequential (the API default); parallel send is REST/MCP only.

zsign send contract.pdf \
  --to "client=Robin Torres <robin@example.com>"

Track and download

Follow status transitions, then download the completed PDF with the original document ID.

zsign status <document-id> --watch
zsign download <document-id> --output signed.pdf

Local webhooks

Test the real delivery path without a public URL

zSign keeps a separate CLI copy of each event. The CLI drains that queue and forwards the exact payload to your local handler with a real webhook signature; production webhook delivery remains independent.

Events survive a short disconnect for up to one hour.
The same machine reattaches after a restart.
Replay a retained event after fixing your handler.

Forward events

zsign listen --forward-to http://localhost:3000/hooks

Replay one retained event

zsign replay <event-id> --forward-to http://localhost:3000/hooks

One listener holds the account lease at a time. Exit code 9 names an active conflict; use --replace only for an intentional takeover.

Automation

Predictable output for scripts and CI

Add --json to non-streaming commands for a stable envelope. status --watch and listen always emit NDJSON. Data is written to stdout and diagnostics to stderr.

zsign status "$DOCUMENT_ID" --json

Credential order

--api-key, then ZSIGN_API_KEY, then the config written by zsign init. Stored keys stay bound to the base URL that issued them.

Exit-code contract

0: Success
2: Usage error or bad request
3: Authentication or authorization error
4: Insufficient credits
5: Document validation failed
6: Resource not found
7: Rate limit retries exhausted
8: Local webhook handler failure
9: State conflict
130: Interrupted

Need every flag?

The package reference documents every command and edge case.

Complete command reference