Metadata-Version: 2.4
Name: sowam
Version: 0.1.0
Summary: Personal software tracking CLI utility
Author-email: jam-ware <devops@jam-ware.com>
License: MIT
Keywords: cli,installer,package-manager,software,tracker
Classifier: Environment :: Console
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: System :: Software Distribution
Classifier: Topic :: Utilities
Requires-Python: >=3.8
Description-Content-Type: text/markdown

# sowam - SoftWare Monitor CLI

![Demo](examples/demo.gif)

## 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](examples/report.html)

---

## Requirements

- Python 3.8 or later
- No external packages required

---

## Installation

### pip (recommended)

```bash
pip install sowam
```

### pipx (isolated)

```bash
pipx install sowam
```

### From source

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

---

## Quick Start

```bash
# 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:

```bash
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:

```bash
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:

```bash
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:

```bash
sowam get vim
sowam get "task manager"
```

### Filters

```bash
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:

```bash
sowam get --apropos "fuzzy search"
sowam get --apropos terminal
```

Filters can be combined:

```bash
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:

```bash
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):

```bash
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

```bash
# 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`):

```json
{
  "_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:

```bash
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
```

```bash
# 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](#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](https://en.wikipedia.org/wiki/AI-assisted_software_development)

Copyright 2026 jam-ware
