Configuration

File locations

What	Default path	Flag	Environment variable
Sources config	~/.config/deckctl/config.yaml	--config	DECKCTL_CONFIG
Themes	~/.config/deckctl/themes.yaml	--theme	DECKCTL_THEME
Apply history	~/.config/deckctl/history.db	--history	DECKCTL_HISTORY
Template cache	~/.cache/deckctl/	--cache-dir	DECKCTL_CACHE_DIR

Precedence is flag → environment variable → default. The cache directory additionally checks XDG_CACHE_HOME (using $XDG_CACHE_HOME/deckctl) before falling back to ~/.cache/deckctl.

Files are created with mode 0640 inside directories created with 0750.

A missing config.yaml or themes.yaml is not an error: deckctl starts with an empty config and its built-in theme.

config.yaml

sources:
  - name: local
    type: local
    path: /home/you/templates

  - name: work
    type: gitlab
    url: https://gitlab.mycompany.com
    group: platform/templates
    token_env: DECKCTL_WORK_TOKEN
    cache_ttl: 24h

default_source: local

Top level

Key	Type	Description
sources	list	The configured sources
default_source	string	Name of the source to treat as default

Source fields

Field	Required	Applies to	Description
name	yes	both	Unique identifier, used as --source <name>
type	yes	both	local or gitlab
path	yes	local	Directory whose subdirectories are templates
url	yes	gitlab	Instance base URL, e.g. https://gitlab.com
group	yes	gitlab	Group path; nesting allowed (parent/child)
token_env	no	gitlab	Name of the env var holding a Personal Access Token
cache_ttl	no	gitlab	How long a cache entry stays fresh. Default 1h.

Validation rules

• type must be local or gitlab.
• name is required, and names must be unique across all sources.
• gitlab sources require both url and group.
• local sources require path.
• token_env must match ^[A-Z_][A-Z0-9_]*$ — it names an environment variable, it does not hold a token.
• cache_ttl must be non-negative, and cannot be set on a local source.

Check a hand-edited file with deckctl validate -t config.

cache_ttl syntax

cache_ttl parses as a Go duration: an optionally-signed decimal with a unit suffix, and units may be combined.

Valid	Invalid
30s, 15m, 2h, 1h30m, 0.5h	1d, 2w, 24 (no unit)

Caution

There is no day or week unit. Write 24h rather than 1d. The --older-than flag on deckctl cache clear uses a different parser that does accept d and w — don’t carry the syntax across.

Tokens

Tokens are never written to config.yaml. token_env names an environment variable that deckctl reads at runtime:

export DECKCTL_WORK_TOKEN=glpat-xxxxxxxxxxxx

Required scopes: read_api to list projects and tags, read_repository to download archives from private projects.

If token_env is set but the variable is empty or unset, deckctl prints a warning to stderr and continues unauthenticated. If token_env is omitted, no warning is printed.

themes.yaml

themes:
  - name: default
    palette:
      primary: "#e0def4"
      secondary: "#9ccfd8"
      accent: "#c4a7e7"
      muted: "#6e6a86"
  - name: solarized
    palette:
      primary: "#93a1a1"
      secondary: "#268bd2"
      accent: "#b58900"
      muted: "#586e75"
active: solarized

Key	Type	Description
themes	list	Named palettes
themes[].name	string	Unique theme name
themes[].palette.primary	hex	Body text
themes[].palette.secondary	hex	Headers
themes[].palette.accent	hex	Highlights
themes[].palette.muted	hex	Borders and de-emphasised text
active	string	Name of the theme in use

Validation rules

• All four palette colours are required, and each must match #rgb or #rrggbb. Named colours are not accepted.
• Theme names must be unique.
• active, when set, must name a theme present in themes.

Check with deckctl validate -t themes.

Environment variables

Variable	Effect
DECKCTL_CONFIG	Path to config.yaml
DECKCTL_THEME	Path to themes.yaml
DECKCTL_HISTORY	Path to the history database
DECKCTL_CACHE_DIR	Cache directory
XDG_CACHE_HOME	Used as $XDG_CACHE_HOME/deckctl when DECKCTL_CACHE_DIR is unset
(your own)	Whatever token_env names, per GitLab source

See also

• Configuring sources
• Theming and output
• Sidecar reference — per-template configuration