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.

Command Patterns

simplicity-cli login

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

simplicity-cli new \
  --form-file ./form.pdf \
  --context "name: John Doe; 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"

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.

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.

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.

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.

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