Command reference
Every command below is available in the mtui REPL (see Invocation for how to start it and load an update). Commands not on the MCP deny-list are also exposed as mtui-mcp tools. Commands that act on a loaded template additionally accept the shared template flags -T/--template <RRID> and --all-templates (session-level commands — load_template, unload, switch, list_templates, list_refhosts, updates, config, whoami, set_log_level, help, quit (exit/EOF) — take neither, regenerate only -T); the cross-command behaviour behind them (fan-out, host-pool selection, locking) is described in Workflow concepts.
run
Runs a command on a specified host or on all enabled targets.
Usage: run [OPTIONS] [COMMAND]...
Arguments:
[COMMAND]...
Command as argv tokens (no shell); pipelines need three tokens: sh, -c, <line>
Options:
-t, --target <HOST>
Host to act on. Can be used multiple times. If omitted all hosts are used
-h, --help
Print help
update
Applies the testing update to the target hosts.
Usage: update [OPTIONS]
Options:
-t, --target <HOST>
Host to act on. Can be used multiple times. If omitted all hosts are used
--newpackage
Install new packages after update
--noprepare
Skip prepare procedure
-h, --help
Print help
install
Installs packages from the current active repositories.
Usage: install [OPTIONS] <PACKAGE>...
Arguments:
<PACKAGE>...
package to install
Options:
-t, --target <HOST>
Host to act on. Can be used multiple times. If omitted all hosts are used
-h, --help
Print help
uninstall
Removes packages from the system.
Usage: uninstall [OPTIONS] <PACKAGE>...
Arguments:
<PACKAGE>...
package to remove
Options:
-t, --target <HOST>
Host to act on. Can be used multiple times. If omitted all hosts are used
-h, --help
Print help
prepare
Installs missing packages and updates existing packages.
Usage: prepare [OPTIONS]
Options:
-t, --target <HOST>
Host to act on. Can be used multiple times. If omitted all hosts are used
-f, --force
force package installation
-i, --installed
prepare only installed packages
-u, --update
enable test update repositories
-h, --help
Print help
downgrade
Downgrades all related packages to the last released version.
Usage: downgrade [OPTIONS]
Options:
-t, --target <HOST>
Host to act on. Can be used multiple times. If omitted all hosts are used
-h, --help
Print help
reboot
Reboots reference hosts and reconnects once they are back up.
Usage: reboot [OPTIONS]
Options:
-t, --target <HOST>
Host to act on. Can be used multiple times. If omitted all hosts are used
-h, --help
Print help
set_repo
Adds or removes an issue repository to or from hosts.
Usage: set_repo [OPTIONS] <--add|--remove>
Options:
-t, --target <HOST>
Host to act on. Can be used multiple times. If omitted all hosts are used
-A, --add
Add issue repos to refhosts
-R, --remove
Remove issue repos from refhosts
-h, --help
Print help
show_update_repos
Shows the update repositories that are valid for the current update.
Usage: show_update_repos
Options:
-h, --help
Print help
add_host
Adds one or more reference hosts to the target host list.
Usage: add_host [OPTIONS]
Options:
-t, --target <HOST>
Address of the target host (FQDN). Can be repeated
-k, --keep-mode
Do not switch to the manual workflow when in automatic mode
-h, --help
Print help
remove_host
Disconnects from a host and removes it from the list.
Usage: remove_host [OPTIONS]
Options:
-t, --target <HOST>
Host to act on. Can be used multiple times. If omitted all hosts are used
-h, --help
Print help
set_host_state
Sets the state of a host.
Usage: set_host_state [OPTIONS] <state>
Arguments:
<state>
enabled | disabled
[possible values: disabled, enabled]
Options:
-t, --target <HOST>
Host to act on. Can be used multiple times. If omitted all hosts are used
-h, --help
Print help
lock
Locks hosts for exclusive usage (the operation/zypper lock).
Usage: lock [OPTIONS]
Options:
-t, --target <HOST>
Host to act on. Can be used multiple times. If omitted all hosts are used
-c, --comment <COMMENT>...
Lock comment (keeps the lock effective across sessions)
-h, --help
Print help
unlock
Unlocks hosts previously locked with lock.
Usage: unlock [OPTIONS]
Options:
-t, --target <HOST>
Host to act on. Can be used multiple times. If omitted all hosts are used
-f, --force
Force unlock - remove locks set by other users or sessions
-p, --pool
Remove the pool claim instead of the zypper/operation lock
-h, --help
Print help
switch
Switches the active template to another loaded one.
Usage: switch <RRID>
Arguments:
<RRID>
RRID of the loaded template to make active
Options:
-h, --help
Print help
unload
Unloads one loaded template, closing only its host connections.
Usage: unload [OPTIONS] <RRID>
Arguments:
<RRID>
RRID of the loaded template to unload
Options:
--discard-authored
unload even though the report document holds edits that were never committed
-h, --help
Print help
list_templates
Lists all loaded templates, marking the active one.
Usage: list_templates
Options:
-h, --help
Print help
whoami
Displays the current user name and session PID.
Usage: whoami
Options:
-h, --help
Print help
list_products
Prints the installed products on the reference hosts.
Usage: list_products [OPTIONS]
Options:
-t, --target <HOST>
Host to act on. Can be used multiple times. If omitted all hosts are used
-h, --help
Print help
reload_products
Reloads and re-parses the products on the target reference hosts.
Usage: reload_products [OPTIONS]
Options:
-t, --target <HOST>
Host to act on. Can be used multiple times. If omitted all hosts are used
-h, --help
Print help
config
Shows or sets runtime configuration values.
Usage: config <COMMAND>
Commands:
show Shows runtime configuration values (all when none named).
set Sets one runtime configuration value for the running session.
help Print this message or the help of the given subcommand(s)
Options:
-h, --help
Print help
quit
Aliases: exit, EOF
Disconnect from all hosts and exit (optionally reboot/poweroff).
Usage: quit [BOOTARG]
Arguments:
[BOOTARG]
reboot or poweroff refhosts on exit
[possible values: reboot, poweroff]
Options:
-h, --help
Print help
shell
Opens an interactive shell on a reference host.
Usage: shell [OPTIONS]
Options:
-t, --target <HOST>
Host to act on. Can be used multiple times. If omitted all hosts are used
-h, --help
Print help
checkout
Refreshes the loaded report document from teregen.
Usage: checkout [OPTIONS]
Options:
--discard-authored
refresh the report document even though it holds edits that were never committed
-h, --help
Print help
commit
Stores the report document and artifacts in teregen.
Usage: commit [OPTIONS]
Options:
--allow-stale
Commit a template that loaded with a stale Gitea hash (load_template --force-continue); refused otherwise.
-h, --help
Print help
show_diff
Shows the raw OBS source diff.
Usage: show_diff
Options:
-h, --help
Print help
analyze_diff
Analyzes the OBS source diff to assist code review.
Usage: analyze_diff
Options:
-h, --help
Print help
list_bugs
Lists related bugs and their Bugzilla/Jira URLs.
Usage: list_bugs
Options:
-h, --help
Print help
list_metadata
Lists the patchinfo metadata for the loaded test report.
Usage: list_metadata
Options:
-h, --help
Print help
list_hosts
Lists all connected hosts with their system and state.
Usage: list_hosts
Options:
-h, --help
Print help
list_timeout
Prints the current command timeout per host, in seconds.
Usage: list_timeout
Options:
-h, --help
Print help
list_update_commands
Lists the commands mtui would invoke to apply the update on the hosts.
Usage: list_update_commands
Options:
-h, --help
Print help
list_sessions
Lists the active SSH sessions connected to each reference host.
Usage: list_sessions [OPTIONS]
Options:
-t, --target <HOST>
Host to act on. Can be used multiple times. If omitted all hosts are used
-h, --help
Print help
list_locks
Lists the lock state of all connected hosts.
Usage: list_locks [OPTIONS]
Options:
-t, --target <HOST>
Host to act on. Can be used multiple times. If omitted all hosts are used
-p, --pool
list pool-claim locks instead of zypper/operation locks
-h, --help
Print help
list_history
Lists the history of mtui events recorded on the reference hosts.
Usage: list_history [OPTIONS]
Options:
-t, --target <HOST>
Host to act on. Can be used multiple times. If omitted all hosts are used
-e, --event <event>
event type to list (repeatable)
[possible values: connect, disconnect, install, update, downgrade, prepare]
-h, --help
Print help
show_log
Prints the command protocol (issued commands + output) from the hosts.
Usage: show_log [OPTIONS]
Options:
-t, --target <HOST>
Host to act on. Can be used multiple times. If omitted all hosts are used
--offset <N>
First log entry to show per host (1-based)
[default: 1]
--limit <N>
Max log entries per host (0: headers with entry totals only)
-h, --help
Print help
list_versions
Lists the available versions of packages in the enabled repositories.
Usage: list_versions [OPTIONS]
Options:
-t, --target <HOST>
Host to act on. Can be used multiple times. If omitted all hosts are used
-p, --package <PACKAGE>
package name to show versions for (repeatable)
-h, --help
Print help
list_packages
Lists packages and their installed versions on the reference hosts.
Usage: list_packages [OPTIONS]
Options:
-t, --target <HOST>
Host to act on. Can be used multiple times. If omitted all hosts are used
-p, --package <PACKAGE>
package name to list (repeatable)
-w, --wanted
print versions wanted by the testreport
-h, --help
Print help
set_timeout
Sets the command-execution timeout, in seconds, for the selected hosts.
Usage: set_timeout [OPTIONS] <timeout>
Arguments:
<timeout>
Timeout in seconds; "0" disables it
Options:
-t, --target <HOST>
Host to act on. Can be used multiple times. If omitted all hosts are used
-h, --help
Print help
put
Uploads a local file (or directory tree) to every enabled reference host.
Usage: put <filename>
Arguments:
<filename>
file (or directory) to upload to all hosts; the path is literal — shell-style globs are deliberately not expanded (put the directory, or let the invoking shell expand)
Options:
-h, --help
Print help
get
Downloads a remote file from every enabled reference host.
Usage: get <filename>
Arguments:
<filename>
file to download from the target hosts
Options:
-h, --help
Print help
checkers
Lists the build-check (checker) result runs for the loaded update.
Usage: checkers [OPTIONS]
Options:
--full-output
print every line of a non-passing check's output, untruncated, instead of a bounded first-line summary (some checks emit long diffs)
-h, --help
Print help
updates
Lists the update queue (unassigned + in-testing by default), fetched live from the TeReGen API.
Usage: updates [OPTIONS]
Options:
-G, --review-group <GROUP>
filter by review group as the bare group name, e.g. qam-sle (not the '<group>-review' login form, which classic rows lack); repeatable — groups are OR-ed (one server query per group)
-F, --field <FIELD>
select output fields by osc-qam name (e.g. -F Rating -F 'Assigned Roles'); repeatable, rendered as one block per update; names match case-insensitively, ignoring spaces/hyphens/underscores; narrow large queues with --limit
--json
print the raw TeReGen rows as a JSON array (each row emitted whole, unlike -F; honours --limit/--offset; not combinable with -F); an empty queue prints []; over-cap stdout is a JSON envelope {"rows": [...], "truncation": {...}} so stdout stays valid JSON
--status <STATUS>
filter by status (default: testing); use 'all' for every status
[default: testing]
--limit <N>
cap the number of rows after --offset (0 = all)
[default: 0]
--offset <N>
skip the first N rows (0 = from the start); with --limit, page any middle slice
[default: 0]
--assignee <USER>
filter to updates assigned to this user (any qam group)
--mine
filter to updates assigned to the current session user
--all-assignees
show every update regardless of assignee, overriding the unassigned default
-h, --help
Print help
openqa_overview
Prints an openQA / QAM Dashboard / build-checks overview for the loaded MU.
Usage: openqa_overview [OPTIONS]
Options:
--no-aggregated
Skip the Aggregated Updates section
--days <N>
How many days to scan back for aggregated builds (1-30, default 5)
[default: 5]
--aggregated-groups <GROUP>
Job groups to search in Aggregated Updates (default: core)
[possible values: core, containers, yast, security]
--url-openqa <URL>
Override openQA URL (default: config openqa_instance)
--url-dashboard-qam <URL>
Override QAM Dashboard base URL (default: derived from config)
--url-qam <URL>
Override QAM base URL (default: derived from config reports_url)
--test-pattern <REGEX>
Custom regex to extract test results from build-check logs
--export
Also author the overview onto the report document (testing.openqa.extra)
--no-fetch
(deferred) reuse cached overview; currently fetches anyway
-h, --help
Print help
openqa_jobs
Lists the individual openQA jobs for the loaded update’s incident build.
Usage: openqa_jobs [OPTIONS]
Options:
--all
keep obsoleted jobs (superseded by a retrigger)
--failed
show only genuinely failed jobs (pending/unfinished excluded)
--arch <ARCH>
only jobs for this architecture
--url-openqa <URL>
Override openQA URL (default: config openqa_instance)
--url-dashboard-qam <URL>
Override QAM Dashboard base URL (default: derived from config)
-h, --help
Print help
reload_openqa
Reloads information from the openQA instances.
Usage: reload_openqa
Options:
-h, --help
Print help
set_workflow
Sets the workflow and reloads data from openQA.
Usage: set_workflow <workflow>
Arguments:
<workflow>
desired workflow - auto, manual or kernel
[possible values: auto, manual, kernel]
Options:
-h, --help
Print help
set_log_level
Changes the current mtui log level.
Usage: set_log_level <level>
Arguments:
<level>
log level for mtui - info, warning, error or debug
[possible values: info, warning, error, debug]
Options:
-h, --help
Print help
assign
Assigns a review request to a user or group.
Usage: assign [OPTIONS]
Options:
-g, --group <GROUP>
Group to act on (not valid for the Gitea workflow)
-u, --user <USER>
User override for the Gitea workflow (Gitea only)
[default: ""]
-f, --force
Assign even if another user holds the review. OBS: never one you already hold (unassign first); Gitea: also your own, and without an open group
-h, --help
Print help
unassign
Unassigns a review request.
Usage: unassign [OPTIONS]
Options:
-g, --group <GROUP>
Group to act on (not valid for the Gitea workflow)
-u, --user <USER>
User override for the Gitea workflow (Gitea only)
[default: ""]
-h, --help
Print help
reject
Rejects a review request.
Usage: reject [OPTIONS] --reason <reason>
Options:
-g, --group <GROUP>
Group to act on (not valid for the Gitea workflow)
-u, --user <USER>
User override for the Gitea workflow (Gitea only)
[default: ""]
-r, --reason <reason>
Reason to reject the update (required)
[possible values: admin, retracted, build_problem, not_fixed, regression, false_reject, tracking_issue]
-m, --message [<message>...]
Rejection message (takes the remainder of the command)
--reviewer <NAME>
Name of the reviewer who reviewed this report; recorded on the report document and uploaded, then reject
--allow-stale
With --reviewer, upload a template that loaded with a stale Gitea hash (load_template --force-continue); refused otherwise.
-h, --help
Print help
comment
Adds a comment to a review request.
Usage: comment [OPTIONS]
Options:
-m, --message <message>...
The comment body (required)
-h, --help
Print help
approve
Approves the loaded update, dispatching to OSC or Gitea like the other backend-API commands.
Usage: approve [OPTIONS]
Options:
-g, --group <GROUP>
Group to approve (not valid for the Gitea workflow)
-u, --user <USER>
User override for the Gitea workflow (Gitea only)
[default: ""]
-r, --reviewer <NAME>
Record reviewer on the report document, then approve
--accept-head <SHA>
Approve only if the PR head is exactly SHA; this is also what lets a head that moved since the report was generated through non-interactively (Gitea only)
-h, --help
Print help
regenerate
Regenerates a test-report template via the TeReGen API (a given RRID need not be loaded first).
Usage: regenerate [OPTIONS] [RRID]
Arguments:
[RRID]
template to regenerate even if not loaded (default: the loaded template)
Options:
--force
overwrite an existing (but unedited) template
--ignore-inconsistent
regenerate despite inconsistent metadata (e.g. arch mismatch)
--no-wait
enqueue the job and return without waiting or reloading
-k, --kernel
load the standalone RRID as a kernel update (default: auto)
--discard-authored
override mtui's own guards against regenerating a document that already carries tester content (verdict, testers, issue answers, install/regression results), loaded or on the server, or holds edits that were never committed; without it the REPL asks before discarding such content and MCP refuses; teregen itself still refuses on a verdict or testers
-h, --help
Print help
request_review
Requests review of the loaded update in Slack.
Usage: request_review [OPTIONS]
Options:
-c, --channel <CHANNEL>
Channel to post to, overriding the configured one
-m, --message <TEXT>
Extra context appended to the review request
-w, --watch
After posting, watch the message for reviewer reactions until a verdict or timeout (Ctrl-C / job_cancel stops it). Over MCP, pair this with background=true so the call does not outlive the client timeout
--allow-stale
Request review of a template that loaded with a stale Gitea hash (load_template --force-continue); refused otherwise.
-h, --help
Print help
export
Exports the gathered update data onto the report document.
Usage: export [OPTIONS]
Options:
-t, --target <HOST>
Host to act on. Can be used multiple times. If omitted all hosts are used
-f, --force
force overwrite of existing install logs
--allow-unverified
write the unverified scaffold even when no selected host has recorded package versions
--allow-stale
Export a template that loaded with a stale Gitea hash (load_template --force-continue); refused otherwise.
-h, --help
Print help
list_refhosts
Lists reference hosts from refhosts.yml (offline search, no connect).
Usage: list_refhosts [OPTIONS]
Options:
--testplatform <QUERY>
match a SMELT testplatform query
-n, --name <GLOB>
hostname glob, e.g. 'whale-*' or '*.qam.suse.cz'
-a, --arch <ARCH>
arch filter (repeatable): x86_64 / aarch64 / ppc64le / s390x
-p, --product <SUBSTR>
base-product substring, e.g. sles / sled / SLE_HPC
--version <VERSION>
product version: 15-SP6 / 15.6 / 15 (SP optional)
--addon <SUBSTR>
addon-name substring (repeatable)
--pool
group by test-target slot (product+version+arch+addons)
--json
emit a JSON array of kept rows; over-cap stdout is a JSON envelope {"rows": [...], "truncation": {...}} so stdout stays valid JSON (--free windowing adds a "probe" object)
--limit <N>
cap the number of rows after --offset (0 = all)
[default: 0]
--offset <N>
skip the first N rows (0 = from the start); with --limit, page any middle slice
[default: 0]
--free
also probe live operation-lock and pool-claim state (connects to each shown host; --offset/--limit window first)
-v, --verbose
include addons in the output
-h, --help
Print help
load_template
Loads a maintenance-update template into the session and connects its reference hosts.
Usage: load_template [OPTIONS] <--auto-review-id <RequestReviewID>|--kernel-review-id <RequestReviewID>>
Options:
-a, --auto-review-id <RequestReviewID>
OBS request review id, e.g. SUSE:Maintenance:1:1
-k, --kernel-review-id <RequestReviewID>
OBS kernel/live-patch request review id, e.g. SUSE:Maintenance:1:1
--force-continue
Load a stale checked-out template as-is, instead of aborting, once TeReGen has refused to regenerate it non-interactively.
--discard-authored
re-load an already-loaded template even though its report document holds edits that were never committed
-h, --help
Print help
help
List commands, or show help for one command.
Usage: help [COMMAND]
Arguments:
[COMMAND]
command to show help for; omit to list all commands
Options:
-h, --help
Print help
edit
Edit the loaded report document, or a local file in $EDITOR.
Usage: edit [FILENAME]
Arguments:
[FILENAME]
File to edit (defaults to the report document)
Options:
-h, --help
Print help