Metadata-Version: 2.4
Name: simplicity-cli
Version: 0.1.1
Summary: CLI for AI-assisted PDF form filling via Simplicity Form-Filler API
Requires-Python: >=3.12
Description-Content-Type: text/markdown
Requires-Dist: httpx<1.0.0,>=0.27.0
Requires-Dist: typer<1.0.0,>=0.12.0

# simplicity-cli

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

## 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 "Use applicant data from profile A."
```

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 "Apply latest account details."
```

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 "Applicant data..."
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 "Use latest profile data"
simplicity-cli existing FORM_ID --context-file ./context.txt --output ./filled.pdf
simplicity-cli existing FORM_ID --no-wait --no-download
```

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
