Get Started

SignatureAPI CLI

Sign in, write API keys into your env file, test webhooks locally, and set up coding agents from your terminal.

The signatureapi CLI sets up an application to use SignatureAPI from a terminal. It signs you in, writes an API key into your env file, delivers test webhooks to the handler running on your machine, and sets up coding agents with the SignatureAPI agent skills and MCP server.

The CLI is the headless path to your account. Use it alongside the REST API, which your application calls, and the MCP server, which agents call.

What you can do

API keys and webhook signing secrets go straight into your env file. The CLI never prints them.

Requirements

  • Node.js 22.20 or newer.
  • A SignatureAPI account. If you don’t have one, sign up first; the free plan includes test mode.
  • A browser on any device, to approve the sign-in once.

Run the CLI

The CLI is published on npm as signatureapi. Run it with npx; there is no install step:

npx signatureapi init

In a non-interactive shell, such as a script or a coding agent running commands for you, add --yes to npx so it never stops to confirm the download:

npx --yes signatureapi whoami

Pin a version

npx signatureapi runs the newest release each time. In scripts and CI, pin an exact version so a new release cannot change behavior under you. Add the CLI to your project as an exact dev dependency:

npm install --save-dev --save-exact signatureapi
npx signatureapi init

npx then runs the version in your lockfile. To run an exact version without adding it to the project, name it: npx --yes signatureapi@<version> .... npm view signatureapi version prints the current release.

You can also install the CLI globally with npm install --global signatureapi and drop the npx prefix. Every command and option is the same. A global install stays at the version you installed until you run npm update --global signatureapi.

Quickstart

Run these from your application’s directory.

1

Write your test API key

npx signatureapi init

The CLI prints a verification URL and a code. Approve the sign-in in your browser and choose the organization. The CLI then writes the account's test API key into .env as SIGNATUREAPI_KEY (.env.local in Next.js projects).

2

Receive test webhooks

Start your application's webhook handler, then run:

npx signatureapi listen --forward-to http://127.0.0.1:3000/webhooks

The CLI registers a test-mode webhook endpoint, saves its signing secret into .env, and forwards every test event to your handler until you press Ctrl+C.

3

Send an example event

In another terminal:

npx signatureapi trigger envelope.completed

The listener's terminal shows the delivery and your handler's response status.

Your application can now call the API with SIGNATUREAPI_KEY. Continue with the API quickstart to send your first envelope.

Test and live mode

SignatureAPI keeps test and live mode apart: a test key only reaches test resources, and a live key only reaches live ones. The CLI follows the same split.

CommandMode
initTest by default. --mode live creates a live key.
api-keys listBoth modes. --mode lists one.
api-keys createLive only. An account has one test key, which init retrieves.
api-keys rollThe mode you pass with --mode.
api-keys revokeLive only. The test key cannot be revoked.
listen, triggerTest only.

Live mode requires an active account and an organization role with live-mode access. Live-key changes ask for confirmation. See API keys.

Get help

Every command documents its options and examples in its help:

npx signatureapi --help
npx signatureapi listen --help
npx signatureapi api-keys roll --help

The help of the version you run is the authoritative reference for that version. Add --json to any command for machine-readable output.

Next steps