Agent-first e-signature MCP server with offline PAdES signing and hash-chained audit.
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.
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.
| If you are… | Start here |
|---|---|
| A new user evaluating the tool | This README's Quick start, then Standard user journey |
| An operator wiring up a hosted provider | docs/setup/ — Dropbox / DocuSign / SignWell / embedded |
| An LLM agent driving the CLI | AGENTS.md → docs/agent-guide.md → docs/recipes/ |
| An auditor verifying a signed bundle | docs/reference/audit-chain.md, docs/reference/legal.md |
| A contributor | docs/reference/architecture.md, docs/regression-testing.md |
| Adding a new CLI to the suite | The build-a-CLI playbook — the conventions every suite CLI follows |
Concept deep-dives live in docs/reference/; task-oriented recipes in docs/recipes/.
# 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.
--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.request send — refuses to double-send unless --force true; pair with --idempotency-key for safe retries.request from-template.sign pdf detect-signature-field + sign sign --auto-place). Detects AcroForm /Sig widgets and anchor text in English + French/EU conventions.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.signer fetch-document and the MCP signer_fetch_document tool surface existingSignatures, so a signer can see what they're countersigning before they sign.sign document (chains the bundled docx2pdf-cli, auto-place, stamp, PAdES-seal, verify in one call against a scoped temp DB).--read-only true on both mcp serve and serve. Mutating tools/routes return FORBIDDEN_READ_ONLY.{{env:VAR}} references for shell-managed secrets). See docs/reference/profiles.md.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.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/.
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.
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.
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.
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"
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.
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 <id> --provider dropbox --test-mode true
Each --signer must include role:<roleName> 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.
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:<order> (required), doc:<i> (multi-doc index), type:signature|initials|date|text|name|email, page:<n> x:<pt> y:<pt> (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.
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 <id> --token <t> --name-signature "Alice" \
--auto-place first # or true | last | all | page:N | index:N
Adjustment strategies in priority order: underline-snap (0.95), below-anchor-probe (0.85, French/EU conventions), whitespace-probe (0.75), shrink-to-fit (0.50). Date anchors are detected separately via sign pdf detect-date-field. Full reference in docs/agent-guide.md §6.4a.
sign request bulk \
--csv ./signers.csv \
--document ./contract.pdf --provider dropbox \
--title "Q2 NDA for {{email}}" --test-mode true
Each row becomes its own request with autoApprove: true. Title template supports {{email}}, {{name}}, {{row}}. Exit code 3 if any row failed; JSON output lists per-row results.
# Inspect any signed PDF (ours, Adobe's, DocuSign's, …) — no DB lookup required
sign pdf inspect --pdf ./signed.pdf
# Inspect the embedded PKCS#7 of a request we sent
sign request verify-signed-pdf --request-id <id>
sign request verify-signed-pdf --request-id <id> --recipient alice@example.com # single-signer view
# Anchor the audit head against a public RFC 3161 TSA
sign audit anchor --request-id <id>
# Bundle for archival
sign audit export --request-id <id> --out ./bundle/
audit verify walks the local hash chain. request verify-signed-pdf recomputes the SHA-256 over the /ByteRange, compares it to the messageDigest in the embedded PKCS#7, and verifies the PKCS#7 signature value against the signer certificate's public key (RSA/ECDSA) — so a forged or tampered signature fails, exit 3, not just a modified-after-signing one. sign pdf inspect works on any signed PDF (no request id required). audit anchor issues a TimeStamp token from a TSA. See docs/reference/audit-chain.md for the full model.
sign profile init --name prod --provider signwell --db "~/.sign-cli/prod.db" --strict-provider true
sign profile set --name prod --key credentials.SIGNWELL_API_KEY --value "{{env:SIGNWELL_API_KEY}}"
sign --profile prod request show --request-id <id>
# Or implicitly via a project-level sign-profile.json (git/npm-style upward discovery)
Resolution order: flag > env > project profile > user profile > built-in default. Credentials redacted by default in profile show (--show-secrets true to reveal). Over the MCP HTTP transport, show_secrets is refused unless an --http-auth-token is configured (it stays available on stdio MCP and the CLI). See docs/reference/profiles.md.
sign doctor # legacy env-report; always exits 0
sign doctor preflight # structured per-check report; exit 0 ok, 1 failed
sign doctor providers # capability matrix across all providers
sign doctor account-check --provider signwell # provider /me check
preflight runs env-health checks (runtime:node_version, storage:db_path) on every provider, then provider-scoped checks layer on top. Branch on checks[].name for agent self-recovery.
.env or API keys.MIT. See LICENSE.
Source-derived launch command. Check the maintainer’s required arguments and credentials before running:
npx -y @drbaher/sign-cliMerge this template into ~/Library/Application Support/Claude/claude_desktop_config.json. Keep existing servers. Add any arguments, credentials, and permissions required by the maintainer; this template has not been install-tested.
{
"mcpServers": {
"io-github-drbaher-sign-cli": {
"command": "npx",
"args": [
"-y",
"@drbaher/sign-cli"
]
}
}
}Restart Claude Desktop completely for changes to take effect. Confirm the server appears connected in the client’s tool list, then try a read-only example from its documentation.
Claude Desktop setup reference@drbaher/sign-clinpmio.github.DrBaher/sign-cli works with any MCP-compatible client. Copy the config snippet from the Configuration section above and add it to the file shown for your client, then restart the application.
~/Library/Application Support/Claude/claude_desktop_config.jsonRestart Claude Desktop completely for changes to take effect.~/.cursor/mcp.jsonRestart Cursor for changes to take effect..vscode/mcp.jsonReload VS Code window for changes to take effect.~/.codeium/windsurf/mcp_config.jsonRestart Windsurf for changes to take effect..mcp.jsonSave at the project root, then start Claude Code in that project and review the MCP server approval prompt. Keep real credentials out of shared files.