Tagging files

Basic tagging

tessera tag FILE... -t TAG[,TAG,...]

Tags are case-sensitive strings. A tag can be:

A plain word: lossless, favourite
A hierarchical path using / as separator: genre/rock, status/todo
A key=value pair: year=2024, rating=5, artist=Kraftwerk

Multiple tags can be given as a comma-separated list or by repeating -t:

tessera tag song.flac -t lossless,year=2024
tessera tag song.flac -t lossless -t year=2024

Recursive tagging

Tag all files in a directory (and its subdirectories):

tessera tag -r Albums/Kraftwerk -t genre/electronic

Tagging from stdin

tessera accepts file paths from standard input, one per line. This lets you combine it with find, fd, fzf, and similar tools:

fd -e flac | tessera tag -t lossless
find . -name "*.jpg" -newer reference.jpg | tessera tag -t new

Use -0 to read NUL-delimited paths (safer for filenames containing newlines or spaces):

fd -0 -e mp4 | tessera tag -0 -t video

Listing tags

# Tags on specific files
tessera tags FILE...

# All tags in the database
tessera tags

# JSON output
tessera tags --json FILE

The tags command is also available as tessera ls.

Removing tags

tessera untag FILE... -t TAG[,TAG,...]

Viewing full file info

tessera show FILE

Shows all tags, the file's database record, size, modification time, and file identity.

Renaming a tag

Renames the tag everywhere in the database:

tessera mv OLD_TAG NEW_TAG

Merging tags

Merge all occurrences of SOURCE into TARGET (destructive — prompts for confirmation):

tessera merge SOURCE TARGET
tessera merge SOURCE TARGET --force   # skip confirmation

Global options

Option	Description
`--json`	JSON Lines output
`--color auto\|always\|never`	Colour mode
`-q`, `--quiet`	Suppress informational messages, and log only errors
`-v`, `--verbose`	Extra detail, including debug-level log records
`--log-level SPEC`	Log verbosity, optionally per target; beats `TESSERA_LOG`, `-v` and `-q`
`--db PATH`	Override the database location
`--no-parents`	Do not include ancestor databases in queries

Log records go to stderr, never to stdout, so --json output stays pipeable. The command writes no log file: it has no lifetime worth a forensic trail, and tessera-web is the process that keeps one. The default level is warn, so an ordinary invocation says nothing beyond its own output; --log-level accepts the same per-target specs as the server, such as info,tessera::embedding=error.

Tessera