CLI reference
Ordinary Loxa CLI commands in the current public source.
This reference summarizes the ordinary CLI commands in the current public source. Details may change before the first stable release.
| Command | Argument | Purpose |
|---|---|---|
loxa calibrate | None | Run the current calibration workflow. |
loxa doctor | None | Report machine and local-tool observations. |
loxa pull <id-or-reference> [--quant <quant>] | Required built-in/user registry ID or Hugging Face reference | Download a registry model or resolve and download a Hugging Face model. |
loxa list | None | List local registry files when no node is running, or running-node models when one is. |
loxa rm <id> | Required registry ID | Remove a managed model file when no node is running; otherwise, stop the node first. |
loxa load <id> | Required registry ID | Ask a running node to load a model. |
loxa unload | None | Ask a running node to unload its current model. |
loxa chat [--chat <id>] <prompt> | Required prompt | Send a prompt to a running node, optionally continuing a chat. |
loxa chats <subcommand> | Required history subcommand | List, show, rename, delete, or clear chat history on a running node. |
loxa run <id> [--ctx <u32>] [--port <u16>] [--engine <backend>] | Required model | Start one managed model runtime. |
loxa serve [--model <id>] [--port <u16>] [--inference-port <u16>] [--engine <backend>] | Optional model | Start a managed node. |
loxa ps | None | Show managed sidecars. |
loxa stop <target> | Required model ID or all | Stop a managed sidecar. |
loxa doctor
loxa doctorThe command takes no arguments. It prints a Machine section with chip, core, RAM,
swap, root disk, and operating system fields. A Detected tools section prints each
tool's install state, run state, and detection evidence.
A completed report exits 0. An output error follows the common CLI error path and
exits 1. See Doctor for the observation boundaries.
loxa list
loxa listThe command takes no arguments. When no managed node is running, it prints one row for
each registry entry with these columns: id, params, quant, size GB, license,
and status. Status is downloaded, partial, or not downloaded, based on the final
and .part files in ~/.loxa/models.
When a managed node is running, it instead prints one row for each model with these
columns: id, status, compatible, and engine.
A completed listing exits 0. An output error follows the common CLI error path and
exits 1.
loxa pull <id-or-reference> [--quant <quant>]
loxa pull <id-or-reference> [--quant <quant>]The required argument is either a built-in or user registry ID, or a Hugging Face
reference. A Hugging Face reference is owner/repo or
hf://owner/repo[@revision][:filename].
--quant <quant> participates only in Hugging Face resolution, where it selects a
matching verified GGUF. For a registry ID, the registry path ignores --quant. When
a node is already running, pull accepts only known registry recipe IDs; stop it
before resolving a Hugging Face reference or custom quantization.
During a transfer, progress includes the filename, transferred and total bytes,
percentage, transfer rate, and estimated time remaining. On success, stdout contains
the final model path and the command exits 0.
For a registry ID, an unknown ID prints the unknown ID and the valid registry IDs to
stderr, then exits 1. Hugging Face reference resolution errors are reported before
a download begins. A download failure prints the selected model ID and failure reason
to stderr, then exits 1.
loxa rm <id>
loxa rm <id>id is required and must match an entry in the built-in or user registry. When no
managed node is running, the command removes both the final model file and its .part
file. It reports each removed path, or reports that nothing is present for the ID. Either
successful result exits 0.
When a managed node is running, loxa rm refuses the removal and tells you to stop the
node first. It exits 1.
An unknown ID prints the unknown ID and the valid registry IDs to stderr, then exits
1. A filesystem or output error follows the common CLI error path and exits 1.
See Models for registry and file behavior and Troubleshooting for known failure cases.