Commands
Resources
Create, list, cancel, and delete envelopes from the SignatureAPI CLI, manage recipients, events, deliverables, and uploads, and run the same commands in CI.
Thirteen commands work with envelopes, recipients, events, deliverables, and uploads. Each one sends the same request as the REST API, so a body that works with the API works here.
# List your test envelopes
npx signatureapi envelopes list
# Create and send an envelope from a JSON body
npx signatureapi envelopes create --body envelope.json
# Follow what happens to it
npx signatureapi events list --envelope eb4cf433-a8af-4161-b37b-7ef57d423e56Every resource command also takes --api-key-var, --credential-store, and --json, and every one except the two uploads commands takes --mode. <command> --help lists every option with an example. The command reference below is generated from the same definitions.
Test and live mode
Commands act in test mode unless you pass --mode live or run them with a live API key. Test mode sends no email to recipients.
A resource belongs to one mode. Reaching a resource of the other mode fails with mode-error, and the message says which mode to use. Uploads belong to the account, not to a mode.
Request bodies
envelopes create and recipients ceremony take the API’s request body: Create an envelope and Create a ceremony. --body <path> reads a JSON file, and --body - reads stdin. The CLI sends the body as written.
{
"title": "Service Agreement",
"message": "Please review the agreement and provide your signature.",
"routing": "parallel",
"documents": [
{
"key": "service_agreement",
"title": "Service Agreement",
"url": "https://pub-9cb75390636c4a8a83a6f76da33d7f45.r2.dev/docs-samples/acme-service-agreement.pdf",
"format": "pdf",
"places": [
{ "key": "client_signs_here", "type": "signature", "recipient_key": "client" },
{ "key": "provider_signs_here", "type": "signature", "recipient_key": "provider" }
]
}
],
"recipients": [
{ "type": "signer", "key": "client", "name": "Jane Doe", "email": "jane.doe@example.com" },
{ "type": "signer", "key": "provider", "name": "John Smith", "email": "john.smith@example.com" }
]
}A body can be at most 1,536,000 bytes. A body that can’t be read, isn’t a JSON object, or is over the limit fails with invalid-options before any request.
Confirmation
Some commands ask before they act:
envelopes cancelandenvelopes deleteask in both modes, because neither can be undone.- In live mode,
envelopes create,recipients resend,recipients replace, andrecipients ceremonyask too, because they reach real people.
In a non-interactive shell, pass --yes. Without it, the command fails with confirmation-required (exit code 2) before it signs in or sends anything. --json does not skip the prompt. A command that reads its body from stdin (--body -) can’t prompt, so it needs --yes whenever it needs confirmation. Declining the prompt changes nothing and reports confirmation-declined.
Upload a local document
uploads create uploads a PDF, DOCX, or PNG and returns a URL you can use as a document’s url in envelopes create. The file’s extension and its first bytes must agree. Uploads expire after 24 hours.
| Credential | Largest file |
|---|---|
| Signed in | 5 MB (5,242,880 bytes) |
| API key | 4.5 MB (4,500,000 bytes) |
Upload a file and create an envelope from it in one go:
url=$(npx signatureapi uploads create contract.pdf --json | jq -r 'select(.type == "result") | .data.url')
jq --arg url "$url" '.documents[0].url = $url' envelope.json | npx signatureapi envelopes create --body -uploads inspect shows a PDF or DOCX upload’s pages, the [[key]] placeholders it found, and its template fields. Run it before you create the envelope to check that every placeholder key is there.
Ceremonies
recipients ceremony creates a new ceremony for a recipient and shows its URL. The new ceremony revokes the recipient’s active one. Anyone with a ceremony URL can sign as that recipient, so share it only with them. When the first authentication method is email_link, there is no URL: SignatureAPI emails the link to the recipient.
Pagination
List commands return up to 20 items per page (--limit 1 to 20). When there are more, the result carries next_cursor, and its next step is the exact command for the next page: the same filters plus --cursor <next_cursor>. The last page has no next_cursor.
No option fetches every page. Loop on next_cursor instead:
cursor=""
while :; do
result=$(npx --yes signatureapi envelopes list --status completed ${cursor:+--cursor "$cursor"} --json \
| jq -c 'select(.type == "result")')
echo "$result" | jq -e '.status == "success"' > /dev/null || exit 1
echo "$result" | jq -r '.data[].id'
cursor=$(echo "$result" | jq -r '.next_cursor // empty')
[ -n "$cursor" ] || break
doneSpace out requests in loops: the API applies rate limits. A read (list, get, inspect) is retried a few times on 429; a change is never resent. A 429 that remains fails with too-many-requests.
Results
With --json, the final result event carries the resource:
| Field | Description |
|---|---|
credential | sign_in or api_key: which credential ran. |
mode | test or live: the mode the request acted in. Absent for uploads. |
data | The API resource, a list’s data array, or { id, url } for uploads create. Absent for envelopes delete. |
next_cursor | Lists only, when there is a next page. |
problem | Failures from an API error: status, type, title, and detail and errors when the API sent them. |
Text output names the credential and the mode in its headline, for example “Envelopes (test mode, signed in)”, and shows the fields a person checks first. Add --json for the full resource. See Output and exit codes for the event stream and the result codes.
A change whose outcome is unknown after the request was sent, for example after a network error, is a partial result (exit code 1), such as envelope_creation_unconfirmed. The CLI never resends a change. Its next step says how to check whether the change happened before you try again.
API keys in CI
Resource commands can run with an API key instead of a sign-in, so a CI job needs no browser.
Which credential runs, in this order:
--api-key-var <name>: the key in the env variable with that name. The option takes a variable name, never a key: a key on the command line would end up in shell history, process lists, and CI logs.SIGNATUREAPI_KEY, when it is set and not empty.- The sign-in.
init writes SIGNATUREAPI_KEY by default, so a CI secret with that name works as is. The CLI reads the key from the process environment only, never from an env file. To use the sign-in while SIGNATUREAPI_KEY is exported, empty it for one command:
SIGNATUREAPI_KEY= npx signatureapi envelopes list--credential-store applies only to the sign-in. With a key, it fails with invalid-options.
The key decides the mode. A test key acts in test mode and a live key in live mode, so --mode is optional. A --mode that differs from the key’s mode fails with api-key-mode-mismatch before any request.
You see which key runs. Before its first request, the command prints “Using the API key in SIGNATUREAPI_KEY, test mode” (with the variable and mode it used). With --json, this is a progress event with the code api_key_selected and the fields variable and mode. The key itself never appears in output, errors, or next steps.
Confirmation still applies. envelopes cancel and envelopes delete always need --yes in CI, in test mode too. With a live key, so do envelopes create, recipients resend, recipients replace, and recipients ceremony.
A CI job with the test key from a secret:
# SIGNATUREAPI_KEY comes from the CI secret store.
id=$(npx --yes signatureapi envelopes create --body envelope.json --json | jq -r 'select(.type == "result") | .data.id')
npx --yes signatureapi envelopes get "$id" --json
npx --yes signatureapi envelopes cancel "$id" --reason "Test run finished" --yes --json
npx --yes signatureapi envelopes delete "$id" --yes --jsonKeep URLs out of shared logs. Text output prints the ceremony URL (recipients ceremony), the deliverable URL (deliverables get), and the upload URL (uploads create). Text output goes to stderr, which CI logs capture, and anyone with a ceremony URL can sign as the recipient. With --json, the URL is in the result on stdout, where your script decides what to do with it.
The key failure codes are listed in Troubleshooting.
Command reference
Generated from the CLI’s own command definitions (the published signatureapi package). The help of the version you run is the authoritative reference for that version.
Envelope commands
envelopes list
List envelopes, newest first, up to 20 per page. Filter by status or topic, and pass --cursor to get the next page.
Usagenpx signatureapi envelopes list [options]
| Option | Description |
|---|---|
--status <status> | Only envelopes with this status, such as in_progress. |
--topic <topic> | Only envelopes with this topic. |
--limit <count> | Envelopes per page, 1 to 20 (default: 20). |
--cursor <cursor> | Cursor of the page to get, from a previous result's next_cursor. |
Global options: --mode, --api-key-var, --credential-store, --json.
# List test envelopes
npx signatureapi envelopes list
# List completed live envelopes as JSON
npx signatureapi envelopes list --status completed --mode live --jsonRelated: Envelope
envelopes get
Show an envelope with its documents and recipients. A live envelope needs live mode: --mode live, or a live API key.
Usagenpx signatureapi envelopes get <envelope-id> [options]
| Argument | Description |
|---|---|
<envelope-id> | ID of the envelope, as envelopes list shows it. Required. |
Global options: --mode, --api-key-var, --credential-store, --json.
# Show a test envelope
npx signatureapi envelopes get 5e5ace5e-...Related: Envelope
envelopes create
Create an envelope from a JSON body: the public Create an envelope request. In test mode, recipients get test-mode requests; live mode asks for confirmation first.
Usagenpx signatureapi envelopes create --body <path> [options]
| Option | Description |
|---|---|
--body <path> | JSON file with the envelope, or - to read it from stdin. Required. |
--yes | Confirm a live-mode change without the prompt (required in non-interactive shells). |
Global options: --mode, --api-key-var, --credential-store, --json.
# Create a test envelope from a file
npx signatureapi envelopes create --body envelope.json
# Create a live envelope from a script
npx signatureapi envelopes create --body - --mode live --yes < envelope.jsonRelated: Envelope
envelopes cancel
Cancel an envelope so its recipients can no longer sign. It cannot be undone. Asks for confirmation in test and live mode.
Usagenpx signatureapi envelopes cancel <envelope-id> [options]
| Argument | Description |
|---|---|
<envelope-id> | ID of the envelope, as envelopes list shows it. Required. |
| Option | Description |
|---|---|
--reason <text> | Reason sent in the envelope.canceled event. |
--yes | Confirm without the prompt (required in non-interactive shells). |
Global options: --mode, --api-key-var, --credential-store, --json.
# Cancel a test envelope
npx signatureapi envelopes cancel 5e5ace5e-...
# Cancel a live envelope from a script
npx signatureapi envelopes cancel 5e5ace5e-... --mode live --reason "Replaced by a new version" --yesRelated: Envelope
envelopes delete
Delete a completed, canceled or failed envelope and its documents. It cannot be undone. Asks for confirmation in test and live mode.
Usagenpx signatureapi envelopes delete <envelope-id> [options]
| Argument | Description |
|---|---|
<envelope-id> | ID of the envelope, as envelopes list shows it. Required. |
| Option | Description |
|---|---|
--yes | Confirm without the prompt (required in non-interactive shells). |
Global options: --mode, --api-key-var, --credential-store, --json.
# Delete a test envelope without the prompt
npx signatureapi envelopes delete 5e5ace5e-... --yesRelated: Envelope
Recipient commands
recipients resend
Send the recipient's signing request again, optionally with another subject or message. Live mode asks for confirmation first.
Usagenpx signatureapi recipients resend <recipient-id> [options]
| Argument | Description |
|---|---|
<recipient-id> | ID of the recipient (re_...), as envelopes get shows it. Required. |
| Option | Description |
|---|---|
--subject <text> | Subject to use instead of the original. |
--message <text> | Message to use instead of the original. |
--yes | Confirm a live-mode change without the prompt (required in non-interactive shells). |
Global options: --mode, --api-key-var, --credential-store, --json.
# Resend a test request
npx signatureapi recipients resend re_...
# Resend a live request with a new subject
npx signatureapi recipients resend re_... --mode live --subject "Reminder: please sign" --yesRelated: Recipient
recipients replace
Replace a recipient who has not signed with another person, who gets the signing request instead. Live mode asks for confirmation first.
Usagenpx signatureapi recipients replace <recipient-id> --email <email> --name <name> [options]
| Argument | Description |
|---|---|
<recipient-id> | ID of the recipient (re_...), as envelopes get shows it. Required. |
| Option | Description |
|---|---|
--email <email> | Email of the new recipient. Required. |
--name <name> | Name of the new recipient. Required. |
--yes | Confirm a live-mode change without the prompt (required in non-interactive shells). |
Global options: --mode, --api-key-var, --credential-store, --json.
# Replace a test recipient
npx signatureapi recipients replace re_... --email jane@example.com --name "Jane Doe"Related: Recipient
recipients ceremony
Create a signing ceremony for a recipient from a JSON body (the public Create ceremony request) and show its URL. A new ceremony revokes the recipient's active one. With email_link as the first authentication method there is no URL: SignatureAPI emails the link. Anyone with the URL can sign as the recipient; share it only with them. Live mode asks for confirmation first.
Usagenpx signatureapi recipients ceremony <recipient-id> --body <path> [options]
| Argument | Description |
|---|---|
<recipient-id> | ID of the recipient (re_...), as envelopes get shows it. Required. |
| Option | Description |
|---|---|
--body <path> | JSON file with the ceremony, or - to read it from stdin. Required. |
--yes | Confirm a live-mode change without the prompt (required in non-interactive shells). |
Global options: --mode, --api-key-var, --credential-store, --json.
# Create an embedded test ceremony
npx signatureapi recipients ceremony re_... --body ceremony.jsonRelated: Recipient
Event commands
events list
List the account's events, or one envelope's or recipient's, newest first, up to 20 per page.
Usagenpx signatureapi events list [options]
Options (5)
| Option | Description |
|---|---|
--envelope <envelope-id> | Only this envelope's events. |
--recipient <recipient-id> | Only this recipient's events. |
--type <event-type> | Only events of this type, such as envelope.completed. |
--limit <count> | Events per page, 1 to 20 (default: 20). |
--cursor <cursor> | Cursor of the page to get, from a previous result's next_cursor. |
Global options: --mode, --api-key-var, --credential-store, --json.
# List an envelope's events
npx signatureapi events list --envelope 5e5ace5e-...
# List recent live events as JSON
npx signatureapi events list --mode live --jsonRelated: Event
Deliverable commands
deliverables list
List the deliverables of an envelope, newest first. A deliverable exists once the envelope is completed.
Usagenpx signatureapi deliverables list --envelope <envelope-id> [options]
| Option | Description |
|---|---|
--envelope <envelope-id> | Envelope whose deliverables to list. Required. |
--limit <count> | Deliverables per page, 1 to 20 (default: 20). |
--cursor <cursor> | Cursor of the page to get, from a previous result's next_cursor. |
Global options: --mode, --api-key-var, --credential-store, --json.
# List a completed envelope's deliverables
npx signatureapi deliverables list --envelope 5e5ace5e-...Related: Deliverable
deliverables get
Show a deliverable: its status and the URL of the signed documents.
Usagenpx signatureapi deliverables get <deliverable-id> [options]
| Argument | Description |
|---|---|
<deliverable-id> | ID of the deliverable (del_...), as deliverables list shows it. Required. |
Global options: --mode, --api-key-var, --credential-store, --json.
# Show a deliverable
npx signatureapi deliverables get del_...Related: Deliverable
Upload commands
uploads create
Upload a local PDF, DOCX or PNG and show the URL to use as a document's url in envelopes create. Uploads expire after 24 hours and belong to the account, not a mode.
Usagenpx signatureapi uploads create <path> [options]
| Argument | Description |
|---|---|
<path> | PDF, DOCX or PNG file to upload, up to 5 MB (4.5 MB with an API key). Required. |
Global options: --api-key-var, --credential-store, --json.
# Upload a contract
npx signatureapi uploads create contract.pdf
# Upload and keep the URL for a script
npx signatureapi uploads create contract.pdf --jsonRelated: Upload
uploads inspect
Show the analyzed structure of a PDF or DOCX upload: pages, the placeholders found and, for DOCX templates, the template fields. Uploads belong to the account, not a mode.
Usagenpx signatureapi uploads inspect <upload-id> [options]
| Argument | Description |
|---|---|
<upload-id> | ID of the upload (upl_...), as uploads create shows it. Required. |
Global options: --api-key-var, --credential-store, --json.
# Inspect an uploaded contract
npx signatureapi uploads inspect upl_...Related: Upload
Global options
Each command lists the global options it takes. They go after the command words.
| Option | Description |
|---|---|
-V, --version | Show the CLI version. |
-h, --help | Show help for a command. |
--credential-store <store> | Where the sign-in is kept; defaults to the OS keychain when one is usable, else a private file. One of keychain, file. |
--json | Print newline-delimited JSON events instead of text. |
--mode <mode> | Mode to act in; with an API key, the key's mode. One of test, live. Default test. |
--api-key-var <name> | Env variable that holds the API key to use instead of the sign-in (default: SIGNATUREAPI_KEY when set). |
Resource commands act in test mode unless --mode live is given or the API key is a live key.