List X11 Clients and Their Commands with xlsclients

You will finish with a reliable way to see which X11 client applications are connected to a display, which screen they are on, and the command string each client advertises. The examples use xlsclients 1.1.5 from the Debian package x11-utils 7.7+6build2.

Allow about ten minutes. You need an X server and permission to connect to it. This is a read-only inspection workflow: it does not close windows, stop applications or change X configuration. It does not require sudo.

1. Confirm the installed command

Check the executable and its version as an ordinary user:

$ command -v xlsclients
/usr/bin/xlsclients
$ xlsclients -version
xlsclients 1.1.5
$ dpkg-query -W -f='${Package} ${Version}\n' x11-utils
x11-utils 7.7+6build2

The version matters because option names and output details belong to the installed implementation. This guide describes the 1.1.5 command documented by its local manpage. The -version option prints the version and exits; it does not contact an X server.

2. Check the display connection

Without -display, xlsclients uses the DISPLAY environment variable. Inspect it before running the query:

$ printf 'DISPLAY=%s\n' "${DISPLAY-}"
DISPLAY=:0

The value in your shell may be different, such as :1 or hostname:0. The output above is an example, not a value to copy blindly. An empty value means that the command has no default X server to contact.

Run the basic query:

$ xlsclients
workstation  /usr/bin/example-window-manager
workstation  /usr/bin/example-terminal

Each line is host-specific. The default format shows a machine name and command string for clients on the default screen. Do not treat the order as a startup sequence, and do not assume that the command string is a complete process command line.

3. Include clients on every screen

By default, the command lists clients on the default screen only. Add -a when the X display has multiple screens and you need the complete display-wide snapshot:

$ xlsclients -a
workstation  /usr/bin/example-window-manager
workstation  /usr/bin/example-terminal
workstation  /usr/bin/example-monitor

The option means all screens, not all displays. To query another X server, supply its display name explicitly with -display:

$ xlsclients -display DISPLAY_NAME
HOSTNAME  COMMAND_STRING

Replace DISPLAY_NAME with a real value, for example :0 or remote-host:0. A remote display also needs network access and X authorisation. That is a security boundary: do not weaken access control merely to make an inventory command work.

4. Ask for window and class details

Use -l for long format when the short list is not enough. It adds each client's window name, icon name and class hints to the machine name and command string:

$ xlsclients -l
Command: /usr/bin/example-terminal
  Machine: workstation
  Name: Terminal
  Icon Name: Terminal
  Class: ExampleTerminal
  Class: ExampleTerminal

Exact spacing, names and values depend on the client. Some applications do not provide every hint, so a blank or less useful field is not proof that the client is broken. Use long format for identification, not as a process audit.

The class hints are X window metadata. They can help match a window to a desktop rule, but they are not a trustworthy security identity. A client can advertise values that are misleading or shared by other applications.

5. Limit very long command strings

The default maximum command-string length is 10,000 characters. Use -m followed by a maximum character count when you are collecting output for a narrow terminal or a script:

$ xlsclients -m 200
workstation  /usr/bin/example-terminal --shortened-command-string...

The argument is a number, not a shell pattern. Choose a value suitable for your output consumer. A small limit can make different clients appear similar, so retain the untrimmed output when exact identification matters.

For a simple snapshot file, redirect standard output as an ordinary user:

$ xlsclients -a -l -m 1000 > /tmp/xlsclients.txt
$ sed -n '1,24p' /tmp/xlsclients.txt

This writes only the file named by the command. The command does not modify the X session. To remove this temporary snapshot later, first check that the path is exactly the file you intend to remove, then use rm -- /tmp/xlsclients.txt; that deletion is irreversible.

6. Turn the result into a cautious check

For a script, check the command's exit status rather than searching for a particular client name. A successful query can still return no lines if no clients are visible on the selected screen:

if xlsclients -a -m 1000 > /tmp/xlsclients.txt; then
    printf '%s\n' 'X client query completed'
else
    status=$?
    printf 'xlsclients failed with status %s\n' "$status" >&2
    exit "$status"
fi

This checks that the query completed, not that a graphical application is healthy. Keep the output separate from the status message so another program can parse the snapshot without also parsing diagnostic text.

Do not use xlsclients to decide whether a process exists, whether it owns a particular file, or whether it is safe to terminate. It reports X client metadata obtained from the server. A client may have multiple windows, no ordinary top-level window, or a command string that does not reflect its current process arguments.

Common traps

• Empty DISPLAY: set it only to a display you are authorised to inspect. A guessed value is not a diagnosis.
• Using sudo first: privilege does not grant the caller the right X cookie. Try the command in the desktop user's session.
• Missing clients: add -a if the display has multiple screens, then compare with the client's own window state.
• Truncated commands: raise -m when identification depends on arguments, or use a process inspection tool for process arguments.
• Wayland confusion: xlsclients queries an X server. A Wayland-native application may not appear unless it is also represented through an X compatibility server.