ai-pdf-filler-cli

# 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 ```bash simplicity-cli login ``` ```bash printf '%s' "$SIMPLICITY_AI_API_KEY" | simplicity-cli login --api-key-stdin ``` ### New form from file with context ```bash simplicity-cli new \ --form-file ./form.pdf \ --context "name: John Doe; dob: 1990-07-07" ``` ### New form from file with source documents ```bash simplicity-cli new \ --form-file ./form.pdf \ --source-file ./w2.pdf \ --source-file ./id.pdf ``` ### New form from URL ```bash simplicity-cli new \ --form-url "https://example.com/form.pdf" \ --source-url "https://example.com/source.pdf" ``` ### Existing form id ```bash 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 ```bash 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](references/commands.md) for concise templates and option reminders.