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 → — 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 <email> 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 <id> --token <token1>
sign approve --request-id <id> --token <token2>

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

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

sign audit show --request-id <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 <id> --provider local
# Each signer runs:
sign sign --request-id <id> --token <their-token> \
  --require-hash <sha256> --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://<id> 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 <id> --provider local

# As the signer, with their token
sign signer list --signer-email alice@example.com
sign signer fetch-document --request-id <id> --token alice-tok-... --out ./nda.pdf
# fetch-document surfaces `existingSignatures` so the signer can see what they're countersigning
sign sign --request-id <id> --token alice-tok-... \
  --require-hash <sha256> --require-title "^Mutual NDA$" --require-signer-email alice@example.com
# or
sign signer decline --request-id <id> --token alice-tok-... --reason "Terms changed"