Introducing Gloss: A Local-First Command Glossary for Your Terminal

Valeriy Bagrintsev — Thu, 07 May 2026 17:21:53 +0000

Introducing Gloss: A Local-First Command Glossary for Your Terminal

Shell history is useful. Until it becomes a pile of almost-right commands, forgotten flags, and aliases with names only past-you understood.

That was the itch behind Gloss.

Gloss is a small open-source CLI/TUI tool for saving reusable shell commands, searching them in a terminal UI, scanning zsh/bash configs, and safely syncing selected aliases into a managed shell config block.

It is built for people who keep re-searching the same commands and slowly turn .zshrc, .bashrc, notes, and shell history into one very specific junk drawer.

What Gloss Does

gloss gives reusable shell commands a small local home.

You can use it to:

save shell commands with descriptions and tags
browse and search commands in a terminal UI
scan zsh and bash config files for aliases/functions
import useful commands from existing shell files
add managed aliases
preview alias sync before writing anything
sync aliases into one dedicated shell config block
create backups when sync changes an existing shell file

The goal is not to replace your shell, your dotfiles, or your favorite fuzzy finder setup.

It is just a focused tool for one annoying workflow: keeping useful commands findable and reusable.

Why I Built It

I kept running into the same pattern.

I would search for a command, use it, forget it, then search for it again later. Sometimes I saved it as an alias. Sometimes I dropped it into notes. Sometimes I trusted shell history, which is optimistic behavior and should probably be monitored.

Eventually I had useful commands spread across:

shell history
.zshrc
.bashrc
random Markdown notes
aliases with unclear names
browser searches I had already done before

A plain text file with fzf can solve part of this. That is a good setup. gloss is for the point where I wanted a bit more structure: descriptions, tags, TUI browsing, scan/import, and safer alias sync.

How Alias Sync Works

Gloss does not rewrite your whole shell config.

Managed aliases are written inside one dedicated block:

# >>> gloss aliases >>>
alias gs="git status"
alias ll="ls -lah"
# <<< gloss aliases <<<

Everything outside that block stays untouched.

Before syncing, you can preview what will be written. When sync changes an existing shell file, gloss creates a backup. If nothing changed, it does not rewrite the file just to feel productive.

That boring behavior is intentional.

Shell config files are not a playground.

Platform Support

Gloss currently supports:

macOS with zsh
Linux with bash

It is written in Go and stores data locally.
Windows is not officially supported yet.

Installation

Install script:

curl -fsSL https://raw.githubusercontent.com/Architeg/gloss/main/scripts/install.sh | bash

Homebrew:

brew install Architeg/tap/gloss

Then run:

gloss

Or check the version:

gloss version

What Gloss Is Not

Gloss is intentionally not:

a shell replacement
a package manager
a shell history analyzer
an AI command explainer
a full dotfiles manager
a cloud sync product

It is a small local utility for documenting, finding, importing, and safely syncing useful shell commands.

Feedback Welcome

Gloss is still new, so feedback is useful.

I am especially interested in thoughts around:

scan/import behavior
managed alias sync
TUI flow
whether the command glossary idea fits real terminal workflows
what would make it safer or simpler

If you already have a clean fzf + notes setup, I am also curious where Gloss feels unnecessary. That is useful feedback too.

DEV Community: WorksFine

Introducing Gloss: A Local-First Command Glossary for Your Terminal