ai-pdf-filler 0.1.3

CLI for AI-assisted PDF form filling via Simplicity Form-Filler API

simplicity-cli

CLI for AI-assisted PDF form filling through the Simplicity Form-Filler API.

PyPI package name: ai-pdf-filler
Installed command: simplicity-cli

Install

pip install ai-pdf-filler

Or with uv:

uv tool install ai-pdf-filler

Authentication

Set your API key before running commands:

Get API keys from simplicity.ai.

export SIMPLICITY_AI_API_KEY="your_api_key"

Or save it once locally:

simplicity-cli --api-key "your_api_key"

You can also pass it explicitly:

simplicity-cli --api-key "your_api_key" status TASK_ID

Auth precedence:

1. --api-key
2. SIMPLICITY_AI_API_KEY
3. saved local key (from simplicity-cli --api-key "...")

Quick start

Get a one-page CLI guide:

simplicity-cli help

Create and autofill from a local form PDF using text context:

simplicity-cli new \
  --form-file ./form.pdf \
  --context "first_name: John; last_name: Smoke; dob: 1990-07-07"

Create and autofill using uploaded source documents:

simplicity-cli new \
  --form-file ./form.pdf \
  --source-file ./w2.pdf \
  --source-file ./drivers_license.pdf

Autofill an existing form:

simplicity-cli existing FORM_ID --context "first_name: John; last_name: Smoke; dob: 1990-07-07"

--context is the source data used to fill form fields. --instructions is optional guidance for how autofill should behave.

Check or wait on tasks:

simplicity-cli status TASK_ID
simplicity-cli wait TASK_ID

Command reference

For full syntax/examples at any time, run:

simplicity-cli help

new

Create a digital form from a PDF and run autofill.

Common usage:

simplicity-cli new --form-file ./form.pdf --context "first_name: John; last_name: Smoke; dob: 1990-07-07"
simplicity-cli new --form-file ./form.pdf --source-file ./w2.pdf --source-file ./id.pdf
simplicity-cli new --form-url https://example.com/form.pdf --source-url https://example.com/source.pdf

Validation rules:

• Exactly one of --form-file or --form-url is required.
• You must provide at least one source via --source-file/--source-url or --context/--context-file.
• --context and --context-file are mutually exclusive.
• --instructions and --instructions-file are mutually exclusive.
• --output cannot be used with --no-download.

Useful flags:

• --no-wait returns immediately with a task ID.
• --no-download skips PDF download after completion.
• --output PATH writes downloaded output to a specific path.
• --poll-interval-seconds and --max-wait-seconds control polling behavior.

existing

Autofill an existing form ID.

Common usage:

simplicity-cli existing FORM_ID --context "first_name: John; last_name: Smoke; dob: 1990-07-07"
simplicity-cli existing FORM_ID --context-file ./context.txt --output ./filled.pdf
simplicity-cli existing FORM_ID --no-wait --no-download

Context and instructions semantics:

• --context / --context-file provide the data to populate form fields.
• --instructions / --instructions-file provide optional behavior guidance and do not replace form data.

Validation rules:

• FORM_ID is required.
• --context and --context-file are mutually exclusive.
• --instructions and --instructions-file are mutually exclusive.
• --output cannot be used with --no-download.

status

Get current task details.

simplicity-cli status TASK_ID

wait

Poll until completion, failure, or timeout.

simplicity-cli wait TASK_ID --poll-interval-seconds 2 --max-wait-seconds 1800

Legacy aliases

Backward-compatible nested commands are still accepted:

• simplicity-cli fill new ...
• simplicity-cli fill existing ...
• simplicity-cli task status ...
• simplicity-cli task wait ...

Output modes

Human-readable output is default. Use strict JSON for scripts:

simplicity-cli --json status TASK_ID

In --json mode, each command writes exactly one JSON object.

Exit codes

• 0: success
• 2: usage/validation/auth missing
• 3: auth rejected (401/403)
• 4: API/request error
• 5: task failed
• 6: wait timeout
• 7: download error