Configuration Guide

Piko is highly customizable through TOML configuration files. This guide covers all configuration options and how to use them effectively.

Configuration File Locations

Piko looks for configuration files in the following order:

  1. Custom path (specified with –config)

  2. System configuration (/etc/piko/default_config.toml)

  3. User configuration (~/.config/piko/default_config.toml on macOS)

Basic Configuration Structure

A Piko configuration file has the following structure:

# Main layout configuration
layout = "default"

[output]
# Output display settings

[logo]
# Logo configuration

[theme]
# Theme and color settings

[display]
# Display and formatting options

[colors]
# Individual color overrides

[symbols]
# Custom symbols for information fields

Output Configuration

The [output] section controls how information is displayed:

[output]
# Logo settings
show_logo = true
logo_position = "left"      # left, right, top, bottom
logo_size = "medium"        # small, medium, large
logo_style = "ascii"        # ascii, unicode, minimal

# Information fields to display
info_keys = [
    "OS",
    "Kernel Version",
    "Desktop Environment",
    "Display Server",
    "Uptime",
    "CPU Model",
    "Memory",
    "GPU Model",
    "Username",
    "Hostname",
    "Disk"
]

# Show/hide specific fields
show_os = true
show_cpu = true
show_memory = true
show_disk = true
show_uptime = true
show_cpu_model = true
show_gpu_model = true
show_kernel_version = true
show_display_server = true
show_desktop_environment = true
show_username = true
show_hostname = true

Logo Configuration

The [logo] section controls the distribution logo display:

[logo]
enabled = true
distro = "auto"             # auto, arch, ubuntu, debian, fedora, etc.
padding = 2                  # Space between logo and info
alignment = "left"           # left, center, right

# Custom ASCII art (optional)
custom_ascii = [
    "  _____",
    " /  ___|",
    "|  |  __",
    "|  | |_ |",
    "|  |__| |",
    " \\_____|"
]

# Custom colors for ASCII art (optional)
custom_colors = ["#D70A53"]

Theme Configuration

The [theme] section defines color schemes:

[theme]
name = "default"             # default, dracula, nord, gruvbox, custom
primary_color = "#FF79C6"    # Main accent color
secondary_color = "#50FA7B"  # Secondary accent color
accent_color = "#BD93F9"     # Highlight color
background_color = ""        # Background color (empty for transparent)
text_color = "#F8F8F2"      # Default text color

Display Configuration

The [display] section controls visual formatting:

[display]
# Border settings
border = false
border_style = "single"      # single, double, rounded, none
border_color = "#6272A4"

# Spacing
padding = 1                  # Internal padding
margin = 0                   # External margin

# Layout
alignment = "left"           # left, center, right
show_separators = true       # Show separators between info lines
separator_style = "dash"     # dash, equals, dots, none

Color Configuration

The [colors] section allows fine-grained color control:

[colors]
# System information colors
OS = "#FF79C6"               # Pink
Username = "#50FA7B"         # Green
Hostname = "#F1FA8C"         # Yellow
"Desktop Environment" = "#BD93F9"  # Purple
Memory = "#8BE9FD"           # Cyan
Disk = "#FF5555"             # Red
"CPU Model" = "#6272A4"      # Blue-grey
"GPU Model" = "#FFB86C"      # Orange
"Kernel Version" = "#44475A" # Dark grey
"Display Server" = "#A4FFFF" # Light cyan
Uptime = "#FF92DF"           # Light pink

Symbol Configuration

The [symbols] section defines custom symbols for information fields:

[symbols]
OS = "🖥️"
Username = "👤"
Hostname = "🏠"
"Desktop Environment" = "🌠"
Memory = "💾"
Disk = "📂"
"CPU Model" = "🧪"
"GPU Model" = "🖨️"
"Kernel Version" = "💻"
"Display Server" = "🖱️"
Uptime = "⏰"

Predefined Themes

Piko comes with several built-in themes:

Default Theme (Dracula-inspired): - Primary: Pink (#FF79C6) - Secondary: Green (#50FA7B) - Accent: Purple (#BD93F9)

Compact Theme: - Primary: Teal (#4ECDC4) - Secondary: Blue (#45B7D1) - Accent: Green (#96CEB4)

Border Theme: - Primary: Red (#FF6B6B) - Secondary: Teal (#4ECDC4) - Accent: Blue (#45B7D1)

Creating Custom Themes

To create a custom theme:

  1. Copy an existing theme file: .. code-block:: bash

    cp /etc/piko/default_config.toml ~/my_theme.toml

  2. Modify colors and settings: .. code-block:: toml

    [theme] name = “my_custom_theme” primary_color = “#FF6B6B” secondary_color = “#4ECDC4” accent_color = “#45B7D1”

  3. Use your custom theme: .. code-block:: bash

    piko –config ~/my_theme.toml

Configuration Examples

Minimal Configuration: .. code-block:: toml

[output] logo_size = “small” logo_style = “minimal”

[display] show_separators = false padding = 0

Professional Configuration: .. code-block:: toml

[display] border = true border_style = “double” border_color = “#FF6B6B” padding = 2

[output] logo_size = “large” logo_style = “ascii”

Colorful Configuration: .. code-block:: toml

[theme] name = “vibrant” primary_color = “#FF6B6B” secondary_color = “#4ECDC4” accent_color = “#45B7D1”

[colors] OS = “#FF6B6B” Username = “#4ECDC4” Hostname = “#45B7D1”

Environment Variables

You can override configuration with environment variables:

export PIKO_CONFIG_PATH="/path/to/config.toml"
export PIKO_LOGO_SIZE="large"
export PIKO_SHOW_BORDER="true"

Configuration Validation

Piko validates configuration files and will show errors for invalid TOML syntax. Common issues:

  • Inline comments: TOML doesn’t support # on the same line as values

  • Missing quotes: Use quotes for strings with spaces

  • Invalid colors: Ensure hex colors are valid (e.g., #FF0000)

Best Practices

  1. Backup configurations: Keep backups of working configurations

  2. Test changes: Test configuration changes before applying to production

  3. Use version control: Track configuration changes in git

  4. Document customizations: Add comments to explain custom settings

  5. Share themes: Share your custom themes with the community

Troubleshooting

Configuration not loading: - Check file permissions: ls -la /etc/piko/ - Verify TOML syntax: toml-validate config.toml - Check file path: piko –config /path/to/config.toml

Colors not working: - Ensure terminal supports true color - Check hex color format: #RRGGBB - Verify color names are correct

Logo not displaying: - Check show_logo = true in output section - Verify logo is enabled: [logo] enabled = true - Test with piko –logo-only

For more advanced configuration options, see the advanced_features guide.