AI PDF Filler CLI

Execute PDF autofill workflows using the installed simplicity-cli command. Prefer direct command execution over manual API calls when this skill applies.

Core Workflow

1. Confirm simplicity-cli is installed by running simplicity-cli --help.
2. If missing, install the CLI:

• Preferred: uv tool install ai-pdf-filler
• Fallback: python3 -m pip install ai-pdf-filler
• Re-check with simplicity-cli --help.

3. Ensure authentication is available (create an account and get API key at https://simplicity.ai):

• Preferred: run simplicity-cli login and paste key in hidden prompt.
• Non-interactive: printf '%s' "$SIMPLICITY_AI_API_KEY" | simplicity-cli login --api-key-stdin.
• Or set env var: SIMPLICITY_AI_API_KEY.

4. Choose the autofill path:

• New PDF form: use simplicity-cli new.
• Existing form id: use simplicity-cli existing FORM_ID.

5. Wait for completion unless the user explicitly requests async behavior.
6. Return the resulting task id, form/document id, and downloaded output path.

Command Patterns

Save API key

simplicity-cli login

printf '%s' "$SIMPLICITY_AI_API_KEY" | simplicity-cli login --api-key-stdin

New form from file with context

simplicity-cli new \
  --form-file ./form.pdf \
  --context "name: John Doe; dob: 1990-07-07"

New form from file with source documents

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

New form from URL

simplicity-cli new \
  --form-url "https://example.com/form.pdf" \
  --source-url "https://example.com/source.pdf"

Existing form id

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. Use --instructions only for optional autofill behavior guidance.

Task monitoring

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

Rules and Validation

• Enforce exactly one of --form-file or --form-url for new.
• Require at least one source (--source-file/--source-url) or context (--context/--context-file) for new.
• Treat --context and --context-file as mutually exclusive.
• Treat --instructions and --instructions-file as mutually exclusive.
• Reject --output when --no-download is set.

Execution Preferences

• Use human output mode for interactive runs.
• Use --json for automation or when machine-parseable output is requested.
• Use --no-wait only when user wants async handoff; otherwise wait to completion.
• Use --output when user requests an explicit file path.

Failure Handling

• If simplicity-cli is not found, install ai-pdf-filler first, then retry.
• If auth is missing, instruct running simplicity-cli login (or --api-key-stdin) or setting SIMPLICITY_AI_API_KEY.
• If a task fails, report task id and failure message; do not hide API error details.
• If download fails after successful task completion, still return task/form identifiers.
• For scripting contexts, rerun with --json and surface error.code and error.message.

References

Use references/commands.md for concise templates and option reminders.