Command reference

--json and --quiet are accepted by every command, before or after the subcommand name.

flag

Emit exactly one JSON object on stdout and nothing else. Progress commentary moves to stderr, so piping stdout stays safe.

flag

Suppress progress output. Errors are still reported.

flag

Print the installed r3alai version.

Free commands

No plan runs consumed. All but usage work offline.

`r3al export <repo-id | local-path>`

Convert a model to ONNX, which is what quantization takes. Free and local — a Hub export downloads weights but uploads nothing.

r3al export google/vit-base-patch16-224 --output-dir ./vit
r3al export weights.pt --input-shape 1,3,224,224 --output-dir ./exported

string

required

A HuggingFace repo id (owner/name) or a path to a local checkpoint. An existing path always wins, so a local directory named like a repo id still works.

path

default:"./exported"

string

Optimum task for a Hub model, e.g. image-classification. Usually inferred; pass it when the error says the task could not be determined.

string

Force the local source type: onnx, pytorch, ultralytics, tensorflow, paddle, tflite. Otherwise detected from the file.

string

Input shape for a local checkpoint that cannot be traced without one, e.g. 1,3,224,224.

int

ONNX opset. Defaults to the export layer’s choice (17).

Reports output_model for a single-file export, or onnx_files when an architecture exports several parts (encoder/decoder). Read those rather than constructing a filename.

Hub exports need Optimum, which is not a base dependency: pip install 'r3alai[export-hf]'. Optimum owns the per-architecture export logic, so deferring to it is what makes arbitrary Hub models work.

Verify an API key and store it for later commands.

export R3AL_API_KEY=r3l_live_... && r3al login
r3al login --status
r3al login --logout

flag

Report which key is in use and where it came from. Changes nothing.

flag

Read the key from stdin, so it never enters shell history.

flag

Remove the stored key.

The key comes from $R3AL_API_KEY or stdin, is validated against the platform before being written, and is stored at ~/.config/r3al/credentials.json with 0600 permissions.

There is deliberately no --key flag. Anything in argv is visible in shell history and in ps output to every process on the machine.

`r3al inspect <model>`

Describe a local model. Nothing is uploaded. Run this first: it catches “wrong file”, “not actually ONNX” and “no such path” for free.

path

required

Path to a model file. ONNX gets the full graph analysis; other formats report size and type only.

Returns input_name, input_shape, opset, node_count, a top_ops histogram, conv_heavy (true when over 15% of nodes are convolutions), and recommended_method.

$ r3al inspect model.onnx
model                model.onnx
format               onnx
opset                17
input_name           images
input_shape          [1, 3, 224, 224]
node_count           7
recommended_method   ptq_static
top_ops              Conv×2, Relu×2, GlobalAveragePool×1, Flatten×1, Gemm×1

`r3al validate`

Check a configuration locally against the same schema the platform uses. Exits 2 on an impossible combination.

ptq | qat

default:"ptq"

string

default:"ptq_static"

ptq_static or ptq_dynamic. Ignored when --mode qat.

4 | 8

default:"8"

string

minmax, percentile or entropy.

$ r3al validate --method ptq_dynamic --bitwidth 4
error: ... 4-bit needs the activation ranges that only calibration provides

`r3al methods`

List the available methods, whether each needs calibration data, and what each quantizes. Offline.

`r3al usage`

The plan and remaining runs for your API key. The only free command that needs the network, so it doubles as a key check — exits 3 when the key is missing or invalid.

`r3al skill`

Install the bundled agent skill, or print where it lives. Offline; downloads nothing, so it works without access to any repository.

claude | codex | cursor

default:"claude"

Which agent’s skills directory to install into.

path

Explicit destination, overriding --agent.

flag

Print the bundled skill’s directory instead of copying it.

flag

Overwrite an existing installation.

`r3al benchmark <model> <quantized>`

Measure both models on this machine with ONNX Runtime. Never uploads anything, never spends a run.

path

required

The original, unquantized model.

path

required

A quantized bundle directory, as produced by quantize or qat, or an explicit .onnx path. Prefer the directory: a downloaded deliverable’s filename carries a job-specific prefix, so it is not predictable.

int

default:"max(10, sample count)"

Timed iterations per model.

With no evaluation data this measures speed, not accuracy — it uses random inputs of the right shape. See Benchmarking.

Commands that spend a plan run

Both validate everything they can locally first, then refuse to submit without --yes.

`r3al quantize <model>`

Post-training quantization on R3AL’s GPUs. Downloads the deliverable bundle.

path

required

A local model. ONNX goes straight up; other supported formats are exported to ONNX locally first.

path | list

A directory, or a comma-separated list of files. Required for ptq_static.

path

default:"./quantized_output"

Where the bundle is downloaded.

string

default:"ptq_static"

ptq_static (best accuracy, needs calibration) or ptq_dynamic (no calibration, quantizes only MatMul/Gemm).

4 | 8

default:"8"

4 quantizes weights and activations to 4 bits. It halves the file again but costs real accuracy on vision models, and because the kernels dequantize to float the win is size rather than speed. Requires ptq_static.

string

default:"minmax"

minmax, percentile or entropy. Reach for the latter two when INT8 accuracy disappoints, or whenever using --bitwidth 4.

float

default:"99.999"

Clipping percentile for --calibration-method percentile, in percent — 99.99, not 0.9999.

flag

Required to actually submit. Without it the command exits 6 after validating.

r3al quantize model.onnx \
  --calibration-data ./calibration_images \
  --output-dir ./quantized \
  --method ptq_static --bitwidth 8 \
  --calibration-method percentile --calibration-percentile 99.99 \
  --yes

`r3al qat <model>`

Quantization-aware training: fine-tunes the model with quantization simulated in the loop. Slower than PTQ and still one plan run. See QAT pipeline.

path

required

path | list

required

Training images. Also used to initialise the activation clip thresholds.

path | list

Held-out samples, never trained on. Strongly recommended: without them the reported fidelity is measured on the images the run trained on, which cannot distinguish learning from memorising.

path

default:"./qat_output"

int

default:"config qat_epochs (1)"

1 is a smoke test. 5–10 is a reasonable first real attempt.

int

default:"8"

Images per training batch. A graph exported with a fixed batch axis overrides this — its baked-in size is used and the run says so. Re-export with a dynamic batch axis to train in larger batches.

float

default:"1e-4"

For the clip thresholds. The weights of quantized layers train at a tenth of this, since they arrive already converged.

int

default:"8"

Weight bit width, 3–8.

int

default:"8"

Activation bit width, 3–8.

flag

Required to submit.

r3al qat model.onnx \
  --calibration-data ./train_images \
  --validation-data ./heldout_images \
  --epochs 10 --yes

With --validation-data the run reports four fidelity figures — training and validation set, before and after — plus a note on what they imply about the learning rate. See QAT pipeline for how to read them.

​Free commands

​r3al export <repo-id | local-path>

​r3al login

​r3al inspect <model>

​r3al validate

​r3al methods

​r3al usage

​r3al skill

​r3al benchmark <model> <quantized>

​Commands that spend a plan run

​r3al quantize <model>

​r3al qat <model>

Free commands

`r3al export <repo-id | local-path>`

`r3al login`

`r3al inspect <model>`

`r3al validate`

`r3al methods`

`r3al usage`

`r3al skill`

`r3al benchmark <model> <quantized>`

Commands that spend a plan run

`r3al quantize <model>`

`r3al qat <model>`