Docs

Install

Arch Linux

Pult is in the subcult pacman repository on git.subcult.tv. Gitea signs it with its own key.

curl -fsS https://git.subcult.tv/api/packages/subculture-collective/arch/repository.key | sudo pacman-key --add -
sudo pacman-key --lsign-key CCE8B0F3BCDD601D909773E4466AA6E8241453D2
printf '\n[subcult]\nSigLevel = Required\nServer = https://git.subcult.tv/api/packages/subculture-collective/arch/$repo/$arch\n' | sudo tee -a /etc/pacman.conf
sudo pacman -Sy pult

Tarball

Download the Linux or macOS tarball for your machine from the releases page, unpack it and put pult on your PATH. The catalog is built in.

From source

You need Go 1.26 or newer, Git and network access.

git clone https://git.subcult.tv/subculture-collective/pult.git
cd pult
make catalog
go build -o ~/.local/bin/pult ./cmd/pult
export PULT_CATALOG=$PWD/.cache/catalog.db.zst

make catalog fetches the pinned theme sources and builds .cache/catalog.db.zst. A source build has no catalog of its own, so Pult needs PULT_CATALOG to find this file. Add the export to your shell profile, with the full path to your checkout. Make sure ~/.local/bin is on your PATH.

First run

$ pult list                             # which apps Pult found
$ pult search -tag pastel rose          # find a theme
$ pult apply -dry-run catppuccin-mocha  # see the plan and diffs
$ pult apply catppuccin-mocha           # asks, then applies
$ pult uninstall                        # put every changed file back

Or run pult tui and do all of that from one screen.

The TUI

pult tui has two screens, themes and apps. Moving through the list shows each theme's colors as swatches. A ↓ beside a theme means its colors aren't bundled and are downloaded when you apply it.

The TUI leaves files other tools own alone. Use pult apply when you want to be asked about those.

Commands

Finding themes

The catalog holds about 2,700 themes from iTerm2 Color Schemes, Tinted Theming, Catppuccin, Dracula and Gogh. About 1,800 ship with their colors. The others are listed by name and marked (downloaded on first use). Each theme keeps its own licence.

$ pult search rose -tag pastel -n 5
$ pult search -similar catppuccin-mocha
$ pult search -tag light -tag warm

Profiles

A profile is a TOML file that picks a theme, a set of apps and a terminal font. Keep profiles in $XDG_CONFIG_HOME/pult/profiles/, or pass any path.

schema = 1
theme = "nord"
apps = ["kitty", "bat"]

[font]
family = "JetBrains Mono"
size = 12

$ pult apply -profile desk          # profiles/desk.toml
$ pult apply -profile ./work.toml   # any file
$ pult apply -profile desk dracula  # the profile, with another theme

Unknown fields are an error, so a typo doesn't pass unnoticed. Pult never installs fonts. On Linux it warns when fc-list doesn't know the family.

Palette files

A palette file is what pult palette prints, in JSON or TOML. It works anywhere a theme ID does. An argument counts as a file when it contains / or ends in .json or .toml.

{
  "schema": 1,
  "theme": {"name": "My Theme", "appearance": "dark"},
  "colors": {
    "ansi0": "#100b19", ... through ... "ansi15": "#f0ece4",
    "background": "#100b19",
    "foreground": "#f0ece4"
  }
}

colors needs ansi0 through ansi15, background and foreground. Pult derives any other role. The theme block is optional.

Palette export

pult palette and pult render hand a theme's colors to other tools without applying anything and without touching the change record.

$ pult palette -format toml catppuccin-mocha
$ pult render catppuccin-mocha my.conf.mustache
$ pult render -o out.conf catppuccin-mocha kitty/pult.conf.mustache

The template is a file path or the name of a bundled template. See the palette export reference and the template variables.

Supported apps

pult list shows the state of each one on your machine. Windows isn't supported.

What gets changed

Pult changes colors and, when a profile asks, the terminal font. It uses each app's own include or theme mechanism where one exists, so your other settings aren't touched. For kitty, it adds one line to kitty.conf and writes colors to a separate file:

 font_size 12
+include pult.conf

Run pult apply -dry-run to see the exact plan and diffs for your machine. If an app rejects its new config during validation, Pult restores that app's files and reports it.

Other tools

Each config file has one owner. Pult works out which and acts on that.

Framework limits are in the framework reference.

Undo and recovery

Every file Pult creates, edits or deletes is recorded before it is touched, with a compressed copy of the original under $XDG_STATE_HOME/pult/. The format is documented, so you can restore a file by hand even if Pult itself is broken.

• pult uninstall restores every changed file and removes the ones Pult created.
• A file you edited after Pult wrote it is left as it is, and Pult shows the difference. pult uninstall -force restores it anyway.
• u in the TUI rolls back the last apply.
• pult doctor reports interrupted runs. pult doctor -recover rolls them back.

Paths and flags

Every command that reads Pult's data takes these flags.

More

• Source on Gitea, the primary repository, and the GitHub mirror
• Issues
• Project documentation: decisions, contracts and the milestone plan
• Contributing and security

Code is GPL-3.0-only. Templates and the app registry are MIT. Themes keep their own licences.