tagmanager-cli 1.4.0

The Ultimate Command-Line File Tagging System - Transform chaos into order with intelligent file organization

🏷️ TagManager

The Ultimate Command-Line File Tagging System

Transform chaos into order with intelligent file organization

Features • Installation • Quick Start • Commands • Examples

---

🌟 Why TagManager?

Folder hierarchies force you to put a file in one place. Tags let a file belong to everything it actually is.

# One command to tag — one command to find
tm add report.pdf --tags work client-a q1 2024 final
tm search --tags work q1        # instantly surface it

TagManager stores tags in a lightweight JSON sidecar (~/file_tags.json) — no database, no daemon required — and ships a full command set for search, bulk operations, smart filtering, an interactive network graph, and a file-system watcher that tags new files automatically.

---

✨ Features

Category	What you get
Core	Add/remove/search tags, fuzzy path search, list & tree views
Bulk	Mass-tag with glob patterns, retag, bulk-remove — all with --dry-run
Auto-tag	Extension-based tag suggestions (60+ file types built-in)
Aliases	Normalize tag variants: py → python, js → javascript
Presets	Save named tag bundles and apply them in one flag
Filters	Duplicate sets, orphans, similarity (Jaccard), clusters, isolated files
Stats	Tag frequency, co-occurrence, ASCII bar charts & histograms
Visualizer	Interactive 2D/3D network graph in your browser — click to open files
Watch mode	Auto-tag files the moment they land in a directory
Move tracking	tm mv keeps tag records in sync when you rename files
Config	Full dot-notation config system with export/import
Shell completion	Tab-complete tag names, presets, and alias names

---

🚀 Installation

pip install tagmanager-cli

Commands are available as both tm (short) and tagmanager (long form).

Optional: Watch mode

Watch mode requires watchdog:

pip install tagmanager-cli[watch]
# or separately
pip install watchdog

Install from source

git clone https://github.com/davidtbilisi/TagManager.git
cd TagManager
pip install -e .

---

⚡ Quick Start

# Tag a file (auto-tags by extension too)
tm add main.py --tags backend core

# Tag everything matching a glob
tm bulk add "src/**/*.py" --tags python

# Find files
tm search --tags backend core     # either tag
tm search --tags backend --match-all core  # both tags

# Visual overview
tm ls --tree
tm tags --cloud
tm stats --chart

# Interactive network graph (opens in browser)
tm graph

# Watch a directory — auto-tag as files arrive
tm watch ~/Downloads --tags inbox

---

📖 Commands

tm add — Tag files

tm add <file> --tags <tag> [<tag>...]   # basic
tm add <file> --tags python --preset webproject  # combine with preset
tm add <file> --no-auto                 # skip extension-based auto-tags
tm add <file> --no-aliases              # skip alias resolution

tm search — Find files

tm search --tags python web            # files with EITHER tag
tm search --tags python --match-all    # files with ALL listed tags
tm search --path /projects/            # by path fragment
tm search --tags python --exact        # exact tag match (no fuzzy)

tm ls — List tagged files

tm ls           # flat table
tm ls --tree    # directory tree with inline tags

tm tags — Explore tags

tm tags                  # list all tags
tm tags --search py      # filter tags by name
tm tags --cloud          # frequency cloud
tm tags --where python   # which files carry this tag

tm stats — Analytics

tm stats              # summary
tm stats --chart      # ASCII bar charts
tm stats --tag python # deep-dive on one tag (co-occurrence, file types)

tm graph — Interactive network visualizer

Opens a self-contained HTML graph in your default browser.

tm graph                        # tag co-occurrence graph, 2D
tm graph --3d                   # start in 3D (toggle button in UI too)
tm graph --mode file            # file similarity graph (Jaccard)
tm graph --mode mixed           # bipartite file↔tag graph
tm graph --export gexf          # also export tag_network.gexf (Gephi)
tm graph --export graphml       # for Cytoscape / yEd
tm graph --min-weight 2         # only show edges with ≥2 co-occurrences
tm graph --output ~/graph.html  # save to a specific path

In the browser UI:

• Sidebar with 10 live filters (search, tag/extension multi-select, weight & degree sliders, cluster highlight, color-by)
• 2D / 3D toggle — WebGL via Three.js, handles thousands of nodes
• Click any file node → opens it in your OS file explorer
• Download GEXF / GraphML buttons (embedded, no server needed)

tm watch — Auto-tag new files

Monitors a directory with watchdog and tags files as they arrive.

tm watch                         # watch current dir
tm watch ~/Downloads             # watch a specific dir
tm watch . --tags inbox          # always add "inbox" to every new file
tm watch . --preset webproject   # apply a saved preset
tm watch . --no-auto             # skip extension auto-tagging
tm watch . --clean-on-delete     # remove tag entry when file is deleted
tm watch . --no-recursive        # top-level only
tm watch . --ignore "*.log"      # extra ignore patterns
tm watch . --plain               # plain text output (no Rich live display)

Rich live display shows a colour-coded event log (✚ created, → moved, ✖ deleted) with resolved tags. Press Ctrl+C to stop.

tm filter — Smart analysis

tm filter duplicates             # files with identical tag sets
tm filter orphans                # files with no tags
tm filter similar <file>         # files similar to this one (Jaccard)
tm filter clusters               # group files by shared tag
tm filter isolated               # files that share few tags with others

tm bulk — Mass operations

tm bulk add "*.py" --tags python          # tag by glob
tm bulk remove --tag deprecated           # remove a tag from all files
tm bulk retag --from js --to javascript   # rename a tag everywhere
# All bulk commands support --dry-run

Aliases, Presets, Move tracking

# Aliases — normalize tag variants
tm alias add py python
tm alias list
tm alias remove py

# Presets — named tag bundles
tm preset save webproject --tags python django web
tm preset apply webproject app.py
tm preset list

# Move tracking — keep the DB in sync
tm mv old/path.py new/path.py
tm clean             # remove entries for deleted files
tm clean --dry-run   # preview

Config

tm config list                         # all settings
tm config set display.emojis false
tm config set search.fuzzy_threshold 0.8
tm config export --file settings.json
tm config import team_settings.json
tm config reset                        # back to defaults

---

🎨 Examples

Network graph

Tag co-occurrence network — 42 nodes, 180 edges
Sidebar filters: search · tag multiselect · min-weight slider · degree range
                 color-by cluster · highlight cluster · show/hide node types
2D ↔ 3D toggle  |  Download GEXF  |  Download GraphML
Click file node → opens in Finder/Explorer

Watch mode output

Watching: /home/user/Downloads
  Recursive: True | Auto-tag: True | Clean-on-delete: False
  Always add tags: ['inbox']
Press Ctrl+C to stop.

[14:02:11] ✚ created ✓  report_q1.pdf  [inbox, pdf, document]
[14:02:45] ✚ created ✓  script.py      [inbox, python]
[14:03:10] → moved   ✓  script.py  →  processed/script.py

Tag cloud

☁️  Tag Cloud
★ python(15)  ◆ web(8)  ● documentation(5)  • config(3)  · backup(1)

Tree view

└── 📁 projects/
    ├── 📁 backend/
    │   └── 📄 api.py 🏷️  [python, web, api, core]
    └── 📁 docs/
        └── 📄 README.md 🏷️  [docs, markdown]

---

🏗️ Architecture

tagmanager/
├── cli.py                  # Typer CLI — all commands registered here
└── app/
    ├── add/                # tm add
    ├── bulk/               # tm bulk
    ├── filter/             # tm filter
    ├── search/             # tm search
    ├── stats/              # tm stats
    ├── graph/              # tm graph  (HTML generator, GEXF/GraphML export)
    ├── watch/              # tm watch  (watchdog integration)
    ├── alias/              # tm alias
    ├── preset/             # tm preset
    ├── autotag/            # extension → tag mappings
    ├── move/               # tm mv / tm clean
    ├── visualization/      # tree, cloud, ASCII charts
    ├── config/             # tm config
    └── helpers.py          # load_tags() / save_tags() — atomic JSON I/O

Storage: ~/file_tags.json (path configurable). Plain JSON — easy to inspect, back up, or version-control.

---

🧪 Testing

pytest tests/ -v                           # full suite (406 tests)
pytest tests/ --cov=tagmanager             # with coverage
pytest tests/test_graph_service.py -v      # graph module only
pytest tests/test_watch_service.py -v      # watch module only

406 tests across 21 test files. Watch mode integration tests require pip install watchdog.

---

🤝 Contributing

1. Fork the repo
2. Create a feature branch
3. Add tests
4. Open a PR

Bug reports and feature requests: GitHub Issues

---

📄 License

MIT — see LICENSE.

---

⭐ Star this repo if TagManager helps you stay organized!

Made by David Chincharashvili • Built with Typer and Rich