# 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

```bash
pip install ai-pdf-filler
```

Or with uv:

```bash
uv tool install ai-pdf-filler
```

## Authentication

Set your API key before running commands:

```bash
export SIMPLICITY_AI_API_KEY="your_api_key"
```

Or save it once locally:

```bash
simplicity-cli --api-key "your_api_key"
```

You can also pass it explicitly:

```bash
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:

```bash
simplicity-cli help
```

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

```bash
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:

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

Autofill an existing form:

```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.
`--instructions` is optional guidance for how autofill should behave.

Check or wait on tasks:

```bash
simplicity-cli status TASK_ID
simplicity-cli wait TASK_ID
```

## Command reference

For full syntax/examples at any time, run:

```bash
simplicity-cli help
```

### new

Create a digital form from a PDF and run autofill.

Common usage:

```bash
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:

```bash
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.

```bash
simplicity-cli status TASK_ID
```

### wait

Poll until completion, failure, or timeout.

```bash
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:

```bash
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
