sowam - SoftWare Monitor CLI

Overview

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.

---

Features

• 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/git/url/…), 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 check scans $PATH and auto-updates the installed field for every entry
• Multiple output formats — table, JSON, YAML, CSV, HTML report (all stdlib, no external deps)
• Batch/scripting mode — --batch suppresses 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

---

Requirements

• Python 3.8 or later
• No external packages required

---

Installation

pip (recommended)

pip install sowam

pipx (isolated)

pipx install sowam

From source

git clone https://github.com/jam-ware/sowam
cd sowam
pip install -e .

---

Quick Start

# 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' \
    --os any \
    --rank 5 \
    --see-also LUKS --see-also GPG \
    --tag encryption --tag cryptography \
    --install-method git=https://github.com/veracrypt/VeraCrypt.git \
    --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.json

[!TIP] 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.

---

Subcommands

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 git install method

Run sowam <subcommand> --help for detailed per-subcommand usage.

---

Entry Metadata

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
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, git=URL, 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.

---

Color System

Rank-based (default)

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

Tag-based

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 tag

Browse 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-readable

Named color aliases include:

• red
• orange
• yellow
• gold
• green
• lime
• teal
• cyan
• blue
• navy
• purple
• violet
• pink
• magenta
• white
• gray
• black
• and more.

---

Tag System

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)

---

Searching

Positional query (get)

Matches the name and description fields:

sowam get vim
sowam get "task manager"

Filters

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.com

Apropos

Broad 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 terminal

Filters can be combined:

sowam get --tag cli --os linux --apropos "file" --rank 8

---

Installing Software

sowam 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 manager

sowam 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 / -G to 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's cmd field 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 with urllib.request and saves to ~/.sowam/downloads/.

Entries whose stored install methods don't include the selected package manager are skipped with a clear message.

Cloning Repositories

sowam clone handles entries stored with a git, gh, or github install method — it clones them into ~/.sowam/repos/ (or a path you specify):

sowam clone taskwarrior                        # clone one entry by name
sowam clone --all --tag cli                    # clone all CLI tools with a git method
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 URL

Downloaded 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.

---

Import / Export

# 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 --force

[!TIP] The import format is flexible: sowam accepts a full sowam JSON export, a bare JSON array of entry objects, or a single entry object.

---

Environment Variables

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.

---

Global Flags

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 File

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.

---

Security Notice

[!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.json

---

Development

sowam 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.py

---

License

MIT — 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