Control Plymouth Safely from the Shell

You will use the installed plymouth client to check whether plymouthd is reachable, send boot-progress updates, display a temporary message, and understand which commands can interrupt the boot display. The examples use Ubuntu's plymouth package version 24.004.60-1ubuntu7.2. Allow about 10 minutes for the checks. Most commands are ordinary user commands, but they only do useful work when the boot daemon is running in the same boot environment.

1. Check the installed interface

Start by asking the binary for its own help. This matters because the installed command can expose more subcommands than an older local manpage describes. On this machine, --help lists commands including reload, while the installed plymouth(1) manpage does not document it.

plymouth --help
dpkg-query -W -f='${Package} ${Version}\n' plymouth

Expected version output is similar to:

plymouth 24.004.60-1ubuntu7.2

Checkpoint: if the version differs, read that machine's help before copying command options from this guide. Do not infer compatibility from the package name alone.

2. Check whether the daemon is available

Use --ping as a non-destructive probe. It checks for a running boot daemon and returns a status code rather than a useful success message.

if plymouth --ping; then
    echo "plymouthd is running"
else
    echo "plymouthd is not reachable"
fi

A successful probe prints the first message and exits with status 0. A failed probe normally prints nothing and enters the second branch. A normal desktop shell often has no Plymouth daemon to contact, so a failure here is not by itself a boot problem.

You can also find the directory used for splash plugins:

plymouth --get-splash-plugin-path

On the stated installation this prints /usr/lib/x86_64-linux-gnu/plymouth/. This option reports a path; it does not install or select a theme.

3. Send a progress update

The system-update command tells the daemon how far an update has progressed. Its --progress value is an integer percentage. This is intended for boot or update orchestration, not for making a desktop splash screen into a general progress widget.

plymouth system-update --progress=42

With no daemon available, this command exits unsuccessfully. When called in the correct boot context, it sends the update and normally produces no terminal output. Check the status explicitly when using it in a script:

plymouth system-update --progress=42
status=$?
if [ "$status" -ne 0 ]; then
    printf 'Plymouth update failed, status %s\n' "$status" >&2
fi

Keep the value within the meaningful percentage range, and do not treat a silent command as proof that a visible splash changed. The daemon and its current mode determine what the user sees.

4. Show a short status message

Use display-message with --text when a boot component needs to present a concise status. The same exact text is required to hide it later.

plymouth display-message --text="Checking the filesystem"
plymouth hide-message --text="Checking the filesystem"

Both commands are safe to run as probes, but they need an active daemon and a theme that displays messages. If the first command fails, there is no message to recover. If you are writing a service or init script, use a stable message string rather than generating a new one for each update, so that the hide command can match it.

5. Show or hide the splash deliberately

The show-splash and hide-splash commands change the display state of the running daemon.

plymouth show-splash
plymouth hide-splash

These commands do not start plymouthd, choose a theme, or repair a missing graphical console. If a test hides a splash that another boot component expects, restore the display with:

plymouth show-splash

Checkpoint: after any display test, run plymouth --ping again. A failed ping means the daemon is absent or unreachable, not that the splash is merely hidden.

6. Treat input and quit commands as privileged operations

ask-for-password and ask-question can send the user's response to a command through standard input. The password form accepts --prompt, --command, and optionally --number-of-tries. This is security-sensitive: the receiving command, its arguments, logs, and process environment must be trusted. Never paste a real password into a shell command or put one in a process argument.

The quit command tells the daemon to exit and normally removes the boot splash. It can disrupt boot presentation and may expose console output at the wrong time. Do not run it on a production machine merely to test the client. If a boot script owns the daemon lifecycle, let that script decide when to quit. The --retain-splash option changes whether the splash is explicitly hidden on exit; it does not make quitting harmless.

Likewise, deactivate, reactivate, pause-progress, and unpause-progress affect shared boot display state. Use them only from the component that owns that state. sudo is not a general fix for a failed client command: elevated privileges do not create a daemon or a graphical virtual terminal.

7. Use the option names that your binary actually supports

The compatibility options such as --show-splash, --hide-splash, --ping, and --quit sit alongside the newer command form. Prefer the command form in new scripts because it makes the action clearer:

plymouth show-splash
plymouth hide-splash
plymouth quit

The final line is deliberately shown only as a reference. It is a service-disrupting action, so do not include it in an unattended test. For a script that must support one specific installed version, validate the command with plymouth --help during deployment and fail closed if the required option is absent.

Done means

• You recorded the installed package version and checked its local help.
• You know whether plymouthd is reachable from the current shell.
• Your progress or message command checks its exit status.
• You can restore a test display with plymouth show-splash.
• You did not use quit or password forwarding as a casual diagnostic.