# CLI reference

> Ordinary Loxa CLI commands in the current public source.

Canonical: https://loxa.dev/docs/cli

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-doctor]

```text
loxa doctor
```

The 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](/docs/doctor) for the observation boundaries.

## `loxa list` [#loxa-list]

```text
loxa list
```

The 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]

```text
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]

```text
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](/docs/models) for registry and file behavior and
[Troubleshooting](/docs/troubleshooting) for known failure cases.