How to Manage Shell Commands Without Turning zsh or bash Into a Junk Drawer

How to Manage Shell Commands Without Turning zsh or bash Into a Junk Drawer

Shell history is great until it becomes a haunted attic. The command is probably there somewhere, wedged between three failed attempts, one typo, and a sudo moment that should not be legally discussed.

I built Gloss because I kept re-searching the same shell commands and spreading useful aliases across zsh, bash, notes, and random config files. This post is not really “use my tool, please clap.” It is more about the workflow problem that pushed me to build it — and the simple alternatives that are honestly good enough for many people.

The Problem: Shell History Is Not Knowledge

Shell history remembers what happened. It does not always remember why it mattered.

That difference becomes painful over time.

A command like this may be useful:

find . -name "*.log" -mtime +7 -delete

But when it appears in history later, it has no context. Was it safe? Was it for the current project? Did I test it first? Did I copy it from somewhere? Did it work, or was it one of the failed attempts before the actual command?

Shell history is chronological, not meaningful. It is a receipt drawer. Useful sometimes, but not exactly a knowledge system.

I still use history constantly. With tools like fzf, searching history becomes much nicer. Ctrl+R with fuzzy search is one of those tiny upgrades that makes the terminal feel less hostile.

But history has a ceiling. It is good for commands I recently used. It is weaker for commands I use once every few weeks, commands with dangerous flags, commands that need a note, or commands that belong to a specific category like Git, Docker, network checks, deployment, WordPress cleanup, or “things I should understand before pressing Enter.”

That is where I wanted something more deliberate.

Why Aliases Alone Become Messy

Aliases are the first obvious fix. And they are useful. Very useful.

alias gs="git status"
alias gp="git push"
alias ll="ls -lah"

A good alias turns a repeated command into muscle memory. One word instead of a small ceremony.

The problem starts when aliases become a private language nobody documented, including the person who wrote them. After enough time, .zshrc, .bashrc, or .bash_aliases can become a junk drawer with syntax highlighting.

You open the file and see:

alias dcu="docker compose up"
alias dcd="docker compose down"
alias fixperms="sudo chown -R $USER:$USER ."
alias thing2="some command I apparently trusted in 2024"

Very professional. Museum-quality chaos.

Aliases are fast, but they are not always self-explanatory. They also do not naturally answer questions like:

• What does this alias do?
• Why did I create it?
• Is it still useful?
• Is it safe?
• Which project or workflow does it belong to?
• Do I have five versions of the same idea?

For small sets of aliases, no problem. For years of terminal usage, things get weird.

Why Notes Are Too Far From the Terminal

The next solution is notes.

A Markdown file. Notion. Obsidian. Apple Notes. A private wiki. A giant commands.md file that starts clean and ends like a basement.

Notes are better than history because they can include explanations:

## Check HTTP headers

Use this when debugging redirects or CDN/cache behavior.

curl -I https://example.com

That is already much better. Context exists. The command is readable. Future-me has a fighting chance.

But notes have another problem: distance.

When I am in the terminal, switching to a browser or notes app often breaks the flow. It is not a huge interruption. It is just enough friction to make me not do it. And when friction wins, the command goes back into history, or worse, into a random alias with no explanation.

There are tools that bridge this gap. For example, QOwnNotes command-line snippet manager can search command snippets stored in notes using fzf or peco. That is a nice idea: keep notes as the source, but make snippets accessible from the command line.

I like that pattern. It proves the core need is real: commands need memory, search, and proximity to the terminal.

The Text File + fzf Solution

Before building anything, the obvious question is: why not just use a text file and fzf?

Honestly? That works.

You can create a simple file:

git status # check repo state git
curl -I https://example.com # inspect HTTP headers curl network
tar -czf archive.tar.gz folder # create compressed archive tar gzip
docker system prune -af # remove unused Docker data docker cleanup

Then search it:

cat commands.txt | fzf

Or make a tiny function:

cmds() {
  selected=$(cat "$HOME/.commands.txt" | fzf)
  printf '%s\n' "$selected"
}

That is already useful. It is simple, transparent, and easy to back up. Nobody needs a new app for every problem. Sometimes the correct architecture is “a file, a pipe, and a little self-control.”

There are also mature tools in this space. pet is a command-line snippet manager that lets you save, tag, search, and execute snippets. It can use fuzzy finders and has been around long enough to prove that command snippets are not a fake problem. navi approaches the idea from the interactive cheatsheet side, which is great when commands need parameters or guided input.

Those tools are worth checking out. They solve overlapping problems, and depending on your workflow, one of them may be the better fit.

So why did I still build gloss?

Because I wanted a particular shape of workflow.

Where I Wanted More Structure

The text-file version is elegant, but I wanted a bit more structure around my own command mess.

Not a full knowledge base. Not an AI command explainer. Not a shell replacement. Just a small local place where reusable shell commands can live with enough context to be useful later.

The missing pieces for me were:

• descriptions that are separate from the command itself
• tags for grouping commands by workflow
• a TUI for browsing and editing without opening a separate notes app
• scan/import from existing zsh and bash config files
• managed alias sync with preview and backups
• local storage, no account, no cloud requirement

That became Gloss.

Gloss is a small local-first CLI/TUI tool for reusable shell commands. It stores commands locally, lets me search them in a terminal UI, scans shell configs, and can sync selected aliases into one managed block.

The goal is not to make terminal work fancy. The goal is to stop re-solving the same small problems.

How Gloss Handles Commands

The basic Gloss workflow is simple.

Launch the TUI:

gloss

Or add an entry:

gloss add

An entry is just:

• command
• description
• tags

For example:

curl -I https://example.com

Description:

Check HTTP response headers without downloading the body

Tags:

network, curl, debug

That sounds small, but this small bit of structure helps. A command stops being a mysterious line from the past and becomes a reusable note that still belongs in the terminal.

Gloss also supports direct commands:

gloss list
gloss list --tag git
gloss scan
gloss edit <command>
gloss delete <command>

The TUI is for browsing and editing. The CLI commands are for quick actions. Nothing revolutionary. That is partly the point.

How Scan and Import Help Clean Up zsh and bash

The part I personally needed most was scanning existing shell files.

Gloss can scan common shell config locations such as:

~/.zshrc
~/.bashrc
~/.bash_aliases

Run:

gloss scan

In the TUI, scan results can include aliases, simple functions, and executable scripts from configured paths. Then I can choose what to import.

This matters because most reusable commands already exist somewhere. They are just not organized. Some are aliases. Some are functions. Some are scripts. Some are ancient fossils from a setup you barely remember.

Importing them into a glossary does not force them to become aliases. It just makes them findable, readable, and editable. That is a safer first step than “rewrite my shell config, good luck everybody.”

How Managed Alias Sync Works

Alias sync is the dangerous part, so I wanted it boring.

Boring is good here.

Gloss does not rewrite the whole shell file. It writes aliases inside one managed block:

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

Everything outside that block stays untouched.

The flow is:

1. add a managed alias in Gloss
2. preview the sync block
3. sync when ready
4. Gloss writes or replaces only the managed block
5. backup is created only if an existing shell file actually changes

That backup behavior matters. Creating endless backups for no-op syncs would be annoying. Not creating backups when modifying shell files would be reckless. The middle ground is simple: backup when sync changes an existing file.

Example:

gloss alias add
gloss alias sync

This is mainly for people who want aliases, but do not want alias management to become a hand-edited swamp.

What I Intentionally Did Not Build

It is tempting to keep adding features. That is how a small command glossary becomes a life management platform with plugins, sync, AI summaries, a graph view, and probably a calendar for some reason.

I tried not to do that.

Gloss is not:

• a shell replacement
• a shell history analyzer
• a package manager
• an AI command generator
• a full dotfiles manager
• a cloud sync product
• a replacement for fzf, pet, or navi

That last point is important. Gloss overlaps with snippet tools, but it does not try to win every category. A commands.txt file with fzf may be enough. pet may be better if you want snippet execution and mature snippet management. navi may be better if you want interactive cheatsheets with parameters.

Gloss is more narrowly about keeping reusable commands documented, searchable, importable from shell configs, and optionally syncable as managed aliases.

That is the lane.

A Practical Setup I Would Recommend

For a sane shell-command workflow, I would not start by installing five tools and reorganizing everything. That is how “productivity” becomes procrastination wearing a nice jacket.

I would start smaller:

1. Keep normal shell history.
2. Add fzf history search if you do not already use it.
3. Keep aliases for commands you run constantly.
4. Save less frequent but important commands somewhere searchable.
5. Use gloss, pet, navi, or a plain text file depending on how much structure you need.

A simple rule helps:

• If I run it daily, it can be an alias.
• If I need to understand it later, it needs a description.
• If I keep searching it again, it belongs in a glossary/snippet system.
• If it modifies shell config, it needs preview and backups.

That rule is not science. It is more like putting labels on boxes before the garage wins.

Installing Gloss

Gloss is open source under the MIT license, written in Go, and supports macOS/Linux with zsh and bash.

Install script:

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

Homebrew:

brew install Architeg/tap/gloss

Run:

gloss

Repo:
https://github.com/Architeg/gloss

Project page:
https://worksfine.dev/gloss/

Final Thoughts

Managing shell commands is not about becoming a terminal wizard. It is about not making the same tiny decisions forever.

Shell history is useful. Aliases are useful. Notes are useful. A text file with fzf is useful. But once commands start spreading across all of them, the workflow gets blurry. Gloss is my attempt to make that middle space cleaner: local, searchable, documented, and close to the terminal.

The terminal does not need another shiny layer of complexity. It needs fewer forgotten commands, fewer mystery aliases, and fewer browser searches for things already solved once. How do you manage the commands you know you will need again?

FAQ

• What problem does Gloss solve?
  Gloss helps manage reusable shell commands that are too important to leave buried in history but not used often enough to remember perfectly. It gives them descriptions, tags, search, scan/import, and optional managed alias sync.

• Is Gloss better than using aliases in zsh or bash?
  Not exactly. Aliases are still great for commands used constantly. Gloss is more useful for commands that need context, tags, or occasional lookup. It can also sync selected commands as aliases when that makes sense.

• Can I just use a text file with fzf instead?
  Yes. A text file plus fzf is a good minimal solution. Gloss is for users who want more structure: separate descriptions, tags, TUI editing, shell config scanning, and safer alias sync with backups.

• Does Gloss replace tools like pet or navi?
  No. pet is a mature command-line snippet manager, and navi is an interactive cheatsheet tool. gloss focuses on a local command glossary plus zsh/bash scan/import and managed alias syncing.

• Is it safe to let a tool write to .zshrc or .bashrc?
  Caution is reasonable. Gloss only writes inside a dedicated managed block, leaves unrelated shell config untouched, and creates backups when sync changes an existing shell file. Still, preview the block before syncing and keep your dotfiles backed up.

How do you manage reusable commands? Drop your setup, questions, or criticism in the comments — I’d like to see what works for other people.