docuseal-cli

Agent 协议

Agent 规则：

• 提供所有必需的标志 — CLI 不会提示输入缺失的参数。
• 输出始终为 JSON。
• 对于正文和数组参数，请使用 -d key=value（方括号表示法）或 -d '{"..": ".."}'（JSON）。

身份验证

设置环境变量：

• DOCUSEAL_API_KEY — API 密钥（必需）。请前往 https://console.docuseal.com/api 获取
• DOCUSEAL_SERVER — global（默认）、europe，或用于可自托管版本的完整 URL（例如 https://docuseal.yourdomain.com）

可用命令

命令组	功能
templates	列出、获取、更新、归档、创建 PDF、创建 DOCX、创建 HTML、克隆、合并、更新文档
submissions	列出、获取、更新、归档、创建、发送电子邮件、创建 PDF、创建 DOCX、创建 HTML、文档
submitters	列出、获取、更新

请阅读对应的参考文件，了解详细标志和示例。

常见错误

#	错误	修正方法
1	在 submissions create 中忘记添加 -d template_id=<id>	--template-id 是一个标志；提交者和其他正文参数应通过 -d 传递
2	将普通文件路径作为 URL 传递	--file 接受本地路径；对于远程文件，请使用 -d "documents[0][file]=https://..."
3	以为数组参数使用逗号分隔	数组使用方括号表示法：-d "template_ids[]=1" -d "template_ids[]=2"
4	未订阅 Pro 套餐就使用 templates create-pdf	标记为 (Pro) 的命令需要 DocuSeal Pro 订阅
5	使用 submissions create 向多个收件人发送	批量发送请使用 submissions send-emails --emails [email protected],[email protected]；submissions create 每次仅适用于一个提交者

安全性

CLI 接受用户提供的文件路径、远程 URL（documents[0][file]=https://...）和作为模板输入的 HTML 内容。这是有意为之 — 所有内容均来自已通过身份验证的用户，并通过 HTTPS 直接发送至 DocuSeal API。CLI 不会在本地获取、渲染或执行远程内容；它会将引用传递给服务端进行处理。任何用户输入都不会插入到 shell 命令中。

常见模式

列出模板：

docuseal templates list --q "NDA" --limit 20

从 PDF 创建模板并发送以供签署：

docuseal templates create-pdf --file contract.pdf --name "NDA"
docuseal submissions send-emails --template-id 1001 --emails [email protected]

创建包含预填字段的提交（方括号表示法）：

docuseal submissions create --template-id 1001 \
  -d "submitters[0][email][email protected]" \
  -d "submitters[0][values][Company Name]=Acme Corp"

创建包含预填字段的提交（JSON）：

docuseal submissions create --template-id 1001 \
  -d '{"submitters": [{"email": "[email protected]", "values": {"Company Name": "Acme Corp"}}]}'

检查签署状态：

docuseal submissions list --template-id 1001 --status pending

更新提交者：

docuseal submitters update 201 --email [email protected] --send-email

何时加载参考文件

• 创建或管理模板 → references/templates.md
• 发送文档以供签署或跟踪状态 → references/submissions.md
• 在 DOCX 中使用动态内容变量 → references/docx-variables.md
• 在 PDF/DOCX 中嵌入字段标签 → references/field-tags.md
• 编写带字段标签的 HTML 模板 → references/html-fields.md
• 列出或更新签署人 → references/submitters.md