Metadata-Version: 2.4
Name: simplicity-cli
Version: 0.1.0
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.

## API target

The CLI uses a hardcoded API base URL:

- `https://api.simplicity.ai`

## Authentication

Set your API key before running commands:

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

## 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

### `new`

Create a digital form from a PDF and run autofill.

```bash
simplicity-cli new \
  (--form-file PATH | --form-url URL) \
  [--source-file PATH ...] \
  [--source-url URL ...] \
  [--context TEXT | --context-file PATH] \
  [--instructions TEXT | --instructions-file PATH] \
  [--no-wait] \
  [--poll-interval-seconds 2] \
  [--max-wait-seconds 1800] \
  [--no-download] \
  [--output PATH]
```

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

### `existing`

Autofill an existing form ID.

```bash
simplicity-cli existing FORM_ID \
  [--context TEXT | --context-file PATH] \
  [--instructions TEXT | --instructions-file PATH] \
  [--no-wait] \
  [--poll-interval-seconds 2] \
  [--max-wait-seconds 1800] \
  [--no-download] \
  [--output PATH]
```

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
