CLI
The esigncomply command-line tool for running a demo ceremony, checking a page against the conformance rules, publishing documents, forwarding test webhooks and verifying evidence.
The esigncomply CLI ships inside the Node SDK package. Run it without installing anything:
npx esigncomply@latest <command>
In a project that already depends on esigncomply, npx esigncomply <command> uses the installed version. The CLI needs Node.js 20.19 or later.
Commands
| Command | What it does |
|---|---|
demo |
Serves a local signup page, runs a test ceremony and prints the record ID. |
check |
Runs the conformance check of your page at three window sizes, or a pack resolution dry run. Returns an exit code for CI. |
documents publish |
Publishes a file as a new version of a document. |
webhooks listen |
Forwards test webhook deliveries to a server on your machine. |
verify |
Verifies an evidence package offline. |
esigncomply <command> [options]
esigncomply <command> --help Options of one command.
esigncomply help [command] The same help.
esigncomply --version The version. Also -v.
esigncomply --help The command list. Also -h.
Flags are written --name value or --name=value. -- ends the flags. Output is plain text. Colors are used only when the output is a terminal and NO_COLOR is not set.
Before you start
demo, check, documents publish and webhooks listen authenticate with a secret API key, like the SDK. verify needs no key.
| Variable | Description |
|---|---|
ESIGNCOMPLY_API_KEY |
Your secret key. demo, check and webhooks listen take test keys (esc_test_...) only and refuse a live key. documents publish takes a test or a live key. |
ESIGNCOMPLY_API_URL |
API base URL. Default: the host for the region in the key. Set it only for local development against another API host. |
ESIGNCOMPLY_WEBHOOK_SECRET |
webhooks listen only: the signing secret of your test endpoint (whsec_...), used when --secret is not given. |
export ESIGNCOMPLY_API_KEY=esc_test_us_...
Never. Do not paste a live key into a terminal or a chat that an AI coding tool can read. Every command on this page works with a test key. The rules are in /auth.md.
Test keys work on localhost, 127.0.0.1 and the preview hosts listed for your domain, with no domain verification. See Test mode.
Exit codes
Every command follows the same convention. The command sections name what counts as a failure.
| Code | Meaning |
|---|---|
0 |
The command did what was asked. |
1 |
The command ran and failed: an API call returned an error, a check found a problem, or a verification did not pass. |
2 |
The command could not run: unknown command or option, a missing argument, a missing key, a live key where a test key is required, or a missing tool. |
130 |
demo only: stopped with Ctrl+C before a record was made. |
A usage error prints the reason and Run esigncomply <command> --help for usage. to standard error. An API error prints the message with the error code, the HTTP status and the request ID. Running esigncomply with no command prints the command list and exits with 2. So do esigncomply documents and esigncomply webhooks without a subcommand, with that command's help.
demo
npx esigncomply@latest demo
esigncomply demo [--port 4310] [--auto]
Records a first test signature without writing any code. The command:
- Creates a document named "Demo Terms of Service", a document named "Demo Privacy Notice" and a profile named "Demo signup" (
US-FED, methodcheckbox, levelL1) in test mode. On a later run it reuses the ones it made before. - Serves a signup page at
http://localhost:4310/and waits. - When you tick the box and click "Create account", the page runs a real ceremony against the API with a session client token.
- Confirms the record from the command's own process with the secret key: it must be a test record, with status
recorded,timestampedoranchored, for the signer and the document versions the command asked for. - Prints the record ID, its status, the verify URL, a link to the record in the dashboard and how the ceremony was captured.
| Flag | Description |
|---|---|
--port <port> |
Port for the local page. Default 4310. 0 lets the system pick a free port. |
--auto |
Do not wait for a person. The command drives the page with Playwright when it is installed. Otherwise it reports the ceremony from its own process as a server_only session, and says so. |
--help, -h |
Show the usage. |
The secret key stays in the command's process. The page receives only the session's client token. The local server listens on 127.0.0.1, answers only requests addressed to localhost or 127.0.0.1, and refuses cross-origin posts.
The page loads the browser SDK from the API host at /sdk/v1/esigncomply.js. If that bundle is not available, the page reports the same steps itself with fetch and the client token, and the output says which of the two happened.
With --auto and no Playwright, no browser is involved: the command sends each required step with the secret key, and every step in the record is tagged asserted instead of observed. See Observed and asserted.
Record sealed.
Record ID rec_Z4m8
Status recorded (test mode: sealed with the test key, no attestation)
Verify https://esigncomply.com/verify/rec_Z4m8
Dashboard <link to the record in the dashboard>
Captured in the browser, by the browser SDK (direct channel)
Confirm it from your own server the same way this command did:
const { data: record } = await esc.records.get("rec_Z4m8");
Exit codes: 0 when a record was sealed and confirmed, 1 when an API call or the confirmation failed, 2 for a usage error or a port that is in use, 130 when stopped with Ctrl+C before a record was made.
The demo page is a sample. It does not change your project.
check
check is the active mode of the conformance rules. It has two uses, which can be combined in one run.
esigncomply check --url <page> [--region US-CA ...] [--json]
| Flag | Description |
|---|---|
--url <page> |
The page that runs the ceremony, for example http://localhost:3000/signup. An http or https URL. |
--region <code> |
Dry-run the pack resolution for a signer in this region, for example US-CA. Repeatable. Works without --url. |
--profile <id> |
Profile for the dry run. Default: the domain's only profile. |
--purpose <purpose> |
context.purpose for the dry run, for example auto_renewal. |
--signer-class <class> |
consumer (default), business or employee, for the dry run. |
--checkbox <css> |
The assent checkbox, when the checker cannot find it. |
--submit <css> |
The button that performs the signing act. |
--fill <css=value> |
Fill a field before submitting. Repeatable. |
--callback <url> |
Your server's confirmation endpoint. The checker posts a forged success to it and expects a refusal. |
--timeout <seconds> |
How long to wait for the ceremony to complete at each size. Default 20, from 1 to 300. |
--json |
Print the report as JSON. |
--help, -h |
Show the usage. |
Pass --url, --region or both. With neither the command exits with 2.
ESIGNCOMPLY_API_KEY must be a test key for the domain the page uses.
Check a page
npx esigncomply@latest check --url http://localhost:3000/signup
Run the command once per page that hosts a ceremony, for example once for /signup and once for /nda/test. The command opens the page in headless Chromium and watches the calls the page itself makes to the ceremony endpoints. Your page creates its own sessions, as it does for a real visitor.
Violations. First, at the phone size, the checker tries things that must be refused:
| Attempt | What the checker does | Refused when |
|---|---|---|
| Submit with the checkbox untouched | Fills the form and clicks the button without ticking the box. | No record is made, or the record is flagged by a blocking finding. |
| Completion from another origin | Calls the completion endpoint from its own process with the token the page used, under a foreign Origin. |
The API answers 403 domain_mismatch. |
| Programmatic click | Ticks the box and clicks the button from a script. | No record is made, or the record is flagged by a blocking finding. |
| Forged success posted to your callback | Only with --callback. Posts a JSON body that names a record that does not exist. |
Your endpoint answers anything other than 2xx. |
In test mode the API seals a record even when a blocking rule failed, so that the finding can be seen. Live mode refuses that record. The checker therefore counts a violation as refused when the test record carries a blocking finding, and names the rule. A violation is ACCEPTED only when a record was made and no rule flagged it.
Each attempt is reported as REFUSED, ACCEPTED or SKIPPED with a reason. An attempt is skipped when it cannot be made: no checkbox and button were found, the page made no ceremony call on load, or --callback was not given. Two more attempts, "Altered document text" and "Skipped verification step", are listed as SKIPPED: this version of the checker does not attempt them.
The forged callback checks your server. Your application must grant access only after its own server has confirmed the record: see Server confirmation.
Ceremonies. Then the checker runs the ceremony as a signer would, once at each window size:
| Window | Size |
|---|---|
| Phone | 390 by 844 |
| Tablet | 768 by 1024 |
| Desktop | 1440 by 900 |
At each size it waits for the page to settle, fills the fields named with --fill, fills empty visible email, password, phone and text fields with test values, waits for a checkbox the page keeps disabled until it is ready, ticks it with a real pointer click, clicks the button and waits up to --timeout seconds for the page to complete the ceremony. Without --checkbox and --submit it looks for a visible checkbox (input[type="checkbox"], then [role="checkbox"]) and a visible button (button[type="submit"], then input[type="submit"], then a button inside a form, then any button).
Findings. Last, the checker asks the API for one conformance run per window size, over the session it ran at that size (POST /v1/conformance/runs), and waits for each result. A rule that fails at one size only is reported for that size. If the run endpoint is not available, it reads the findings from each record and from the API's answers to each ceremony event instead, and the report says so.
The headless browser is driven through Playwright, an optional peer dependency of the package. If the command reports that Playwright or its browser is missing, it exits with 2. Add them to the project:
npm install --save-dev playwright
npx playwright install chromium
Read the report
The report is printed in the terminal. With --json it is one JSON object.
Conformance check of http://localhost:3000/signup
Window sizes: 390x844, 768x1024, 1440x900
Violations that must be refused
REFUSED Submit with the checkbox untouched No record was made.
REFUSED Completion from another origin The API answered 403 domain_mismatch.
REFUSED Programmatic click No record was made.
SKIPPED Altered document text Not attempted by this version of the checker.
SKIPPED Skipped verification step Not attempted by this version of the checker.
SKIPPED Forged success posted to your callback Pass --callback <url> to post a forged success to your server and expect a refusal (CC-3).
Ceremonies
390x844 record rec_Z4m8 session ses_5nWq, 5 events
...
Findings
WARN CR-05 390x844 <message>
measured: contrast_ratio=2.23
element: #tos-link
fix: <repair>
Summary: 0 block, 1 warn, 14 pass.
Findings are advisory statements about measurable design facts. The checker does not state that a flow is lawful or enforceable.
Messages, counts and IDs above are sample values. Findings with status pass are counted in the summary and not listed. Each listed finding has:
| Part | Meaning |
|---|---|
| Status | BLOCK or WARN. (advise) marks a rule that is measured and stored only. |
| Rule | The rule ID, for example CR-04. Each ID has a section, for example CR-04. |
| Window | The window size the finding was measured at. |
measured |
The numbers behind the result, for example a contrast ratio or a pixel distance. |
element |
The selector of the element that was measured. |
fix |
A plain-language repair for the page. |
prompt |
The instruction in your generated prompt that the rule relates to. |
The JSON report has these fields:
| Field | Content |
|---|---|
url, viewports |
The page and the three window sizes. |
dry_runs |
One { region, resolution, error } per --region. |
attempts |
One { id, title, outcome, detail } per violation attempt. outcome is refused, accepted or skipped. The IDs are untouched_checkbox, foreign_origin, programmatic_click, altered_document, skipped_verification and forged_callback. |
sessions |
The sessions the page ran: id, viewport, purpose, apiBase, events, recordId, completeStatus, completeError. Client tokens are left out. |
run_endpoint_available, runs |
Whether the conformance run endpoint answered, and one { viewport, run } per window size. Each run's markdown field holds its findings as Markdown to paste into a coding tool. |
findings |
Every finding: rule, status, state, message, measurement, selector, fix, prompt_instruction, viewport, record_id, session_id, event_type. |
summary |
{ pass, warn, block }. |
problems, note |
Notes about the run, and the advisory sentence. |
Fix every finding marked block. List every finding marked warn in your report to the developer. Then run the command again.
Findings describe measurable design facts. They are not a statement that a flow is lawful or enforceable.
Check which rules apply
npx esigncomply@latest check --region US-CA --region US-NY --purpose auto_renewal
With --region the command runs a dry run of pack resolution for a signer in each region and prints the packs with their versions and reasons, the required steps, the required strings, the number of rules fired, the rule set version, the guidance release, and any advisories and warnings. It creates no session and is not metered. It is the terminal form of POST /v1/jurisdictions/resolve: see the jurisdictions API.
The dry run needs a profile. Without --profile the command uses the domain's profile. When the domain has several it uses the first one listed and adds a note to the report's problems. When it has none the command exits with 2. The signer's country is taken from the region code: US-CA gives US.
Exit codes of check
| Code | Meaning |
|---|---|
0 |
No blocking finding. |
1 |
A blocking finding, a violation that was not refused, a ceremony that did not complete, or a dry run that failed. |
2 |
The check could not run: bad arguments, no key, a live key, or Playwright or its browser not installed. |
Use it in CI
check returns an exit code, so a regression such as a restyled link or a pre-checked box fails the build. Start your application, then run the check against it with a test key stored as a CI secret.
# .github/workflows/conformance.yml
name: conformance
on: [pull_request]
jobs:
check:
runs-on: ubuntu-latest
env:
ESIGNCOMPLY_API_KEY: ${{ secrets.ESIGNCOMPLY_TEST_KEY }}
steps:
- uses: actions/checkout@v4
- uses: actions/setup-node@v4
with:
node-version: 22
- run: npm ci
- run: npx playwright install chromium
- run: npm run build
- run: npm run start &
- run: npx wait-on http://localhost:3000/signup
- run: npx esigncomply check --url http://localhost:3000/signup
Test mode never blocks a ceremony on a finding. The check is what turns a finding into a failed build before the page reaches live traffic.
documents publish
npx esigncomply@latest documents publish ./legal/terms.md --document doc_8Hq2 --label 2026-11-21 --material --summary "Added arbitration clause in section 14."
esigncomply documents publish <file> --document <doc_id> --label <version label> [options]
Publishes a file as a new, immutable version of a registered document, for example from a release script. The API returns the content hash that every record of this version will name. Publish when the text is final.
| Flag | Description |
|---|---|
--document <doc_id> |
The document to add the version to. Required. |
--label <label> |
Version label, for example 2026-11-21. Required. |
--language <code> |
Language of this version. Default en. |
--material |
Mark the change as material. Earlier acceptances become outstanding in the signer status. |
--summary <text> |
Summary of changes, shown to signers asked to accept again. |
--effective-at <time> |
RFC 3339 time from which the version is current. Default: now. |
--format <format> |
markdown, html, text or pdf. Default: from the file extension (.md, .markdown, .html, .htm, .txt, .pdf). |
--json |
Print the version object as JSON. |
The key can be a test or a live key with document write access. Name exactly one file.
Published dv_3kT9 (2026-11-21, en) of doc_8Hq2
content hash sha256:9f2c...
render hash sha256:41d0...
effective 2026-11-21T15:03:20.291Z
material yes: earlier acceptances are now outstanding
mode test
Warnings the API returned for the version, such as html_sanitized, are printed as further lines.
The command calls POST /v1/documents/{id}/versions with an idempotency key derived from the document, the label, the language and the file's content. Running it again with the same file, document, label and language returns the version already published. A PDF is sent as base64. Other formats are sent as UTF-8 text.
Exit codes: 0 when the version is published, 1 when the API refused it, 2 for a usage error: no file or more than one, a missing --document or --label, a file that cannot be read, or a format that cannot be told from the extension.
Fields and responses are in the documents API. Marking a version as a material change leaves earlier acceptances outstanding: see Re-acceptance.
webhooks listen
npx esigncomply@latest webhooks listen --forward http://localhost:3000/api/esigncomply/webhook --secret whsec_...
esigncomply webhooks listen --forward <local URL> [options]
Forwards test-mode webhook deliveries to a server on your machine, so you can build the handler before your endpoint is reachable from the internet. Live deliveries are never forwarded: the command takes a test key only, and the key needs full_access.
Deliveries exist only for registered endpoints. Create a test endpoint first, with esc.webhooks.create({ url }) or in the dashboard, and keep the secret it returns.
| Flag | Description |
|---|---|
--forward <url> |
Where to post deliveries. An http or https URL. Required. |
--secret <whsec_...> |
The signing secret of your test endpoint. The command signs each forwarded delivery with it. Default: ESIGNCOMPLY_WEBHOOK_SECRET. |
--endpoint <id> |
Forward the deliveries of this endpoint only. |
--interval <ms> |
How often to ask for new deliveries. Default 2000, minimum 1000. |
--since <time> |
Start from this RFC 3339 time. Default: now. |
--once |
Ask once, forward what is there, and exit. |
The command polls GET /v1/webhooks/deliveries with since, limit=100 and include=payload, and posts each new event to the URL, oldest first. An event that was delivered to several endpoints is forwarded once, unless --endpoint is given. Stop the command with Ctrl+C.
For each delivery it sends:
- the event as JSON, serialized the way Esign Comply serializes the body it delivers
Content-Type: application/jsonandUser-Agent: EsignComply-CLI-Forwarder/1.0webhook-id, set to the event IDwebhook-timestamp, set to the time of forwarding, andwebhook-signature, computed with your secret over<webhook-id>.<webhook-timestamp>.<body>
The API does not return the signature it sent with the original delivery. That is why the command signs each forwarded delivery itself, the way Esign Comply signs it, so that esc.webhooks.verify(rawBody, headers, secret) in your route accepts it with the same secret. Should the API return all three original signature headers for a delivery, the command forwards those unchanged instead. Without a secret, deliveries are forwarded with webhook-id only. The command says so at start, marks each line (unsigned), and your handler's verification refuses them.
In your route, verify each delivery exactly as in production and handle each webhook-id once. Event types and payloads are in Webhooks. The fields of a delivery are in the account API.
Forwarding test webhook deliveries to http://localhost:3000/api/esigncomply/webhook
Asking https://esigncomply.com/v1 every 2000 ms. Stop with Ctrl+C.
15:03:21 record.completed evt_91xA -> 200
Forwarded 1 delivery.
A forward waits up to 10 seconds for your server. A 2xx answer counts as forwarded. Any other answer, or no answer, is counted as not accepted and shown on the line. A delivery for which the API returned no payload is skipped and counted the same way.
Exit codes: 0 when stopped or after --once. 1 when the first read of deliveries fails, when a read fails with an authentication or permission error, or when the deliveries endpoint answers 404. 2 for a usage error. A later read that fails for another reason is reported and tried again.
The reserved test signer addresses trigger the matching events without manual steps. For example a ceremony for signer+dispute@test.esigncomply.com produces record.disputed. See Test mode.
verify
npx esigncomply@latest verify rec_Z4m8.zip
esigncomply verify <package.zip | directory> [--jwks <file or https URL>] [--tsa-roots <pem file>] [--json]
esigncomply verify <certificate.json> --evidence <package.zip>
Verifies an evidence package offline. The command hands its arguments to the open-source verifier, esigncomply-verify, so both commands behave the same. No API key, no account and no network are needed. Nothing is fetched unless --jwks is an https URL.
| Flag | Description |
|---|---|
--jwks <file or https URL> |
Check signatures against these sealing keys instead of the bundled ones. |
--tsa-roots <pem file> |
Trust anchors for the timestamp authority's certificate chain. |
--evidence <zip or directory> |
With a certificate: the evidence package of a record it covers. |
--json |
Print the report as JSON. |
Exit codes: 0 when verified, 1 when not, 2 when the command could not run. The checks, the report and the library are described in Offline verifier.
A passing verification shows that the record matches its seal and bounds when it existed. It does not establish who signed or whether any agreement is valid or enforceable.
For AI coding tools
When a generated prompt tells you to verify before reporting success, the sequence is:
- Run the project's build. No file marked
"use client"may importesigncomplyor readESIGNCOMPLY_API_KEY. - Run
npx esigncomply check --url <page>for every page that hosts a ceremony. Add--callback <url>with your server's confirmation endpoint, so the forged-success attempt runs. - Fix every finding marked
blockand every attempt markedACCEPTED, and run the check again until the exit code is0. - Report every finding marked
warn, with its rule ID, to the developer.
The person creates the account and accepts the terms once: never tick that box or type their code. Keys are yours to create with an agent token, the test key with POST /v1/agent/api-keys and the live key with POST /v1/agent/go-live when the person says go live. Live keys stay out of the repository and out of client code. The full runbook is in /setup.md and the account calls are in the agent account API.
MCP server (Planned)
Planned. A Model Context Protocol server that lets AI coding tools read the docs, generate prompts, run conformance checks and inspect test records is not available yet. Until it is, use this CLI, the REST API and the Markdown version of these pages listed in /llms.txt.