Metadata-Version: 2.4
Name: tag-mgr
Version: 1.0.0
Summary: Command-line tag manager for Markdown files.
Project-URL: Homepage, https://gitlab.com/avarf/tag-mgr
Project-URL: Repository, https://gitlab.com/avarf/tag-mgr
Project-URL: Issues, https://gitlab.com/avarf/tag-mgr/-/issues
Project-URL: Maintainer, https://gitlab.com/avarf
Maintainer: avarf
License-Expression: MIT
License-File: LICENSE
Keywords: cli,frontmatter,markdown,notes,tags
Classifier: Development Status :: 5 - Production/Stable
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Text Processing :: Markup :: Markdown
Classifier: Topic :: Utilities
Requires-Python: >=3.10
Requires-Dist: argcomplete>=3
Provides-Extra: publish
Requires-Dist: build>=1.2; extra == 'publish'
Requires-Dist: hatchling>=1.26; extra == 'publish'
Requires-Dist: twine>=5; extra == 'publish'
Description-Content-Type: text/markdown

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

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

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

# Notes
```

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

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

## Install

After the package is published to PyPI:

```bash
python3 -m pip install tag-mgr
```

For an isolated command-line install, use `pipx`:

```bash
pipx install tag-mgr
```

From this repository for development:

```bash
python3 -m pip install -e .
```

Install shell completion after installing `tag-mgr`:

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

## Shell Completion

`tag-mgr` supports shell completion through `argcomplete`.

For Bash, install completion with:

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

For zsh:

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

Then typing this and pressing tab completes the option:

```bash
tag-mgr --sea<TAB>
```

## Usage

Read tags from a file:

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

Build the index at the Git repository root:

```bash
tag-mgr --index
```

Build the index somewhere else:

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

Search for files related to a tag:

```bash
tag-mgr --search llm
```

Search for files that have all listed tags with `&`:

```bash
tag-mgr --search 'llm & hardware'
```

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

```bash
tag-mgr --search 'llm | hardware'
```

Add or remove a tag from a Markdown file:

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

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

Build and validate the package:

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

Upload to TestPyPI first:

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

Upload to PyPI:

```bash
python3 -m twine upload dist/*
```

For token-based upload, set:

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