> ## Documentation Index
> Fetch the complete documentation index at: https://docs.r3al.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# CLI
> Quantize vision models from the terminal with the r3al command.
`pip install r3alai` gives you an `r3al` command. It covers the same workflow as
the Python SDK: inspect a model, quantize it on R3AL's GPUs, and benchmark the
result on your own machine.
Requires **r3alai 2.4.3 or newer**. Earlier versions either ship no command at
all (\< 2.4.0), have a broken `benchmark` (2.4.0–2.4.1), or ship without the
bundled skill so `r3al skill install` fails (2.4.2). Check with `r3al --version`.
## Install
```bash theme={null}
pip install r3alai
export R3AL_API_KEY=r3l_live_... # from platform.r3al.ai -> SDK page
r3al login # verifies the key and stores it
```
`r3al login` writes the key to `~/.config/r3al/credentials.json` with `0600`
permissions, so later commands need no environment variable. It has no `--key`
flag on purpose: an argv secret is visible in shell history and to every process
on the machine. `r3al login --status` reports which key is in use, and
`r3al login --logout` removes the stored one.
For HuggingFace models, add the export extra:
```bash theme={null}
pip install 'r3alai[export-hf]'
```
## The cost model
Read this before anything else. Five commands are free; two spend a plan run.
`export` · `methods` · `validate` · `inspect` · `benchmark` · `usage` ·
`login` · `skill`
No plan runs. Nothing but `usage`, `login` and a Hub `export` touches the
network, and none of them upload your model.
`quantize` · `qat`
Both validate locally first and **refuse to submit without `--yes`**.
The confirmation gate exists so a mistyped command, or an automated retry, costs
nothing. Compose and correct with the free commands until you are certain, then
add `--yes`.
## A complete run
```bash theme={null}
# 0. get it into ONNX (free; downloads weights for a Hub model)
r3al export google/vit-base-patch16-224 --output-dir ./vit
# 1. what is this model? (free, offline, nothing uploaded)
r3al inspect model.onnx
# 2. is the plan valid? (free, offline)
r3al validate --method ptq_static --bitwidth 8
# 3. quantize (spends one plan run)
r3al quantize model.onnx \
--calibration-data ./calibration_images \
--output-dir ./quantized \
--yes
# 4. measure it (free, runs on your hardware)
r3al benchmark model.onnx ./quantized
```
`inspect` reports the input shape, opset, an operator histogram, and a
`recommended_method` derived from how convolution-heavy the graph is. Use that
rather than guessing between `ptq_static` and `ptq_dynamic`.
`quantize` reports both `output_dir` and `output_model` — the resolved path to
the deliverable inside the bundle. Use `output_model` rather than constructing a
filename: a downloaded deliverable carries a job-specific prefix.
## Calibration data
Static quantization observes real inputs to derive activation ranges, so
`ptq_static` cannot run without them. The CLI refuses rather than generating
random tensors, because calibrating on noise yields a model that looks
successful and is quietly worse.
```
$ r3al quantize model.onnx --yes
error: ptq_static needs calibration data and none was given. Cause: static
quantization derives activation ranges by observing real inputs, so it cannot
run without representative samples. Resolution: pass --calibration-data with a
directory of images (256-1024 covering your deployment distribution), or choose
--method ptq_dynamic, which needs no calibration but only quantizes
MatMul/Gemm layers and so suits transformers far better than convolutional
backbones.
```
Pass a directory or a comma-separated list. Accepted formats: images (`.jpg`,
`.jpeg`, `.png`, `.bmp`, `.gif`, `.tif`, `.tiff`, `.webp`, `.ppm`), resized and
scaled automatically; or `.npy`/`.npz` arrays already shaped like the model
input, used exactly as given. See [Calibration](/concepts/calibration) for how
many samples and what makes a good set.
## Machine-readable output
`--json` makes any command emit exactly one JSON object on stdout, with all
progress commentary on stderr. It works before or after the subcommand.
```bash theme={null}
r3al inspect model.onnx --json | jq .recommended_method
r3al --json usage | jq .remaining
```
## Exit codes
Distinct per failure class, so scripts can branch without parsing output.
| Code | Meaning | What to do |
| ---- | ------------------------------- | --------------------------------------------- |
| `0` | success | continue |
| `1` | unexpected failure | report it |
| `2` | bad arguments or invalid config | fix the command — free to retry |
| `3` | no or invalid API key | set `R3AL_API_KEY` |
| `4` | plan exhausted | stop; retrying cannot succeed |
| `5` | the job ran and failed | read the error, which names a cause and a fix |
| `6` | would spend a run, unconfirmed | add `--yes` |
Codes `2` and `6` cost nothing.
## Environment
| Variable | Purpose |
| ------------------- | ---------------------------------------------------------------- |
| `R3AL_API_KEY` | required by `quantize`, `qat` and `usage`; beats a stored key |
| `R3AL_CONFIG_DIR` | where `r3al login` stores credentials (default `~/.config/r3al`) |
| `R3AL_ASSUME_YES=1` | treats every command as confirmed, for non-interactive pipelines |
`R3AL_ASSUME_YES=1` disables the confirmation gate for the whole session. Set it
only in a pipeline you control, never as a convenience while experimenting.
## Next
Every command and every flag.
Install the bundled skill, and how the guard rails work for agents.