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
- Sign in with your SignatureAPI account and choose the organization the CLI acts for.
- Write an API key into
.env, and list, create, roll, and revoke API keys. - Receive test webhooks at a local handler, and send example events to it.
- Set up coding agents with the agent skills and the MCP server.
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.
Write your test API key
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).
Receive test webhooks
Start your application's webhook handler, then run:
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.
Send an example event
In another terminal:
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.
| Command | Mode |
|---|---|
init | Test by default. --mode live creates a live key. |
api-keys list | Both modes. --mode lists one. |
api-keys create | Live only. An account has one test key, which init retrieves. |
api-keys roll | The mode you pass with --mode. |
api-keys revoke | Live only. The test key cannot be revoked. |
listen, trigger | Test 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.