tag-mgr

tag-mgr is a terminal tag manager for Markdown files. It reads YAML tags from the top of Markdown files, builds a JSON index, searches that index, and can add or remove tags in a specific file.

The tags should be stored in YAML format at the top of the Markdown files:

title: Local LLM Laptop Benchmark - MacBook Pro 128GB vs Ryzen AI Max+ 395 vs RTX 5090 Laptop
date: 2026-06-22
tags:
  - local-ai
  - llm
  - hardware
  - benchmarks
  - macbook-pro
  - ryzen-ai-max
  - rtx-5090

YAML front matter with --- delimiters is also supported:

---
title: Local LLM Laptop Benchmark
tags:
  - local-ai
  - llm
---

# Notes

Language-marked YAML fences such as ---yaml and --- yaml are supported too:

---yaml
title: Vaazaar Fundraising
tags:
  - funding
  - vc
---

Install

After the package is published to PyPI:

python3 -m pip install tag-mgr

For an isolated command-line install, use pipx:

pipx install tag-mgr

From this repository for development:

python3 -m pip install -e .

Install shell completion after installing tag-mgr:

tag-mgr --install-completion
source ~/.bashrc

Shell Completion

tag-mgr supports shell completion through argcomplete.

For Bash, install completion with:

tag-mgr --install-completion bash
source ~/.bashrc

For zsh:

tag-mgr --install-completion zsh
source ~/.zshrc

Then typing this and pressing tab completes the option:

tag-mgr --sea<TAB>

Usage

Read tags from a file:

tag-mgr --version
tag-mgr --read --file notes/example.md

Build the index at the Git repository root:

tag-mgr --index

Build the index somewhere else:

tag-mgr --index /tmp/tag-index.json

Search for files related to a tag:

tag-mgr --search llm

Search for files that have all listed tags with &:

tag-mgr --search 'llm & hardware'

Search for files that have at least one listed tag with |:

tag-mgr --search 'llm | hardware'

Add or remove a tag from a Markdown file:

tag-mgr --add hardware --file notes/example.md
tag-mgr --remove hardware --file notes/example.md

By default, the index is stored as .tag-mgr-index.json at the Git repository root. Use --index-file PATH with --search, --add, or --remove to use a different index file. Use --root DIR to scan a directory other than the current Git repository.

Publish

Before publishing, update the version in pyproject.toml and tag_mgr/__init__.py, then document the release in CHANGELOG.md.

Install publishing tools:

python3 -m pip install -e '.[publish]'

Build and validate the package:

rm -rf dist build *.egg-info
python3 -m build
python3 -m twine check dist/*

Upload to TestPyPI first:

python3 -m twine upload --repository testpypi dist/*

Upload to PyPI:

python3 -m twine upload dist/*

For token-based upload, set:

export TWINE_USERNAME=__token__
export TWINE_PASSWORD=pypi-your-token