# docuseal-cli

Adopt this skill: https://proskills.md/skills/other/docusealco-docuseal-cli-skills-docuseal-cli

Page: https://proskills.md/skills/other/docusealco-docuseal-cli-skills-docuseal-cli
This document is the public skill bundle for that page. It contains SKILL.md and every helper file the catalog carries. No login is required.

## File: skills/docuseal-cli/SKILL.md
size: 5550
sha: 8adbe1e65a4ba4cad4cdf542717fbe686c51cdbc
upstream: https://github.com/docusealco/docuseal-cli/blob/master/skills/docuseal-cli/SKILL.md

````text
---
name: docuseal-cli
description: >
  Manage DocuSeal e-signature workflows from the terminal via the DocuSeal CLI -
  create templates from PDF/DOCX/HTML, send documents for signing, track submissions,
  and update submitters. Use when the user wants to run DocuSeal commands in the shell,
  scripts, or CI/CD pipelines. Always load this skill before running `docuseal` commands.
license: MIT
metadata:
  author: DocuSeal
  version: "1.0.8"
  homepage: https://www.docuseal.com
  source: https://github.com/docusealco/docuseal-cli
  openclaw:
    emoji: "📝"
    requires:
      env:
        - DOCUSEAL_API_KEY
        - DOCUSEAL_SERVER
      bins:
        - docuseal
      primaryEnv: DOCUSEAL_API_KEY
    install:
      - id: npm
        kind: npm
        package: docuseal
        bins:
          - docuseal
        label: Install DocuSeal CLI (npm)
  hermes:
    tags:
      - DocuSeal
      - E-signature
      - Documents
      - PDF
      - CLI
required_environment_variables:
  - name: DOCUSEAL_API_KEY
    prompt: DocuSeal API key (global, EU, or self-hosted account)
    help: "Get it at https://console.docuseal.com/api (global), https://console.docuseal.eu/api (EU), or https://<your-domain>/api (self-hosted). Overrides the key saved by `docuseal configure` in ~/.config/docuseal/credentials.json."
    required_for: authenticating the docuseal CLI
  - name: DOCUSEAL_SERVER
    prompt: DocuSeal server - global, europe, or self-hosted URL (leave empty for global)
    help: "Optional. Use global (docuseal.com), europe (docuseal.eu), or https://<your-domain> for self-hosted. Overrides the server saved by `docuseal configure` in ~/.config/docuseal/credentials.json; the CLI falls back to global only when neither is set."
    required_for: selecting the DocuSeal region or self-hosted server
    optional: true
---

## Agent Protocol

**Rules for agents:**
- Supply ALL required flags — the CLI will not prompt for missing parameters.
- Output is always JSON.
- Use `-d key=value` (bracket notation) or `-d '{"..": ".."}'` (JSON) for body and array parameters.

## Authentication

Set environment variables:
- `DOCUSEAL_API_KEY` — API key (required). Get yours at https://console.docuseal.com/api
- `DOCUSEAL_SERVER` — `global` (default), `europe`, or full URL for self-hosted (e.g. `https://docuseal.yourdomain.com`)

## Available Commands

| Command Group | What it does |
|---|---|
| `templates` | list, retrieve, update, archive, create-pdf, create-docx, create-html, clone, merge, update-documents |
| `submissions` | list, retrieve, update, archive, create, send-emails, create-pdf, create-docx, create-html, documents |
| `submitters` | list, retrieve, update |

Read the matching reference file for detailed flags and examples.

## Common Mistakes

| # | Mistake | Fix |
|---|---|---|
| 1 | **Forgetting `-d template_id=<id>` on `submissions create`** | `--template-id` is a flag; submitters and other body params go via `-d` |
| 2 | **Passing a plain file path as a URL** | `--file` accepts a local path; for remote files use `-d "documents[0][file]=https://..."` |
| 3 | **Expecting array params as comma-separated** | Arrays use bracket notation: `-d "template_ids[]=1"` `-d "template_ids[]=2"` |
| 4 | **Using `templates create-pdf` without a Pro plan** | Commands marked _(Pro)_ require a DocuSeal Pro subscription |
| 5 | **Sending to multiple recipients with `submissions create`** | Use `submissions send-emails --emails a@b.com,c@d.com` for bulk; `submissions create` is per-submitter |

## Security

The CLI accepts user-provided file paths, remote URLs (`documents[0][file]=https://...`), and HTML content as template input. This is by design — all content originates from the authenticated user and is sent directly to the DocuSeal API over HTTPS. The CLI does not fetch, render, or execute remote content locally; it passes references to the server for processing. No user input is interpolated into shell commands.

## Common Patterns

**List templates:**
```bash
docuseal templates list --q "NDA" --limit 20
```

**Create a template from a PDF and send for signing:**
```bash
docuseal templates create-pdf --file contract.pdf --name "NDA"
docuseal submissions send-emails --template-id 1001 --emails signer@example.com
```

**Create a submission with pre-filled fields (bracket notation):**
```bash
docuseal submissions create --template-id 1001 \
  -d "submitters[0][email]=john@acme.com" \
  -d "submitters[0][values][Company Name]=Acme Corp"
```

**Create a submission with pre-filled fields (JSON):**
```bash
docuseal submissions create --template-id 1001 \
  -d '{"submitters": [{"email": "john@acme.com", "values": {"Company Name": "Acme Corp"}}]}'
```

**Check signing status:**
```bash
docuseal submissions list --template-id 1001 --status pending
```

**Update a submitter:**
```bash
docuseal submitters update 201 --email new@acme.com --send-email
```

## When to Load References

- **Creating or managing templates** → [references/templates.md](references/templates.md)
- **Sending documents for signing or tracking status** → [references/submissions.md](references/submissions.md)
- **Using dynamic content variables in DOCX** → [references/docx-variables.md](references/docx-variables.md)
- **Embedding field tags in PDF/DOCX** → [references/field-tags.md](references/field-tags.md)
- **Writing HTML templates with field tags** → [references/html-fields.md](references/html-fields.md)
- **Listing or updating signers** → [references/submitters.md](references/submitters.md)
````

## File: skills/docuseal-cli/references/docx-variables.md
size: 2395
sha: fc4612c5b09eb58d40c7eae8bc588732da809b0d
upstream: https://github.com/docusealco/docuseal-cli/blob/master/skills/docuseal-cli/references/docx-variables.md

````text
# DOCX Dynamic Content Variables

DocuSeal supports dynamic content variables in DOCX templates. Variables are replaced with provided values when creating a submission via `submissions create-docx` using the `-d "variables[key]=value"` syntax.

Full guide: https://www.docuseal.com/guides/use-dynamic-content-variables-in-docx-to-create-personalized-documents

## Syntax

Variables use double-bracket notation: `[[variable_name]]`

## Simple Variables

```
[[signer_name]]
[[company_name]]
[[contract_date]]
```

Replaced with the corresponding value passed via `variables`.

## Conditional Logic

**If:**
```
[[if:is_vip]] Thank you for being a valued VIP customer! [[end]]
```

**If/else:**
```
[[if:is_vip]] Thank you for being a valued VIP customer! [[else]] Thank you for being our customer. [[end:is_vip]]
```

The condition variable is a boolean.

## Loops

Iterate over arrays using `[[for:array_name]]`:

```
[[for:items]] - [[item.name]] ([[item.quantity]]) [[end]]
```

Table rows:
```
[[for:invoices]]
| [[invoice.name]] | [[invoice.quantity]] | [[invoice.price]] | [[invoice.total]] |
[[end]]
```

Inside the loop, access properties via singular dot notation: `items` array → `item.name`.

## HTML Content Variables

Variable values can contain styled HTML rendered directly in the DOCX:

**Paragraphs:**
```html
<p><b style="color: #1976D2; text-decoration: underline;">Bold blue text</b> normal text.</p>
```

**Lists:**
```html
<ul>
  <li>Item one</li>
  <li>Item two</li>
</ul>
```

**Tables:**
```html
<table border="1" style="border-collapse: collapse;">
  <tr><th style="padding: 8px;"><b>Item</b></th><th><b>Price</b></th></tr>
  <tr><td style="padding: 8px;">Widget</td><td>$50</td></tr>
</table>
```

**Links:**
```html
<a href="https://example.com" style="color: #1976D2;">Example Link</a>
```

## Using with CLI

```bash
# Simple variables
docuseal submissions create-docx --file contract.docx \
  -d "submitters[0][email]=john@acme.com" \
  -d "variables[signer_name]=John Doe" \
  -d "variables[company_name]=Acme Corp"

# Boolean for conditionals
docuseal submissions create-docx --file contract.docx \
  -d "submitters[0][email]=john@acme.com" \
  -d "variables[is_vip]=true"

# HTML content
docuseal submissions create-docx --file contract.docx \
  -d "submitters[0][email]=john@acme.com" \
  -d 'variables[description]=<p><b>Important</b> details here.</p>'
```
````

## File: skills/docuseal-cli/references/field-tags.md
size: 3718
sha: 72f74bee7d8fa221e3b70fe85ec0c25a47e5e64a
upstream: https://github.com/docusealco/docuseal-cli/blob/master/skills/docuseal-cli/references/field-tags.md

````text
# PDF / DOCX Field Tags

DocuSeal uses embedded text tags in PDF and DOCX documents to define fillable fields. Tags are placed directly in the document text and are automatically detected when uploaded via `templates create-pdf`, `templates create-docx`, `submissions create-pdf`, or `submissions create-docx`.

Full guide: https://www.docuseal.com/guides/use-embedded-text-field-tags-in-the-pdf-to-create-a-fillable-form

## Syntax

Tags use double curly braces. Attributes are separated by semicolons:

```
{{Field Name}}
{{Field Name;type=signature}}
{{Field Name;type=date;role=First Party;required=true}}
```

## Field Types

| Type | Description |
|---|---|
| `text` | Text input (default) |
| `signature` | Signature capture |
| `initials` | Initials capture |
| `date` | Date picker |
| `datenow` | Auto-filled signing date (read-only) |
| `image` | Image upload |
| `file` | File upload |
| `payment` | Payment field |
| `stamp` | Document stamp |
| `select` | Dropdown menu |
| `checkbox` | Boolean checkbox |
| `multiple` | Multiple selection |
| `radio` | Radio button |
| `phone` | Phone number (2FA) |
| `verification` | Identity verification |
| `kba` | Knowledge-based authentication |

## Attributes

| Attribute | Description |
|---|---|
| `name` | Field name (the text before the first `;`) |
| `type` | Field type (default: `text`) |
| `role` | Signer role for multi-party signing |
| `default` | Pre-filled value |
| `required` | Required field (`true` by default) |
| `readonly` | Prevent editing (`false` by default) |
| `title` | Display label in signing UI |
| `description` | Help text in signing UI |
| `options` | Comma-separated values for select/radio/multiple |
| `option` | Single option value for radio buttons |
| `condition` | Conditional visibility: `FieldName:value` |
| `width` | Width in pixels |
| `height` | Height in pixels |
| `hidden` | Hide field (`true`/`false`) |
| `mask` | Mask sensitive data (`true`/`false`) |

## Text Formatting

| Attribute | Values |
|---|---|
| `font` | `Times`, `Helvetica`, `Courier` |
| `font_size` | Numeric value |
| `font_type` | `bold`, `italic`, `bold_italic` |
| `color` | `blue`, `red`, `black` (default) |
| `align` | `left`, `center`, `right` |
| `valign` | `top`, `center`, `bottom` |

## Type-Specific Attributes

| Attribute | Applies to | Values |
|---|---|---|
| `format` | date | `DD/MM/YYYY`, `MM/DD/YYYY` (default) |
| `format` | signature | `drawn`, `typed`, `drawn_or_typed` (default), `upload` |
| `format` | number | `usd`, `eur`, `gbp` |
| `min` / `max` | date, number | Min/max allowed value |
| `method` | verification | `aes`, `qes` |

## Examples

**Basic fields:**
```
{{Full Name}}
{{Email;title=Email Address}}
{{Sign;type=signature}}
{{Date;type=date;format=DD/MM/YYYY}}
{{Today;type=datenow}}
```

**Multi-role signing:**
```
{{Landlord Name;role=Landlord}}
{{Landlord Sign;type=signature;role=Landlord}}
{{Tenant Name;role=Tenant}}
{{Tenant Sign;type=signature;role=Tenant}}
```

**Selection fields:**
```
{{Department;type=select;options=Engineering,Sales,Marketing,HR}}
{{Priority;type=radio;option=Low}}
{{Priority;type=radio;option=Medium}}
{{Priority;type=radio;option=High}}
{{type=checkbox}} I agree to the terms
```

**Conditional fields:**
```
{{Agree;type=checkbox}}
{{Details;condition=Agree:true}}
```

**Using with CLI:**
```bash
docuseal templates create-pdf --file contract.pdf --name "Contract"
docuseal templates create-docx --file contract.docx --name "Contract"
docuseal submissions create-pdf --file contract.pdf \
  -d "submitters[0][email]=john@acme.com" \
  -d "submitters[0][role]=Tenant"
```

## Resources

- Example PDF with field tags: https://www.docuseal.com/examples/fieldtags.pdf
````

## File: skills/docuseal-cli/references/html-fields.md
size: 5456
sha: 9938c0a31d1b31651852950dc4315a9412484bd2
upstream: https://github.com/docusealco/docuseal-cli/blob/master/skills/docuseal-cli/references/html-fields.md

````text
# HTML Field Tags

DocuSeal uses custom HTML tags to define fillable fields in templates. These tags can be used in `--html` or `--file` values for `templates create-html` and `submissions create-html` commands.

Full guide: https://www.docuseal.com/guides/create-pdf-document-fillable-form-with-html-api

## Available Tags

| Tag | Purpose |
|---|---|
| `<text-field>` | Text input |
| `<signature-field>` | Signature capture |
| `<date-field>` | Date picker |
| `<image-field>` | Image upload |
| `<initials-field>` | Initials capture |
| `<phone-field>` | Phone number input |
| `<stamp-field>` | Document stamp |
| `<file-field>` | File attachment |
| `<checkbox-field>` | Boolean checkbox |
| `<radio-field>` | Single option selection |
| `<select-field>` | Dropdown menu |
| `<multi-select-field>` | Multiple selection dropdown |
| `<payment-field>` | Payment processing |
| `<verification-field>` | Identity verification |

## Common Attributes

All tags support:

| Attribute | Description |
|---|---|
| `name` | Field identifier (required) |
| `role` | Signer role assignment |
| `default` | Pre-filled value |
| `required` | Required field, `true` by default |
| `readonly` | Prevent editing by signer |
| `title` | Display label |
| `description` | Help text shown to signer |
| `condition` | Conditional visibility, e.g. `"Status:active"` |
| `style` | CSS styling for field size and placement. Set `width` and `height` so the field renders on the page. |

**Important:** HTML field tags should usually include a `style` attribute with at least `width` and `height`. Without explicit dimensions, the rendered field can collapse and not appear where you expect in the document. For inline fields, `display: inline-block` is commonly used.

## Style Examples

Use `style=""` to control field size and layout:

```html
<text-field name="Full Name" role="Tenant" style="width: 160px; height: 20px; display: inline-block;"></text-field>
<signature-field name="Tenant Signature" role="Tenant" style="width: 160px; height: 80px; display: inline-block;"></signature-field>
```

## Text Formatting Attributes

| Attribute | Values |
|---|---|
| `font` | `Times`, `Helvetica`, `Courier` |
| `font-size` | Numeric value |
| `font-type` | `bold`, `italic`, `bold_italic` |
| `color` | `blue`, `red`, `black` (default) |
| `align` | `left`, `center`, `right` |
| `valign` | `top`, `center`, `bottom` |
| `mask` | `true` / `false` (hide sensitive data) |

## Type-Specific Attributes

**`<select-field>`, `<multi-select-field>`, `<radio-field>`:**

| Attribute | Description |
|---|---|
| `options` | Comma-separated list: `"opt1,opt2,opt3"` |

**`<date-field>`:**

| Attribute | Description |
|---|---|
| `min` / `max` | Min/max date |
| `format` | `DD/MM/YYYY` or `MM/DD/YYYY` |

**`<signature-field>`:**

| Attribute | Description |
|---|---|
| `format` | `drawn`, `typed`, `drawn_or_typed`, `upload` |

**`<payment-field>`:**

| Attribute | Description |
|---|---|
| `price` | Amount |
| `currency` | Currency code (e.g. `USD`) |

**`<verification-field>`:**

| Attribute | Description |
|---|---|
| `method` | `aes` or `qes` |

## Examples

**Simple contract:**
```html
<h1>Non-Disclosure Agreement</h1>
<p>This agreement is entered by
  <text-field name="Company Name" role="Company" style="width: 180px; height: 20px; display: inline-block;"></text-field>
  and
  <text-field name="Recipient Name" role="Recipient" style="width: 180px; height: 20px; display: inline-block;"></text-field>.
</p>

<p>Date:
  <date-field name="Date" format="MM/DD/YYYY" style="width: 110px; height: 20px; display: inline-block;"></date-field>
</p>

<p>Company signature:</p>
<signature-field name="Company Signature" role="Company" style="width: 180px; height: 80px; display: inline-block;"></signature-field>

<p>Recipient signature:</p>
<signature-field name="Recipient Signature" role="Recipient" style="width: 180px; height: 80px; display: inline-block;"></signature-field>
```

**Form with various field types:**
```html
<h2>Application Form</h2>
<p>Full Name: <text-field name="Full Name" required="true" style="width: 220px; height: 20px; display: inline-block;"></text-field></p>
<p>Phone: <phone-field name="Phone" style="width: 160px; height: 20px; display: inline-block;"></phone-field></p>
<p>Department: <select-field name="Department" options="Engineering,Sales,Marketing,HR" style="width: 180px; height: 24px; display: inline-block;"></select-field></p>
<p>Start Date: <date-field name="Start Date" min="2024-01-01" style="width: 120px; height: 20px; display: inline-block;"></date-field></p>
<p>Photo ID: <image-field name="Photo ID" style="width: 140px; height: 90px; display: inline-block;"></image-field></p>
<p>I agree to the terms: <checkbox-field name="Terms" required="true" style="width: 16px; height: 16px; display: inline-block;"></checkbox-field></p>
<signature-field name="Signature" style="width: 180px; height: 80px; display: inline-block;"></signature-field>
```

**Using with CLI:**
```bash
docuseal templates create-html --name "NDA" --html '<h1>NDA</h1>
<p>Party: <text-field name="Name" style="width: 180px; height: 20px; display: inline-block;"></text-field></p>
<signature-field name="Signature" style="width: 180px; height: 80px; display: inline-block;"></signature-field>'

docuseal templates create-html --name "NDA" --file nda.html

docuseal submissions create-html --file nda.html \
  -d "submitters[0][email]=john@acme.com"
```
````

## File: skills/docuseal-cli/references/submissions.md
size: 11694
sha: ca9e233caa01008a9bf36e79c6e45a19a9cf7e6b
upstream: https://github.com/docusealco/docuseal-cli/blob/master/skills/docuseal-cli/references/submissions.md

````text
# Submissions

## `docuseal submissions list`

List all submissions.

| Option | Description |
|---|---|
| `--template-id <value>` | Filter by template ID |
| `--status <value>` | pending, completed, declined, expired |
| `--q <value>` | Filter by submitter name, email, or phone |
| `--slug <value>` | Filter by unique slug |
| `--template-folder <value>` | Filter by template folder name |
| `--archived` | Get only archived submissions |
| `--active` | Get only active submissions |
| `-l, --limit <value>` | Number of results (default 10, max 100) |
| `--after <value>` | Pagination cursor — pass `pagination.next` from previous response |
| `--before <value>` | Pagination end cursor |

```bash
docuseal submissions list
docuseal submissions list --status pending
docuseal submissions list \
  --template-id 1001 \
  --limit 50
docuseal submissions list --q "john@example.com"
```

---

## `docuseal submissions retrieve <id>`

Get a submission by ID.

```bash
docuseal submissions retrieve 502
```

---

## `docuseal submissions update <id>`

Update a submission's name, expiration, or archive state.

| Option | Description |
|---|---|
| `--name <value>` | Submission name |
| `--expire-at <value>` | Expiration date/time (use `-d '{"expire_at":null}'` to clear) |
| `--archive` | Archive the submission |
| `--unarchive` | Unarchive the submission |

```bash
docuseal submissions update 502 --name "Q3 Contract"
docuseal submissions update 502 --expire-at "2025-12-31 23:59"
docuseal submissions update 502 --unarchive
```

---

## `docuseal submissions archive <id>`

Archive a submission.

```bash
docuseal submissions archive 502
```

---

## `docuseal submissions create`

Create a submission from an existing template.

| Option | Description |
|---|---|
| `--template-id <value>` | Template ID (required) |
| `--send-email` | Send signature request emails (default) |
| `--no-send-email` | Do not send signature request emails |
| `--send-sms` | Send signature request via SMS |
| `--order <value>` | `preserved` (default) or `random` |
| `--expire-at <value>` | Expiration date/time |
| `--completed-redirect-url <value>` | Redirect URL after completion |
| `--bcc-completed <value>` | BCC address for signed documents |
| `--reply-to <value>` | Reply-To email address |

| Data param (`-d`) | Description |
|---|---|
| `variables[key]` | Template variable |
| `message[subject]` | Custom email subject |
| `message[body]` | Custom email body |
| `submitters[N][name]` | Full name |
| `submitters[N][role]` | Role name (e.g. "First Party") |
| `submitters[N][email]` | Email address (required) |
| `submitters[N][phone]` | Phone in E.164 format (e.g. +1234567890) |
| `submitters[N][values][fieldName]` | Pre-filled field value |
| `submitters[N][external_id]` | App-specific ID |
| `submitters[N][completed]` | Mark as completed (true/false) |
| `submitters[N][metadata][key]` | Submitter metadata |
| `submitters[N][send_email]` | Send email (true/false) |
| `submitters[N][send_sms]` | Send SMS (true/false) |
| `submitters[N][reply_to]` | Reply-To email |
| `submitters[N][completed_redirect_url]` | Redirect URL after completion |
| `submitters[N][order]` | Signing order (0, 1, 2...) |
| `submitters[N][require_phone_2fa]` | Require phone 2FA (true/false) |
| `submitters[N][require_email_2fa]` | Require email 2FA (true/false) |
| `submitters[N][invite_by]` | Role name of inviting party |
| `submitters[N][message][subject]` | Per-submitter email subject |
| `submitters[N][message][body]` | Per-submitter email body |
| `submitters[N][fields][M][name]` | Field name (required) |
| `submitters[N][fields][M][default_value]` | Default value |
| `submitters[N][fields][M][readonly]` | Read-only (true/false) |
| `submitters[N][fields][M][required]` | Required (true/false) |
| `submitters[N][roles][]` | Merge multiple roles |

```bash
docuseal submissions create \
  --template-id 1001 \
  -d "submitters[0][email]=john@acme.com"
docuseal submissions create \
  --template-id 1001 \
  -d "submitters[0][email]=a@b.com" \
  -d "submitters[1][email]=c@d.com"
docuseal submissions create \
  --template-id 1001 \
  -d "submitters[0][email]=john@acme.com" \
  -d "submitters[0][role]=Signer"
docuseal submissions create \
  --template-id 1001 \
  -d "submitters[0][email]=john@acme.com" \
  --no-send-email
```

---

## `docuseal submissions send-emails`

Send a template to multiple recipients by email — creates one submission per recipient.

| Option | Description |
|---|---|
| `--template-id <value>` | Template ID (required) |
| `--emails <value>` | Comma-separated list of email addresses |
| `--send-email` | Send signature request emails (default) |
| `--no-send-email` | Do not send signature request emails |

| Data param (`-d`) | Description |
|---|---|
| `message[subject]` | Custom email subject |
| `message[body]` | Custom email body |

```bash
docuseal submissions send-emails \
  --template-id 1001 \
  --emails a@b.com,c@d.com
docuseal submissions send-emails \
  --template-id 1001 \
  --emails a@b.com \
  -d "message[subject]=Please sign" \
  -d "message[body]=Hello"
```

---

## `docuseal submissions create-pdf` _(Pro)_

Create a submission directly from a PDF file (no pre-existing template needed).

See [PDF / DOCX Field Tags](field-tags.md) for embedded `{{...}}` field syntax in PDF and DOCX documents.

| Option | Description |
|---|---|
| `--file <path>` | Path to local PDF file |
| `--name <value>` | Submission name |
| `--send-email` | Send signature request emails (default) |
| `--no-send-email` | Do not send signature request emails |
| `--send-sms` | Send signature request via SMS |
| `--order <value>` | `preserved` or `random` |
| `--flatten` | Remove PDF form fields |
| `--merge-documents` | Merge into single PDF |
| `--remove-tags` | Remove `{{text}}` tags (default) |
| `--no-remove-tags` | Keep `{{text}}` tags in the PDF |
| `--expire-at <value>` | Expiration date/time |
| `--completed-redirect-url <value>` | Redirect URL after completion |
| `--bcc-completed <value>` | BCC address for signed documents |
| `--reply-to <value>` | Reply-To email address |

| Data param (`-d`) | Description |
|---|---|
| `template_ids[]` | Template ID to use alongside provided documents |
| `documents[N][name]` | Document name |
| `documents[N][file]` | Local file path, URL, or base64-encoded content |
| `documents[N][position]` | Position in template |
| `submitters[N][name]` | Full name |
| `submitters[N][role]` | Role name |
| `submitters[N][email]` | Email address (required) |
| `submitters[N][phone]` | Phone (E.164) |
| `submitters[N][values][fieldName]` | Pre-filled field value |
| `submitters[N][external_id]` | App-specific ID |
| `submitters[N][completed]` | Mark as completed (true/false) |
| `submitters[N][metadata][key]` | Submitter metadata |
| `submitters[N][send_email]` | Send email (true/false) |
| `submitters[N][send_sms]` | Send SMS (true/false) |
| `submitters[N][reply_to]` | Reply-To email |
| `submitters[N][completed_redirect_url]` | Redirect URL after completion |
| `submitters[N][order]` | Signing order (0, 1, 2...) |
| `submitters[N][require_phone_2fa]` | Require phone 2FA (true/false) |
| `submitters[N][require_email_2fa]` | Require email 2FA (true/false) |
| `submitters[N][invite_by]` | Role name of inviting party |
| `submitters[N][fields][M][name]` | Field name (required) |
| `submitters[N][fields][M][default_value]` | Default value |
| `submitters[N][fields][M][readonly]` | Read-only (true/false) |
| `submitters[N][fields][M][required]` | Required (true/false) |
| `submitters[N][roles][]` | Merge multiple roles |
| `message[subject]` | Custom email subject |
| `message[body]` | Custom email body |

```bash
docuseal submissions create-pdf \
  --file doc.pdf \
  -d "submitters[0][email]=john@acme.com"
docuseal submissions create-pdf \
  -d "documents[0][file]=./doc.pdf" \
  -d "submitters[0][email]=john@acme.com"
docuseal submissions create-pdf \
  -d "documents[0][file]=https://..." \
  -d "submitters[0][email]=john@acme.com"
```

---

## `docuseal submissions create-docx` _(Pro)_

Create a submission directly from a DOCX file.

See [PDF / DOCX Field Tags](field-tags.md) for embedded `{{...}}` field syntax. See [DOCX Variables](docx-variables.md) for DOCX-specific variables, loops, and conditional content.

| Option | Description |
|---|---|
| `--file <path>` | Path to local DOCX file |
| `--name <value>` | Submission name |
| `--send-email` | Send signature request emails (default) |
| `--no-send-email` | Do not send signature request emails |
| `--send-sms` | Send signature request via SMS |
| `--merge-documents` | Merge into single PDF |
| `--remove-tags` | Remove `{{text}}` tags (default) |
| `--no-remove-tags` | Keep `{{text}}` tags |
| `--order <value>` | `preserved` or `random` |
| `--expire-at <value>` | Expiration date/time |
| `--completed-redirect-url <value>` | Redirect URL after completion |
| `--bcc-completed <value>` | BCC address for signed documents |
| `--reply-to <value>` | Reply-To email address |

| Data param (`-d`) | Description |
|---|---|
| `variables[key]` | Template variable |
| `template_ids[]` | Template ID to use alongside provided documents |
| `documents[N][name]` | Document name |
| `documents[N][file]` | Local file path, URL, or base64-encoded content |
| `documents[N][position]` | Position in template |

Supports same `-d submitters[N]...` and `message` data params as `submissions create-pdf`.

```bash
docuseal submissions create-docx \
  --file doc.docx \
  -d "submitters[0][email]=john@acme.com"
docuseal submissions create-docx \
  -d "documents[0][file]=./doc.docx" \
  -d "submitters[0][email]=john@acme.com"
docuseal submissions create-docx \
  -d "documents[0][file]=https://..." \
  -d "submitters[0][email]=john@acme.com"
```

---

## `docuseal submissions create-html` _(Pro)_

Create a submission directly from HTML.

See [HTML Field Tags](html-fields.md) for supported tags, attributes, and `style` guidance.

| Option | Description |
|---|---|
| `--file <path>` | Path to local HTML file |
| `--name <value>` | Submission name |
| `--send-email` | Send signature request emails (default) |
| `--no-send-email` | Do not send signature request emails |
| `--send-sms` | Send signature request via SMS |
| `--merge-documents` | Merge into single PDF |
| `--order <value>` | `preserved` or `random` |
| `--expire-at <value>` | Expiration date/time |
| `--completed-redirect-url <value>` | Redirect URL after completion |
| `--bcc-completed <value>` | BCC address for signed documents |
| `--reply-to <value>` | Reply-To email address |

| Data param (`-d`) | Description |
|---|---|
| `template_ids[]` | Template ID to use alongside provided documents |
| `documents[N][name]` | Document name |
| `documents[N][html]` | HTML template with field tags |
| `documents[N][html_header]` | HTML header for every page |
| `documents[N][html_footer]` | HTML footer for every page |
| `documents[N][size]` | Page size (Letter, A4, ...) |
| `documents[N][position]` | Position in template |

Supports same `-d submitters[N]...` and `message` data params as `submissions create-pdf`.

```bash
docuseal submissions create-html \
  --file template.html \
  -d "submitters[0][email]=john@acme.com"
docuseal submissions create-html \
  -d 'documents[0][html]=<p><text-field name="Name"></text-field></p>' \
  -d "submitters[0][email]=john@acme.com"
```

---

## `docuseal submissions documents <id>`

Get documents for a submission.

| Option | Description |
|---|---|
| `--merge` | Merge all documents into a single PDF |

```bash
docuseal submissions documents 502
docuseal submissions documents 502 --merge
```
````

## File: skills/docuseal-cli/references/submitters.md
size: 2266
sha: cc9f19d8985050e828ab237a0ecd45263e28a2a1
upstream: https://github.com/docusealco/docuseal-cli/blob/master/skills/docuseal-cli/references/submitters.md

````text
# Submitters

## `docuseal submitters list`

List all submitters.

| Option | Description |
|---|---|
| `--submission-id <value>` | Filter by submission ID |
| `--q <value>` | Filter by name, email, or phone partial match |
| `--slug <value>` | Filter by unique slug |
| `--external-id <value>` | Filter by external ID |
| `--completed-after <value>` | Filter by completion date (after) |
| `--completed-before <value>` | Filter by completion date (before) |
| `-l, --limit <value>` | Number of results (default 10, max 100) |
| `--after <value>` | Pagination cursor — pass `pagination.next` from previous response |
| `--before <value>` | Pagination end cursor |

```bash
docuseal submitters list
docuseal submitters list --submission-id 502
docuseal submitters list --q "john@example.com"
```

---

## `docuseal submitters retrieve <id>`

Get a submitter by ID.

```bash
docuseal submitters retrieve 201
```

---

## `docuseal submitters update <id>`

Update a submitter — change contact info, pre-fill fields, re-send notifications, or mark as completed.

| Option | Description |
|---|---|
| `--name <value>` | Full name |
| `--email <value>` | Email address |
| `--phone <value>` | Phone in E.164 format (e.g. +1234567890) |
| `--external-id <value>` | App-specific unique key |
| `--send-email` | Re-send signature request email |
| `--send-sms` | Re-send via SMS |
| `--completed` | Mark as completed (auto-signed) |
| `--reply-to <value>` | Reply-To email address |
| `--completed-redirect-url <value>` | Redirect URL after completion |
| `--require-phone-2fa` | Require phone 2FA |
| `--require-email-2fa` | Require email 2FA |

| Data param (`-d`) | Description |
|---|---|
| `values[fieldName]` | Pre-filled field value |
| `metadata[key]` | Submitter metadata |
| `message[subject]` | Custom email subject |
| `message[body]` | Custom email body |
| `fields[N][name]` | Field name (required) |
| `fields[N][default_value]` | Default value |
| `fields[N][readonly]` | Read-only (true/false) |
| `fields[N][required]` | Required (true/false) |

```bash
docuseal submitters update 201 --email new@acme.com
docuseal submitters update 201 --completed
docuseal submitters update 201 \
  -d "values[First Name]=John" \
  -d "metadata[department]=Sales"
```
````

## File: skills/docuseal-cli/references/templates.md
size: 7990
sha: f01531c3d62e09f20e35aee12d57f7f4128e1ec5
upstream: https://github.com/docusealco/docuseal-cli/blob/master/skills/docuseal-cli/references/templates.md

````text
# Templates

## `docuseal templates list`

List all templates.

| Option | Description |
|---|---|
| `--q <value>` | Filter by name search |
| `--folder <value>` | Filter by folder name |
| `--slug <value>` | Filter by unique slug |
| `--external-id <value>` | Filter by external ID |
| `--archived` | Get only archived templates |
| `--active` | Get only active templates |
| `--shared` | List templates shared with test mode |
| `-l, --limit <value>` | Number of results (default 10, max 100) |
| `--after <value>` | Pagination cursor — pass `pagination.next` from previous response |
| `--before <value>` | Pagination end cursor |

```bash
docuseal templates list
docuseal templates list --folder Legal --limit 50
docuseal templates list --archived
```

---

## `docuseal templates retrieve <id>`

Get a template by ID.

```bash
docuseal templates retrieve 1001
```

---

## `docuseal templates update <id>`

Update a template.

| Option | Description |
|---|---|
| `--name <value>` | Template name |
| `--folder-name <value>` | Move to folder |
| `--archive` | Archive the template |
| `--unarchive` | Unarchive the template |

| Data param (`-d`) | Description |
|---|---|
| `roles[]` | Submitter role name |

```bash
docuseal templates update 1001 --name "NDA v2"
docuseal templates update 1001 --folder-name Contracts
docuseal templates update 1001 \
  -d "roles[]=Signer" \
  -d "roles[]=Reviewer"
docuseal templates update 1001 --unarchive
```

---

## `docuseal templates archive <id>`

Archive a template.

```bash
docuseal templates archive 1001
```

---

## `docuseal templates create-pdf` _(Pro)_

Create a template from a PDF file.

See [PDF / DOCX Field Tags](field-tags.md) for embedded `{{...}}` field syntax in PDF and DOCX documents.

| Option | Description |
|---|---|
| `--file <path>` | Path to local PDF file |
| `--name <value>` | Template name |
| `--folder-name <value>` | Folder to create in |
| `--external-id <value>` | App-specific unique key |
| `--shared-link` | Make available via shared link |
| `--no-shared-link` | Disable shared link |
| `--flatten` | Remove PDF form fields |
| `--remove-tags` | Remove `{{text}}` tags (default) |
| `--no-remove-tags` | Keep `{{text}}` tags in the PDF |

| Data param (`-d`) | Description |
|---|---|
| `documents[N][name]` | Document name |
| `documents[N][file]` | Local file path, URL, or base64-encoded content |
| `documents[N][fields][M][name]` | Field name |
| `documents[N][fields][M][type]` | text, signature, initials, date, number, image, checkbox, multiple, file, radio, select, cells, stamp, payment, phone, verification, kba |
| `documents[N][fields][M][role]` | Signer role name |
| `documents[N][fields][M][required]` | Required (true/false) |
| `documents[N][fields][M][title]` | Display title |
| `documents[N][fields][M][description]` | Display description (Markdown) |
| `documents[N][fields][M][areas][K][x/y/w/h]` | Position as fraction of page (0-1) |
| `documents[N][fields][M][areas][K][page]` | Page number (starts at 1) |
| `documents[N][fields][M][options][]` | Select/radio option values |

```bash
docuseal templates create-pdf --file contract.pdf --name "NDA"
docuseal templates create-pdf --file form.pdf --folder-name Legal
docuseal templates create-pdf \
  -d "documents[0][file]=./contract.pdf" \
  --name "NDA"
docuseal templates create-pdf \
  -d "documents[0][file]=https://..." \
  --name "NDA"
docuseal templates create-pdf --file form.pdf \
  -d "documents[0][fields][0][name]=Name" \
  -d "documents[0][fields][0][type]=text"
```

---

## `docuseal templates create-docx` _(Pro)_

Create a template from a Word DOCX file.

See [PDF / DOCX Field Tags](field-tags.md) for embedded `{{...}}` field syntax in PDF and DOCX documents.

| Option | Description |
|---|---|
| `--file <path>` | Path to local DOCX file |
| `--name <value>` | Template name |
| `--folder-name <value>` | Folder to create in |
| `--external-id <value>` | App-specific unique key |
| `--shared-link` | Make available via shared link |
| `--no-shared-link` | Disable shared link |

| Data param (`-d`) | Description |
|---|---|
| `documents[N][name]` | Document name |
| `documents[N][file]` | Local file path, URL, or base64-encoded content |
| `documents[N][dynamic]` | Dynamic document with editable content and `[[variables]]` (true/false) |

```bash
docuseal templates create-docx --file template.docx --name "Contract"
docuseal templates create-docx \
  -d "documents[0][file]=./template.docx" \
  --name "Contract"
docuseal templates create-docx \
  -d "documents[0][file]=https://..." \
  --name "Contract"
docuseal templates create-docx --file template.docx \
  -d "documents[0][fields][0][name]=Name" \
  -d "documents[0][fields][0][role]=Signer"
```

---

## `docuseal templates create-html` _(Pro)_

Create a template from HTML.

See [HTML Field Tags](html-fields.md) for supported tags, attributes, and `style` guidance.

| Option | Description |
|---|---|
| `--html <value>` | Inline HTML with field tags |
| `--file <path>` | Path to local HTML file |
| `--html-header <value>` | Header HTML (shown on every page) |
| `--html-footer <value>` | Footer HTML (shown on every page) |
| `--name <value>` | Template name |
| `--size <value>` | Page size: Letter (default), A4, Legal, A3, A5, A6, Tabloid, Ledger, A0, A1, A2 |
| `--folder-name <value>` | Folder to create in |
| `--external-id <value>` | App-specific unique key |
| `--shared-link` | Make available via shared link |
| `--no-shared-link` | Disable shared link |

| Data param (`-d`) | Description |
|---|---|
| `documents[N][html]` | HTML with field tags |
| `documents[N][name]` | Document name |

```bash
docuseal templates create-html \
  --html '<p><text-field name="Name"></text-field></p>' \
  --name "Simple"
docuseal templates create-html \
  --file template.html \
  --name "Contract"
docuseal templates create-html \
  -d 'documents[0][html]=<p><text-field name="Name"></text-field></p>' \
  -d "documents[0][name]=Page 1"
```

---

## `docuseal templates clone <id>`

Clone a template.

| Option | Description |
|---|---|
| `--name <value>` | Name for the clone (default: original name + "(Clone)") |
| `--folder-name <value>` | Folder to clone into |
| `--external-id <value>` | App-specific unique key |

```bash
docuseal templates clone 1001
docuseal templates clone 1001 --name "NDA Copy"
```

---

## `docuseal templates merge` _(Pro)_

Merge multiple templates into one.

| Option | Description |
|---|---|
| `--name <value>` | Name for the merged template |
| `--folder-name <value>` | Folder to place merged template |
| `--external-id <value>` | App-specific unique key |
| `--shared-link` | Make available via shared link |
| `--no-shared-link` | Disable shared link |

| Data param (`-d`) | Description |
|---|---|
| `template_ids[]` | Template ID to include (required, repeatable) |
| `roles[]` | Submitter role name |

```bash
docuseal templates merge \
  -d "template_ids[]=1001" \
  -d "template_ids[]=1002"
docuseal templates merge \
  -d "template_ids[]=1001" \
  -d "template_ids[]=1002" \
  --name "Combined"
```

---

## `docuseal templates update-documents <id>` _(Pro)_

Update documents within an existing template.

| Option | Description |
|---|---|
| `--merge` | Merge all docs into a single PDF |

| Data param (`-d`) | Description |
|---|---|
| `documents[N][name]` | Document name |
| `documents[N][file]` | Local file path, URL, or base64-encoded content |
| `documents[N][html]` | HTML template with field tags |
| `documents[N][position]` | Position in template |
| `documents[N][replace]` | Replace existing document (true/false) |
| `documents[N][remove]` | Remove document (true/false) |

```bash
docuseal templates update-documents 1001 \
  -d "documents[0][file]=./contract.pdf"
docuseal templates update-documents 1001 \
  -d "documents[0][file]=https://..."
docuseal templates update-documents 1001 \
  -d "documents[0][file]=https://..." \
  -d "documents[0][name]=New Doc"
```
````

## File: README.md
upstream: https://github.com/docusealco/docuseal-cli/blob/master/README.md

````text
<p align="center">
  <a href="https://www.docuseal.com">
    <img width="70" src="https://www.docuseal.com/logo.svg" alt="DocuSeal Logo">
  </a>
</p>

<h1 align="center">DocuSeal CLI</h1>

<p align="center">
  Manage e-signature templates, submissions, and submitters with the terminal or AI agent.
</p>

<p align="center">
  <a href="https://www.npmjs.com/package/docuseal"><img src="https://img.shields.io/npm/v/docuseal.svg" alt="npm version"></a>
  <a href="https://www.npmjs.com/package/docuseal"><img src="https://img.shields.io/npm/dm/docuseal.svg" alt="npm downloads"></a>
  <a href="https://github.com/docusealco/docuseal-cli/blob/master/LICENSE.md"><img src="https://img.shields.io/npm/l/docuseal.svg" alt="license"></a>
</p>

---

## Quick Start

```bash
# Run directly with npx (no install needed)
npx docuseal configure

# Or install globally
npm install -g docuseal
docuseal configure
```

The `configure` command will prompt for your API token and server:

```
Server [global/europe/url] (default: global): global
Enter your API token: xxxxxxxxxx
✓ Saved to ~/.config/docuseal/credentials.json
```

Get your API token from [DocuSeal Console](https://console.docuseal.com/api) or [DocuSeal EU Console](https://console.docuseal.eu/api).

## Installation

```bash
npm install -g docuseal
```

**Requirements:** Node.js 18+

## Usage

```
docuseal [COMMAND]

TOPICS
  templates    Manage templates
  submissions  Manage submissions
  submitters   Manage submitters

COMMANDS
  configure    Configure API key and server
```

Every command supports `--help` for full usage details:

```bash
docuseal submissions create --help
```

---

## Configuration

### Interactive Setup

```bash
docuseal configure
```

### Non-Interactive Setup

```bash
docuseal configure --api-key YOUR_KEY --server global
```

### Show Current Config

```bash
docuseal configure --list
# ✓ Current configuration
#   api_key: vS7EwXPy...kDmq
#   server: https://api.docuseal.com
```

### Environment Variables

```bash
export DOCUSEAL_API_KEY=your_key
export DOCUSEAL_SERVER=global    # global, europe, or full URL
```

### Config File

Stored at `~/.config/docuseal/credentials.json`:

```json
{
  "apiKey": "your_key",
  "server": "https://api.docuseal.com"
}
```

**Priority:** CLI flag > environment variable > config file.

### Servers

| Value | URL                        |
|-------|----------------------------|
| `global` | `https://api.docuseal.com` |
| `europe` | `https://api.docuseal.eu`  |
| URL   | Your self-hosted instance  |

---

## Agent Skills

This CLI ships with an [agent skill](skills/docuseal-cli/SKILL.md) that teaches AI coding agents (Cursor, Claude Code, Windsurf, etc.) how to use the DocuSeal CLI effectively — including non-interactive flags, output formats, and common pitfalls.

Install skills from the [central skills repository](https://github.com/docusealco/docuseal-agent-skills):

```sh
npx skills add docusealco/docuseal-agent-skills
```

For [Hermes Agent](https://hermes-agent.nousresearch.com):

```sh
hermes skills install docusealco/docuseal-agent-skills/skills/docuseal-cli
```

---

## Templates

### List Templates

```bash
docuseal templates list
docuseal templates list --folder Legal -l 50
docuseal templates list --archived
docuseal templates list --active
```

### Retrieve Template

```bash
docuseal templates retrieve 1001
```

### Create Template from PDF

```bash
docuseal templates create-pdf --file contract.pdf --name "NDA"
docuseal templates create-pdf --file form.pdf --folder-name Legal
```

### Create Template from DOCX

```bash
docuseal templates create-docx --file template.docx --name "Contract"
```

### Create Template from HTML

```bash
# Inline HTML
docuseal templates create-html --html "<p><text-field name=\"Name\"></text-field></p>" --name "Simple"

# From file
docuseal templates create-html --file template.html --name "Contract"
```

### Update Template

```bash
docuseal templates update 1001 --name "NDA v2"
docuseal templates update 1001 --folder-name Contracts
docuseal templates update 1001 -d "roles[]=Signer" -d "roles[]=Reviewer"
docuseal templates update 1001 --archive
docuseal templates update 1001 --unarchive
```

### Clone Template

```bash
docuseal templates clone 1001
docuseal templates clone 1001 --name "NDA Copy"
```

### Merge Templates

```bash
docuseal templates merge -d "template_ids[]=1001" -d "template_ids[]=1002"
docuseal templates merge -d "template_ids[]=1001" -d "template_ids[]=1002" --name "Combined"
```

### Update Template Documents

```bash
docuseal templates update-documents 1001 -d "documents[0][file]=https://example.com/doc.pdf" -d "documents[0][name]=New Doc"
docuseal templates update-documents 1001 --merge
```

### Archive Template

```bash
docuseal templates archive 1001
```

---

## Submissions

### List Submissions

```bash
docuseal submissions list
docuseal submissions list --status pending
docuseal submissions list --template-id 1001 -l 50
```

### Create Submission

Send a template for signing:

```bash
# Single submitter
docuseal submissions create \
  --template-id 1001 \
  -d "submitters[0][email]=john@acme.com"

# Multiple submitters with roles
docuseal submissions create \
  --template-id 1001 \
  -d "submitters[0][role]=Signer" \
  -d "submitters[0][email]=john@acme.com" \
  -d "submitters[1][role]=Witness" \
  -d "submitters[1][email]=jane@acme.com"

# With options
docuseal submissions create \
  --template-id 1001 \
  -d "submitters[0][email]=john@acme.com" \
  --no-send-email \
  --expire-at "2025-12-31" \
  --order random

# Using JSON
docuseal submissions create \
  --template-id 1001 \
  -d '{"submitters":[{"email":"john@acme.com","role":"Signer"}]}'
```

### Create Submission from PDF

Skip template creation — send a tagged PDF directly for signing:

```bash
docuseal submissions create-pdf \
  --file document.pdf \
  -d "submitters[0][email]=john@acme.com"
```

### Create Submission from DOCX

```bash
docuseal submissions create-docx \
  --file document.docx \
  -d "submitters[0][email]=john@acme.com"
```

### Send by Email

Send a template to multiple email addresses at once:

```bash
docuseal submissions send-emails \
  --template-id 1001 \
  --emails john@acme.com,jane@acme.com
```

### Retrieve Submission

```bash
docuseal submissions retrieve 502
```

### Get Submission Documents

```bash
docuseal submissions documents 502
docuseal submissions documents 502 --merge
```

### Archive Submission

```bash
docuseal submissions archive 502
```

---

## Submitters

### List Submitters

```bash
docuseal submitters list
docuseal submitters list --submission-id 502
```

### Retrieve Submitter

```bash
docuseal submitters retrieve 201
```

### Update Submitter

```bash
# Change email
docuseal submitters update 201 --email new@acme.com

# Mark as completed (auto-sign via API)
docuseal submitters update 201 --completed

# Re-send signature request
docuseal submitters update 201 --send-email

# Pre-fill fields and metadata
docuseal submitters update 201 -d "values[First Name]=John" -d "metadata[department]=Sales"
```

---

## Global Flags

These flags work on every command:

| Flag          | Description                                   |
|---------------|-----------------------------------------------|
| `--api-key`   | Override API key for this invocation           |
| `--server`    | Server: `global`, `europe`, or full URL         |

Flags available on list commands:

| Flag            | Description                               |
|-----------------|-------------------------------------------|
| `-l`, `--limit` | Limit number of results                   |
| `--after`       | Cursor for pagination                     |

Flag available on commands with body parameters:

| Flag          | Description                                   |
|---------------|-----------------------------------------------|
| `-d`, `--data`| Set params with bracket notation or JSON (repeatable) |

### Override Server Per-Command

```bash
````
