Files & storage¶

Commando has no database. Every piece of state is a plain, human-readable file you can cat, grep, edit, back up, or delete. This page is the complete map of what lives where.

The layout¶

~/.config/commando/                 ← config root  ($XDG_CONFIG_HOME/commando)
├── config.toml                     ← key binding, redaction, custom providers
├── bookmarks.toml                  ← saved commands + tags/notes
└── cheats/
    ├── git.toml                    ← seeded on first run
    ├── docker.toml                 ← seeded on first run
    ├── kubectl.toml                ← seeded on first run
    ├── files.toml                  ← seeded on first run
    └── user.toml                   ← where `commando add` appends

~/.local/share/commando/            ← data root  ($XDG_DATA_HOME/commando)
├── memory.toml                     ← remembered variable values (frecency)
├── usage.toml                      ← per-entry launch counts (ranking)
└── data/                           ← auxiliary files for cheat `src` commands
                                       (exposed as $COMMANDO_DATA_DIR)

$HISTFILE (e.g. ~/.zsh_history)     ← shell history — read live, never copied

Commando may also create *.lock sidecars next to mutable TOML files. They are empty advisory-lock files used to merge updates safely when several shells run Commando at once; leave them in place.

Every file, explained¶

File	Read/Written	Contents
`config.toml`	you write	Key binding, history redaction denylist, custom providers. See Configuration.
`cheats/*.toml`	you + `commando add`	Cheat sheet entries. Every `.toml` here is loaded. See Cheat sheets.
`bookmarks.toml`	Commando + you	Saved commands with tags and notes. See Bookmarks.
`memory.toml`	Commando + you	Remembered variable values, keyed by `(command, variable, scope)`, ranked by frecency. See Argument memory.
`usage.toml`	Commando	Per-entry launch counts and last-used times, used to rank the list.
`data/*`	you	Arbitrary candidate-list files your cheats read via `$COMMANDO_DATA_DIR`.
`$HISTFILE`	Commando reads	Your shell's own history file. Commando reads it live and never modifies or copies it.

Why plain files?¶

Inspectable. cat ~/.local/share/commando/memory.toml and see exactly what Commando remembers — no opaque binary blob.
Editable. Fix a typo in a remembered value, prune a bookmark, or hand-write a cheat, all with your normal editor.
Portable. Commit your cheats to a dotfiles repo, sync them across machines, or share them with your team.
Debuggable. When something looks wrong, the state is right there in text.

Writes are assembled in a temporary file, synced, and atomically renamed. Concurrent processes lock and merge the latest file before writing. Remembered values are capped at 25 per command-variable-scope bucket, and usage ranking is capped at the 5,000 most recent entries, so these files remain bounded.

The data directory (`COMMANDO_DATA_DIR`)¶

~/.local/share/commando/data/ is a scratch space for candidate-list data files your cheats read. When Commando runs a variable's src or preview command, it sets the COMMANDO_DATA_DIR environment variable to this path:

[[cmd.var]]
name = "service"
src  = 'cat "$COMMANDO_DATA_DIR/service-names.txt"'

Drop a service-names.txt in data/, and the variable's candidates come from it. Great for lists that are expensive to compute or come from an external source.

XDG overrides¶

Both roots honor the XDG environment variables:

Root	Env var	Default
Config	`XDG_CONFIG_HOME`	`~/.config`
Data	`XDG_DATA_HOME`	`~/.local/share`

Set these to relocate Commando's files — useful for testing or for keeping everything under a single dotfiles tree.

Resetting¶

To reset…	Do this
Remembered values	`commando state clear memory`
Ranking / usage	`commando state clear usage`
Both state files	`commando state clear all`
Bookmarks	Delete `bookmarks.toml` or edit it
A cheat	Edit or delete the relevant `cheats/*.toml`
Everything	Remove `~/.config/commando` and `~/.local/share/commando`

Commando recreates whatever it needs on the next run (including re-seeding the starter cheats).