Skip to main content

The pareta CLI

The pareta command is the SDK in your shell: call model="auto", run an eval on your own data, and read auto's metrics — each as one command, rendered as a table or, with --json, as machine-readable output for scripts. It ships with the Python package (pip install "pareta[cli]") and, once installed, works from any shell regardless of your project's language.

Install​

The CLI is an optional extra on the Python package — it adds typer + rich:

pip install "pareta[cli]"

Because the install puts a pareta console script on your PATH, an isolated install with pipx is often cleaner — it keeps the CLI and its dependencies out of your project's environment while still putting the command on your PATH:

pipx install "pareta[cli]"

Either way you get the same command. Confirm it:

pareta --version

Authenticate​

The CLI reads the same environment as the SDK — PARETA_API_KEY (required) and the optional PARETA_BASE_URL. Mint a pareta_sk_ key in the dashboard and export it:

export PARETA_API_KEY="pareta_sk_…"

There is no login command and no config file: auth is the environment, so the same export works in your shell, a Makefile, or CI. A missing or bad key prints a one-line error to stderr and exits non-zero (2 for an auth/config problem you can fix locally, 1 for a genuine API error) — never a traceback.

Output: tables or --json​

Every command prints a human-readable table by default. Add the global --json (or -j) flag — before the subcommand — to get the raw JSON the SDK returns instead, for piping into jq or a script:

pareta --json models list | jq '.[].id'

Data goes to stdout and diagnostics to stderr, so piped output stays clean.

Command tree​

pareta --help (or pareta <group> --help) documents the whole tree. The groups mirror the SDK's resource namespaces.

chat — one-shot inference​

pareta chat "Summarize this contract clause: …"           # prompt as an argument
echo "Summarize this clause: …" | pareta chat             # or piped on stdin
pareta chat "Tell me a story" --stream                    # stream tokens as they arrive

Every chat goes to model="auto": Pareta plans the request, routes it to benchmark-proven open specialists, verifies, and falls back to a frontier model when that's the right call — one request, one debit. Inference is metered.

tasks — how your data gets scored​

pareta tasks match "pull the key fields out of these contracts"   # verdict: task / capability / unsupported
pareta tasks list                                                 # every benchmarked task auto routes across
pareta tasks show contract-key-fields                             # one task's schema + default scorer

match takes a free-text description of your dataset and tells you how an eval will score it (or names a general lane, or reports no match — a statement about scoring, not serving). --top-k (default 5) controls how many candidates it considers.

models — the model catalog​

pareta models list            # exactly one entry: "auto"

There is one model id. Everything behind it — planning, routing, verification, frontier fallback — is Pareta's job, per request.

evals — benchmark on your own data​

# Build a set on the fly from a JSONL file and benchmark "auto" against the frontier baselines:
pareta evals run --prompt "extract the key fields from each contract" --file rows.jsonl \
  --models auto --frontier --wait

# Or run an existing eval set:
pareta evals run --eval-set es_abc --models auto --wait

# Preview how your rows would be scored (nothing is created):
pareta evals propose --file rows.jsonl --prompt "extract the key fields from each contract"

# Manage eval sets (your data rows):
pareta evals sets create --prompt "extract the key fields from each contract" --file rows.jsonl
pareta evals sets list
pareta evals sets show es_abc
pareta evals sets delete es_abc --yes

--models is required — pass auto to benchmark Pareta's routing itself. When you build a set from --file, --prompt (one sentence on what the model should do with each item) is required — Pareta works out the scoring from it and your data's shape, so --task is optional (pass it only to pin a specific task). Running an existing set with --eval-set needs neither. --frontier adds the task's benchmarked vendor models as baselines, which is the comparison that matters. Each item in --file is one JSON object per line; eval runs are metered against your org balance.

auto — watch it and compare it​

pareta auto metrics                                              # requests + success rate (30d), spend, projected savings vs frontier
pareta auto compare "Summarize this clause: …"                   # one prompt: auto vs a frontier vendor, side by side with both bills
pareta auto compare "Summarize this clause: …" --frontier claude-sonnet-4-6

metrics is read-only and free. compare is metered — it makes two real calls, one to auto and one to the vendor at the vendor's actual token cost (a failed vendor call bills $0). Allowed vendors: gpt-5.5, gemini-3-5-flash, gemini-3-1-pro, claude-sonnet-4-6.

rerank + embed — the retrieval lanes​

pareta rerank "governing law" "clause one…" "clause two…" --top-n 3   # docs as arguments
pareta rerank "governing law" --file docs.txt                         # or one document per line
pareta embed "what governs this contract?" --type query              # query-side vector
pareta embed --file passages.txt --out vectors.jsonl                  # document vectors → JSONL

rerank scores every document against the query (calibrated 0–1 scores, best first; --top-n only truncates the output) — metered per document scored. embed returns unit-normalized vectors; the table shows sizes only, so grab the vectors with --out (JSONL rows {"index", "vector"}) or --json — metered per input token.

audio — speech in and out​

pareta audio transcribe meeting.wav                         # speech-to-text (prints the transcript)
pareta audio speak "Hello from Pareta" --out hello.wav      # text-to-speech (writes an audio file)

Both are metered per minute of audio.

image — text to image​

pareta image "a red fox in the snow" --out fox.png                    # 1024x1024 default
pareta image "wide product banner" --size 2560x1440 --seed 7          # pinned seed
pareta image-edit fox.png "give the fox a red scarf" --out fox2.png   # instruction edit

image writes a PNG (default image.png), billed FLAT per image — every size costs the same (the model renders at full 2K internally either way). image-edit takes a reference image + a plain-language instruction (no mask), keeps the reference's aspect ratio, and is billed FLAT per edit.

Scripting​

Because every command takes --json and exits non-zero on failure, the CLI composes into shell pipelines and CI. For example, see how your rows will be scored, benchmark auto on your own rows, then run the real call:

export PARETA_API_KEY="pareta_sk_…"

pareta --json tasks match "pull the key fields out of these contracts" | jq -r '.type'
pareta evals run --prompt "extract the key fields from each contract" --file rows.jsonl --models auto --frontier --wait
pareta chat "What is the contract's effective date? …"

Next steps​