Hydra User's Tutorial

This is a very quick tutorial on how to use the Hydra suite of image tagging applications.


Hydra is designed as a high performance, scalable tagging solution. It is designed to be able to work with thousands of images weather via its graphical interface (Hydra Desktop) or via its command line tools. The command line programs allow for further automation and scripting over groups of images.

Hydra maintains a central database in the user's home directory (SQLite files, usually in .hydradb). Every file that Hydra works with is fingerprinted (hashed) and it is with these fingerprints that Hydra associates tags. This has many benefits, the biggest being:

Command Line Tools

The hydra suite includes command lines programs. These programs can perform tagging operations and queries from the command line or from automated scripts/batch files.


The main command line tool is hydratag. This command can be used to tag and query image files. Running hydratag without parameters will show some basic help. Here are some useful code examples:

hydratag add files.jpg

Adds (fingerprints) the given file(s) to the database.

hydratag add dir

Adds all the image files in the given directory, and all its sub-directories.

hydratag add -t test files...

Adds the files, but also add the tag test to the files too.

hydratag tag -t test files..

Add the tag test to all the given files. -r tag can be used to remove tags, and -c can be used to clear all the tags for the supplied files.

hydratag list

List all the files (in the current directory and all its sub-directories) and their current tags.

hydratag list -q query

List all the files that match the given query (see the query section for how to contruct tag searches/queries)

hydratag list -x

List all the files, but use an XML file format as the output. Other formats that are useful include -f (just the file names) and -0 (thats a zero) (just the file names, but null terminated, suitable for xargs)

hydratag contains other commands that are not documented here (but are mentioned if you run hydratag without any parameters)


hydraweb can be used to generate static web sites. It will make collections of thumbnails and html files that are suitable for uploading to a web server. You can run it without any parameters for some basic help - more documentation will be added here in the future.

Hydra Desktop

The Hydra Desktop application is a powerful, interactive interface to the hydra tagging system. Its features and functionality are still in development and are best explored by simply running the application.

Tag Search/Query Syntax

Most hydra-based programs can accept a tag search (query) string for when doing various operations.

Currently, this query langauge is based on a rudamentary reverse-polish notation of sorts. Future versions may change this. This odd style is best described with a few query examples


A lone tag will match all records that have atleast that tag. In this example, this will match all the files that contain the family tag

work family or

This will match all entries that have either the work or family tags. Yes, the or command/operation is at the end.

family dog not and

This will match all the family files that are NOT tagged with DOG.


This is a special tag that only matches if the file has no tags at all.


This will match all files that have any tags that start with the work "vacation". So vacation-rome and vacation-paris would both match this search.