CLI - R3AL.AI

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

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:

pip install 'r3alai[export-hf]'

The cost model

Read this before anything else. Five commands are free; two spend a plan run.

Free

export · methods · validate · inspect · benchmark · usage · login · skillNo plan runs. Nothing but usage, login and a Hub export touches the network, and none of them upload your model.

Spends one plan run

quantize · qatBoth 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

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

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.

Command reference

Every command and every flag.

Use it from a coding agent

Install the bundled skill, and how the guard rails work for agents.

​Install

​The cost model

Free

Spends one plan run

​A complete run

​Calibration data

​Machine-readable output

​Exit codes

​Environment

​Next

Command reference

Use it from a coding agent

Install

The cost model

A complete run

Calibration data

Machine-readable output

Exit codes

Environment

Next