v0.1.0

🎉 dotref v0.1.0 — First Release

This is the first working release of dotref — a tldr-style reference CLI for Linux configuration knobs.

What started as a README and an RFC two days ago is now a working command-line tool. That's entirely thanks to @jshaofa-ui who picked up the idea and delivered a complete implementation in one pull request. Open source at its best.

What's included

This release ships a fully working Python CLI with a small but real dataset to get you started. You can look up ZSH history parameters and GTK environment variables right now, out of the box.

pipx install dotref

dotref list                  # see available apps
dotref show zsh              # list zsh categories  
dotref show zsh history      # show zsh history knobs
dotref show gtk environment  # show GTK env vars
dotref search <keyword>      # search across everything

What's in the box

The CLI reads from a local ~/.dotref/data/ directory of plain TOML files — one file per category per app. The format is intentionally simple so anyone can contribute a new subsystem without knowing how to code. Two subsystems ship by default: zsh/history and gtk/environment.

Known limitations

This is a v0.1.0 — it works, but there's a lot of road ahead. The dataset is tiny right now and needs community contributions to grow. The dotref update command is a stub that tells you to clone the repo manually. Dynamic routing (dotref zsh without a show subcommand) is being cleaned up. Search works but requires the data to be in ~/.dotref/data/.

What's next

The most valuable thing you can do right now is contribute a .toml file for a subsystem you know well — XDG, Qt, Wayland, Bash, SDL, Mesa, or anything else. You don't need to know Python. Just copy the format from an existing file in data/, fill it in, and open a PR.

The dream is a community-maintained reference that covers everything — the kind of tool you reach for before opening a browser.

v0.2.0

dotref v0.2.0 — the "actually useful" release

The first version where dotref is a real tool you'd reach for. Reshapes the CLI surface, lands colors and an interactive picker, triples the database, and reconciles the contributor docs with what the code actually does.

Highlights

• 🎨 Colors + interactive fzf picker. Bare dotref launches a colorized, fuzzy picker for every knob in the database. Type tags (env / parameter / setopt / shopt / config / flag) are color-coded so you can scan output at a glance.
• 🔍 Direct knob lookup. dotref zsh HISTFILE now works — no more drilling through dotref zsh history and scrolling. Type the subsystem and the knob name; get the answer.
• 🧱 3× the database. From 6 subsystems / 19 files / ~260 knobs in 0.1.0 to 9 subsystems / 31 files / 429 knobs. New: bash, qt, mesa, plus expanded xdg, hyprland, systemd, uwsm.
• 🔗 Per-file [meta] block. Each TOML can declare an authoritative docs URL — rendered in category headers, the fzf preview, and --json output. All 31 shipped files seeded.
• 🤖 Machine-readable output. --json and --plain flags for piping into jq, scripts, and other tools.
• 📊 Ranked search. Results ordered exact → prefix → substring → description match. dotref search gtk puts gtk/* knobs at the top.
• 📦 Auto-bootstrap on first run. No more mkdir -p ~/.dotref/data && cp -r data/* after install. The CLI seeds ~/.dotref/data from the bundled database the first time it runs against an empty dir.
• 🔄 Real dotref update. Fetches the latest data/ tree from this repo as a tarball and atomically replaces ~/.dotref/data. Stdlib-only — no requests dependency. Refuses to operate inside a git checkout.

Breaking changes

• show subcommand removed. dotref show zsh history no longer works. Use dotref zsh history instead. The first positional argument is the subsystem; the optional second is a category or a knob name.

Install / upgrade

Fresh install:

git clone https://github.com/evoppuden/dotref
cd dotref
pipx install -e .
dotref                  # bootstraps ~/.dotref/data on first run

Existing 0.1.0 install:

cd path/to/dotref && git pull
pipx reinstall dotref
dotref update           # pull the latest data

Optional: install fzf for the interactive picker.

Try it

dotref                          # interactive fzf picker
dotref bash                     # list bash categories
dotref qt scaling               # show all Qt scaling env vars
dotref zsh HISTFILE             # direct knob lookup
dotref search theme             # ranked cross-subsystem search
dotref --json mesa drivers      # machine-readable output
dotref update                   # pull the latest database

Stats

	0.1.0	0.2.0
Subsystems	3	9
TOML files	3	31
Knobs	~30	429
CLI LOC	~250	~600
Subcommands	list, show, search, update	list, search, pick, update, plus implicit <sub> / <sub> <cat> / <sub> <name>

What's next

The big lever is more data. Planned subsystems wanted by users:

• wayland, nvidia, x11 (graphics stack)
• dbus, locale, color (smaller, can land together)
• expanded zsh (completion, prompt, expansion)

PRs that just add a .toml file are very welcome — see CONTRIBUTING.md.

Full changelog

See CHANGELOG.md for the complete entry.

---

Thanks to everyone who reviewed early drafts and pointed out that "you know, man zsh really is terrible for finding HISTFILE."