Skip to main content
When precompiled configuration is disabled (the default), Draconis++ reads configuration from a config.toml file at runtime. This provides maximum flexibility for customization without recompiling.
Runtime configuration is only available when built with -Dprecompiled_config=false (the default).

​
Configuration file location

Draconis++ searches for config.toml in the following locations (in order):
  1. $XDG_CONFIG_HOME/draconis++/config.toml
  2. $HOME/.config/draconis++/config.toml
  3. $HOME/.draconis++/config.toml
  4. ./config.toml (current directory)
If no configuration file is found, Draconis++ automatically creates a default one at the first location.
The recommended location is ~/.config/draconis++/config.toml on Unix-like systems and %LOCALAPPDATA%\draconis++\config.toml on Windows.

​
Configuration structure

The TOML configuration file is divided into several sections:
config.toml
[general]
name = "User"
language = "en"

[logo]
path = "/path/to/logo.png"
protocol = "kitty"
width = 200
height = 0

[packages]
enabled = ["cargo", "pacman", "nix"]

[plugins]
enabled = true
auto_load = ["weather"]

[[ui.layout]]
name = "system"

  [[ui.layout.rows]]
  key = "host"

  [[ui.layout.rows]]
  key = "os"
  label = "Operating System"
  icon = "  "

​
General settings

[general]
name = "User"      # Display name for greeting (default: system username)
language = "en"    # UI language: en, es, fr, de (default: en)
FieldTypeDefaultDescription
namestringsystem usernameDisplay name shown in the greeting
languagestring"en"Language code for localization (en, es, fr, de)
If name is not specified, Draconis++ uses the system username from getpwuid() on Unix or GetUserNameA() on Windows.

​
Logo configuration

Configure inline image rendering for supported terminal protocols: 
[logo]
path = "/home/user/.config/draconis++/logo.png"  # Path to image file
protocol = "kitty"                               # Protocol: kitty, kitty-direct, iterm2
width = 200                                      # Width in pixels (0 = terminal default)
height = 0                                       # Height in pixels (0 = auto from aspect ratio)
Supported protocols:
  • kitty - Kitty graphics protocol (default)
  • kitty-direct - Kitty direct rendering
  • iterm2 - iTerm2 inline images
[logo]
path = "~/.config/draconis++/logo.png"
protocol = "kitty"
width = 200

​
Package managers

Only available when built with -Dpackagecount=enabled.
Specify which package managers to display: 
[packages]
enabled = ["cargo", "pacman", "nix"]
Available package managers by platform:
  • apk - Alpine Package Keeper
  • cargo - Rust package manager
  • dpkg - Debian packages
  • moss - Serpent OS
  • nix - Nix package manager
  • pacman - Arch Linux
  • rpm - Red Hat packages
  • xbps - Void Linux
  • cargo - Rust package manager
  • homebrew - Homebrew
  • macports - MacPorts
  • nix - Nix package manager
  • cargo - Rust package manager
  • chocolatey - Chocolatey
  • scoop - Scoop
  • winget - Windows Package Manager
  • cargo - Rust package manager (all BSD)
  • nix - Nix package manager (all BSD)
  • pkgng - FreeBSD, DragonFly BSD
  • pkgsrc - NetBSD
  • haikupkg - Haiku package manager
Unknown package manager names are ignored with a warning logged to the console.

​
Plugin configuration

Only available when built with -Dplugins=enabled.
[plugins]
enabled = true                  # Enable/disable plugin system
auto_load = ["weather"]         # Plugins to load automatically at startup
FieldTypeDefaultDescription
enabledbooleantrueEnable or disable the entire plugin system
auto_loadarray of strings[]List of plugin names to load at startup
Plugin-specific configuration: Plugins can have their own TOML sections. For example, the weather plugin: 
[plugins]
enabled = true
auto_load = ["weather"]

[weather]
provider = "openmeteo"
units = "metric"
lat = 40.7128
lon = -74.0060
Plugins are loaded from $PREFIX/lib/draconis++/plugins/ by default. The plugin system uses dynamic loading (.so, .dylib, .dll).

​
UI layout

Customize the information displayed and its organization: 
[[ui.layout]]
name = "system"  # Group name (for organization only)

  [[ui.layout.rows]]
  key = "host"              # Required: data key
  label = "Hostname"        # Optional: custom label
  icon = "  "              # Optional: custom icon
  color = "cyan"            # Optional: value color
  auto_wrap = false         # Optional: enable word wrapping

  [[ui.layout.rows]]
  key = "os"

[[ui.layout]]
name = "hardware"

  [[ui.layout.rows]]
  key = "cpu"

  [[ui.layout.rows]]
  key = "ram"
  color = "yellow"

​
Built-in data keys

KeyDescription
dateCurrent date and time
hostHostname and model
osOperating system name
kernelKernel version
cpuCPU model and information
gpuGPU model and driver
ramMemory usage
diskDisk usage
uptimeSystem uptime
shellCurrent shell
packagesPackage counts (requires packagecount feature)
deDesktop environment
wmWindow manager
playingNow playing (media)
Plugin keys use the format plugin.<name> (e.g., plugin.weather).

​
Row properties

PropertyTypeDefaultDescription
keystringrequiredData identifier (see Built-in data keys)
labelstringautoCustom label (overrides default)
iconstringautoCustom icon (overrides default)
colorstring"white"Value foreground color
auto_wrapbooleanfalseEnable automatic word wrapping

​
Available colors

white, black, red, green, yellow, blue, magenta, cyan
Color names are case-insensitive. Invalid color names fall back to white.

​
Complete example

config.toml
# General configuration
[general]
name = "JohnDoe"
language = "en"

# Logo configuration (Kitty terminal)
[logo]
path = "~/.config/draconis++/archlinux-logo.png"
protocol = "kitty"
width = 220
height = 0  # Auto-calculate from aspect ratio

# Package managers to display
[packages]
enabled = ["pacman", "cargo", "nix"]

# Plugin system
[plugins]
enabled = true
auto_load = ["weather"]

# UI Layout - Introduction
[[ui.layout]]
name = "intro"

  [[ui.layout.rows]]
  key = "date"

  [[ui.layout.rows]]
  key = "plugin.weather"
  label = "Weather"
  icon = " 󰖐 "
  color = "cyan"
  auto_wrap = true

# UI Layout - System Information
[[ui.layout]]
name = "system"

  [[ui.layout.rows]]
  key = "host"
  icon = "  "

  [[ui.layout.rows]]
  key = "os"
  label = "Operating System"
  color = "blue"

  [[ui.layout.rows]]
  key = "kernel"

# UI Layout - Hardware
[[ui.layout]]
name = "hardware"

  [[ui.layout.rows]]
  key = "cpu"
  label = "Processor"

  [[ui.layout.rows]]
  key = "gpu"
  color = "green"

  [[ui.layout.rows]]
  key = "ram"
  color = "yellow"

  [[ui.layout.rows]]
  key = "disk"
  color = "yellow"

  [[ui.layout.rows]]
  key = "uptime"

# UI Layout - Software
[[ui.layout]]
name = "software"

  [[ui.layout.rows]]
  key = "shell"

  [[ui.layout.rows]]
  key = "packages"

# UI Layout - Session
[[ui.layout]]
name = "session"

  [[ui.layout.rows]]
  key = "de"
  label = "Desktop"

  [[ui.layout.rows]]
  key = "wm"
  label = "Window Manager"

  [[ui.layout.rows]]
  key = "playing"
  label = "Now Playing"
  color = "magenta"

# Weather plugin configuration
[weather]
provider = "openmeteo"
units = "metric"
lat = 40.7128
lon = -74.0060

​
Error handling

Draconis++ handles configuration errors gracefully:
  • File not found: Creates a default config file automatically
  • Parse errors: Logs the error with line number and falls back to defaults
  • Unknown keys: Ignored (allows plugin sections without breaking)
  • Invalid values: Logged with warnings, uses sensible defaults
[ERROR] Failed to parse config file: Expected end of table 'ui.layout.rows[0]', but got 'invalid_field'
[INFO] Using in-memory defaults.

​
Reloading configuration

The CLI reads configuration once at startup. To apply changes: 
# Edit your config
vim ~/.config/draconis++/config.toml

# Restart the CLI to apply changes
draconis++
For faster iteration during customization, keep a terminal open and run draconis++ after each config edit.

​
Advantages vs precompiled config

FeatureRuntime TOMLPrecompiled
Edit without rebuildingYesNo (requires recompile)
Startup overheadTOML parsingNone
Configuration fileconfig.tomlconfig.hpp
ValidationRuntimeCompile-time
Plugin loadingDynamic (.so/.dll)Static (embedded)
Binary sizeSmallerLarger
PortabilityRequires config fileSingle binary
Use runtime config for development and daily use. Use precompiled config for deployment and distribution.

Build docs developers (and LLMs) love

Get started for freeTalk to us