# 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.

Source: https://esigncomply.com/docs/sdk/cli

The `esigncomply` CLI ships inside the [Node SDK](https://esigncomply.com/docs/sdk/node.md) package. Run it without installing anything:

```bash
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. |

```text
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. |

```bash
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](https://esigncomply.com/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](https://esigncomply.com/docs/guides/test-mode.md).

## 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

```bash
npx esigncomply@latest demo
```

```text
esigncomply demo [--port 4310] [--auto]
```

Records a first test signature without writing any code. The command:

1. Creates a document named "Demo Terms of Service", a document named "Demo Privacy Notice" and a profile named "Demo signup" (`US-FED`, method `checkbox`, level `L1`) in test mode. On a later run it reuses the ones it made before.
2. Serves a signup page at `http://localhost:4310/` and waits.
3. When you tick the box and click "Create account", the page runs a real ceremony against the API with a session client token.
4. Confirms the record from the command's own process with the secret key: it must be a test record, with status `recorded`, `timestamped` or `anchored`, for the signer and the document versions the command asked for.
5. 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](https://esigncomply.com/docs/sdk/browser.md) 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](https://esigncomply.com/docs/concepts/observed-and-asserted.md).

```text
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](https://esigncomply.com/docs/conformance.md). It has two uses, which can be combined in one run.

```text
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

```bash
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`](https://esigncomply.com/docs/api/errors.md#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](https://esigncomply.com/docs/guides/server-confirmation.md).

**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:

```bash
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.

```text
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](https://esigncomply.com/docs/conformance.md#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

```bash
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](https://esigncomply.com/docs/api/jurisdictions.md).

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.

```yaml
# .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

```bash
npx esigncomply@latest documents publish ./legal/terms.md --document doc_8Hq2 --label 2026-11-21 --material --summary "Added arbitration clause in section 14."
```

```text
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.

```text
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](https://esigncomply.com/docs/api/documents.md). Marking a version as a material change leaves earlier acceptances outstanding: see [Re-acceptance](https://esigncomply.com/docs/guides/reacceptance.md).

## webhooks listen

```bash
npx esigncomply@latest webhooks listen --forward http://localhost:3000/api/esigncomply/webhook --secret whsec_...
```

```text
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/json` and `User-Agent: EsignComply-CLI-Forwarder/1.0`
- `webhook-id`, set to the event ID
- `webhook-timestamp`, set to the time of forwarding, and `webhook-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](https://esigncomply.com/docs/api/webhooks.md). The fields of a delivery are in the [account API](https://esigncomply.com/docs/api/account.md).

```text
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](https://esigncomply.com/docs/guides/test-mode.md).

## verify

```bash
npx esigncomply@latest verify rec_Z4m8.zip
```

```text
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](https://esigncomply.com/docs/sdk/verify.md).

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:

1. Run the project's build. No file marked `"use client"` may import `esigncomply` or read `ESIGNCOMPLY_API_KEY`.
2. 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.
3. Fix every finding marked `block` and every attempt marked `ACCEPTED`, and run the check again until the exit code is `0`.
4. 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](https://esigncomply.com/setup.md) and the account calls are in the [agent account API](https://esigncomply.com/docs/api/agent.md).

## 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](https://esigncomply.com/llms.txt).
