Sign Cli

sign-cli

Fully-offline e-signature CLI. The built-in PAdES signer (PKCS#7 in /ByteRange, self-issued cert) produces real, cryptographically verifiable signed PDFs with no signup and no third-party provider — or routes through Dropbox Sign / DocuSign / SignWell when you need an external trust anchor. Per-signer approval tokens (TTL-bounded, scoped to one email), hash-chained audit events, RFC 3161 timestamping, named profiles, a 19-tool MCP server, and a 20-route HTTP API.

The asymmetry is the architecture: an agent can drive every step except the actual signing gesture, which stays gated behind a human.

Part of the contract-ops CLI suite — optional. sign-cli works entirely on its own; it's also the signing + audit step of the contract-ops suite: template-vault-cli → draft-cli → nda-review-cli → docx2pdf-cli → sign-cli, with drift detection via compare-cli.

Run this

npx @drbaher/sign-cli demo

That single command runs the entire lifecycle — create (consent + email-verification gates on) → send → watch the gates block signing → verify email → capture consent → approve → sign → verify chain → export receipt — against the offline local provider, then deletes everything. No signup. No keys. ~5 seconds.

[Live demo →](https://sign-cli-demo-production.up.railway.app/web-demo/) — read-only, resets every 4 hours. Self-host: see deploy/README.md.

Where to go next

Concept deep-dives live in docs/reference/; task-oriented recipes in docs/recipes/.

Quick start

# Install

npm i -g @drbaher/sign-cli

Or run without installing

npx @drbaher/sign-cli demo

After install, the binary is named sign

sign --version sign demo sign init # wizard: provider selection + .env sign doctor preflight # structured per-check readiness report

Or download a standalone binary from Releases — ./sign-linux-x64 demo. See DISTRIBUTION.md for every install path.

What this gives you

• Offline PAdES signing with a self-issued cert — real PKCS#7 signed PDFs, no signup, no API keys.
• Three hosted providers when you need them: Dropbox Sign, DocuSign, SignWell. Same surface across all four.
• Per-signer approval tokens (single-use, TTL-bounded, tied to one email). Tokens go to the human, not the agent.
• Consent + attribution evidence, opt-in per request: --require-consent gates signing on a recorded intent-to-sign attestation + electronic-records consent (versioned canonical texts, hashed into the audit chain); --require-email-verification gates it on a mailbox-control code; signer record-identity logs how identity was checked out-of-band. No KYC data is collected — by design. See docs/reference/consent-and-identity.md.
• Hash-chained audit chain with append-only DB triggers + RFC 3161 anchors. See docs/reference/audit-chain.md.
• Idempotent `request send` — refuses to double-send unless --force true; pair with --idempotency-key for safe retries.
• Multi-document + multi-signer requests; CSV-driven bulk send.
• Templates from each provider's dashboard via request from-template.
• Auto-detect signature field (sign pdf detect-signature-field + sign sign --auto-place). Detects AcroForm /Sig widgets and anchor text in English + French/EU conventions.
• Inspect any signed PDF with sign pdf inspect — parses PAdES PKCS#7 from sign-cli or any other producer (Adobe, DocuSign, Dropbox Sign, SignWell). Returns signer CN/email, cert subject + issuer, validity window, fingerprint, trust label (self_signed_local / self_signed_other / ca_signed / unknown), and message-digest match.
• Counter-sign visibility — signer fetch-document and the MCP signer_fetch_document tool surface existingSignatures, so a signer can see what they're countersigning before they sign.
• One-shot DOCX → sealed PDF via sign document (chains the bundled docx2pdf-cli, auto-place, stamp, PAdES-seal, verify in one call against a scoped temp DB).
• Sandbox via `--read-only true` on both mcp serve and serve. Mutating tools/routes return FORBIDDEN_READ_ONLY.
• Path-traversal guards on every input and output path. See docs/reference/security-controls.md.
• Named profiles bundle provider + dbPath + credentials (with {{env:VAR}} references for shell-managed secrets). See docs/reference/profiles.md.
• PDF verification end-to-end offline: request verify-signed-pdf recomputes the digest, extracts X.509 signer certs, supports --recipient for a redacted single-signer view, and reports per-signer trust labels.

Standard user journey

sign request create \

--title "Mutual NDA" \ --document ./nda.pdf \ --signer name:Alice,email:alice@acme.com,order:1 \ --signer name:Bob,email:bob@beta.com,order:2 \ --provider signwell

sign approve --request-id --token sign approve --request-id --token

sign request send --request-id --provider signwell --test-mode true

sign request watch \ --request-id --provider signwell \ --interval-seconds 5 --fetch-final true \ --out ./signed.pdf

sign audit show --request-id

Or fully offline:

sign request create --title "Mutual NDA" --document ./nda.pdf \

--signer name:Alice,email:alice@example.com,order:1 \ --signer name:Bob,email:bob@example.com,order:2 \ --provider local --auto-approve true sign request send --request-id --provider local

Each signer runs:

sign sign --request-id --token \ --require-hash --require-title "^Mutual NDA$"

For full provider-specific setup, see docs/setup/.

One-shot DOCX → sealed PDF

sign document contract.docx \

--signer "Alice Founder" --signer-email "alice@acme.com" \ --name-signature "Alice Founder" --auto-place first \ --out contract.sealed.pdf

sign document chains: convert (via the bundled docx2pdf-cli) → detect signature field → stamp → PAdES-seal → verify chain. All intermediate state lives in a scoped temp DB.

MCP server (for LLM agents)

sign mcp serve                  # stdio MCP server

sign mcp serve --read-only true # sandboxed: mutating tools return FORBIDDEN_READ_ONLY sign mcp tools # print the catalog (live; don't hardcode the list)

19 tools, split read-only vs mutating. Backed by the same SignCliError envelopes you'd see at the CLI. The full discovery contract, wire-up snippets (Claude Desktop, Cursor), and read-only walkthrough are in AGENTS.md. Three resource shapes (request:// snapshot, .../document PDF blob, .../audit chain) and four agent-as-signer prompt templates (review_and_sign, policy_check, inbox_triage, verify_receipt) are also exposed.

HTTP API (for non-MCP clients)

sign serve --port 4000 --auth-token <t> --read-only true --rate-limit 5

curl http://127.0.0.1:4000/v1/openapi.json # discover the route catalog

Twenty routes under /v1/*, 1:1 parity with the MCP tool surface — same input shape, same path-traversal guards, same read-only gating. Bearer auth via --auth-token or SIGN_HTTP_AUTH_TOKEN. Responses are { ok, result } on success or the standard error envelope on failure.

Signer-side flow (agent-friendly)

For --provider local, an agent can act as a signer end-to-end without an email link. Set SIGN_LOCAL_AUTOCOMPLETE=false so the local provider holds at sent until each signer explicitly runs sign sign.

# As the requester (agent or human)

sign request create --title "Mutual NDA" --document ./nda.pdf \ --signer name:Alice,email:alice@example.com,order:1 \ --signer name:Bob,email:bob@example.com,order:2 \ --provider local --auto-approve true

response includes per-signer tokens

sign request send --request-id --provider local

As the signer, with their token

sign signer list --signer-email alice@example.com sign signer fetch-document --request-id --token alice-tok-... --out ./nda.pdf

fetch-document surfaces existingSignatures so the signer can see what they're countersigning

sign sign --request-id --token alice-tok-... \ --require-hash --require-title "^Mutual NDA$" --require-signer-email alice@example.com

or

sign signer decline --request-id --token alice-tok-... --reason "Terms changed"

Multi-signer: status only flips to completed when every signer is in signedBy[]. Pre-sign safety checks (--require-hash / --require-title / --require-signer-email) throw PRE_SIGN_*_MISMATCH before any state mutation.

Templates

Reuse a template defined in the provider dashboard (no PDF upload):

sign request from-template \

--template-id tmpl_abc --provider dropbox \ --signer role:Buyer,name:Alice,email:alice@example.com,order:1 \ --signer role:Seller,name:Bob,email:bob@example.com,order:2 \ --prefill name:purchase_price,value:1000 \ --auto-approve true

sign request send --request-id --provider dropbox --test-mode true

Each --signer must include role: matching a template role. --prefill name:K,value:V[,signer:N] populates template fields. Per-provider behavior: DocuSign uses per-signer text tabs; Dropbox uses custom_fields; SignWell uses placeholders.

Field placement

By default the hosted providers auto-append a generic signature page. For real contracts, pass --field (repeatable) on request create:

sign request create \

--title "NDA" --document ./contract.pdf \ --signer name:Alice,email:alice@example.com,order:1 \ --field signer:1,page:1,x:100,y:200,type:signature \ --field signer:1,page:1,x:100,y:240,type:date

Spec: signer: (required), doc: (multi-doc index), type:signature|initials|date|text|name|email, page: x: y: (coordinate), or DocuSign-only anchor:"text" with optional x-offset / y-offset / anchor-units. The fields persist on the request and forward to the provider at send time.

Auto-detect signature field

For --provider local, sign sign --auto-place calls the detector and uses the top candidate iff there's a unique high-confidence (≥0.8) match.

# Inspect candidates first

sign pdf detect-signature-field --pdf ./contract.pdf

Auto-place (errors loudly on ambiguity)

sign sign --request-id --token --name-signature "Alice" \ --auto-place first # or true | last | all | page:N | index:N

Adjustment strategies in priority orde