KDE Theme Colors - User Guide¶

KDE Theme Colors is a command-line tool that extracts color schemes from KDE Plasma desktop themes. This guide explains how to use the CLI, including all available commands, options, and output formats.

Installation¶

pip install kde-colors

Basic Usage¶

The basic syntax for the KDE Theme Colors CLI is:

kde-colors [GLOBAL OPTIONS] COMMAND [COMMAND OPTIONS]

Global Options¶

These options can be used with any command:

Option	Description
`-j`, `--json`	Output as JSON instead of text format.
`-o`, `--output PATH`	Write output to the specified file instead of stdout.
`-v`, `--verbose`	Increase verbosity level. Can be specified multiple times for more detail (e.g., `-vv` for debug level).
`--version`	Show the version number and exit.
`-h`, `--help`	Show help message and exit.

Commands¶

List Command¶

Lists all available KDE themes installed on the system.

kde-colors list [OPTIONS]

List Options¶

The List command uses the global options described above.

List Example¶

# List all themes in text format (default)
kde-colors list

# List all themes in JSON format
kde-colors list --json

# Save the list of themes to a file in JSON format
kde-colors list --json --output themes.json

List Output¶

Text Format:

Available desktop themes (current theme marked with *):
  oxygen
* breeze-dark
  kubuntu
  default
  breeze-light

JSON Format:

{
  "current_theme": "Breeze",
  "themes": [
    {
      "name": "Breeze",
      "display_name": "Breeze",
      "description": "Default KDE theme"
    },
    {
      "name": "BreezeDark",
      "display_name": "Breeze Dark",
      "description": "Dark version of Breeze"
    },
    ...
  ]
}

Paths Command¶

Shows the system paths where KDE searches for theme files.

kde-colors paths [OPTIONS]

Paths Options¶

The Paths command uses the global options described above.

Paths Example¶

# View theme paths in text format (default)
kde-colors paths

# View theme paths in JSON format
kde-colors paths --json

# Save theme paths to a file in JSON format
kde-colors paths --json --output paths.json

Paths Output¶

Text Format:

KDE Theme Search Paths:
- System-wide: /usr/share/plasma/desktoptheme
- User-specific: /home/username/.local/share/plasma/desktoptheme
...

JSON Format:

{
  "theme_paths": [
    {
      "type": "system",
      "path": "/usr/share/plasma/desktoptheme"
    },
    {
      "type": "user",
      "path": "/home/username/.local/share/plasma/desktoptheme"
    },
    ...
  ]
}

Theme Command¶

Extracts colors from the specified KDE theme. If no theme name is provided, information about the current theme is displayed.

kde-colors theme [THEME_NAME] [OPTIONS]

Theme Arguments¶

Argument	Description
`THEME_NAME`	(Optional) Name of the theme to extract colors from. If not specified, the current theme will be used.

Theme Options¶

The Theme command uses the global options described above.

Theme Example¶

# Extract colors from the Breeze theme in text format (default)
kde-colors theme Breeze

# Extract colors from the Breeze theme in JSON format
kde-colors theme Breeze --json

# Extract colors from the Breeze Dark theme and save as JSON
kde-colors theme "Breeze Dark" --json --output breeze-dark-colors.json

# Extract colors from the current theme
kde-colors theme

Theme Output¶

Text Format:

Theme: Breeze (Breeze)
Author: KDE Visual Design Group
Version: 1.0
Description: KDE's default theme
Path: /usr/share/plasma/desktoptheme/Breeze

Colors:
  [Colors:View]
    BackgroundNormal: #fcfcfc
    BackgroundAlternate: #eff0f1
    ForegroundNormal: #232629
    ForegroundInactive: #7f8c8d
    ...

  [Colors:Window]
    BackgroundNormal: #eff0f1
    BackgroundAlternate: #e3e5e7
    ...

JSON Format:

{
  "theme": {
    "name": "Breeze",
    "display_name": "Breeze",
    "author": "KDE Visual Design Group",
    "version": "1.0",
    "description": "KDE's default theme",
    "path": "/usr/share/plasma/desktoptheme/Breeze"
  },
  "colors": {
    "Colors:View": {
      "BackgroundNormal": "#fcfcfc",
      "BackgroundAlternate": "#eff0f1",
      "ForegroundNormal": "#232629",
      "ForegroundInactive": "#7f8c8d"
    },
    "Colors:Window": {
      "BackgroundNormal": "#eff0f1",
      "BackgroundAlternate": "#e3e5e7"
    },
    ...
  }
}

Exit Codes¶

The CLI uses the following exit codes to indicate the result of the operation:

Code	Description
0	Success
1	General error
2	Invalid arguments
3	Theme not found
4	I/O error

Examples¶

Extract Colors from Current Theme¶

kde-colors theme current

Find the Current Theme¶

kde-colors list --format text | grep "(current)"

Extract Colors and Format with jq¶

kde-colors theme Breeze | jq '.colors."Colors:View"'

List All Dark Themes¶

kde-colors list | jq '.themes[] | select(.name | contains("Dark"))'

Troubleshooting¶

Common Issues¶

Theme not found
Check if the theme name is correct (use kde-colors list to verify)
Theme names are case-sensitive
Use quotes for theme names with spaces: kde-colors theme "Breeze Dark"
Permission errors
Ensure you have read access to KDE theme directories
For writing output files, ensure you have write permission to the target directory
Invalid output format
Only text and json formats are supported
Check for typos in the format option

If you encounter any issues, increase verbosity with -v or -vv to get more information about the error.