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

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.

Links

• GitHub: https://github.com/Architeg/gloss
• Website: https://worksfine.dev/gloss/

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.