orvanitag/README.md

---
contexts:
- frrreee
projects: []
tags:
- fool
- writeme
---

# Orvani Tagger

(From עוֹרְבָנִי, the Hebrew name for th Eurasian Jay)

Platform independent, folder-based, and portable tagging system for organizing and searching files. The command line interface and organizing principles are heavily inspired by the todo.txt standard. 

Every file can be assigned projects, contexts, and tags and have a descriptive note.

Exactly like tasks in todo.txt, files can be categorized by freely defined contexts, defined by the
`@` prefix or projects, defined by the `+` prefix. In addition, the `#` prefix defines hashtags that can be assigned.

So a as an example an audio-file could be assigned to project `+album` and have a context of `@drums` and tagged with `#boombap`, `#lofi`, `#snare`. It's completely up to you how you use the different means of categorization.

## Installation

```
$ uv tool install 'orvanitag[all]'
```

The core only needs PyYAML and rich. Reading and writing embedded metadata uses optional extras: `audio` (pytaglib, needs the TagLib C library), `pdf` (pypdf), `office` (olefile, only for legacy `.doc`/`.xls`/`.ppt`) and `markdown` (python-frontmatter). Plugins whose extra is not installed are skipped.

## Command Line Tool

### Assigning Contextual Tags

Let's
```
$ otag add <file/path> [contextual tags ...]
```

Removing contextual tags from a file
```
$ otag remove <file/path> [contextual tags ...]
```