Configuration Files

Sireno Deck uses a config.yml file to define your decks, buttons, addons, and themes.

File Discovery

The config file is searched in this order:

1. Explicit path via --config option
2. $XDG_CONFIG_HOME/sirenodeck/config.yml (defaults to ~/.config/sirenodeck/config.yml)
3. ./config.yml in the current working directory

The explicit path wins. Otherwise the XDG config is preferred over the current-directory config. Sireno Deck does not walk up parent directories.

Config Structure

# Theme configuration
theme: "default"

# Logging settings
logging:
  level: "info" # trace, debug, info, warn, error, fatal, silent
  verbose: true # optional

# Deck definitions
decks:
  main:
    name: "Main Deck"
    icon: "icon://Deck"
    background: "#000000"
    paginated: false
    trigger: # optional - for overlay decks
      process_name: "chrome"
      window_name: "VSCode"
    autoShow: true
    buttons:
      - { position: 0, type: "date-time:time" }
      - position: 1
        type: "core:action"
        config:
          icon: "icon://globe"
          label: "Open"
        actions:
          tap: "xdg-open https://example.com"

# Addons
addons:
  - "local-addon" # local path ./local-addon
  - "/absolute/path" # absolute path
  - "npm-addon" # npm package
  - "npm-addon@1.2.3" # npm with version
  # OR with config:
  - src: "my-addon"
    enabled: true
    # Set global: true when the package was installed globally.
    global: true
    config:
      defaults:
        autoShow: false
      decks:
        my-addon:shortcuts:
          name: "Chrome Shortcuts"
          autoShow: true

# Lock configuration (optional)
lock:
  buttons:
    - { position: 0, type: "date-time:time" }

Theme

# Use a built-in theme
theme: "default"

Use a package installed for this config:

theme: "my-theme"

Use a globally installed theme package:

theme:
  src: "my-theme"
  global: true

Logging

logging:
  level: "info" # trace, debug, info, warn, error, fatal, silent
  verbose: true # enables extra debug output

Decks

Basic Deck

decks:
  main:
    name: "Main Deck"
    icon: "icon://Deck"
    background: "#000000"
    buttons:
      - { position: 0, type: "date-time:time" }
      - position: 1
        type: "core:action"
        config:
          icon: "icon://play"
          label: "Play"
        actions:
          tap: "spotify play"

Overlay Deck

Overlay decks appear automatically when specific apps are active:

decks:
  vscode:
    name: "VS Code"
    icon: "icon://Code"
    paginated: true
    autoShow: true
    trigger:
      process_name: ["code", "code-oss", "Code"]
      window_name: ["*Visual Studio Code*"]
    buttons:
      - position: 0
        type: "core:action"
        actions:
          tap: "macro://[macos:cmd+shift+p]ctrl+shift+p"
        config:
          label: "Command Palette"

Paginated Deck

decks:
  shortcuts:
    name: "Shortcuts"
    paginated: true
    buttons:
      - { position: 0, type: "date-time:time" }
      - { position: 1, type: "date-time:date" }
      - { position: 2, type: "date-time:analog-clock" }

Buttons

Button Shorthand

# Full form
- position: 0
  type: "core:action"
  config:
    icon: "icon://globe"
    label: "Open"
  actions:
    tap: "xdg-open https://example.com"

# Short form (type only)
- "date-time:time"

# Short form (type with position)
- { position: 0, type: "date-time:time" }

Button Position

Positions are 0-indexed. The last position is reserved for system buttons (back/settings).

Addons

Addon Entry Formats

# Local relative path
addons:
  - "./my-addon"

# Local absolute path
addons:
  - "/Users/me/sireno-addons/my-addon"

# NPM package
addons:
  - "sireno-my-addon"
  - "sireno-my-addon@1.0.0"

# With configuration
addons:
  - src: "my-addon"
    enabled: true
    config:
      defaults:
        autoShow: false
      decks:
        shortcuts:
          name: "My Shortcuts"

Lock Mode

Lock mode prevents accidental button presses. Only specific button types can escape it:

lock:
  buttons:
    - { position: 0, type: "date-time:time" }

Includes

You can use YAML anchors and aliases for reusable button definitions:

# Define a button template
.base-button: &base-button
  type: "core:action"
  config:
    icon: "icon://globe"

# Use it
decks:
  main:
    buttons:
      - position: 0
        <<: *base-button
        config:
          label: "One"
      - position: 1
        <<: *base-button
        config:
          label: "Two"

Validation

Sireno Deck validates your config on startup. Invalid configurations will prevent the service from starting with clear error messages.