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 searching for the same commands while useful snippets and aliases were scattered across shell history, notes, and config files. Gloss brings them together in one local tool, with descriptions, tags, fast 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
• Release architectures: amd64 and arm64
• 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 the install directory is not in PATH, an interactive install offers to add it to ~/.zshrc or ~/.bashrc. You can decline. When no interactive terminal is available, the installer prints the exact line to add manually. The installer never invokes sudo; after updating the file, restart the terminal or run the printed source command.

Install a specific version:

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

Option 2 - Homebrew

brew install Architeg/tap/gloss

Option 3 - Manual install

Download the correct ZIP and checksums.txt from GitHub Releases. Verify the ZIP before extracting it.

Example for macOS Apple Silicon:

grep -E '^[0-9a-fA-F]{64}  gloss-darwin-arm64\.zip$' checksums.txt > gloss.sha256
test "$(wc -l < gloss.sha256)" -eq 1
shasum -a 256 -c gloss.sha256
unzip gloss-darwin-arm64.zip
mkdir -p "$HOME/.local/bin"
install -m 0755 gloss-darwin-arm64 "$HOME/.local/bin/gloss"
gloss version

Option 4 - Go install

With Go 1.25 or newer:

go install github.com/Architeg/gloss/cmd/gloss@latest

Updates

Check the latest stable release without changing the installed executable:

gloss update

For a standalone installation, explicitly verify and install an available update:

gloss update --install

For Homebrew:

brew upgrade Architeg/tap/gloss

On the first TUI launch, Gloss asks whether it may check GitHub for updates automatically. The choice can be changed later in Settings. Automatic checks run at most once per configured interval, stay quiet when current or offline, and never install updates.

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 paths and turn automatic update checks on or off
• 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 Architeg/tap/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 you added Gloss to your PATH, remove the corresponding line from your shell config:

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.