---
title: "Resources"
description: "Create, list, cancel, and delete envelopes from the SignatureAPI CLI, manage recipients, events, deliverables, and uploads, and run the same commands in CI."
canonical: "https://signatureapi.com/docs/cli/resources"
source: "https://signatureapi.com/docs/cli/resources.md"
last_verified_api_version: "1.18.0"
last_modified: "2026-11-18T13:54:43Z"
---

# Resources

Create, list, cancel, and delete envelopes from the SignatureAPI CLI, manage recipients, events, deliverables, and uploads, and run the same commands in CI.

_Last verified against API version 1.18.0._

Thirteen commands work with envelopes, recipients, events, deliverables, and uploads. Each one sends the same request as the [REST API](https://signatureapi.com/docs/api/overview), so a body that works with the API works here.

```bash
# 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-7ef57d423e56
```

Every 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](https://signatureapi.com/docs/cli/resources#command-reference) below is generated from the same definitions.

## Test and live mode

Commands act in [test mode](https://signatureapi.com/docs/api/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](https://signatureapi.com/docs/api/resources/envelopes/create) and [Create a ceremony](https://signatureapi.com/docs/api/resources/ceremonies/create). `--body <path>` reads a JSON file, and `--body -` reads stdin. The CLI sends the body as written.

```json envelope.json
{
  "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 cancel` and `envelopes delete` ask in both modes, because neither can be undone.
- In live mode, `envelopes create`, `recipients resend`, `recipients replace`, and `recipients ceremony` ask 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:

```bash
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](https://signatureapi.com/docs/api/resources/ceremonies/create) 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:

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

Space out requests in loops: the API applies [rate limits](https://signatureapi.com/docs/api/rate-limiting). 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](https://signatureapi.com/docs/cli/output) 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:

1. `--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.
2. `SIGNATUREAPI_KEY`, when it is set and not empty.
3. 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:

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

```bash
# 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 --json
```

**Keep 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](https://signatureapi.com/docs/cli/troubleshooting#api-keys-in-ci).

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

Commands of the `signatureapi` CLI, version 0.5.1. Run `npx signatureapi <command> --help` for the same text in a terminal.

### `envelopes list`

List envelopes, newest first, up to 20 per page. Filter by status or topic, and pass --cursor to get the next page.

```bash
npx signatureapi envelopes list [options]
```

Options:

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

```bash
npx signatureapi envelopes list
```

List completed live envelopes as JSON:

```bash
npx signatureapi envelopes list --status completed --mode live --json
```

Related: https://signatureapi.com/docs/api/resources/envelopes/object

### `envelopes get`

Show an envelope with its documents and recipients. A live envelope needs live mode: --mode live, or a live API key.

```bash
npx signatureapi envelopes get <envelope-id> [options]
```

Arguments:

- `<envelope-id>`: ID of the envelope, as envelopes list shows it

Global options: `--mode`, `--api-key-var`, `--credential-store`, `--json`.

Show a test envelope:

```bash
npx signatureapi envelopes get 5e5ace5e-...
```

Related: https://signatureapi.com/docs/api/resources/envelopes/object

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

```bash
npx signatureapi envelopes create --body <path> [options]
```

Options:

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

```bash
npx signatureapi envelopes create --body envelope.json
```

Create a live envelope from a script:

```bash
npx signatureapi envelopes create --body - --mode live --yes < envelope.json
```

Related: https://signatureapi.com/docs/api/resources/envelopes/object

### `envelopes cancel`

Cancel an envelope so its recipients can no longer sign. It cannot be undone. Asks for confirmation in test and live mode.

```bash
npx signatureapi envelopes cancel <envelope-id> [options]
```

Arguments:

- `<envelope-id>`: ID of the envelope, as envelopes list shows it

Options:

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

```bash
npx signatureapi envelopes cancel 5e5ace5e-...
```

Cancel a live envelope from a script:

```bash
npx signatureapi envelopes cancel 5e5ace5e-... --mode live --reason "Replaced by a new version" --yes
```

Related: https://signatureapi.com/docs/api/resources/envelopes/object

### `envelopes delete`

Delete a completed, canceled or failed envelope and its documents. It cannot be undone. Asks for confirmation in test and live mode.

```bash
npx signatureapi envelopes delete <envelope-id> [options]
```

Arguments:

- `<envelope-id>`: ID of the envelope, as envelopes list shows it

Options:

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

```bash
npx signatureapi envelopes delete 5e5ace5e-... --yes
```

Related: https://signatureapi.com/docs/api/resources/envelopes/object

## Recipient commands

Commands of the `signatureapi` CLI, version 0.5.1. Run `npx signatureapi <command> --help` for the same text in a terminal.

### `recipients resend`

Send the recipient's signing request again, optionally with another subject or message. Live mode asks for confirmation first.

```bash
npx signatureapi recipients resend <recipient-id> [options]
```

Arguments:

- `<recipient-id>`: ID of the recipient (re_...), as envelopes get shows it

Options:

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

```bash
npx signatureapi recipients resend re_...
```

Resend a live request with a new subject:

```bash
npx signatureapi recipients resend re_... --mode live --subject "Reminder: please sign" --yes
```

Related: https://signatureapi.com/docs/api/resources/recipients/object

### `recipients replace`

Replace a recipient who has not signed with another person, who gets the signing request instead. Live mode asks for confirmation first.

```bash
npx signatureapi recipients replace <recipient-id> --email <email> --name <name> [options]
```

Arguments:

- `<recipient-id>`: ID of the recipient (re_...), as envelopes get shows it

Options:

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

```bash
npx signatureapi recipients replace re_... --email jane@example.com --name "Jane Doe"
```

Related: https://signatureapi.com/docs/api/resources/recipients/object

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

```bash
npx signatureapi recipients ceremony <recipient-id> --body <path> [options]
```

Arguments:

- `<recipient-id>`: ID of the recipient (re_...), as envelopes get shows it

Options:

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

```bash
npx signatureapi recipients ceremony re_... --body ceremony.json
```

Related: https://signatureapi.com/docs/api/resources/recipients/object

## Event commands

Commands of the `signatureapi` CLI, version 0.5.1. Run `npx signatureapi <command> --help` for the same text in a terminal.

### `events list`

List the account's events, or one envelope's or recipient's, newest first, up to 20 per page.

```bash
npx signatureapi events list [options]
```

Options:

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

```bash
npx signatureapi events list --envelope 5e5ace5e-...
```

List recent live events as JSON:

```bash
npx signatureapi events list --mode live --json
```

Related: https://signatureapi.com/docs/api/resources/events/object

## Deliverable commands

Commands of the `signatureapi` CLI, version 0.5.1. Run `npx signatureapi <command> --help` for the same text in a terminal.

### `deliverables list`

List the deliverables of an envelope, newest first. A deliverable exists once the envelope is completed.

```bash
npx signatureapi deliverables list --envelope <envelope-id> [options]
```

Options:

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

```bash
npx signatureapi deliverables list --envelope 5e5ace5e-...
```

Related: https://signatureapi.com/docs/api/resources/deliverables/object

### `deliverables get`

Show a deliverable: its status and the URL of the signed documents.

```bash
npx signatureapi deliverables get <deliverable-id> [options]
```

Arguments:

- `<deliverable-id>`: ID of the deliverable (del_...), as deliverables list shows it

Global options: `--mode`, `--api-key-var`, `--credential-store`, `--json`.

Show a deliverable:

```bash
npx signatureapi deliverables get del_...
```

Related: https://signatureapi.com/docs/api/resources/deliverables/object

## Upload commands

Commands of the `signatureapi` CLI, version 0.5.1. Run `npx signatureapi <command> --help` for the same text in a terminal.

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

```bash
npx signatureapi uploads create <path> [options]
```

Arguments:

- `<path>`: PDF, DOCX or PNG file to upload, up to 5 MB (4.5 MB with an API key)

Global options: `--api-key-var`, `--credential-store`, `--json`.

Upload a contract:

```bash
npx signatureapi uploads create contract.pdf
```

Upload and keep the URL for a script:

```bash
npx signatureapi uploads create contract.pdf --json
```

Related: https://signatureapi.com/docs/api/resources/uploads/object

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

```bash
npx signatureapi uploads inspect <upload-id> [options]
```

Arguments:

- `<upload-id>`: ID of the upload (upl_...), as uploads create shows it

Global options: `--api-key-var`, `--credential-store`, `--json`.

Inspect an uploaded contract:

```bash
npx signatureapi uploads inspect upl_...
```

Related: https://signatureapi.com/docs/api/resources/uploads/object

## Global options

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