sowam is a personal software tracking CLI utility. This tool is used to build and maintain a permanent, searchable inventory of desirable software, anything from CLI tools and system packages to language modules, shells, cybersecurity utilities, desktop applications, games, and non-critical license keys.
Entries can be tagged by purpose, ranked by frequency of use, and filtered into 256-color table views for a quick visual reference of your entire toolbox. Additionally, it can also wrap install commands as a convenience, although it is not a package manager. All data lives in a single portable file in your home directory, making backups and cross-system portability a one-step operation.
- Subcommands for every lifecycle stage — add, list, search, modify, delete, import, export, install, check, tag, info/zoom, stats
- Per-entry metadata — name, executable command, rank, tags, OS targets, install methods (apt/dnf/brew/pip/url/…), URL, repository URL, docs, vendor, license key, description, and more
- 256-color table output — rows color-coded by rank (1 = red → 10 = vivid green) or by user-assigned tag color, switchable at runtime
- Tag registry with named colors — assign any of 256 ANSI colors to tags; browse the full palette from the terminal with
sowam tag --list-colors - PATH-based install detection —
sowam checkscans$PATHand auto-updates theinstalledfield for every entry - Multiple output formats — table, JSON, YAML, CSV, HTML report (all stdlib, no external deps)
- Batch/scripting mode —
--batchsuppresses all interactive prompts - Zero external dependencies — pure Python 3.8+ stdlib
Note
To see an example of a browser-friendly (HTML-formatted) software report, download the following file from this repository and open it with your browser of choice: Demo Report
- Python 3.8 or later
- No external packages required
pip install sowampipx install sowamgit clone https://github.com/jam-ware/sowam
cd sowam
pip install -e .# Add a few entries
sowam add nvim --cmd nvim -r 10 -t editor -o any
sowam add taskwarrior --cmd task -r 9 -t productivity \
-m apt=taskwarrior -m dnf=task
sowam add ripgrep --cmd rg -r 8 -t search -t cli -o linux -o darwin
sowam add veracrypt \
--description 'Free Open source disk encryption with strong security' \
--docs 'https://veracrypt.io/en/Documentation.html' \
--url 'https://veracrypt.io/en/Home.html' \
--repository https://github.com/veracrypt/VeraCrypt.git \
--os any \
--rank 5 \
--see-also LUKS --see-also GPG \
--tag encryption --tag cryptography \
--install-method url=https://veracrypt.io/en/Downloads.html \
--vendor=VeraCrypt \
--cmd veracrypt
# View everything (color-coded by rank)
sowam list
sowam list -a
# Color rows by tag instead of rank
sowam tag --assign-color editor green
sowam tag --assign-color productivity gold
sowam list --color-by tag
# Search
sowam get --tag cli --os linux
sowam get --apropos "file search"
# Check which tools are actually on PATH
sowam check --dry-run
sowam check
# Install all productivity tools on this OS
sowam install --tag productivity --os linux
# Export a backup
sowam export --json -o ~/sowam-backup.jsonTip
The table output that is displayed in the terminal was created to be customizable in order to suit your needs. By default, only the fields NAME, RANK, TAGS, and DESCRIPTION are displayed, but by using the --fields x,x,x,x flag under the list subcommand or the SOWAM_FIELDS environment variable, you can provide a comma-separated list of metadata fields that you want displayed each time you run the sowam list command / subcommand.
| Subcommand | Alias | Description |
|---|---|---|
add |
Add a new software entry | |
list |
view |
List all tracked software |
get |
search |
Search and filter entries |
modify |
Update fields on an existing entry | |
delete |
Remove an entry | |
tag |
Manage tag registry and colors | |
check |
Scan PATH and update installed status | |
import |
Import entries from a JSON file | |
export |
backup |
Write tracker data to a file |
info |
zoom |
Show full details for a single entry |
stats |
Show tracker config and file metadata | |
install |
Install tracked software via the detected package manager | |
clone |
Clone git repositories for entries with a repository URL |
Run sowam <subcommand> --help for detailed per-subcommand usage.
Each entry stores the following fields:
| Field | Flag | Description |
|---|---|---|
name |
--name / -n |
Human-readable display name (e.g. TaskWarrior) |
cmd |
--cmd / -x |
Executable as typed in the terminal (e.g. task). Defaults to name if not set. |
description |
--description |
Short description of what the software does |
rank |
--rank / -r |
Frequency of personal use, 1–10 (10 = use constantly) |
tags |
--tag / -t |
Category tags, repeatable |
os |
--os / -o |
Target OS(es): linux, darwin, windows, any, … |
url |
--url / -u |
Official project / vendor URL (homepage, product page, etc.) |
repository |
--repository / -R |
Git repository URL used by sowam clone (e.g. https://github.com/user/repo.git) |
docs |
--docs |
Documentation URL or string |
install |
--install-method / -m |
Install methods, repeatable. Format: medium or medium=value. E.g. apt, apt=vim, dnf=task, pip=requests, url=URL |
license |
--license / -l |
Product or license key (see Security Notice) |
sw_version |
--sw-version |
Software version string |
vendor |
--vendor |
Vendor or provider name |
see_also |
--see-also |
Related software names, repeatable |
dependencies |
--dependencies |
Dependency names, repeatable |
installed |
--installed |
true, false, or null (unknown) |
other_info |
--other-info |
Free-form notes |
Note
A significant note regarding the ranking (rank) system (metadata field and command flag) is that this feature is only used to measure the frequency of how much a software is installed or used on a daily basis - this is NOT intended to rank software by any other factors.
When looking at a software list, a lower ranking does not imply any negative connotation of the software (e.g. A network scanning tool being ranked lower than a TODO item software does not mean that one is 'better' than the other, just that one is used more frequently in a personal sense). The ranking system is intended to be used for itemized filtering and prioritization, not for the judgement of software.
Table rows are colored by rank using a 256-color ANSI gradient:
| Rank | Color |
|---|---|
| 10 | Vivid green |
| 8–9 | Green shades |
| 6–7 | Yellow-green |
| 5 | Yellow |
| 3–4 | Orange |
| 1–2 | Red shades |
| none | Dark gray |
Assign any of the 256 ANSI terminal colors to a tag, then switch the table to color by tag instead of rank:
sowam tag --assign-color admin red
sowam tag --assign-color networking 21 # by ANSI number
sowam tag --assign-color editor green
sowam list --color-by tag
sowam get --tag admin --color-by tagBrowse the full 256-color palette:
sowam tag --list-colors # compact grid (default)
sowam tag --list-colors long # one per line with name
sowam tag --list-colors json # machine-readableNamed color aliases include:
redorangeyellowgoldgreenlimetealcyanbluenavypurplevioletpinkmagentawhitegrayblack- and more.
Tags auto-register when first used with add or modify. The tag subcommand
manages the registry:
sowam tag --list # list all tags, colors, entry counts
sowam tag --create admin # explicitly register
sowam tag --assign-color admin red # assign a color
sowam tag --assign-color networking 21 # assign by ANSI number
sowam tag --clear-color admin # remove color assignment
sowam tag --rename admin sysadmin # rename everywhere (updates all entries)
sowam tag --delete obsolete # remove from registry (does not untag entries)Matches the name and description fields:
sowam get vim
sowam get "task manager"sowam get --tag networking --os linux
sowam get --rank 10
sowam get --install-method apt # entries installable via apt
sowam get --install-method pip # entries installable via pip
sowam get --url github.comBroad keyword search across all text fields (name, cmd, description, tags,
vendor, other_info, see_also) — like man -k but for your software list:
sowam get --apropos "fuzzy search"
sowam get --apropos terminalFilters can be combined:
sowam get --tag cli --os linux --apropos "file" --rank 8sowam install auto-detects the system package manager and runs it for matching entries:
sowam install taskwarrior # install one entry by name
sowam install --all --os linux # install everything for Linux
sowam install --tag productivity # install all productivity tools
sowam install --tag cli --os darwin # install CLI tools for macOS
sowam install vim --force # reinstall even if already marked installed
sowam install vim --package-manager dnf # force a specific package managersowam picks one package manager for the entire run — the first one found on your system in priority order:
- (
apt→dnf→yum→pacman→zypper→brew→choco→winget→ …, then language toolchains). - Use
--package-manager/-Gto override.
Install mediums by type:
- Package managers (
apt,dnf,yum,pacman,zypper,brew,choco,winget,apk, …) — runs the detected (or specified) manager. Package name defaults to the entry'scmdfield if omitted. - Language toolchains (
pip,pipx,cargo,npm,gem,go, …) — treated as package managers; selected the same way, lower priority than system PMs. - Direct download (
url,wget,curl) — downloads the stored URL withurllib.requestand saves to~/.sowam/downloads/.
Entries whose stored install methods don't include the selected package manager are skipped with a clear message.
sowam clone clones entries that have a repository URL set — into ~/.sowam/repos/ (or a path you specify). Store the git URL when adding the entry with --repository:
sowam add ripgrep --repository https://github.com/BurntSushi/ripgrep.git
sowam clone taskwarrior # clone one entry by name
sowam clone --all --tag cli # clone all entries with a repository URL
sowam clone myrepo --force # reclone even if the directory exists
sowam clone myrepo --clone-to ~/src # override destination directory
sowam clone myrepo --url https://github.com/x/y # override the stored repository URLDownloaded files go to ~/.sowam/downloads/ and cloned repos go to ~/.sowam/repos/ by default. Both directories are created automatically on first use and are overridable via SOWAM_DOWNLOADS / SOWAM_REPOS environment variables.
# Export a full JSON backup
sowam export --json -o ~/sowam-backup.json
# Export to other formats
sowam export --csv -o ~/software.csv
sowam export --yaml -o ~/software.yaml
sowam export --html -o ~/software.html # opens in a browser
# Import from a backup (skips duplicates by name)
sowam import ~/sowam-backup.json
# Import and overwrite existing entries
sowam import ~/sowam-backup.json --forceTip
The import format is flexible: sowam accepts a full sowam JSON export, a bare JSON array of entry objects, or a single entry object.
| Variable | Description |
|---|---|
SOWAM_DATA |
Path to the data file. Overridden by --path/-p. Default: ~/.sowam/data.json |
SOWAM_DOWNLOADS |
Directory for files downloaded by install (url/curl/wget methods). Default: ~/.sowam/downloads/ |
SOWAM_REPOS |
Directory for repositories cloned by clone. Default: ~/.sowam/repos/ |
SOWAM_COLOR_BY |
Default color mode: rank or tag. Overridden by --color-by. |
SOWAM_FIELDS |
Comma-separated list of fields to display in list table output. Overridden by --fields/-F. E.g. export SOWAM_FIELDS=name,rank,installed,url. Run sowam list --list-fields for the full list of available fields. |
NO_COLOR |
If set (any value), disables all ANSI color output. |
COLOR |
Set to on or off to control color; checked alongside --color. |
These flags are available on every subcommand:
| Flag | Short | Description |
|---|---|---|
--color MODE |
-c |
Color output: auto (default), on, or off |
--batch |
-b |
Suppress all interactive prompts (for scripting) |
--path PATH |
-p / -d |
Path to data file (overrides SOWAM_DATA) |
--debug |
-D |
Verbose debug output to stderr |
Data is stored as JSON at the default path ~/.sowam/data.json (or at the path specified in the environment variable $SOWAM_DATA):
{
"_meta": {
"version": "1",
"created": "2026-07-24T10:00:00",
"updated": "2026-07-24T12:00:00",
"entry_count": 3,
"hash": "a1b2c3d4e5f6a7b8"
},
"tags": {
"editor": { "color": 82 },
"productivity": { "color": 214 }
},
"entries": [
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "nvim",
"cmd": "nvim",
"description": "Hyperextensible Vim-based text editor",
"rank": 10,
"tags": ["editor", "cli"],
"os": ["any"],
"install": { "apt": "neovim", "dnf": "neovim", "brew": null },
"url": "https://neovim.io",
"installed": true,
"created": "2026-07-24T10:00:00",
"updated": "2026-07-24T10:00:00"
}
]
}The file is human-readable and can be edited directly. The _meta.hash is a
SHA-256 truncated checksum of the entries array and is recalculated on every
write.
Warning
sowam stores all entry data, including any value entered with --license or --other-info, as plain text in ~/.sowam/data.json. The file is unencrypted.
Caution
Do not include ~/.sowam/ in public dotfiles repos, cloud-synced folders, or unencrypted backups. sowam prints a warning to stderr any time --license is used.
Do not store highly sensitive or critical license keys in sowam. Keys for expensive commercial software (Adobe, Windows, enterprise tools) can be used by anyone who obtains a copy of your data file. sowam is suitable for low-risk reference notes or easily replaceable keys, not for secrets management.
To restrict access:
chmod 600 ~/.sowam/data.jsonsowam is a single-file Python CLI in a pip-installable src-layout package.
sowam/
pyproject.toml pip build config (hatchling)
src/
sowam/
__init__.py
cli.py full implementation
docs/
sowam.1 man page
examples/ example data files and import lists
TODO.md roadmap
# Development install
pip install -e .
# Run directly without installing
python3 src/sowam/cli.py list
# Format
black src/sowam/cli.pyMIT — see the license header in src/sowam/cli.py or the License.
Important
Several components of this repository, such as documentation, have been developed with the use of an AI coding agent. For more information on AI-assisted development, read here: AI-assisted software development
Copyright 2026 jam-ware