Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
25 commits
Select commit Hold shift + click to select a range
767b4d0
Add Sphinx documentation site
pmoutsias-amd Aug 26, 2026
e1336bf
Single-source the platform-support table in the install page
pmoutsias-amd Aug 26, 2026
540239e
fix(docs): address review feedback on Sphinx docs site
pmoutsias-amd Aug 26, 2026
fda13f1
fix(docs): add ReadTheDocs config and a CI job to build docs with -W
pmoutsias-amd Aug 26, 2026
87f3460
docs: use docs-relative cross-page links consistently
pmoutsias-amd Aug 26, 2026
518580a
docs: use descriptive nav title for Demos section
pmoutsias-amd Aug 26, 2026
f307a60
docs: fix sentence fragments in intro blurb
pmoutsias-amd Aug 26, 2026
77ea773
docs: style guide pass on README and CONTRIBUTING
pmoutsias-amd Aug 26, 2026
d6a45e9
fix(lemonade): retry interrupted backend setup (#249)
volen-silo Aug 27, 2026
7cd8902
ci(dependabot): track pre-commit hook versions (#235)
rominf Aug 27, 2026
d1253c5
fix: raise the supported Linux minimum to Ubuntu 24.04 (#261)
rominf Aug 27, 2026
e641dd2
ci(e2e): repair a pre-warm tree that records a folder elsewhere (#316)
volen-silo Aug 27, 2026
98bd916
fix(install): record the folder the files land in, not the link (#317)
volen-silo Aug 27, 2026
131690d
fix(install): resolve driver repo version and package release in plan…
r0x0r Aug 27, 2026
7fa0f82
fix(cli): accept negative float flag values in space form (EAI-8243) …
r0x0r Aug 27, 2026
f4618e9
fix(serve): validate --device via clap possible values (exit 2) (#304)
r0x0r Aug 27, 2026
61a28a3
fix(dash): launcher shows live serving instances; amd-smi detection o…
r0x0r Aug 27, 2026
908671e
Fix diagnose emitting invalid UNKNOWN render-group remediation (#302)
r0x0r Aug 27, 2026
d7f2c6b
Merge remote-tracking branch 'origin/main' into docs/add-sphinx-docum…
pmoutsias-amd Aug 27, 2026
9169fbb
docs(readme): reframe install channels around published release, docu…
pmoutsias-amd Aug 27, 2026
b7300c3
docs(readme): remove rocm model from command reference
pmoutsias-amd Aug 27, 2026
482e763
docs(conf): switch to rocm-ai flavor, enable repo and download buttons
pmoutsias-amd Aug 27, 2026
cbd3063
Merge remote-tracking branch 'origin/main' into docs/add-sphinx-docum…
pmoutsias-amd Aug 27, 2026
b893d04
docs(conf): revert repository/download header buttons
pmoutsias-amd Aug 27, 2026
8414709
docs(conf): fix flavor fallback and pin repository buttons
pmoutsias-amd Aug 27, 2026
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
41 changes: 41 additions & 0 deletions .github/workflows/ci.yml
Original file line number Diff line number Diff line change
Expand Up @@ -82,6 +82,7 @@ jobs:
heavy: ${{ steps.filter.outputs.heavy || steps.all.outputs.forced }}
lint: ${{ steps.filter.outputs.lint || steps.all.outputs.forced }}
tpn: ${{ steps.filter.outputs.tpn || steps.all.outputs.forced }}
docs: ${{ steps.filter.outputs.docs || steps.all.outputs.forced }}
steps:
- uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1

Expand Down Expand Up @@ -148,6 +149,15 @@ jobs:
- 'ruff.toml'
- 'PSScriptAnalyzerSettings.psd1'
- '.github/workflows/**'
# Sphinx docs site: the doc sources themselves, plus README.md and
# CONTRIBUTING.md, which several pages single-source via MyST
# `{include}` directives, plus the build config/toolchain pins.
docs:
- 'docs/rocm-docs/**'
- 'README.md'
- 'CONTRIBUTING.md'
- '.readthedocs.yaml'
- '.github/workflows/**'

- name: Force full run off pull requests
id: all
Expand Down Expand Up @@ -618,6 +628,37 @@ jobs:
run: |
"${HAWKEYE_INSTALL_DIR}/hawkeye" check

docs-build:
name: Sphinx docs build (-W)
runs-on: ubuntu-latest
timeout-minutes: 20
needs: [changes]
# A manual E2E dispatch only exercises the E2E jobs; skip the rest. Off a
# dispatch, `needs.changes` never ran, so short-circuit on event_name first.
if: github.event_name != 'workflow_dispatch' && needs.changes.outputs.docs == 'true'
steps:
- uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1

- name: Cache pip packages
id: cache-pip
uses: actions/cache@55cc8345863c7cc4c66a329aec7e433d2d1c52a9 # v6.1.0
with:
path: ~/.cache/pip
key: ${{ runner.os }}-docs-pip-${{ hashFiles('docs/rocm-docs/sphinx/requirements.txt') }}

- name: Install Sphinx toolchain
run: |
python3 -m venv .docs-venv
.docs-venv/bin/pip install -q -r docs/rocm-docs/sphinx/requirements.txt

# Same source Sphinx points at (docs/rocm-docs/conf.py) and the same
# -W (warnings-as-errors) mode read-the-docs builds with, so a broken
# MyST include, dead xref, or toctree gap fails CI instead of surfacing
# as a silent RTD build failure after merge.
- name: Build docs (warnings as errors)
run: |
.docs-venv/bin/sphinx-build -b html docs/rocm-docs /tmp/rocm-cli-docs -W

commit-signatures:
name: Commit signatures + sign-off
runs-on: ubuntu-latest
Expand Down
4 changes: 4 additions & 0 deletions .gitignore
Original file line number Diff line number Diff line change
Expand Up @@ -17,3 +17,7 @@ __pycache__/
/plans/
/workspace/
/e2e-consolidated-report.md

# Sphinx docs: _toc.yml is generated from _toc.yml.in at build time
docs/rocm-docs/sphinx/_toc.yml
docs/rocm-docs/_build/
13 changes: 13 additions & 0 deletions .readthedocs.yaml
Original file line number Diff line number Diff line change
@@ -0,0 +1,13 @@
version: 2

build:
os: ubuntu-24.04
tools:
python: "3.12"

sphinx:
configuration: docs/rocm-docs/conf.py

python:
install:
- requirements: docs/rocm-docs/sphinx/requirements.txt
20 changes: 10 additions & 10 deletions CONTRIBUTING.md
Original file line number Diff line number Diff line change
Expand Up @@ -10,13 +10,13 @@ Thank you for your interest in contributing. This document explains how to get s

## Code of Conduct

By participating in this project you agree to abide by the [Code of Conduct](CODE_OF_CONDUCT.md).
By participating in this project you agree to abide by the [Code of Conduct](https://github.com/ROCm/rocm-cli/blob/main/CODE_OF_CONDUCT.md).

## Issue Tracking
## Issue tracking

Bug reports and feature requests are tracked as [GitHub Issues](../../issues). Before opening a new issue, search existing ones to avoid duplicates.
Bug reports and feature requests are tracked as [GitHub Issues](https://github.com/ROCm/rocm-cli/issues). Before opening a new issue, search existing ones to avoid duplicates.

## Branch and Commit Naming
## Branch and commit naming

Use [Conventional Commits](https://www.conventionalcommits.org/) for commit messages:

Expand All @@ -34,7 +34,7 @@ feat/vllm-multi-gpu
fix/vram-probe-fallback
```

## Development Setup
## Development setup

Prerequisites: Rust (see `rust-toolchain.toml` for the pinned version) and [uv](https://github.com/astral-sh/uv) (for prek and scripts).

Expand Down Expand Up @@ -74,7 +74,7 @@ cargo install cargo-about@0.9.1 --locked --features cli # optional, for THIRD_

See `docs/testing.md` for the full test guide and `docs/manual-testing.md` for manual QA steps.

## Making Changes
## Making changes

1. **Fork** the repository and create a branch from `main`.
2. **Make your changes.** Keep commits focused — one logical change per commit.
Expand All @@ -84,7 +84,7 @@ See `docs/testing.md` for the full test guide and `docs/manual-testing.md` for m

### Commit signing and sign-off

Commits must be both cryptographically **signed** and carry a DCO **`Signed-off-by`** trailer. Use `git commit -s` to add the trailer automatically. This is enforced by the prek hooks and by a blocking CI check.
Commits must be both cryptographically **signed** and carry a Developer Certificate of Origin (DCO) **`Signed-off-by`** trailer. Use `git commit -s` to add the trailer automatically. This is enforced by the prek hooks and by a blocking CI check.

Enable SSH signing once with:

Expand All @@ -102,10 +102,10 @@ See `docs/commit-signatures.md` for GPG signing, GitHub "Verified" status, and t
- No secrets, credentials, or internal hostnames in committed files
- Third-party dependencies declared in `Cargo.lock`; license headers present on new source files (see `licenserc.toml`)

## Reporting Security Issues
## Reporting security issues

Do **not** open a public GitHub Issue for security vulnerabilities. See [SECURITY.md](SECURITY.md) for the responsible disclosure process.
Do **not** open a public GitHub Issue for security vulnerabilities. See [SECURITY.md](https://github.com/ROCm/rocm-cli/blob/main/SECURITY.md) for the responsible disclosure process.

## License

By contributing you agree that your contributions will be licensed under the [MIT License](LICENSE.TXT).
By contributing you agree that your contributions will be licensed under the [MIT License](https://github.com/ROCm/rocm-cli/blob/main/LICENSE.TXT).
104 changes: 54 additions & 50 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -23,19 +23,21 @@ SPDX-License-Identifier: MIT
ROCm CLI is a command-line tool for setting up and running local AI on AMD GPUs, with a
full-screen TUI dashboard for GPU telemetry, model serving, and chat.

A single prebuilt binary for Linux and Windows (x86_64). No Python, Rust, or
existing ROCm install required. Ships with inference engine adapters for
Lemonade and vLLM.
It ships as a single prebuilt binary for Linux and Windows (x86_64), needs no
Python, Rust, or existing ROCm install, and includes inference engine adapters
for Lemonade and vLLM.

<!-- platform-support-table-start -->
| Platform | Prebuilt binary | Notes |
|---|---|---|
| Linux (x86_64) | Yes | Ubuntu 24.04 or newer; full support, including the live dashboard and both inference engines |
| Windows (x86_64) | Yes | CLI and Lemonade serving; no live dashboard or vLLM |
| WSL2 (x86_64) | Yes (Linux binary) | Ubuntu 24.04 or newer; full support, including the live dashboard; see [docs/wsl.md](docs/wsl.md) for setup |
| WSL2 (x86_64) | Yes (Linux binary) | Ubuntu 24.04 or newer; full support, including the live dashboard; see [docs/wsl.md](https://github.com/ROCm/rocm-cli/blob/main/docs/wsl.md) for setup |
| macOS | No | No official installer, release, CI, or QA coverage |
<!-- platform-support-table-end -->

Live dashboard telemetry requires Linux or WSL2 (see
[Interactive interfaces](#interactive-interfaces)). vLLM serving is Linux/WSL2
[Interactive interfaces](#interactive-interfaces)). vLLM serving is Linux or WSL2
only (see [docs/vllm.md](docs/vllm.md)).

The minimum supported Linux release, native or under WSL2, is Ubuntu 24.04. On
Expand All @@ -47,7 +49,7 @@ glibc 2.39 and `GLIBCXX_3.4.33`.

> [!IMPORTANT]
> **Tech Preview** -- This software is provided as-is, without warranty or
> guarantee of stability. APIs, commands, and behavior may change without
> guarantee of stability. APIs, commands, and behavior might change without
> notice. Intended for experimentation and early feedback only.

## Demos
Expand Down Expand Up @@ -78,30 +80,32 @@ The installer downloads a prebuilt bundle, verifies its SHA-256 checksum,
installs the `rocm` and `rocmd` binaries into `~/.local/bin`, and adds that
directory to your shell `PATH`. Rerun it any time to upgrade.

### Linux / WSL (x86_64)

Only nightly builds are published today, so pass the `nightly` channel:
### Linux and WSL (x86_64)

```bash
curl -fsSL https://raw.githubusercontent.com/ROCm/rocm-cli/main/install.sh | sh -s -- nightly
curl -fsSL https://raw.githubusercontent.com/ROCm/rocm-cli/main/install.sh | sh
```

Once a stable release exists, omit the argument to track the default `release`
channel instead:
This tracks the default `release` channel. For nightly builds, pass the
`nightly` channel instead:

```bash
curl -fsSL https://raw.githubusercontent.com/ROCm/rocm-cli/main/install.sh | sh
curl -fsSL https://raw.githubusercontent.com/ROCm/rocm-cli/main/install.sh | sh -s -- nightly
```

### Windows (x86_64, PowerShell)

```powershell
$env:ROCM_CLI_CHANNEL = "nightly"
irm https://raw.githubusercontent.com/ROCm/rocm-cli/main/install.ps1 | iex
```

Drop the `ROCM_CLI_CHANNEL` line to track the default `release` channel once a
stable release is published.
This tracks the default `release` channel. For nightly builds, set
`ROCM_CLI_CHANNEL` to `nightly` first:

```powershell
$env:ROCM_CLI_CHANNEL = "nightly"
irm https://raw.githubusercontent.com/ROCm/rocm-cli/main/install.ps1 | iex
```

## Build from source

Expand Down Expand Up @@ -131,11 +135,13 @@ Or copy the release binaries onto your `PATH`:
install -m 0755 target/release/rocm target/release/rocmd ~/.local/bin/
```

See [CONTRIBUTING.md](CONTRIBUTING.md) for the full development setup, test
See [CONTRIBUTING.md](https://github.com/ROCm/rocm-cli/blob/main/CONTRIBUTING.md) for the full development setup, test
commands, and commit-signing requirements.

## First run

Launch ROCm CLI with no arguments:

```
rocm
```
Expand Down Expand Up @@ -173,7 +179,7 @@ five tabs (switch with `Tab`/`Shift+Tab` or number keys `1`–`5`):
| Tab | What it shows |
|---|---|
| **Home** | At-a-glance status: GPU, active runtime, running servers |
| **ROCm** | Guided ROCm/runtime actions with inline details |
| **ROCm** | Guided ROCm and runtime actions with inline details |
| **Serving** | Start, inspect, and manage model servers |
| **Observe** | Live GPU utilization, instances, and benchmark telemetry |
| **Chat** | Assistant chat backed by a local server or configured provider |
Expand All @@ -182,7 +188,7 @@ Live mode reads telemetry over a Unix domain socket, so it requires Linux or
WSL. Use `rocm dash --demo` for a synthetic session that runs anywhere without a
GPU or daemon.

## Getting started
## Configure ROCm and serve a model

Before serving a model, ensure a managed ROCm runtime is configured:

Expand All @@ -206,9 +212,6 @@ box. You can also serve any compatible Hugging Face model directly — see
[Model serving](#model-serving) for the GGUF-vs-safetensors rule, since which
form works depends on the engine your GPU selects.

Use `rocm model` to see available model recipes and their GPU memory
requirements.

## Quick reference

| Command | Description |
Expand All @@ -225,11 +228,28 @@ requirements.

## Commands

### Examine

```
rocm examine [--json] [--framework auto|pytorch|llama-cpp|skip]
```

Checks this computer's GPU, ROCm install, engines, and managed setup
folders — the command to run first to see whether a system is ready, and
what `rocm install sdk` and `rocm serve` will see. `--json` emits a
machine-readable report for diagnosis tooling instead of the human-readable
summary. `--framework` controls which ML framework the `--json` report probes
for its ROCm build and compiled GPU architectures: `auto` (the default) tries
PyTorch, then falls back to llama.cpp; `pytorch` or `llama-cpp` probe only
that framework; `skip` runs no framework probe at all, which is fastest and
still enough to answer GPU and driver questions. `--framework` only affects
the JSON report, not the human-readable one.

### ROCm installation

```
rocm install sdk [--channel release|nightly] [--format wheel|tarball]
[--version X.Y.Z | --build-date YYYY-MM-DD]
[--version x.y.z | --build-date YYYY-MM-DD]
[--family gfx110X-all] [--prefix PATH] [--dry-run]

rocm install driver [--dkms] [--yes] [--dry-run] [--reconcile]
Expand Down Expand Up @@ -257,7 +277,7 @@ rocm runtimes adopt --python <path> [--root <path>] [--runtime-id ID]
```

`adopt` registers an existing TheRock-based Python environment as a managed
runtime. It does not work with standard ROCm package installs (e.g.
runtime. It does not work with standard ROCm package installs (for example,
`/opt/rocm`); use `rocm install sdk` instead.

### Disk space
Expand Down Expand Up @@ -345,15 +365,14 @@ to stop the server instead. `--managed` is the explicit form of the default
background behavior. `--no-smoke-test` skips the post-startup inference probe.

Which model form to pass depends on the engine your GPU selects. The Lemonade
engine (Ryzen AI / Radeon) serves llama.cpp **GGUF** models — pass a GGUF repo
with an explicit quantization variant, e.g.
engine (Ryzen AI or Radeon) serves llama.cpp **GGUF** models — pass a GGUF repo
with an explicit quantization variant, for example,
`rocm serve unsloth/Qwen3-0.6B-GGUF:Q4_0`. The vLLM engine (Instinct) serves
**safetensors** repos, e.g. `rocm serve Qwen/Qwen2.5-1.5B-Instruct`. A
**safetensors** repos, such as `rocm serve Qwen/Qwen2.5-1.5B-Instruct`. A
safetensors-only id has no GGUF build, so serving it through Lemonade fails
rather than silently substituting a different model. Short
aliases from `rocm model` may not resolve with all engines.
rather than silently substituting a different model.

Some models (e.g., Llama) are gated and require HuggingFace authentication.
Some models (such as Llama) are gated and require HuggingFace authentication.
Log in with `huggingface-cli login` or set `HF_TOKEN` in your environment
before serving gated models.

Expand All @@ -367,26 +386,6 @@ model across multiple GPUs is not supported. Because selection uses the
`amd-smi` ordinal but is applied via `HIP_VISIBLE_DEVICES`, rocm-cli warns when
`ROCR_VISIBLE_DEVICES` is set, since the two orderings can diverge.

Show recommended models and hardware compatibility:

```
rocm model [--verbose]
```

`rocm model` prints a curated catalog of popular open-weight models grouped by
the hardware path they target — Strix Halo (Lemonade / llama.cpp) and MI300X
(vLLM) — using canonical Hugging Face ids, and shows for each the quantization
that fits a single GPU. Strix Halo entries use the `owner/repo:variant` GGUF form
(e.g. `unsloth/Qwen3.6-35B-A3B-GGUF:Q4_K_M`) that `rocm serve` needs; MI300X
entries serve at BF16. This catalog ships inside the binary, so it is available
offline; when a recipe index is configured instead, the header names it.
`--verbose` also lists the other recipes (the default assistant and smoke/test
paths) that `rocm serve` can still resolve but that are hidden from the list.

The catalog is only a starting point: you can serve any compatible Hugging Face
model by passing its id to `rocm serve` — `owner/repo` for vLLM, or
`owner/repo:<quant>` for a Lemonade GGUF.

Manage background servers started with `--managed`:

```
Expand Down Expand Up @@ -449,6 +448,11 @@ Optional background checks that can propose or apply changes automatically.

### Configuration

Show or change rocm-cli's saved settings — the default engine and runtime,
which runtime each engine prefers, local GPU telemetry opt-in, and the
provider used for chat, automations, and ambiguous natural-language plans
(including enabling providers and storing their API keys).

```
rocm config show
rocm config set-default-engine <engine>
Expand Down
19 changes: 19 additions & 0 deletions docs/rocm-docs/about/contributing.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,19 @@
<!--
Copyright © Advanced Micro Devices, Inc., or its affiliates.

SPDX-License-Identifier: MIT
-->

# Contributing

```{include} ../../../CONTRIBUTING.md
:start-after: "# Contributing to ROCm CLI"
```

## More docs

<!-- No end-before: this intentionally runs to end of file, so any section
appended after "## More docs" in README.md is picked up automatically. -->
```{include} ../../../README.md
:start-after: "## More docs"
```
11 changes: 11 additions & 0 deletions docs/rocm-docs/about/license.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,11 @@
<!--
Copyright © Advanced Micro Devices, Inc., or its affiliates.

SPDX-License-Identifier: MIT
-->

# License

```{literalinclude} ../../../LICENSE.TXT
:language: text
```
Loading
Loading