idle.1

.TH IDLESCREEN 1 "July 2026" "idlescreen" "IdleScreen CLI"
.SH NAME
idlescreen \- control the IdleScreen daemon
.SH SYNOPSIS
.B idlescreen
[\fICOMMAND\fR] [\fIARGS\fR...]
.SH DESCRIPTION
.B idlescreen
is the CLI for the IdleScreen user daemon
.BR idle-daemon (1).
It controls idle presentation, previews plugins, and runs diagnostics over D-Bus.
.br
Note: this package does
.B not
install
.BR /usr/bin/idle ,
which is reserved for Fedora's
.B python3-idle
(Python IDE).
.SH COMMANDS
.TP
.B tui
(\fBui\fR) Launch the live TUI dashboard (
.BR idle-tui ).
.TP
.B status
[\fB-j\fR|\fB--json\fR] (\fBst\fR)
Show daemon state.
.TP
.B on\fR, \fBenable
Enable idle screensaver.
.TP
.B off\fR, \fBdisable
Disable idle screensaver.
.TP
.BI timeout " [<minutes>]"
Set idle timeout (1–240 minutes); bare shows current.
.TP
.B list\fR (\fBls\fR), \fBsaver list
[\fB-j\fR|\fB--json\fR] List installed savers.
.TP
.B saver
[\fBset\fR \fI<name|random>\fR|\fBlist\fR]
Show or change the active saver; bare shows current.
.TP
.BI preview " <saver> [\fB-t\fR \fI<seconds>\fR]"
Preview a saver now; \fB-t\fR auto-stops.
.TP
.B stop
(\fBx\fR) Stop preview or idle presentation.
.TP
.B inhibitors
[\fB-j\fR|\fB--json\fR] (\fBinhib\fR) List active inhibitors.
.TP
.BI inhibit " [\fB-r\fR \fI<reason>\fR] \fI<cmd>\fR [\fIargs\fR...]"
(\fBhold\fR) Hold an idle inhibitor while \fIcmd\fR runs, then release it.
.TP
.BI fps-overlay " on|off|status"
FPS overlay control.
.TP
.BI render-scale " <0.25-1.0>|default|status"
Simulation render scale.
.TP
.B restart
(\fBrs\fR) Restart the idle-daemon user service.
.TP
.B logs
[\fB-f\fR|\fB--follow\fR] [\fB-n\fR \fI<lines>\fR] (\fBlog\fR)
Show daemon logs (journalctl); \fB-f\fR follows.
.TP
.B doctor
[\fB--fix\fR] [\fB--json\fR]
System diagnostics. \fB--fix\fR reloads/enables the user unit.
.TP
.B config
\fBlist\fR|\fBget\fR \fI<key>\fR|\fBset\fR \fI<key> <val>\fR|\fBpath\fR|\fBedit\fR|\fBreset\fR
Read/write daemon config keys (live state); \fBpath\fR/\fBedit\fR/\fBreset\fR
operate on the file. \fBreset\fR restores defaults (asks unless \fB--yes\fR).
All read ops accept \fB-j\fR|\fB--json\fR.
.TP
.B completion
\fI<bash|zsh|fish|nushell|powershell|elvish>\fR
Print a generated shell completion script.
.TP
.B clean
[\fB-n\fR|\fB--dry-run\fR] (\fBcl\fR)
Remove stale run state and log caches; \fB-n\fR previews only.
.TP
.B bug-report
(\fBbug\fR) Print a sanitized diagnostics bundle.
.TP
.B self-update
[\fB-c\fR|\fB--check\fR] (\fBupdate\fR, \fBupgrade\fR)
Check and apply package updates (dnf/apt); \fB-c\fR reports only.
Runs a pre-flight check and skips the sudo prompt entirely when every
IdleScreen package is already current; when updates exist it lists only
the pending packages and verifies each one reached its candidate version.
.TP
.B interactive
Simple console menu.
.TP
.B version\fR (\fBv\fR), \fBabout\fR (\fBinfo\fR)
Version and project info; \fB-l\fR extended, \fB-j\fR JSON.
.SH OPTIONS
.TP
.B -h\fR, \fB--help
Show help for the CLI or a subcommand.
.TP
.B -V\fR, \fB--version
Print the CLI version.
.TP
.B -q\fR, \fB--quiet
Suppress confirmations and other non-essential output.
.SH "EXIT STATUS"
.B 0
success;
.B 1
operational failure (daemon down, package manager error);
.B 2
usage error (unknown command, invalid flag, bad argument).
.SH FILES
.TP
.I ~/.config/idle/config.yaml
Daemon configuration.
.SH SEE ALSO
.BR idle-daemon (1),
.BR idle-tui (1)
.SH AUTHOR
IdleScreen <jerydleuck@gmail.com>
.SH WWW
https://idlescreen.github.io