Set Terminal Attributes Safely with setterm

You will finish with a small setterm workflow for changing terminal presentation and console behaviour, checking what the command emitted, and restoring the normal rendering defaults. The examples use /usr/bin/setterm from util-linux 2.39.3, matching the installed setterm(1) manual on this machine.

Allow about ten minutes. You need a shell and a terminal that understands the capabilities you ask for. Most examples are ordinary user commands. They write control sequences to standard output; they do not edit a configuration file. Virtual-console-only options need a Linux virtual console, not an arbitrary terminal emulator.

1. Check which setterm you are running

There can be more than one copy on a development machine, so check the path and version before relying on behaviour:

$ command -v setterm
/home/linuxbrew/.linuxbrew/bin/setterm
$ /usr/bin/setterm --version
setterm from util-linux 2.39.3

The first result is host-specific. If it is not the binary you intend to use, call /usr/bin/setterm explicitly in scripts or correct your PATH. The local manual documents util-linux 2.39.3 and says that long options with two hyphens are supported since version 2.25. It also recommends the historical single-hyphen form in scripts for compatibility, although the examples below use the clearer double-hyphen form interactively.

Checkpoint: run /usr/bin/setterm --help. The output should identify the command as setting terminal attributes and list options such as --foreground, --cursor, --clear and --default.

2. Change a reversible display attribute

Set the foreground colour to green for the current terminal:

$ /usr/bin/setterm --foreground=green
$ printf '%s\n' 'This text should be green'

The first command normally prints a short terminal control sequence rather than a report. A terminal emulator interprets it and the following text appears in the selected colour. If you redirect it to a file, you will capture those bytes instead of changing the terminal display:

$ /usr/bin/setterm --foreground=green > /tmp/setterm-colour.seq
$ wc -c /tmp/setterm-colour.seq
5 /tmp/setterm-colour.seq

The byte count is an observation from this installed environment, not a portable output contract. Terminfo and the terminal type determine the sequence. Do not print a captured sequence into a log or paste it into an untrusted terminal without understanding that it is control data.

Restore the normal rendering settings before leaving a shared session:

$ /usr/bin/setterm --default

This is the undo step for the colour and rendering examples. If a terminal still looks wrong, /usr/bin/setterm --reset emits the terminal reset string, which is a stronger reset and may clear more state.

3. Use cursor, wrapping and clearing deliberately

These options alter the current terminal session, so keep them visible in a script and provide a recovery command beside them:

$ /usr/bin/setterm --cursor=off
$ /usr/bin/setterm --linewrap=off
$ /usr/bin/setterm --cursor=on
$ /usr/bin/setterm --linewrap=on

--cursor controls whether the cursor is displayed. --linewrap controls whether a full line continues on a new line. The final two commands restore the usual enabled state. Boolean options accept on or off; the manual says the default for boolean options is on.

Be careful with clearing: --clear without an argument, or with --clear=all, clears the whole screen and homes the cursor. --clear=rest clears from the cursor to the end. Neither operation deletes files, but it can erase useful terminal output. Treat it as a display-disrupting action, not as a harmless status command.

4. Change console-only settings only on a virtual console

Options such as --repeat, --msg, --msglevel, --blank, --tabs and --regtabs target Linux virtual-console behaviour. The manual marks them as virtual consoles only. A terminal emulator usually cannot provide those capabilities, and setterm may ignore an unsupported option or report that the terminal does not support it.

For example, this is a read-like tab query with no requested positions:

$ /usr/bin/setterm --tabs
setterm: terminal dumb does not support --tabs

The exact diagnostic depends on TERM and the terminal. On a real virtual console, --tabs without arguments shows current tab settings; --regtabs=8 clears the tab stops and creates a regular eight-column pattern. Do not use these options in a service or remote shell expecting them to configure every terminal.

Likewise, --blank=10 changes the inactivity interval in minutes, while --blank=0 disables automatic blanking. --blank=force keeps a virtual console blank after a key press and --blank=poke unblanks it. These affect the active console and can interrupt someone else working there, so obtain agreement before changing them. The corresponding undo for a ten-minute setting is --blank=0, but verify the host's desired policy first.

5. Separate terminal type from privilege

setterm consults terminfo where possible. If TERM is wrong, the generated sequence can be wrong too. Inspect it before forcing an override:

$ printf 'TERM=%s\n' "$TERM"
TERM=xterm-256color
$ /usr/bin/setterm --term=xterm-256color --foreground=cyan

--term overrides the environment for this invocation; it does not change the shell or system configuration. Use the actual terminal type rather than copying this placeholder value.

Do not reach for sudo for ordinary colour, cursor or reset operations. Elevated privileges are not a general fix for an unsupported terminal. Virtual-console operations may require access to the active console, but first confirm that you are on the intended console and understand the effect. The command writes terminal control data; it does not grant permission to change another user's terminal.

6. Use scripts without confusing output and status

setterm's useful result is often the escape sequence, not human-readable output. Check its exit status and keep diagnostic output separate:

if /usr/bin/setterm --foreground=default > /dev/tty; then
    printf '%s\n' 'terminal rendering restored'
else
    status=$?
    printf 'setterm failed with status %s\n' "$status" >&2
    exit "$status"
fi

Replace /dev/tty only when the process has a specific controlling terminal. A service without a terminal should not pretend that it changed a user's display. For a script that must preserve an existing terminal state, avoid broad resets and document exactly which attributes it changes; setterm does not provide a general transaction or automatic rollback.