.TH RISO 1 "2026-08-22" "riso 0.6.3" "User Commands"
.SH NAME
riso \- modular ricing framework
.SH SYNOPSIS
.B riso
.I command
.RI [ options ]
.SH DESCRIPTION
.B riso
renders a theme into the configuration files a desktop reads. A theme is data:
a palette, optionally some wallpapers, and any file its author chose to write
by hand. Everything else is generated from templates, so adding support for an
application does not make existing themes incomplete.
.PP
Precedence runs from strongest to weakest: a file the theme ships, then each
template directory in turn, then the templates built into
.BR riso .
A theme therefore cannot be incomplete, and a desktop that ships its own
templates keeps its own look.
.SH COMMANDS
Commands are grouped by component, and every one has a short alias:
.B riso t s
is
.BR "riso theme set" ,
and
.B backgrounds
answers to
.BR bg " and " b .
.TP
.BI "theme set " "[name] [--gui|--tui]"
Render a theme, swap it in, and tell the running desktop. The name is folded
the way a menu spells it, so
.B "Tokyo Night"
and
.B tokyo-night
are the same theme. Without a name,
.B \-\-gui
opens a full-screen strip of previews (runs on
.BR quickshell ,
which must be on PATH) and
.B \-\-tui
draws the same picker in the terminal, with image previews where the
terminal speaks kitty, sixel or iTerm2 graphics and unicode half-blocks
anywhere else. In both, typing filters, arrows move, Enter applies.
.TP
.B "theme get"
Print the theme in use.
.TP
.B "theme list"
List every theme found, marking those a package manager owns as read-only.
With
.B \-\-gui
or
.B \-\-tui
the same pickers open read-only, for looking at previews without applying.
.TP
.BI "theme install " "[source] [--gui|--tui]"
Install from the catalog by name, or from any git URL. The theme is validated
before it is kept. Without a source,
.B \-\-gui
and
.B \-\-tui
browse the catalog with previews, and Enter installs the pick through the
same gate.
.TP
.BI "theme update " [name]
Bring installed themes to where they came from: the revision the catalog
pins for themes it carries, the origin's tip for the rest. What arrives
passes the same safety gate an install does; an update that fails it is
rolled back to the revision that was trusted. Each theme is narrated as
it is checked;
.B \-q
prints nothing at all and leaves the verdict to the exit status, which
is nonzero when any update failed or was refused.
.TP
.BI "theme validate " path
Report anything that would make a theme unsafe to install.
.TP
.BI "theme remove " name
Remove a theme
.B riso
installed. Themes owned by a package manager are refused.
.TP
.BI "backgrounds set " "[image] [--gui|--tui]"
Point the current-background link at an image and tell the desktop that
draws its own wallpaper; a bare compositor is not told, because the daemon
that paints for it is not
.BR riso 's
to guess.
.B \-\-gui
and
.B \-\-tui
open the same pickers over the current theme's wallpapers. The image in use
is recorded against the theme showing it, so returning to a theme returns
to its image.
.TP
.B "backgrounds next"
Advance to the current theme's next wallpaper. A theme applied for the first
time settles on its first image; this is the command that moves through the
rest, since applying is also what a shell switch does to retint.
.TP
.BI "backgrounds mode " [mode]
Set or print how the wallpaper is scaled
.RB ( fill ", " fit ", " center ", " stretch ", " tile ).
.TP
.B "backgrounds get"
Print the wallpaper in use and its mode.
.TP
.B "plugin list|install|remove"
Manage plugins, which teach
.B riso
to theme applications it does not know about.
.TP
.B "config [list|get|set|apps|check [name]|wire [app...]]"
Read and change the few options kept in
.IR ~/.config/riso/config.toml :
.B output
(the format used when
.B \-o
is not given) and
.B omarchy\-themes
(set it to
.B false
to keep Omarchy's theme directories out of the search path). Everything
situational stays a flag.
.B config check
inspects the system instead of the file: the tools riso calls, the
desktop it recognized, the themes and catalog it can reach, and for
every themable application found installed, whether its config actually
reads the rendered fragment, printing the exact include line when it
does not. With
.B \-\-desktop
the check evaluates the system as that desktop instead of detecting
one. Every line answers alone by its name, tool, section or
application alike, applications even when not installed; a named
check's exit status reflects that check, the full run fails only on a
missing required tool.
.B config wire
adds the missing include lines itself, cautiously: the plan is shown
first, each file asks its own confirmation (or
.B \-\-yes
for scripts), every touched file is captured so
.B riso restore
puts it back byte for byte, and riso keeps its hands off symlinked
configs and files where an automatic edit could clash, showing the
line to place by hand instead. On a declaratively managed system
(NixOS is detected; RISO_DECLARATIVE=1 declares any other) nothing is
ever edited: every line is only shown, to carry into the system
configuration. A lua Hyprland config gets a dofile
line for the hyprland.lua fragment riso renders from the palette.
Noctalia is wired by a symlink instead of a line: its palettes
directory gets riso.json pointing at the fragment, and every apply
tells a running Noctalia to re-read it and to take the wallpaper.
.B config apps
lists everything the current configuration can theme and where each
piece comes from, resolved the way a render resolves it: the applied
theme's own files, then each
.B \-\-templates
directory in order, then the templates built into riso, plus plugins.
.TP
.B "dev palette|render"
Tools for theme authors: print a theme's palette as resolved key and value
pairs, or render a theme into a directory without applying it.
.TP
.B restore
Put back every file
.B riso
wrote over.
.TP
.B uninstall
Put everything back and forget the generated theme. Requires
.BR \-\-yes .
.SH OPTIONS
.TP
.BI \-o ", " \-\-output " FORMAT"
How results are printed:
.BR human ", " json ", or " yaml .
Available on every command, so scripts never parse prose. When not given, the
.B output
option in
.I config.toml
decides, and
.B human
is the default.
.TP
.BI \-\-themes " DIR"
Theme directory. Repeat for more; a later one overlays an earlier one. When
not given,
.B riso
searches its default path: see
.BR THEMES .
.TP
.BI \-\-templates " DIR"
Template directory. Repeat for more; an earlier one takes precedence.
.TP
.BI \-\-plugins " DIR"
Plugin directory. Repeat for more; a later one overrides an earlier one.
.TP
.BI \-\-state " DIR"
Where the generated theme lives. Defaults to
.I $XDG_STATE_HOME/riso
or
.IR ~/.local/state/riso .
.TP
.BI \-\-desktop " NAME"
One of
.BR omarchy ", " hyprland ", " sway ", " niri ", " none .
Detected from the session when not given.
.TP
.B \-\-no\-reload
Write the files without telling the desktop.
.TP
.B \-\-no\-builtin
Ignore the templates compiled into
.BR riso .
.SH THEMES
Without
.BR \-\-themes ,
themes are looked up on a search path, weakest first:
.IR /usr/share/riso/themes ,
.IR /etc/riso/themes ,
Omarchy's theme directories when that desktop is present
(unless the
.B omarchy\-themes
option says otherwise),
the directories named by
.BR RISO_THEMES ,
.IR $XDG_DATA_HOME/riso/themes ,
and
.IR ~/.config/riso/themes .
A theme found later shadows one of the same name found earlier, so a user's
copy always wins over what a package shipped.
.PP
A theme that carries no
.I colors.toml
but does carry an
.I alacritty.toml
derives its palette from the terminal colors, exactly the way Omarchy does.
.PP
When the whole path turns up nothing, the theme compiled into
.B riso
is written to the user directory as an ordinary editable theme, so applying a
theme never depends on having installed one first.
.SH ENVIRONMENT
.TP
.B RISO_THEMES
Colon-separated list of extra theme directories. This is how a distribution or
a session points
.B riso
at the themes it ships.
.SH FILES
.TP
.I ~/.config/riso/config.toml
The options
.B riso config
manages.
.TP
.I ~/.config/riso/themes
Themes installed by the user.
.TP
.I ~/.config/riso/plugins
Plugins installed by the user.
.TP
.I ~/.local/state/riso/current/theme
The generated theme now in use.
.TP
.I ~/.local/state/riso/ownership
What
.B riso
wrote over, and copies of what was there before.
.SH EXIT STATUS
.B riso
exits 0 on success and 1 on failure. A theme that is missing, unsafe, or fails
to render leaves the previous theme in place.
.SH SEE ALSO
.BR git (1),
.BR curl (1)
.SH BUGS
Report at https://github.com/eldios/riso/issues