Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
15 commits
Select commit Hold shift + click to select a range
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
20 changes: 18 additions & 2 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -357,10 +357,14 @@ Without `--version`, `rocm install sdk` installs the newest stable release
(ROCm 10.1 today) from `stable.repo.amd.com`, and `--channel nightly` installs the
newest nightly build from `nightly.repo.amd.com`. Earlier releases stay
installable by pinning them: `--version 7.14.1` installs the ROCm 7.14.1 release,
`--version 7.14` the newest release in the 7.14 line,
and `--channel nightly --build-date 2026-08-19` installs a nightly from before
the nightly channel moved on 2026-08-23. If ROCm CLI can't tell which exact GPU
arch this computer has, or you want a different one, also add `--family` with the
raw `gfx` code from `rocm examine`. For example: `--family gfx1200`.
A `major.minor` pin such as `--version 10.1` selects the newest stable release in
that line (for example `10.1.0`); a `major.minor.patch` pin such as
`--version 10.1.0` stays exact.

On WSL, wheel runtime installs and updates (`rocm install sdk`,
`rocm update --apply`) also link `librocdxg.so` to the runtime's own
Expand Down Expand Up @@ -621,7 +625,7 @@ unknown option `-1`, a usage error that exits 2.

```
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 gfx1100] [--prefix PATH] [--devel] [--dry-run]
[--python-version X.Y]
[--approve-replacing-active-default] [--yes]
Expand Down Expand Up @@ -742,7 +746,9 @@ ROCm 10 and newer ship from a different source layout than ROCm 7: stable
releases from `stable.repo.amd.com` and nightlies from `nightly.repo.amd.com`.
That is the layout an install reads unless it asks for something older. A stable
pin of ROCm 10 or newer, a nightly pinned to a build date of 2026-08-23 or later,
and an install with no pin at all all read it. The earlier release stream
and an install with no pin at all all read it. A two-component pin
(`--version 10.1`) is the 10.1 line and installs the newest stable release in it;
`--version 10.1.0` installs that exact release. The earlier release stream
(`repo.amd.com`) and the earlier nightly stream (`rocm.nightlies.amd.com`), which
stopped receiving builds on 2026-08-22, are read only when you pin something that
exists only there: a ROCm 7 release, or a nightly from before 2026-08-23. These
Expand Down Expand Up @@ -808,6 +814,16 @@ streams no longer publish new builds, so reinstall with `rocm install sdk` to
move it. `install sdk` doesn't quietly retry against the other layout when a
lookup finds nothing; it tells you what it couldn't find instead.

When a ROCm 10 pin can't be satisfied because that release isn't published, or
has no installable packages for this computer, the error lists the other stable
ROCm 10 releases that source publishes, if any, and suggests one of them to
re-run with, in the same `--format` as the failed request. When `rocm update`
fails the same way, it suggests a whole `rocm install sdk` command that keeps
the runtime's format and `--devel` toolchain. A failure no other version can
fix, such as an unknown GPU arch or a network error, suggests no version, and
neither does a failed `--channel nightly` request, whose builds are not stable
releases.

#### Driver installation

`install driver` installs the AMD kernel driver on Linux, using DKMS or a native
Expand Down
2 changes: 1 addition & 1 deletion apps/rocm/src/chat/turn.rs
Original file line number Diff line number Diff line change
Expand Up @@ -626,7 +626,7 @@ fn find_ascii_case_insensitive(haystack: &str, needle: &str) -> Option<usize> {
/// to, and a WSL user was told "on native Windows, vLLM is skipped" while vLLM
/// was in fact their supported path. Anything host-dependent now comes from
/// [`chat_host_facts::HostFacts`], which knows which machine it is describing.
const ROCM_CHAT_TOOL_SYSTEM_PROMPT: &str = "You are ROCm CLI's local assistant. Speak in simple English for non-technical users. Use the provided ROCm tools when you need to inspect this machine, preview setup, read service logs, check updates, inspect automations, install or start ROCm-managed apps, or request ROCm/TheRock, config, engine, app, and local model server changes. For simple greetings or thanks like hello, hi, hey, ok, or thank you, reply normally; do not inspect ROCm, do not call tools, and do not launch or propose a model server. Tool-use rules: inspect first with read-only tools; call rocm_command only with argv-style args and no shell text; use natural_language_plan for ROCm requests that do not fit another read-only tool; ask for a mutating tool call only after explaining why it is needed; summarize tool results after they are returned. Read-only tools may run immediately. Tools that install, launch, stop, delete, or change state require user approval; request rocm_command and explain why. For 'is X running?', 'what is running?', status, or port questions, inspect before answering and do not start, stop, install, or serve anything. For ComfyUI or port 8188 use [\"comfyui\",\"status\"] or port_status. For vLLM, Lemonade, AIM, qwen, or local model servers use [\"services\",\"list\",\"--all\"] for running state and [\"engines\",\"list\"] for installed/available engine state. Treat ready/running as running, starting/recovering as starting, failed/stopped as not running, and no matching record as unknown or not managed by ROCm CLI. Interpret Examine carefully: active_runtime_status=ready means ROCm CLI has an active managed TheRock/ROCm runtime; legacy_rocm_status=not_detected only means no global system ROCm install was found. If active_runtime_status=ready, tell the user ROCm/TheRock is installed and active for ROCm CLI. For 'is TheRock installed', 'is ROCm installed', or 'which GPU is on this machine', use examine or gpu_snapshot before answering. For 'how do I setup TheRock' or install/setup requests, guide the user to choose an install folder first; do not answer with only a status check. For 'which LLMs can this machine support', use rocm_command args [\"model\"] or natural_language_plan before answering. For TheRock installs, always let the user choose the install folder. If the user names a folder or prefix, preserve that exact folder with [\"--prefix\",\"PATH\"]; you may call path_exists first to check whether that user-provided folder or its parent exists. If the user asks you to install TheRock/ROCm but has not named a folder, ask for the folder or let the guided setup folder picker collect it; do not invent a hidden default folder and do not request an install command without --prefix. Use rocm_command args [\"install\",\"sdk\",\"--channel\",\"release\",\"--format\",\"wheel\",\"--prefix\",\"PATH\"] only when the user asks you to install it and a folder is known; for a requested build date add [\"--build-date\",\"YYYY-MM-DD\"] and for a requested exact version add [\"--version\",\"VERSION\"]. For config changes, inspect with [\"config\",\"show\"] first when useful, then request config subcommands such as [\"config\",\"set-default-engine\",\"lemonade\"], [\"config\",\"set-default-runtime\",\"RUNTIME_KEY\"], or [\"config\",\"set-telemetry\",\"local\"] only after explaining why. For ComfyUI, use rocm_command with args like [\"comfyui\",\"status\"], [\"comfyui\",\"logs\"], [\"comfyui\",\"install\"], [\"comfyui\",\"start\"], or [\"comfyui\",\"stop\"]. First-time setup is the same thing as bootstrap in ROCm CLI; it is a deterministic ROCm setup flow, not a separate model chat. The built-in local assistant is fixed to qwen, which maps to Qwen3-4B-Instruct-2507-GGUF served by Lemonade with gpu_required. vLLM, Lemonade, and AIM (Docker-based) are the general serving engines; inspect or manage them when the user asks about general model serving, but do not switch the built-in assistant away from Lemonade. Use qwen-smoke only for a quick server smoke test. For vLLM management, inspect engines first and use [\"engines\",\"install\",\"vllm\"] or [\"serve\",\"MODEL\",\"--engine\",\"vllm\",\"--device\",\"gpu_required\",\"--managed\"] only where the host supports it. Do not invent shell commands and do not request CPU fallback.";
const ROCM_CHAT_TOOL_SYSTEM_PROMPT: &str = "You are ROCm CLI's local assistant. Speak in simple English for non-technical users. Use the provided ROCm tools when you need to inspect this machine, preview setup, read service logs, check updates, inspect automations, install or start ROCm-managed apps, or request ROCm/TheRock, config, engine, app, and local model server changes. For simple greetings or thanks like hello, hi, hey, ok, or thank you, reply normally; do not inspect ROCm, do not call tools, and do not launch or propose a model server. Tool-use rules: inspect first with read-only tools; call rocm_command only with argv-style args and no shell text; use natural_language_plan for ROCm requests that do not fit another read-only tool; ask for a mutating tool call only after explaining why it is needed; summarize tool results after they are returned. Read-only tools may run immediately. Tools that install, launch, stop, delete, or change state require user approval; request rocm_command and explain why. For 'is X running?', 'what is running?', status, or port questions, inspect before answering and do not start, stop, install, or serve anything. For ComfyUI or port 8188 use [\"comfyui\",\"status\"] or port_status. For vLLM, Lemonade, AIM, qwen, or local model servers use [\"services\",\"list\",\"--all\"] for running state and [\"engines\",\"list\"] for installed/available engine state. Treat ready/running as running, starting/recovering as starting, failed/stopped as not running, and no matching record as unknown or not managed by ROCm CLI. Interpret Examine carefully: active_runtime_status=ready means ROCm CLI has an active managed TheRock/ROCm runtime; legacy_rocm_status=not_detected only means no global system ROCm install was found. If active_runtime_status=ready, tell the user ROCm/TheRock is installed and active for ROCm CLI. For 'is TheRock installed', 'is ROCm installed', or 'which GPU is on this machine', use examine or gpu_snapshot before answering. For 'how do I setup TheRock' or install/setup requests, guide the user to choose an install folder first; do not answer with only a status check. For 'which LLMs can this machine support', use rocm_command args [\"model\"] or natural_language_plan before answering. For TheRock installs, always let the user choose the install folder. If the user names a folder or prefix, preserve that exact folder with [\"--prefix\",\"PATH\"]; you may call path_exists first to check whether that user-provided folder or its parent exists. If the user asks you to install TheRock/ROCm but has not named a folder, ask for the folder or let the guided setup folder picker collect it; do not invent a hidden default folder and do not request an install command without --prefix. Use rocm_command args [\"install\",\"sdk\",\"--channel\",\"release\",\"--format\",\"wheel\",\"--prefix\",\"PATH\"] only when the user asks you to install it and a folder is known; for a requested build date add [\"--build-date\",\"YYYY-MM-DD\"] and for a requested version add [\"--version\",\"VERSION\"] (an exact version such as 10.1.0, or a release line such as 10.1 for its newest stable release). For config changes, inspect with [\"config\",\"show\"] first when useful, then request config subcommands such as [\"config\",\"set-default-engine\",\"lemonade\"], [\"config\",\"set-default-runtime\",\"RUNTIME_KEY\"], or [\"config\",\"set-telemetry\",\"local\"] only after explaining why. For ComfyUI, use rocm_command with args like [\"comfyui\",\"status\"], [\"comfyui\",\"logs\"], [\"comfyui\",\"install\"], [\"comfyui\",\"start\"], or [\"comfyui\",\"stop\"]. First-time setup is the same thing as bootstrap in ROCm CLI; it is a deterministic ROCm setup flow, not a separate model chat. The built-in local assistant is fixed to qwen, which maps to Qwen3-4B-Instruct-2507-GGUF served by Lemonade with gpu_required. vLLM, Lemonade, and AIM (Docker-based) are the general serving engines; inspect or manage them when the user asks about general model serving, but do not switch the built-in assistant away from Lemonade. Use qwen-smoke only for a quick server smoke test. For vLLM management, inspect engines first and use [\"engines\",\"install\",\"vllm\"] or [\"serve\",\"MODEL\",\"--engine\",\"vllm\",\"--device\",\"gpu_required\",\"--managed\"] only where the host supports it. Do not invent shell commands and do not request CPU fallback.";

const ROCM_CHAT_TOOL_SKILL: &str = include_str!("../../../../skills/rocm-cli-assistant/SKILL.md");

Expand Down
50 changes: 47 additions & 3 deletions apps/rocm/src/cli.rs
Original file line number Diff line number Diff line change
Expand Up @@ -841,9 +841,13 @@ rocm install sdk --version 10.0.0 --python-version 3.12")]
/// Full folder path where the ROCm Python environment should be created.
#[arg(long)]
prefix: Option<std::path::PathBuf>,
/// Exact TheRock package version to install; with none, the channel's
/// newest build. An earlier ROCm 7 release such as 7.14.1 is supported,
/// for a wheel install only.
/// TheRock package version to install; with none, the channel's newest
/// build.
///
/// `major.minor.patch` is exact, including a prerelease suffix.
/// `major.minor` (for example `10.1`) selects the newest stable
/// release in that line. An earlier ROCm 7 release such as 7.14.1 or
/// the 7.14 line is supported, for a wheel install only.
#[arg(long, conflicts_with = "build_date")]
version: Option<String>,
/// Pick the TheRock package built on this date; nightlies from before
Expand Down Expand Up @@ -1602,6 +1606,46 @@ mod tests {
);
}

#[test]
fn install_sdk_version_help_describes_line_and_exact_pins() {
// Wording pin: `--version 10.1` selecting the newest stable 10.1.x, and
// `--version 10.1.0` staying exact, are proven by
// `two_component_version_pin_routes_and_matches_its_release_line` in
// `therock/source.rs` and by scenarios therock-next-24 and -26. This
// only keeps the help that describes them from drifting back to
// "exact version". It reads the `version` argument's own help, so the
// sibling `--build-date` doc cannot satisfy it.
let mut command = Cli::command();
let sdk = command
.find_subcommand_mut("install")
.expect("install subcommand")
.find_subcommand_mut("sdk")
.expect("install sdk subcommand");
let version = sdk
.get_arguments()
.find(|arg| arg.get_id() == "version")
.expect("`install sdk` must offer --version");
let version_help = version
.get_long_help()
.or_else(|| version.get_help())
.expect("--version must be documented")
.to_string();

assert!(
version_help.contains("`major.minor.patch` is exact"),
"`--version` must say a three-component pin is exact:\n{version_help}"
);
assert!(
version_help.contains("`major.minor` (for example `10.1`) selects the newest stable"),
"`--version` must say a two-component pin selects the newest stable \
release in that line:\n{version_help}"
);
assert!(
!version_help.starts_with("Exact"),
"`--version` no longer takes only an exact version:\n{version_help}"
);
}

#[test]
fn install_sdk_help_separates_the_two_consents_yes_carries() {
// `--yes` approves two unrelated things: replacing the active default
Expand Down
2 changes: 1 addition & 1 deletion apps/rocm/src/therock.rs
Original file line number Diff line number Diff line change
Expand Up @@ -243,7 +243,7 @@ pub(crate) fn install_sdk(
&& layout_serving(channel, Some(selector)) == SourceLayout::Canonical
{
bail!(
"specific TheRock version selection for tarball installs is supported only for the newer package layout: a stable ROCm 10+ release (e.g. `--version 10.0.0`) or a nightly built on or after {THEROCK_NEXT_NIGHTLY_FIRST_BUILD_DATE}; for any earlier version, use `--format wheel`"
"specific TheRock version selection for tarball installs is supported only for the newer package layout: a stable ROCm 10+ release or release line (e.g. `--version 10.0.0` or `--version 10.1`) or a nightly built on or after {THEROCK_NEXT_NIGHTLY_FIRST_BUILD_DATE}; for any earlier version, use `--format wheel`"
)
}
install_tarball_runtime(
Expand Down
8 changes: 5 additions & 3 deletions apps/rocm/src/therock/resolve.rs
Original file line number Diff line number Diff line change
Expand Up @@ -5,10 +5,12 @@
//! How a request is turned into the artifact an install fetches. Only module
//! declarations and re-exports live here, no logic: `tarball` resolves the SDK
//! tarball from the catalog's index, `wheel` resolves the wheel stack from the
//! wheel indexes (with `uv_access` deciding who may fetch `uv` while it does,
//! and `torchaudio` choosing the torchaudio build a ROCm 10 or newer install
//! pins), and the rest of `therock` reads the names below.
//! wheel indexes (with `uv_access` deciding who may fetch `uv` while it does),
//! `torchaudio` chooses the torchaudio build a ROCm 10 or newer install pins,
//! `next_hint` words what a failed ROCm 10 resolution suggests next, and the
//! rest of `therock` reads the names below.

mod next_hint;
mod tarball;
mod torchaudio;
mod uv_access;
Expand Down
Loading
Loading