CLI Reference

Complete reference for every xreduce command, grouped by workflow phase. For walkthroughs and worked examples, see the sidebar pages under Set up a model and Run XReduce.

Command summary

xreduce login

Authenticate and store credentials at ~/.xreduce/credentials. Required before any model command.

# Interactive
xreduce login

# Use an existing API key (non-interactive)
xreduce login --api-key xr-1234-5678-9abc

# Named profile (multiple accounts)
xreduce login --profile staging

xreduce logout

Remove stored credentials.

xreduce logout                   # default profile
xreduce logout --profile staging # specific profile
xreduce logout --all             # remove all profiles

xreduce model create

Register a new model and write its config.yaml. See Register a model for the full flag list and walkthrough - there are roughly 20 optional flags covering architecture, hardware, task settings, and version metadata.

xreduce model create \
  --name my-org/my-model \
  --task-type text-to-sql

xreduce model list

List all models registered under the current account.

xreduce model list             # formatted table
xreduce model list --json      # machine-readable JSON

xreduce model show

Show details for a single model. --yaml emits a config.yaml suitable for profile and evaluate; --json emits the raw API response.

xreduce model show <model-id>

# Re-generate config.yaml for an existing model
xreduce model show <model-id> --yaml -o config.yaml

# Raw API response
xreduce model show <model-id> --json

xreduce models (plural) is supported as a deprecated alias for one release. Use xreduce model going forward.

xreduce init

Scaffold a model folder with config.yaml and benchmarks/config.yaml. If a benchmark JSONL is already present, the field-mapping is inferred automatically. See Initialize a project for the full walkthrough.

xreduce init my-org/my-model

# Add a system_prompt placeholder
xreduce init my-org/my-model --with-system-prompt

# Pre-fill the system_prompt
xreduce init my-org/my-model --system-prompt "You are a SQL expert."

xreduce remap

Re-infer benchmarks/config.yaml from the benchmark JSONL without touching the model config.yaml. Use it when you add or change benchmark data after running init. User-owned keys in benchmarks/config.yaml are preserved; only field_map, input_serializer, and the task-default system_prompt are owned by remap.

xreduce remap my-org/my-model

xreduce profile

Run a single-prompt telemetry pass. Sanity check before a full evaluation. See Profile for the full walkthrough.

xreduce profile --config my-org/my-model/config.yaml

# Override the prompt
xreduce profile --config my-org/my-model/config.yaml --prompt "Translate this..."

# Show full telemetry
xreduce profile --config my-org/my-model/config.yaml --verbose

xreduce evaluate

Evaluate a model against benchmark data. --config is repeatable for multi-model runs against a shared benchmark. See Evaluate for the full walkthrough.

# Single model, all benchmarks in benchmarks/
xreduce evaluate --config my-org/my-model/config.yaml

# Multiple models against a shared benchmark
xreduce evaluate \
  --config models/a/config.yaml \
  --config models/b/config.yaml \
  --benchmark shared/benchmarks/text2sql.jsonl

# With a baseline for delta reporting
xreduce evaluate --config my-org/my-model/config.yaml --baseline <run-uuid>

xreduce compare

Compare models on accuracy, latency, energy, and cost from the cost-quality matrix. Two modes: explicit head-to-head with positional model identifiers, or fleet-wide via --task-type. See Compare for the full walkthrough.

# Head-to-head - model names or UUIDs, plus --benchmark
xreduce compare qwen3-4b qwen2.5-coder-7b --benchmark text2sql.jsonl

# Fleet-wide by task type
xreduce compare --task-type text-to-sql