Quick start

This page walks you through tagging your first files and finding them again in under five minutes.

1. Initialise a database

Go to the root of a directory tree you want to tag — your music folder, photos, or any other collection:

cd ~/Music
tessera init

This creates .tessera/db.sqlite3 in the current directory. Every file you tag must live somewhere inside this directory (or a subdirectory).

2. Tag some files

# Tag a single file
tessera tag song.flac -t lossless

# Tag with a key=value pair
tessera tag song.flac -t year=2024

# Multiple tags at once
tessera tag song.flac -t lossless,genre/rock,year=2024

# Tag a whole directory recursively
tessera tag -r Albums/Kraftwerk -t genre/electronic,year=1974

# Tag files piped from another command
fd -e flac | tessera tag -t lossless

3. List tags on a file

tessera tags song.flac

4. Find files by tag

# Simple tag query
tessera find lossless

# Combine tags
tessera find "lossless and genre/rock"

# Key=value comparison
tessera find "year>=2020 and genre/electronic"

Results are printed one path per line, ready for piping:

tessera find lossless | xargs -I{} cp {} ~/export/

5. Open the web interface

tessera-web ~/Music

Open http://localhost:4141 in your browser to browse, search, and tag files visually.

Next steps