Gloss

A local-first command glossary for your terminal.

   

Gloss keeps reusable shell commands organized, searchable, and ready when you need them.

I built it because I kept re-searching the same commands and spreading aliases across shell history, notes, and config files. Gloss gives those commands a small local home: descriptions, tags, TUI search, config scanning, and safe managed alias sync.

Features

• Save shell commands with descriptions and tags
• Browse, search, filter, add, edit, and delete entries in a TUI
• Scan zsh/bash configs for aliases, simple functions, and executable scripts
• Import only the scan suggestions you choose
• Add managed aliases without writing to your shell config immediately
• Preview and sync aliases into one dedicated managed block
• Create backups only when sync changes an existing shell file
• Store everything locally under ~/.config/gloss/

Platform support

• Officially supported: macOS with zsh
• Officially supported: Linux with bash
• Not officially supported yet: Windows

Default shell files:

• zsh → ~/.zshrc
• bash → ~/.bashrc
• bash scan also includes ~/.bash_aliases

Existing config is never overwritten automatically. You can edit ~/.config/gloss/config.yaml if you want to change shell or scan paths.

Installation

Option 1 - Install script

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

By default, the script installs Gloss to:

~/.local/bin/gloss

If ~/.local/bin is not in your PATH, the installer prints the exact commands to add it.

Install a specific version:

curl -fsSL https://raw.githubusercontent.com/Architeg/gloss/main/scripts/install.sh -o /tmp/gloss-install.sh
VERSION=v0.1.0 bash /tmp/gloss-install.sh

Option 2 - Homebrew

brew install Architeg/tap/gloss

If Homebrew behaves unexpectedly, check this:

echo "$HOMEBREW_NO_INSTALL_FROM_API"

If it returns 1, unset it and retry:

unset HOMEBREW_NO_INSTALL_FROM_API
brew install Architeg/tap/gloss

You can also skip Homebrew auto-update during install:

HOMEBREW_NO_AUTO_UPDATE=1 brew install Architeg/tap/gloss

Option 3 - Manual install

Download the correct asset from GitHub Releases.

Example for macOS Apple Silicon:

unzip gloss-darwin-arm64.zip
chmod +x gloss-darwin-arm64
sudo mv gloss-darwin-arm64 /usr/local/bin/gloss
gloss version

Quick start

Launch the TUI:

gloss

Or use direct CLI commands:

gloss help
gloss version
gloss list
gloss list --tag git
gloss scan
gloss add
gloss edit <command>
gloss delete <command>
gloss alias add
gloss alias sync
gloss alias delete <name>

TUI overview

Main sections:

• Commands — browse, search, filter, open, add, edit, and delete saved commands
• Add — create a command entry with description and tags
• Scan — review aliases/functions/scripts found in configured scan paths
• Aliases — add, view, preview, sync, and delete managed aliases
• Settings — view shell file, storage path, scan paths, and config path
• Readme — built-in help

Common keys:

• ↑ / ↓ — move
• Enter — open, select, or confirm
• Esc — go back
• q — quit
• / — search where available
• F — filter where available
• Space — toggle scan/import items where available

Commands screen

The Commands screen is the main glossary browser.

You can:

• browse saved entries grouped by tag
• open entry details
• add new entries
• edit existing entries
• delete entries
• search by command/description
• filter by tag

Entries without tags are shown under Untagged.

───────────────────────────── Commands ─────────────────────────────                          

Search:   > substring in command or description                                              
Tag:      > exact tag                                                                        


› Category: Git
───────────────────────

  gs                    git status
  ga                    git add .
  gc                    git commit -m
  gp                    git push                                                     


› Category: Tools
───────────────────────

  nano                  Open nano editor
  serve                 Start a local static file server
  updatebrew            brew update && brew upgrade                                               


› Category: Network
───────────────────────

  headers               curl -I
  pingg                 ping github.com
  myip                  curl ifconfig.me
  dns                   dig
  speed                 networkQuality



/ Search │ F Filter │ E Edit │ D Delete │ A Add │ ↑↓ Move │ Enter Open │ Esc Back │ Q Quit  

Scan and import

Gloss can detect:

• aliases from your configured shell file
• zsh aliases from ~/.zshrc
• bash aliases from ~/.bashrc and ~/.bash_aliases
• simple shell functions
• executable files in configured scan directories

Scan suggestions are selected by default. Use the TUI Scan screen to toggle and import only the entries you want.

Imported scan entries are intentionally added without tags by default. This keeps bulk import fast; you can tag entries later.

Managed aliases

Gloss treats managed aliases as normal glossary entries with extra sync behavior.

Add a managed alias:

gloss alias add

Preview and sync from the TUI, or sync directly:

gloss alias sync

Gloss writes aliases only inside this managed block:

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

When syncing, Gloss will:

1. Build the managed alias block
2. Replace the existing Gloss-managed block if it exists
3. Append the block if it does not exist
4. Leave unrelated shell config untouched

If the generated block already matches the shell file, Gloss does not rewrite the file and does not create a backup.

Delete a managed alias:

gloss alias delete <name>

Then sync again to remove it from the managed block.

Safety and backups

Backups are created only when:

• the shell file already exists
• sync is actually going to modify it

No backup is created when:

• Gloss creates a missing shell file for the first time
• sync detects there is no change to write

Backup names look like this:

~/.zshrc.gloss.bak-20260423-223500
~/.bashrc.gloss.bak-20260423-223500

Old Gloss-created backups are pruned automatically.

Configuration

Gloss stores config and data under:

~/.config/gloss/

Typical files:

~/.config/gloss/config.yaml
~/.config/gloss/gloss.db

Example macOS/zsh config:

shell_file: /Users/yourname/.zshrc
storage_path: /Users/yourname/.config/gloss
scan_paths:
  - /Users/yourname/.zshrc
use_color: true

Example Linux/bash config:

shell_file: /home/yourname/.bashrc
storage_path: /home/yourname/.config/gloss
scan_paths:
  - /home/yourname/.bashrc
  - /home/yourname/.bash_aliases
use_color: true

Uninstall

Remove the binary:

rm -f "$HOME/.local/bin/gloss"

If installed system-wide:

sudo rm -f /usr/local/bin/gloss

If installed with Homebrew:

brew uninstall gloss

Optional: remove local data and config:

rm -rf "$HOME/.config/gloss"

Optional: remove the managed alias block from ~/.zshrc or ~/.bashrc:

# >>> gloss aliases >>>
# ...
# <<< gloss aliases <<<

If the install script added Gloss to your PATH, remove this block from your shell config:

# --- Path to Gloss ---
export PATH="$HOME/.local/bin:$PATH"

What Gloss is not

Gloss is not a shell replacement, history analyzer, package manager, AI command explainer, full shell plugin manager, or cloud sync product.

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

Development

Clone the repo:

git clone https://github.com/Architeg/gloss.git
cd gloss

Run locally:

go run ./cmd/gloss

Build:

go build ./cmd/gloss

Check version:

go run ./cmd/gloss version

⭐ Support Gloss

If Gloss saves you time or becomes part of your workflow, you can share it, give it a star, or support the project here:

Contributing

Issues, suggestions, and small focused PRs are welcome.

Please keep changes simple, readable, and focused on the core workflow.

Thanks to everyone who contributes to Gloss. ❤️

See the contributors graph.

License

MIT. See LICENSE.