kscreen-doctor

Show display output information

$ kscreen-doctor [[-o|--outputs]]

$ kscreen-doctor [output.1.rotation.right]

$ kscreen-doctor [output.HDMI-2.scale.2]

kscreen-doctor [GLOBAL_OPTIONS] COMMAND [COMMAND_OPTIONS/ARGUMENTS]

--help, -h
    Displays a help message with available commands and options.

--version
    Shows the version information for kscreen-doctor.

--json
    Formats the output of commands like outputs into JSON for programmatic parsing.

--brief
    Provides a concise, less verbose output for commands, often used with outputs.

outputs
    Lists all currently detected display outputs with their detailed status and available modes.

list
    An alias for the outputs command.

apply <file>
    Applies a screen configuration previously saved to the specified file.

save <file>
    Saves the current display configuration to the specified file.

output <output-name>
(enable | disable | mode <mode-name> | auto-mode | position <x>,<y> | scale <value> | rotation <angle> | primary | not-primary | clone <source-output> | head-on-display-orientation)
    Configures a specific display output by its name. Options include enabling/disabling it, setting its display mode, position, scaling, rotation, designating it as primary, cloning another output's content, or adjusting its head-on-display orientation.

set-mode <output-name> <mode-name>
    Shorthand to set the display mode (resolution and refresh rate) for a specific output.

set-position <output-name> <x>,<y>
    Shorthand to set the top-left corner position for a specific output.

set-scale <output-name> <value>
    Shorthand to set the UI scaling factor for a specific output (e.g., 1.25, 1.5).

set-rotation <output-name> <angle>
    Shorthand to set the rotation angle (0, 90, 180, 270) for a specific output.

toggle <output-name>
    Toggles the enabled/disabled state of the specified display output.

clone <source-output> <target-output>
    Clones the display content from the source-output to the target-output.

rescan
    Forces KScreen to rescan for connected displays, useful when displays are hot-plugged.

kscreen-doctor is a command-line utility designed for managing and diagnosing display configurations within the KDE Plasma desktop environment. It offers a powerful interface to query current display states, list available outputs and modes, and apply changes such as enabling or disabling displays, setting resolutions, positions, scaling, and rotations. Unlike lower-level tools like xrandr, kscreen-doctor interacts directly with the KScreen 2 D-Bus interface, making it the preferred and most integrated tool for programmatic display management in Plasma. It can be used for scripting display setups, troubleshooting multi-monitor arrangements, or quickly adjusting screen settings without relying on the graphical System Settings module. It also supports outputting information in JSON format for easier parsing by other tools.

kscreen-doctor is designed specifically for the KDE Plasma desktop environment and relies on the KScreen D-Bus interface. It may not function correctly or at all in other desktop environments (e.g., GNOME, XFCE) or when a display manager other than Plasma's KScreen is active. Changes made via kscreen-doctor are generally applied immediately but may not persist across reboots or user logins unless explicitly saved and loaded (e.g., via Plasma startup scripts or by saving the configuration). Always ensure you have a way to revert changes if the display becomes unusable, especially when experimenting with positions or rotations.

kscreen-doctor communicates with the running KScreen D-Bus service, which is solely responsible for managing all display configurations within the KDE Plasma session. This positions it as a high-level tool that interacts with Plasma's abstract display state rather than directly with the X server or Wayland compositor, ensuring seamless integration with the desktop environment.

While kscreen-doctor can save and apply configurations using the --save and --apply commands, these files are typically in a JSON format understood specifically by KScreen. This means they might not be directly compatible or interchangeable with configuration files used by other display management tools or desktop environments.

kscreen-doctor emerged as part of the KScreen 2 project, which significantly overhauled KDE Plasma's display management system. It provides a modern command-line interface to interact with the D-Bus services of KScreen 2, offering a more robust and Plasma-integrated alternative to older display management tools like xrandr for KDE users. Its development paralleled the evolution of Plasma's display configuration capabilities, aiming to provide comprehensive CLI control over the features available in the graphical System Settings display module.

xrandr(1), kcm_display(1)