Chee is a command line tool for managing and organizing photos.

How do you organize your photos? I have a bunch of folders with contents from various flash cards, because manually sorting alot of photos is too time consuming. Chee wants to help at this point. It can search photos from different directories by querying its image metadata. So the idea is to simply keep these flash card dumps and work with them.

Some features are:

  • no “application lock-in”; chee uses open formats for storing data so that it can be easily accessed using other (free or open-source) tools

  • search photos using a simple query language

  • manage named queries (called collections)

  • copy/symlink images into a custom folder structure

  • create thumbnails or scaled versions (creates new files, original files are not touched)

  • encrypt files using OpenPGP

  • tag and comment photos

  • create static html photo gallery

It is a simple program: the metadata of image (and other) files are put in a database which can then be queried more conveniently. But this already allows some useful features.

It is written in Scala and runs on the JVM so it is quite platform neutral. Chee uses two databases: sqlite for file metadata and a rec file for user metadata (tags and comments). It allows to query and print information from the database in very flexible ways. Still, in case you need raw data access, use sqlite cli tool or sqliteman to look at the sqlite database and rec utilities or any text editor to access user metadata.

Concepts

Properties

When chee sees a file, it extracts certain properties and uses these to answer queries. Every file is represented as a set of properties.

There are basic file properties that can be obtained from any file:

Standard file properties:
  • checksum a sha256 checksum of the file

  • location the location of a file

  • path the absolute file name

  • filename the name of the file (with extension)

  • extension the file extension

  • length the file size

  • lastmodified the last modified time of the file

  • added the time the file has been added to chee

  • mimetype the mimetype of the file

Then there are properties that are only applicable to image files:

Image roperties:
  • created the created timestamp. This timestamp is saved by the camera when taking the picture. The problem is, that there is no time zone information supplied. Thus this timestamp is considered being in the “current” time zone (the system default time zone).

  • make camera make

  • model camera model

  • width width of the image (pixel)

  • height height of the image (pixel)

  • orientation the orientation tag (integer)

  • iso the iso value

If image properties cannot be obtained from a file, they are ignored (they are then not part of the properties set of that file).

Custom metadata
  • tag a list of tags associated to a file

  • comment a comment on a file

Virtual Properties

Virtual properties are not extracted from an image, but computed from existing properties. They can be used in queries and format patterns. Since the query language does not support arithmetic, virtual properties provide a way to have predefined functions. See the chapters about queries and format patterns for more information.

Currently there are the following virtual properties:

pixel

It is the product of width and height and allows to query images based on their pixel size.

For instance, find photos with more than 5 mega pixel: pixel>5m.

encrypted

This property is present if the file is encrypted. It contains either pbc or pkc indicating that the file is password encrypted (the former) or public key encrypted (the latter). Files that are not encrypted don’t have a value for this property.

Locations

Locations are directories with images that chee queries by default.

Chee can be used to query images anywhere in the file system. But since most of the time photos are stored at the same places, chee can index them into a database and perform queries much faster. If you add a directory with images to the index, this directory is refered to as “location”. Chee tries to normalise these such that no nested location exists. For instance, if you add directory /a/b/c and then /a/b, chee will update the former location to /a/b.

Images from other directories can be “imported“ into a location. Chee simply copies the files and skips any duplicate by default.

Query

A query is a condition or a combination of them. A simple condition is a property-name,op,value tuple that can be matched against the properties of a file.

extension:jpg

The tuple would match every file with a JPG extension (case insensitive). It consists of a property name extension, a comparator : and a value jpg. Tuples can be composed using the usual boolean operation and, or and not. Compositions are grouped by parens.

(& extension:jpg width>2000)

This query would match every file with extension JPG and a width greater than 2000 pixels.

Names can be abbreviated to the shortest non-ambiguous term. So the example above could be written like this:

(& ext:jpg w>2000)

See the Properties section for a list of property names.

A not is specified by a ! in front of a condition. This inverts its subsequent condition.

(& ext:jpg !w<2000)

Use a | instead of & to combine conditions with or:

(| ext:jpg !w<2000)

With the exists operator (?) a property can be checked for existence.

extension?

This would match every file that has an extension.

Whitespace

A simple value definition must not contain whitespace or parens. If a value needs this, it must be quoted in single or double quotation marks.

model:'Nikon 1*'
model:"Nikon 1*"

Both are equivalent and are provided for convenience (ususally the shell’s quotation must be escaped). Within a quoted value, the quotation characters can be included using a backslash.

model:"Nikon \"1*"

Whitespace between condition elemens is optional. So model : Nikon and model:Nikon are the same.

Comparators

There are the following comparators.

:(like)

It compares strings case insensitive and allows to use the wildcard * to match zero or more characters. Properties that have numeric values are compared as strings. Date/Timestamps are converted to a standard pattern yyyy-MM-dd HH:mm:ss and matched against the input.

=(equal)

Compares strings case sensitive and converts non-string property values.

<,>(lower/greater than)

For numeric comparisons. Compares strings alphabetically. Dates/ Timestamps are converted to a numeric value before being compared.

~ (in)

Checks if a value is contained in a predifined set.

More about the ~ comparator, others are self explaining. The ~ can be used to abbreviate conditions like the following:

(| ext:jpg ext:png ext:gif)

is

ext~jpg;png;gif

The value must be an enumeration, where each item is separated by a semi-colon ;. If an item contains a semicolon, it must be escaped using a backslash \. If items contain whitespace the whole enumeration must be enclosed in quotes, as usual.

Values are always compared case insensitive; as with like without wildcards. The wildcard (*) character is not supported (it is not treated specially).

Special Values

For some properties, values can be specified in different ways.

pixel

The pixel property is the product of width and height. Values can be suffixed by m or mp to mean “mega pixel”.

pixel>5m pixel<2mp
length

The length property denotes the size of a file in bytes. For querying, numbers can be suffixed with either kb/k, mb/m, or gb/g to mean the corresponding size.

len>5m
dates

Specifying Dates

The date and time string is written in format year month day hour minute second. Year is specified with 4 digits, other groups with one or two digits. Groups are separated by exactly one non-numeric character except #. Often a dash is used for the date parts and a colon for the time parts (and both parts are separated by space or T), but any non-numeric character except # will do.

Example
2015-10-22 12:33:00

Certain parts can be omitted and will be initialised with a default value:

If the year is omitted, it is set to the current or last year, making it a date in the past. So in Februar 2015, the string 10-10 would be expanded to 2014-10-10, but 01-14 would yield 2015-01-14.

If parts are missing from the right, they are set to their first values. So 2015-01 is expanded to 2015-01-01 00:00:00 and 2015-05-12 12 to 2015-05-12 12:00:00 and so on.

Another option is to use date-keywords: reserved words that mean a specific date (that differs from year to year):

  • now yields the current date and time

  • eastersun yields the start of easter sunday of current year

  • ascension yields the day of ascension of the current year

  • whitsun yields the start of whitsun (sunday)

The last option is to calculate a date from another one. Specify a date as described above and add or subtract an amount of time. Searching for photos from last week, on could write:

date>now#-7d

The term now#-7d means to subtract 7 days from now which is the current date. All time parts of the result are set to 0. The # character separates date definition and the amount to add/subtract. The now keyword can be omitted, so

date>-7d

is the same. Instead of subtracting you can also add amounts.

The following units can be used to mean years, months, day, hours, minutes and seconds, respectively: y, m, d, h, min, s. Subtracting/adding date parts will set the time to 0 and missing date parts to its current values. For example, on November 06. 2015 the term -1y would yield 2014-11-06 00:00:00. Subtracting monthes keeps the current year and day, instead. If no unit is specified, it defaults to d.

Comparing Dates

If the like comparator is used, the date value of the photo is converted to a string following the standard pattern yyyy-MM-dd HH:mm:ss, for example 2015-10-23 14:40:22, and this is matched against the input pattern.

When other comparators are used, dates are converted to a point in time and compared numerically. Local date/times (the created property) are considered in default (system) time zone. Therefore, using like, the input string is used as is and is not tried to expand to a complete date/time value. For example, the following two queries could yield same results (“could” because of time zone):

date>2015-10   <=>    date:2015-10*

If the comparator is not like, an error is raised, if the date/time cannot be expanded. Using like with created compares it to the exact value as extracted from the file, where other comparators parse this value into a local date and place it into the system time zone.

identifiers

Properties can be compared against each other. A special value is used to indicate that a value should be interpreted as an identifier.

Example
width>'height

This condition compares the width against the height property of a file. The quote ' without a closing one is used to indicate that the value to compare width to should be looked up with identifier height.

Macros

Macros are query conditions that expand to some other query condition. They are used to capture common (and longer) conditions in a succinct way. There are macros that use special property names and those that add comparators. Special property names cannot be used in format patterns, since they are not real properties.

There are the following macros:

date

This is a special property name that handles the case when there is no created property (as provided only by exif data). It then falls back to the lastmodified timestamp.

So the simple condition date:2015* is expanded into:

(| created:2015* (& !created? lastmodified:2015*))

The date macro cannot be specified in a format pattern literally, but it can be encoded using a condition directive:

date in format pattern
~[created~;~#created~fyyyy-MM-dd HH:mm~;~#lastmodified~fyyyy-MM-dd HH:mm~]

See Format Patterns for details.

range

The / comparator abbreviates conditions that check range containment. For example, to find files between 2 and 3 mega pixels one could write this:

(& pixel>2mp pixel<3mp)

With the / comparator, this can be abbreviated:

pixel/2mp--3mp

This works by parsing the value into a range: specifying the lower and upper bound separated by two dashes --. That means that a single value may not contain a double dash, since it is interpreted as the separator.

Once the value is recognized being two values, the condition is expanded in the standard range condition:

(& pixel>2mp pixel<3mp)

There is a special syntax for date ranges. First of all, the standard range syntax works:

date/2015-10-10--2015-10-20

This would create two date values, as described above in how date/times are specified. Then it is expanded to an and condition. Since the comparators > and < are used, dates are compared numerically and local dates are considered in the default (system) time zone.

Then, you can specify the second date by calculating from the first date. Normally, a term like +7d would subtract 7 days from the current date. But if used in a range (the upper bound date), it will use the lower bound date as the reference value. For instance:

date/2015-10--+7d

would expand to the following:

date/2015-10-01--2015-10-08
id

The id macro is useful when comparing file checksums. For each file its sha256 checksum is generated and added to the property list (and to the index). This value can be used as a file id.

When doing exact searches using these ids it is inconvenient to specify the full checksum, which is a 64 character string. To uniquely identify a file, the first 8-10 characters are usually sufficient (unless you have really really many files). So one can use the like comparator in most cases. The id macro does this:

id:15e59afb0

expands to

checksum:15e59afb0*

If the value is a complete checksum, then the equal operator is used instead:

id:04343d3ff0102c26eb355db5333266e77e6ef06db3c9bcbcc0bd30b7a1c92f38

expands to

checksum=04343d3ff0102c26eb355db5333266e77e6ef06db3c9bcbcc0bd30b7a1c92f38

The comparator that is used with id does not matter. It is always expanded in a like or equal.

Collections

A collection is a user defined query macro. Chee allows to manage a custom set of macros for storing complex queries behind a simple name. A collection therefore consists of a query condition and a name.

Another way is to think of a collection as a tag: it associates a name to a set of files. The set of files is not fixed, but the result of executing a query.

A collection can optionally have a description. The collection command allows to manage collections. A collection is referenced in a query using the identifier collection followed by any comparator followed by the collection name.

For example, there is a collection with name holidays2015 and query date/2015-08-14--2015-08-28. Then you can use this in the find command:

chee find coll:holidays2015

This is would be expanded into this form:

chee find date/2015-08-14--2015-08-28

A collection may reference other collections, but be careful to not create cycles. Since collections are just queries, they can be combined with other conditions.

chee find (& coll:holidays2015 model:nikon*)

See the collection command for editing collections.

Format Patterns

Format patterns are a flexible way to print property maps. A format pattern is a string with literal text and directives. A directive specfies how to print a certain value from the property map.

Format patterns are used by a few commands (i.e. the find command) to generate human readable output for a property map.

A directive always starts with a tilde ~ character followed by more characters that control its behaviour. There are basic directives that print a value of a property map and there are directives that change the output of other directives. This makes creating output very flexible.

Since a directive starts with ~, to really print a ~ it must be doubled, like ~~.

Value Directive

The ~# directive returns the value of a property. For example, the following prints the value of the filename property:

~#filename

Given a property map, it would look up the value for filename and interpolate it into the string.

As in queries, the identifiers can be abbreviated to the shortest non-ambiguous term.

Formatting Values

Another directive can be appended to the ~# directive, to further format the value. For example, the width property has a numeric value and could be printed with padded 0.

~#width~f%08d

would print 00002048 for a width of 2048. The special format string %08d is a printf-style format string.

This is more useful for date/time values that should be printed using a custom pattern. For example

~#created~fyyyy

would only print the year of the created property in 4 digits. A description of possible date patterns can be found here.

Readable Directive

To print the file size, the ~#length directive would print the number of bytes of the file. But this is usually not a very user friendly value. And others, like date and times are similiar.

That is why the ~: directive exists. It can be used to print more user friendly output: dates/times are printed in a specific pattern and the length value is converted to a string like “7.1mb”. Likewise the pixel property is printed in abbreviated form: instead of 4100000 it prints 4mp.

Newline Directive

The directive ~% prints a newline character. This is useful to generate multi line output.

Fixed Width

The ~xy directive, where x is a number and y is either l or r (for “left” and “right”) wraps another directive and cuts or pads its output such that it is exactly x characters long. If l is specified, shorter strings are padded with spaces on the left. If r is specified, spaces are appended to shorter strings to yield the requested size.

If the string is too long it is cut at some point and characters are removed until the required length is reached. The point where deletion started is marked with an ellipsis character.

For example:

>~20l~#filename<

would print for the value “test.jpg”

>            test.jpg<

and for a value “/home/pictures/2014/winter/test.jpg”

>/home/pi…er/test.jpg<

The > and < are not part of the directive; it is normal literal text.

Max Length Directive

This directive is similiar to the fixed width directive, but will only cut strings longer than the specified length. It is written xmy where x is the maximum length and y is either l for cut from left or r for cut from right.

~8mr~:checksum

would print the first 8 characters of the checksum

a90545b8

Sequence Directive

The ~{ directive can be used to group more directives into one. It must be closed by a matching ~}.

This is useful, if you want to apply a modifying directive like the fixed-width directive to multiple directives.

~20l~{~:width x ~:height~}

This applies the fixed-width directive to the concatenation of the string inside ~{ and ~}.

Conditional Directive

There is a directive that can be used to print something if a value exists for a property and a different thing in case it does not exist. The directive looks like this:

~[<condition>~;<ifTrue>~;<ifFalse>~]

There are three directives inside ~[ and ~] that are separated by a ~;.

The condition directive is a property name. In case there is a value for this property, the ifTrue directive is used, otherwise the ifFalse directive.

Example
~[model~;~:model~;no model~]

This would print the camera model if it exists and otherwise the literal text no model.

Loop Directive

If you want to print all properties, the ~@ directive can be used. It must be followed by a sequence directive is evaluated for every known property identifier.

Inside the sequence directive, there are two more property values available: ident and value refering to the current property identifier and associated value.

For example, this print all properties in a comma separated line:

~@~{~#value,~}

It results in something like this:

,2012-11-26 13:50:19,jpg,CIMG2590_s.JPG,1536,100,2015-12-21T21:33:04Z,48746,/workspace/projects/chee2,CASIO COMPUTER CO.,LTD,image/jpeg,EX-Z750,top, left side (horizontal / normal),/images/CIMG2590_s.JPG,2048,95254d11a2916bff2357ea3f1572d366398de17150b8ef11d5f11ef8061f371b,

It would be nicer, if the last comma is not printed. For this the stop directive ~^ can be used:

~@~{~#value~^,~}

It tells the loop directive, that everything following it should only be printed if the loop is not finished. If it is on the last element, everything after the stop directive is ignored. The stop directive itself prints nothing.

The loop directive skips virtual properties. To include them, a * can be added:

~@*~{~#value~^,~}

With the newline directive, it is easy to print every property on its own line. And a fixed-width directive can provide a nicely formatted output:

~@~{~20r~{~#ident:~} ~:value~^~%~}

This prints all properties:

added:               2015-12-22 15:33:37
created:             2012-11-26 13:50:19
extension:           jpg
filename:            CIMG2590_s.JPG
height:              1536
iso:                 100
lastmodified:        2015-12-21T21:33:04Z
length:              2.3mb
location:            /workspace/projects/chee2
make:                CASIO COMPUTER CO.,LTD
mimetype:            image/jpeg
model:               EX-Z750
orientation:         top, left side (horizontal / normal)
path:                /images/CIMG2590_s.JPG
width:               2048
checksum:            95254d11a2916bff2357ea3f1572d366398de17150b8ef11d5f11ef8061f371b

The variant ~@! of the loop directive will skip non-existing properties. The body of the loop is only evaluated for existing properties.

Within the loop directive, the value identifier can only be used with the ValueDirective or ReadableDirective. When using the ValueDirective it is not possible to use the ~f format pattern.

Quote Directive

The loop directive is intended to print output that is parsed by other programs. It is often required to put strings in quotes to protect whitespace (in filenames for example). But numeric values don’t need to be quoted (often it is more convenient, if not).

The quote directive ~" or ~' wraps the output of the following directive in double and single quotation, respectively, if it is not numeric. Numeric values are not wrapped.

For example, this can be used to format properties in a CSV style:

~@~{~"~#value~^,~}

Prints

"","2012-11-26 13:50:19","jpg","CIMG2590_s.JPG",1536,100,"2015-12-21T21:33:04Z",48746,"/workspace/projects/chee2","CASIO COMPUTER CO.,LTD","image/jpeg","EX-Z750","top, left side (horizontal / normal)","/images/CIMG2590_s.JPG",2048,"95254d11a2916bff2357ea3f1572d366398de17150b8ef11d5f11ef8061f371b"

Empty Directive

Since the value directive ends in an identifier, it is not possible to write literal text immediately following it, because it would be interpreted as part of the identifier. In order to do this, use the empty directive ~.. It prints nothing and can be used to separate identifiers from literal text.

Example
~:width~.x~:height

would print

2048x1536

Predifined Formats

These directives allow for very flexible output control. If patterns get too complex, they can be stored in the configuration file and referred to by name. Chee also provides a few patterns for some common uses:

  • oneline prints one line with columns of some of the properties

  • lisp prints a property list of all properties as a lisp data structure

  • detail prints all properties, each on one line

  • paths prints only the absolute filenames separated by newline

If you want to add your own bookmarks, add them in the configuration file to the key chee.formats. For example:

chee {
  formats {
    mycsv : "~@~{~\"~:value~^,~}~%"
  }
}

Then, whenever there is a pattern to be specified, you can use the name mycsv to refer to this pattern.

Metadata

Chee allows to attach custom metadata, tags and comments, to files.

This data is stored in a plain text file using the rec format. It is attached to the contents of a file, rather to its name. Thus, if files are moved or duplicated, the tags and comments are preserved. It also means, if files are modified all original tags and comments are “gone”: they are in the database, but not attached to the modified file.

Here is a sample file:

Sample metadata file
Checksum: 7c90e5fad6b2386e00e990fb28722bada270def72bb61e58d1d84d353972221b
Comment: funny ride
Tag: car
Tag: bike

Checksum: d13081ea54417bd5f06f536ac56f3a064dea733411c102475b4ff0d337d96125
Comment: funny ride
Tag: car
Tag: bike

This contains two entries, that each add a comment and two tags to a file. The file checksum is required, because it identifies the contents of a file. Tags and comments are optional. Tags can occur multiple times, but comments at most once. The order of the fields does not matter.

This format has some advantages:

  • it is simple and can be easily edited by any text editor

  • gnu recutils can be used to query the data (besides chee) making it easy to integrate with/migrate to other tools

  • plain text remains accessible, even once the tools are gone

But it comes at the cost that searching and modifying is slower than with other options.

Tags and comments can be refered to in normal queries. It is implemented by a macro that replaces tag and comment conditions with a checksum condition, that is created by searching the metadata file first.

When used in format patterns, tags are wrapped by a | characters. So multiple tags can be distinguished: |car|bike|.

Metadata can be edited using chee’s meta command or a text editor. The file is by default in chee’s config dir, called metadata.rec.

Encryption

Chee can encrypt (and decrypt, of course) your files. It uses OpenPGP which means you can use other (free) tools like gnupg to decrypt the files.

Chee supports public key encryption and password based encryption. It utilises the bouncycastle library, that provides a pure Java implementation of the OpenPGP standard.

While usually all modifications to files are non-destructive, the notably exception is encrypting: When chee encrypts a file, the original file is deleted! And likewise when decrypting a file, the encrypted file is deleted.

When a file is encrypted, a new file is written with an extension appended to the original file name. Chee uses this extension to distinguish the encryption method. If the file is indexed only the path property of that file is updated to reflect the new encrypted file. All other remain those of the original file. That allows to still search encrypted files.

A virtual property encrypted is provided so that you can easily find encrypted files. It simply looks at the path property and checks its extension.

Commands that operate on files (like view, thumb, etc) always skip encrypted files by default. You can change that by adding options to decrypt them instead. Then the files are decrypted to a temporary directory that can be configured in the configuration file.

Note that this temporary directory is not cleaned automatically. The clean command can be used for this.

There exists two ways to specify passwords in the config file so that you don’t need to type them in all the time.

  • Put them in a plain text file and reference this file in the configuration file. Only the first line is read from that file and used as password.

  • Specify a system command that returns the password with its output. Then you can put the password in an encrypted file and use a command like gpg -d mypassfile.gpg to return the password. This works well with the pass password manager, if you use this.

Please see the configuration chapter for related configuration values.

The keys for pubkey encryption are retrieved from files. These files are by default ~/.gnupg/chee-pubring.gpg and ~/.gnupg/chee-secring.gpg. They are expected to be in OpenPGP format (either ascii-armored or binary). When using gnupg, you can create them via the --export command:

Export Keys
gpg2 --export [keyid] > ~/.gnupg/chee-pubring.gpg
gpg2 --export-secret-keys [keyid] > ~/.gnupg/chee-secring.gpg

The secret key will still be password protected and a password must be given when decrypting files using the private key. The location of the files can be changed in the config file.

Configuration

This documents how chee is configured.

Chee reads a configuration file from the following locations:

  • $HOME/.chee.conf

  • $HOME/.config/chee/chee.conf

The first existing file is used. This is the user configuration. Chee never writes to this file, it is only read on start. But another config file is created (by default at $HOME/.config/chee/system.cfg) where chee stores data.

A config file can be in three formats:

  • java properties

  • json

  • hocon (a json superset)

The HOCON format is probably the most convenient of the three for us humans. Here is the default config file in HOCON format:

Default Config File
chee {

  # The working directory to store some data. By default the index
  # database is put there as well as some other things
  workingdir : ${user.home}"/.chee-work"

  # The config dir is used to store system configuration and the user
  # config file is looked up in this directory.
  configdir : ${user.home}"/.config/chee"

  # Temporary data that is safe to remove at any time
  tmpdir : ${chee.workingdir}"/tmp"

  # The directory the scale and thumb command use to store its output
  # files.
  scaleddir: ${chee.workingdir}"/scaled"

  # The name of the index database. By default it is in the working
  # dir.
  dbfile : ${chee.workingdir}"/index.db"

  # The name of the system configuration file. By default it is stored
  # in chee's configdir.
  system-config : ${chee.configdir}"/system.cfg"

  # Chee uses logback for logging. A logback config file can be
  # specified to have full control about how logging is done.
  logConfig : ${chee.configdir}"/logback.xml"

  # If `logConfig' is not used, chee defaults to something that is
  # configured to write into this file.
  logFile : ${chee.workingdir}"/chee.log"

  # If `logConfig' is not used, chee logs at this level.
  logLevel : "info"

  # The file containing the custom metadata: tags and comments. This
  # as a plain text file in “rec” format:
  #
  # https://www.gnu.org/software/recutils/manual/recutils.html#The-Rec-Format
  #
  # It can be manually edited conveniently using any text editor. The
  # “recutils“ provide utilities to manipulate and query this file.
  metadata-file : ${chee.configdir}/"metadata.rec"

  # One of FastScale, Lanczos3,  BSpline, Bilinear or Bicubic
  scalemethod {
    thumb : "fastscale"
    scale : "bicubic"
  }

  # Commands to open/browse files. If not defined it defaults to the
  # current desktops handler to open the file. If specified, use %s as
  # a placeholder for the file(s)/uri(s) (e.g. 'firefox %s'); only the
  # last occurrence of %s is replaced.
  programs {
    # A command to browse files. Use %s as placeholder.
    browser : ""
    # A command to edit files. Use %s as placeholder.
    editor: ""
    # A command to view images. Use %s as placeholder.
    viewer: "feh -. %s"
  }

  queries {
    # When searching directories on the file system, skip hidden
    # files/directories and include only image and video files.
    file-default : "(| encrypted? (& !filename:.* (| mimetype:image/* mimetype:video/*)))"

    # The scale command should only be applied to images.
    scale-default : "mimetype:image/*"

    # The thumb command should only be applied to images.
    thumb-default : ${chee.queries.scale-default}

    # The gallery command is only applied to images
    gallery-default : ${chee.queries.scale-default}
  }

  formats {
    # The pattern to use with find command if the --pattern option is
    # omitted.
    default-find-format : "oneline"

    # The pattern used to print the output of the metadata database
    default-metafind-format : "detail"

    default-scale-format: "oneline-no-location"

    default-thumb-format: "oneline-no-location"
  }

  repo {
    # This denotes the repository root directory. This is set by chee
    # on start if it is invoked inside a repository (a directory
    # containing the directory `.chee'). You should not set it your
    # config file.
    root : ""

    # When in "repository mode", do not allow to add locations outside
    # the repository root. It can be set to false for a repository to
    # allow it.
    restrict-to-root : true
  }

  crypt {

    # The default strategy for encryption. There are two values
    # allowed (case insensitive):
    #
    # - pubkey
    # - password
    #
    # If it is `password' the `default-password' and `algorithm' are
    # used if not overriden using options. If this is not set, an
    # error is raised. If it is `pubkey' then a public key is needed
    # which is retrieved from `public-key-file' using `key-id'.
    default-encryption : "pubkey"

    # The pgp key id. Can be part of the user-id or key ID, must
    # uniquely identify a key in the key ring.
    key-id : ""

    # The keyring file for public keys. This can be a in ascii armored
    # or openpgp file format. Note to gnupg2.1+ users: the new keyring
    # file format (pubring.kbx) is not supported by chee. Please
    # export your keys to a standard format using `gpg2 -o
    # chee-pubring.gpg --export [keyid]'.
    public-key-file : ${user.home}"/.gnupg/chee-pubring.gpg"

    # The keyring file for the secret keys. This can be in ascii
    # armored or openpgp file format. Note to gnupg2.1+ users: the new
    # keyring file format (in private-keys-v1.d) is not supported by
    # chee. Please export your keys to a standard format using `gpg2
    # -o chee-secring.gpg --export-secret-keys [keyid]'. The private
    # keys are still password protected (if you chose so)!
    secret-key-file : ${user.home}"/.gnupg/chee-secring.gpg"

    # The file containing the password to access the private key in
    # `secret-key-file'. The first line in the file is used as
    # password.
    secret-key-pass-file : ""

    # A system command that retrieves a password used to access the
    # private key in `secret-key-file'. If this is set,
    # `secret-key-pass-file' is ignored. The first line of the output
    # of the command is used, other output is
    secret-key-pass-command : ""

    # A default passphrase file to use with password-based
    # encryption. The first line in the file is used as password.
    default-passphrase-file : ""

    # A system command that retrieves a password used for password
    # based encryption. If this is set, `default-passphrase-file' is
    # ignored. The first line of the output of the command is used,
    # other output is ignored.
    default-passphrase-command : ""

    # The algorithm to use when using password based encryption. The
    # following values are possible (case insensitive):
    #
    # - AES128
    # - AES256
    # - Twofish
    # - Blowfish
    # - DES3 (= Triple-DES)
    # - IDEA
    # - CAST5
    # - CAMELLIA128
    # - CAMELLIA256
    algorithm : "AES256"

    # The directory where encrypted files are decrypted to do certain
    # tasks (view, scale, etc).
    decrypt-temp : ${chee.workingdir}"/decrypt"
  }
}

The HOCON format allows to create a hierarchical layout, where a key is a path. Path elements are separated by a dot .. So writing

chee {
  formats {
    key = "test"
  }
}

is the same as

chee {
  formats.key = "test"
}

or

chee.formats.key = "test"

This way it translates easily into java property files. More detailed information about the HOCON format can be found here and in its specification.

All config values are inside the chee { … } namespace. The two important properties are workingdir and configdir. The first defines the directory where chee can store work-data. The latter names a directory where chee stores user data. The difference is that workingdir contains data that can be removed without really loosing information. For instance, the index database is stored at workingdir, because it can be derived from the image files. And configdir contains user data that cannot be deleted safely.

Any value in the config file can be overridden by a system property.

Repository Mode

You can restrict chee to work only on a specific folder, the repository. A repository is a directory that has a .chee directory as its direct child. So a repository can be created by simply doing mkdir .chee.

On start chee looks for a .chee directory in the current working directory and above. If it is found, the chee configures itself by setting chee.configdir to .chee and chee.workingdir to .chee/work. The configuration file is read from .chee/chee.conf. If a config file doesn’t exists, an empty one is used.

The repository is isolated from global chee data and only directories below the repository folder can be added. The repository contains the images as well as chee data and can be moved around in the file system. When files inside a repository are indexed, file names relative to the repository root are stored.

By default only directories inside the repository can be added as locations. But this check can be removed by setting chee.repo.restrict-to-root to false (in .chee/chee.conf). Note that this breaks the isolation, because the index must use absolute paths to reference files outside the repository. This means the repository cannot be renamed or moved around.

Logging

Logging is configured via another configuration file that is by default at ${chee.configdir}/logback.xml. If this file does not exist, chee simply logs into a logfile. Only very few logging is done by default.

Two things can be controlled via the configuration file: where the log file should be (key chee.logFile) and the log level (key chee.logLevel). The log file is by default in chee’s workingdir and the default log level is INFO. This logs only very little. If you encounter strange behaviour, try setting the chee.logLevel to DEBUG or even TRACE to see more log output. If you set it to OFF, no logging is done.

You can also specify a custom logging configuration by providing a logback.xml file. How logging can be configured is beyond the scope of this manual. You can read it up here.

System Properties

System properties can be specified by using the environment variable CHEE_OPTS. This is added to the java command that starts chee. It can be used to override config values for the next run of chee.

For example to change the log level, you could do

CHEE_OPTS=-Dchee.logLevel=TRACE chee find …

Since the configuration file is used to configure logging, the process that reads the configuration cannot log itself. If you like to see which file chee is really reading, set a system property chee.debugConfig=true.

Example
CHEE_OPTS=-Dchee.debugConfig=true chee config

Custom config file

You can skip chee config file lookup by specifying a config file using the system property chee.config. If you specify a non-existing file, an empty configuration is used. This will always override any other config file, be it a .chee or the global one.

Commands

help

Provides access to specific help pages and the complete manual.

Usage
Usage: help [options] [<name>]

Note: Use `chee help' for detailed help topics. This is a quick option
overview.

  --usage
        Show usage
  --html
        Show the manual page in html (opens the browser).
  -c | --command
        See help for a command
  -a | --about
        See help about a concept topic.
  <name>
        The name of a page or command; or `manual' to open the
        complete manual in a browser.

Some manual pages describe the basic concepts of chee. They can be opened using --about. Help pages about specific commands open with the --command switch. By default (if no switch is present) command pages are requested.

The --html can be used to request html pages that are opened in a browser. By default, the text version is printed to stdout.

The name manual is special, it will always start a browser with the complete manual (all pages combined in one html). There is no text version.

Complete Manual
chee help manual

Choose from the following concept pages:

  1. property

  2. location

  3. query

  4. collection

  5. format

  6. encryption

  7. config

And here is a list of commands:

  • add

  • clean

  • collection

  • config

  • decrypt

  • encrypt

  • find

  • gallery

  • help

  • import

  • info

  • meta

  • mktree

  • mv

  • rm

  • scale

  • sync

  • thumb

  • view

find

Executes a query against all locations or a directory.

Usage
Usage: find [options] [<query>]

Note: Use `chee help' for detailed help topics. This is a quick option
overview.

  --usage
        Show usage
  -f <value> | --file <value>
        A directory to search instead of the index.
  -r | --recursive
        Find files recursively. Only applicable if `-f` is specified.
  -i <value> | --indexed <value>
        Find indexed or not indexed files. Only applicable if `-f' is
        specified.
  -a | --all
        When used with `-f', ignore the default query, otherwise
        select non-existing files.
  --skip <n>
        Drop the first n items. This is applied before `first'.
  --first <n>
        Limit output to the first n items.
  -p <value> | --pattern <value>
        The format pattern.

  <query>
        The query string. See the manual page about queries for more
        information.
Example
chee find created:201410*

Find searches by default all locations. If --file is given, it searches this directory instead. Note that using --file takes longer, since the directory must be traversed. Without -f an index is used and searching this is much faster. If you use --file you can also specify --recursive to recursively traverse the directory and --indexed true|false to find files that are indexed or not. You can also specify a single file to --file, then a query and a --recursive flag are simply ignored.

The option --all has two meanings, depending on whether --file is specified or not: Normally with --file, the directory is scanned for image and video files and all other are skipped. This is done by using a default query and with --all this default query is ignored. The default query can also be changed in the configuration file; see the configuration chapter for details.

If --file is not specified, the index is searched and non-existing files are not in the result. Then --all will ignore this and non-existing files show up in the result.

With --first the result can be limited to the first n files.

The output can be controlled with a format pattern, specified by the --pattern option. Please see the chapter on Format Patterns on how to use this. If no pattern is specified, a default pattern is used which lists certain properties of the files, one file per line. The value for --pattern can be a reference to a pattern in the configuration file or a pattern definition. There are three predefined patterns: oneline (the default), detail and lisp. If the pattern is not one of these, it is tried to find in the configuration file and then it is used as a pattern itself.

The query is used to search a directory or the index. If multiple conditions are given, they are wrapped in a (& …). Please see the page abount queries for details.

Other commands that operate on a set of files usually share these options.

view

View the images with an external image viewer.

The view command is just like find, but instead of listing it runs an external program to view the resulting files.

Usage
Usage: view [options] [<query>]

Note: Use `chee help' for detailed help topics. This is a quick option
overview.

  --usage
        Show usage

Find options:
  -f <value> | --file <value>
        A directory to search instead of the index.
  -r | --recursive
        Find files recursively. Only applicable if `-f` is specified.
  -i <value> | --indexed <value>
        Find indexed or not indexed files. Only applicable if `-f' is
        specified.
  -a | --all
        When used with `-f', ignore the default query, otherwise
        select non-existing files.
  --skip <n>
        Drop the first n items. This is applied before `first'.
  --first <n>
        Limit output to the first n items.

Decrypt options:
  -d | --decrypt
        Enable transparent decryption.
  --method password|pubkey
        The encryption method: either pubkey or password. The default
        value is taken from the config file or is `pubkey'.
  -W | --passprompt
        Always prompt for a passphrase. Do not use the
        default-passphrase-file from in the config file. Only
        applicable when password-based encryption is used.
  --key-file <file>
        The file containing the secret key. The openpgp formats (ascii
        and binary) can be used.
  --secret-key-pass <file>
        The passphrase file to access the private key. If not
        specified, it is prompted for.
  --passphrase <file>
        Specify a passphrase file to use for password-based
        encryption. The `-W' option overrides this.

  <query>
        The query string. See the manual page about queries for more
        information.
Example
chee view date:201410*

The query definition is the same as with the find command. So both commands can be used interchangeably.

The image viewer program is defined in the config file under the key chee.programs.viewer. It should be the program name followed by some options. The files are appended to the arguments arguments. By default the feh image viewer is used and started with feh -. to enable auto resizing.

By default, all encrypted files are skipped. With -d those files are tried to decrypt. The Decryption options can be used to specify how to decrypt. Since there are two encryption methods, it is possible to use both or just one. If there are only options for one method given, the other is not used (meaning these encrypted files are skipped).

Create a html photo gallery.

Usage
Usage: gallery [options] [<query>]

Note: Use `chee help' for detailed help topics. This is a quick option
overview.

  --usage
        Show usage

Find options:
  -f <value> | --file <value>
        A directory to search instead of the index.
  -r | --recursive
        Find files recursively. Only applicable if `-f` is specified.
  -i <value> | --indexed <value>
        Find indexed or not indexed files. Only applicable if `-f' is
        specified.
  -a | --all
        When used with `-f', ignore the default query, otherwise
        select non-existing files.
  --skip <n>
        Drop the first n items. This is applied before `first'.
  --first <n>
        Limit output to the first n items.

Decrypt options:
  -d | --decrypt
        Enable transparent decryption.
  --method password|pubkey
        The encryption method: either pubkey or password. The default
        value is taken from the config file or is `pubkey'.
  -W | --passprompt
        Always prompt for a passphrase. Do not use the
        default-passphrase-file from in the config file. Only
        applicable when password-based encryption is used.
  --key-file <file>
        The file containing the secret key. The openpgp formats (ascii
        and binary) can be used.
  --secret-key-pass <file>
        The passphrase file to access the private key. If not
        specified, it is prompted for.
  --passphrase <file>
        Specify a passphrase file to use for password-based
        encryption. The `-W' option overrides this.

Gallery options
  -c | --concurrent
        Process files concurrently.
  --thumb-size <width>x<height>
        The size for thumbnails. Default is 100x100.
  --scale-factor <value>
        Scale images by this factor.
  --scale-maxlen <value>
        Scale image such that the longest side of the image is not
        more than `maxlen'. Default is set to 1400.
  --no-scale
        Don't scale images and use original files.
  --link-original
        Provide links to the original picture. This requires to
        include all original files into the gallery folder.
  --template <file>
        A custom mustache template for creating the gallery page.
  --write-template
        Write the default template to current directory or to the file
        specified by `--out'. If this option is set, only the template
        is written and nothing else is done.
  --theme <value>
        Choose a css theme. Based on bootstrap this selects a css
        available from bootswatch. Possbible themes are: darkly,
        superhero, flatly, cerulean, cyborg, journal, united,
        spacelab, simplex, lumen, yeti, paper, sandstone, slate,
        bootstrap, cosmo, readable. Default is `bootstrap'.
  --title <value>
        A custom title for the page.
  --out <dir or zip>
        Write the gallery into the given directory. It is created if
        non existing. If the name ends with `.zip' a temporary folder
        is used and then zipped into a file with this name (it must
        not exist).

  <query>
        The query string. See the manual page about queries for more
        information.
Example
chee gallery 'date:201410*'
chee gallery --out gallery.zip 'date:201410*'

This command generates a html page containing an image gallery. The image gallery is provided by the well known bootstrap and bootstrap gallery css and javascript libraries.

The --theme option can be used to select a theme for the html page. This just selects a css file from one of the collection at bootswatch. The default theme is bootstrap which is the standard bootstrap look. The default template contains only the thumbnail list, so using a theme becomes more useful with custom templates.

The images to use for the gallery are selected using a query, like with view and find commands. Then the query is constrained to only select image files by appending a query condition from the config file.

By default, all encrypted files are skipped. With -d those files are tried to decrypt. The Decryption options can be used to specify how to decrypt. Since there are two encryption methods, it is possible to use both or just one. If there are only options for one method given, the other is not used (meaning these encrypted files are skipped).

If --out is specified, all resources and images are placed into this folder. It is then possible to transfer this folder to somewhere else and view the gallery page. If --out is not specified, the page is generated in a temporary directory and images are linked directly to its original location. This makes it a little faster to generate the gallery as images don’t need to be copied.

By default, images are scaled such that the longest side is at most 1400px. This is to reduce bandwidth and improve responsiveness when viewing it over the internet. With --no-scale this can be skipped. In this case the original image files are used unscaled.

With --link-original the page provides a donwload link to download the original image file (when scaled images are used, it may be desireable to access the original unscaled image nevertheless). The --title option can be used to set the title in the html file. Any other customization must be done by using a custom template.

The page is generated by expanding a mustache template. A custom template can be given by the --template option. For an easy start, --write-template saves the default template to a file for you to edit. The template is supplied the following object:

  • files - an array of objects for each image file:

    • it contains all file properties plus

    • thumbnail refers to the thumbnail path

    • scaled-image refers to the scaled image. If --no-scale is in effect, this is an alias to path

    • _format this is a special function that parses its body as a format pattern and applies to it the current map. See Format Patterns section for details. This is useful when rendering human readable values of certain properties. Example: {{#_format}}~:length{{/_format}} would render the file size in human readable form.

  • link-original a boolean refering to the same named option

  • title a string refering to the same named option

  • js an array of all javascript urls

  • css an array of all css urls

  • projectInfo an object containing information about chee

    • name the project name “chee“

    • version chee version

    • homepage url to the homepage of chee

The default template renders a simple photo gallery: a list of thumbnails and a detail view for each picture. When on detail view, the image description can be turned on and off by clicking into the image or by pressing ENTER. Custom metadata (tags and comments) are rendered in the detail view. The comment is treated as markdown and converted into html.

Please see the mustache syntax documentation for an explanation of its syntax.

add

Adds files and directories to the index.

Usage
Usage: add [options] <files or directories>

Note: Use `chee help' for detailed help topics. This is a quick option
overview.

  --usage
        Show usage

Find options:
  -r | --recursive
        Find files recursively.
  -a | --all
        Ignore the default query that only selects images and video
        files,
  --skip <n>
        Drop the first n items. This is applied before `first'.
  --first <n>
        Limit output to the first n items.
  -q <value> | --query <value>
        The query string. See the manual page about queries for more
        information.

Decrypt options:
  -d | --decrypt
        Enable transparent decryption.
  --method password|pubkey
        The encryption method: either pubkey or password. The default
        value is taken from the config file or is `pubkey'.
  -W | --passprompt
        Always prompt for a passphrase. Do not use the
        default-passphrase-file from in the config file. Only
        applicable when password-based encryption is used.
  --key-file <file>
        The file containing the secret key. The openpgp formats (ascii
        and binary) can be used.
  --secret-key-pass <file>
        The passphrase file to access the private key. If not
        specified, it is prompted for.
  --passphrase <file>
        Specify a passphrase file to use for password-based
        encryption. The `-W' option overrides this.

Add options:
  --fail-fast
        Stop on first error. Otherwise keep adding next files. Default
        is false.

Arguments:
  <files or directories>
        One or more existing files or directories.

The options are self explaining: without any options, chee searches a given directory for image and video files. This means it looks for files with content type image/* and video/*. It skips all directories and files starting with .. You can change this restriction by either specifying --all, which disables this condition, or by changing it in the config file. You can further restrict the set of files by specifying a query with --query.

Each given directory is added as the location to the index. If a file is given, its parent directory is used.

By default, all encrypted files are skipped. With -d those files are tried to decrypt. The Decryption options can be used to specify how to decrypt. Since there are two encryption methods, it is possible to use both or just one. If there are only options for one method given, the other is not used (meaning these encrypted files are skipped).

Example
$ chee add -r /mnt/photos/sdcard0
$ chee add -r /mnt/photos/*

import

Imports files from a folder into a location.

Usage
Usage: import [options] <files...>

Note: Use `chee help' for detailed help topics. This is a quick option
overview.

  --usage
        Show usage

Find options:
  -r | --recursive
        Find files recursively.
  -a | --all
        Ignore the default query that only selects images and video
        files,
  --skip <n>
        Drop the first n items. This is applied before `first'.
  --first <n>
        Limit output to the first n items.
  -q <value> | --query <value>
        The query string. See the manual page about queries for more
        information.

Decrypt options:
  -d | --decrypt
        Enable transparent decryption.
  --method password|pubkey
        The encryption method: either pubkey or password. The default
        value is taken from the config file or is `pubkey'.
  -W | --passprompt
        Always prompt for a passphrase. Do not use the
        default-passphrase-file from in the config file. Only
        applicable when password-based encryption is used.
  --key-file <file>
        The file containing the secret key. The openpgp formats (ascii
        and binary) can be used.
  --secret-key-pass <file>
        The passphrase file to access the private key. If not
        specified, it is prompted for.
  --passphrase <file>
        Specify a passphrase file to use for password-based
        encryption. The `-W' option overrides this.

Import options:
  --fail-fast
        Stop on first error. Otherwise keep adding next files. Default
        is false.
  --duplicates
        Import files that already exists in some location.

Arguments
  <files...>
        The files or directories to import. The last is the target.
        The target must be a directory.

Searches <sourcedir> directory and copies matching files into the given location directory, adding them to the index. If a file is already present in the index (no matter which location), it is not copied unless --duplicates is specified. Files are never overwritten, new filenames are generated (appending a number until a non-existent file is found) if the a target file already exists.

The directory structure in <sourcedir> is preserved in <location> directory.

Example
chee import -r /media/sdcard/DCIM /disk/fotos/camera2

Searches recursively through /media/sdcard/DCIM and copies files to /disk/fotos/camera2 while preserving the folder structure below /media/sdcard/DCIM. So the file /media/sdcard/DCIM/102ND200/DSC0645.JPG is copied to /disk/fotos/camera2/102ND200/DSC0645.JPG.

sync

Synchronise files and directories with the index.

Usage
Usage: sync [options] [<files or directories>]

Note: Use `chee help' for detailed help topics. This is a quick option
overview.

  --usage
        Show usage

Find options:
  -r | --recursive
        Find files recursively.
  -a | --all
        Ignore the default query that only selects images and video
        files,
  --skip <n>
        Drop the first n items. This is applied before `first'.
  --first <n>
        Limit output to the first n items.
  -q <value> | --query <value>
        The query string. See the manual page about queries for more
        information.

Decrypt options:
  -d | --decrypt
        Enable transparent decryption.
  --method password|pubkey
        The encryption method: either pubkey or password. The default
        value is taken from the config file or is `pubkey'.
  -W | --passprompt
        Always prompt for a passphrase. Do not use the
        default-passphrase-file from in the config file. Only
        applicable when password-based encryption is used.
  --key-file <file>
        The file containing the secret key. The openpgp formats (ascii
        and binary) can be used.
  --secret-key-pass <file>
        The passphrase file to access the private key. If not
        specified, it is prompted for.
  --passphrase <file>
        Specify a passphrase file to use for password-based
        encryption. The `-W' option overrides this.

Sync options:
  --fail-fast
        Stop on first error. Otherwise keep adding next files. Default
        is false.
  --reindex
        Update all files even if unchanged. Default is false.
  --everything
        Sync all indexed directories. The `<files or directories>'
        argument must not be used then.

Arguments:
  <files or directories>
        One or more existing files or directories.

Checks each file if it has changed with respect to the information in the index. If so, the index is updated with new properties from the file. With --reindex the check is skipped so that the index is always updated with new properties from the files.

You can specify files or directories to sync or --everything, which will sync all known locations.

If a file has been deleted on the file system, it is also removed from the index. If chee encounters a new file it is added the same way as with the add command. If one of the directories to sync does not exist, the sync commands fails with an error to avoid dropping the index accidentally. If you want to remove all files below a location directory, use the rm command.

By default, all encrypted files are skipped. With -d those files are tried to decrypt. The Decryption options can be used to specify how to decrypt. Since there are two encryption methods, it is possible to use both or just one. If there are only options for one method given, the other is not used (meaning these encrypted files are skipped).

If a file has been encrypted outside of chee, chee will recognise this and update the index accordingly. This requires to specify decrypt options. On the other hand, if a file has been decrypted and chee still refers to the encrypted version, it will update the index accordingly, too, but in this case decrypt options are not needed.

Example
$ chee sync -r /mnt/photos/card0
$ chee sync /mnt/photos/card0/DSC_7877.JPG

info

Lists all registered locations and the number of files it contains.

$ chee location info
/mnt/nas/fotos/one: 587
/mnt/nas/fotos/two: 1254

meta

Manage custom metadata.

Usage
chee meta [attach|find] […]

attach

Attach or remove tags and comments.

Usage
Usage: attach [options] [<query>]

Note: Use `chee help' for detailed help topics. This is a quick option
overview.

  --usage
        Show usage

Find options:
  -f <value> | --file <value>
        A directory to search instead of the index.
  -r | --recursive
        Find files recursively. Only applicable if `-f` is specified.
  -i <value> | --indexed <value>
        Find indexed or not indexed files. Only applicable if `-f' is
        specified.
  -a | --all
        When used with `-f', ignore the default query, otherwise
        select non-existing files.
  --skip <n>
        Drop the first n items. This is applied before `first'.
  --first <n>
        Limit output to the first n items.

Meta options
  --tags tag1,tag2,…,tagN
        The tags to set. Use comma separated list of tag names.
  --add-tags tag1,tag2,…,tagN
        The tags to add. Use comma separated list of tag names.
  --remove-tags tag1,tag2,…,tagN
        The tags to remove. Use comma separated list of tag names.
  --comment <value>
        A comment to attach.
  --drop-comment
        Removes the comment. Cannot be uset with `--comment'.
  --drop-tags
        Removes all tags.
  --drop-all
        Drop tags and comments. This is short for `--drop-tags
        --drop-comment'.

  <query>
        The query string. See the manual page about queries for more
        information.

Attach comments and tags to a selection of files. Files are selected as with the find command. The given comments or tags are applied to all files in the selection.

Tags are specified with --tags and can be a comma-separated list of names. The --comment option allows to define some commentary text. This is then attached to the selected files, overwriting any existing value.

To remove something, use --drop-tags or --drop-comment. If both are given, the entry is removed from the database.

Attach tags
$ chee meta attach --tags car,bike --first 7 'date/2015-03-20--+2d'
Attaching to _DSC0286.JPG …
Attaching to _DSC0286.JPG …
Attaching to _DSC0287.JPG …
Attaching to _DSC0287.JPG …
Attaching to _DSC0288.JPG …
Attaching to _DSC0288.JPG …
Attaching to _DSC0289.JPG …
Metadata file written.

This adds the tags car and bike to the first 7 files in the given time range. Now the files can be searched by one of tags:

Find by tag
$ chee find 'tag:bike'
2015-03-20 11:46  3872x2592 10mp    (NIKON D200)         4.1mb /mnt/nas…s/sdcard _DSC0286.JPG
2015-03-20 11:46  3872x2592 10mp    (NIKON D200)         4.1mb /mnt/nas…s/sdcard _DSC0286.JPG
2015-03-20 11:47  3872x2592 10mp    (NIKON D200)         5.6mb /mnt/nas…s/sdcard _DSC0287.JPG
2015-03-20 11:47  3872x2592 10mp    (NIKON D200)         5.6mb /mnt/nas…s/sdcard _DSC0287.JPG
2015-03-20 11:47  3872x2592 10mp    (NIKON D200)         5.4mb /mnt/nas…s/sdcard _DSC0288.JPG
2015-03-20 11:47  3872x2592 10mp    (NIKON D200)         5.4mb /mnt/nas…s/sdcard _DSC0288.JPG
2015-03-20 11:48  3872x2592 10mp    (NIKON D200)         5.4mb /mnt/nas…s/sdcard _DSC0289.JPG

find

Query the metadata database.

Usage
Usage: find [options] [<query>]

Note: Use `chee help' for detailed help topics. This is a quick option
overview.

  --usage
        Show usage
  --skip <n>
        Drop the first n items. This is applied before `first'.
  --first <n>
        Limit output to the first n items.
  -p <value> | --pattern <value>
        The format pattern.
  <query>
        The query string. See the manual page about queries for more
        information.

This command queries the metadata database only. The output can be controlled via a Format Patterns using the --pattern option (like with the find command). Here only the properties checksum, tag and comment are available, though.

Example
$ chee meta find 'tag?'
checksum:            c37b3f3f8ac8cd21d6f26d1632ec774aa82a4f2bbaf73bea5860306c1f91ca66
tag:                 |car|bike|

checksum:            7425f8d4ceb858ccf1a062d6b82e1b008cf1ba1d9586fd1b721103a6051ecb45
tag:                 |car|bike|

checksum:            c37b3f3f8ac8cd21d6f26d1632ec774aa82a4f2bbaf73bea5860306c1f91ca66
tag:                 |car|bike|

checksum:            7425f8d4ceb858ccf1a062d6b82e1b008cf1ba1d9586fd1b721103a6051ecb45
tag:                 |car|bike|

checksum:            0839f9657bf7429fd7a868cc5b6ab92d105369ee1031f9322a9216d718439509
tag:                 |car|bike|

checksum:            c37b3f3f8ac8cd21d6f26d1632ec774aa82a4f2bbaf73bea5860306c1f91ca66
tag:                 |car|bike|

checksum:            7425f8d4ceb858ccf1a062d6b82e1b008cf1ba1d9586fd1b721103a6051ecb45
tag:                 |car|bike|

The query syntax is not different, but only applicable to the three mentioned properties. The default output prints a list of rec records.

mv

Moves files and directories.

Usage
Usage: mv [options] <files...>

Note: Use `chee help' for detailed help topics. This is a quick option
overview.

  --usage
        Show usage
  --index
        Only update the index but don't move the directory.
  <files...>
        The files or directories to move. The last is the target. The
        target must be a directory if multiple sources are specified.

The mv moves (or renames) files and synchronises the index accordingly. It works only for files that are known to chee (are indexed). Otherwise, use import or add to add files to the index.

Multiple source files can be specified. The last file is the target. The target must be an existing directory if multiple source files are specified.

Here are some examples:

Move files
chee mv DSC_7600.JPG dsc_7600_1.jpg

This renames the file to lowercase. The same is used to rename directories.

Move multiple files in a directory
chee mv loc1/*.jpg loc1/old

The target loc1/old must be an existing directory. The loc1/*.jpg uses shell expansion to get all files with a jpg extension to move them in the folder old.

Move directory (1)
chee mv loc1/sdcard0 loc2/

This moves the directory sdcard0 into another one loc2. Since loc2 exists, the directory loc2/sdcard0 is created.

Rename a directory (2)
chee mv loc1/ newloc/

This moves the directory loc1 to a new one newloc. Since loc1 is indexed, the directory is renamed and the index is updated such that path and location properties point to the new one newloc.

rm

Remove files and update the index.

Usage
Usage: rm [options] <files...>

Note: Use `chee help' for detailed help topics. This is a quick option
overview.

  --usage
        Show usage
  --index
        Only update the index but don't remove any files.
  <files...>
        The files or directories to remove. Directories are removed
        recursively.

Remove files from disk and synchronise the index. With --index files are not deleted from disk but index is updated only. Directories are deleted recursively.

collection

Manages collections. The collection command requires subcommands.

Usage
collection [edit|show]

edit

Edits a collection or creates a new one.

Usage
Usage: edit [options] <name>

Note: Use `chee help' for detailed help topics. This is a quick option
overview.

  --usage
        Show usage

Options are optional, if not specified an editor opens to edit a
collection or create a new one. If any option is given, the value is
set non-interactively.

  --name <value>
        Set a new name.
  --query <value>
        Set a new query.
  --description <value>
        Set a new description.
  <name>
        The collection name to edit. Creates a new collection if there
        is none with this name.

The argument is mandatory and names the collection to edit. If the name is unknown, a new one is created with that name.

The command works interactively and non-interactively. If a value for name, query or description is given, it is set into the collection silently. Otherwise an external editor opens to allow changing or creating a collection.

The editor is filled with a template. You can specify the name, query and a description. When the file is saved and the editor exists, the text is saved to the list of collections. If you leave the name or query empty, the process is cancelled and the collection list is not updated.

The editor program is determined from the configuration file. Set a program at key chee.programs.editor. If this is not set, the OS is asked to open an editor and at last the file is opend using a common program (xdg-open, open, etc).

show

Shows details about collections.

Usage
Usage: show [options] [<name>]

Note: Use `chee help' for detailed help topics. This is a quick option
overview.

  --usage
        Show usage
  -p <value> | --pattern <value>
        The format pattern.
  <name>
        The collection name or enough of it to uniquely identify a
        collection.

By default it lists all collections with name and title, one per line.

A Format Pattern can be used to customize the output. There are the same predefined patterns as with the find command: oneline (the default), detail and lisp. If the pattern is not one of these, it is tried to find in the configuration file or used as a pattern itself.

The detail pattern prints all details about an collection. The properties to use in the format pattern are: name, title, query and description.

The argument is a portion of a name to restrict the output to only those collection that start with <name>. If not given, all collections are listed.

remove

Remove a collection.

Usage
Usage: remove [options] <name>

Note: Use `chee help' for detailed help topics. This is a quick option
overview.

  --usage
        Show usage
  <name>
        The name of the collection to remove.

Removes a collection from the list. The name argument may be shortened to a non-ambigous term.

mktree

Copies or symlinks a set of files into another directory.

Usage
Usage: mktree [options] [<query>]

Note: Use `chee help' for detailed help topics. This is a quick option
overview.

  --usage
        Show usage

Find options:
  -f <value> | --file <value>
        A directory to search instead of the index.
  -r | --recursive
        Find files recursively. Only applicable if `-f` is specified.
  -i <value> | --indexed <value>
        Find indexed or not indexed files. Only applicable if `-f' is
        specified.
  -a | --all
        When used with `-f', ignore the default query, otherwise
        select non-existing files.
  --skip <n>
        Drop the first n items. This is applied before `first'.
  --first <n>
        Limit output to the first n items.

Decrypt options:
  -d | --decrypt
        Enable transparent decryption.
  --method password|pubkey
        The encryption method: either pubkey or password. The default
        value is taken from the config file or is `pubkey'.
  -W | --passprompt
        Always prompt for a passphrase. Do not use the
        default-passphrase-file from in the config file. Only
        applicable when password-based encryption is used.
  --key-file <file>
        The file containing the secret key. The openpgp formats (ascii
        and binary) can be used.
  --secret-key-pass <file>
        The passphrase file to access the private key. If not
        specified, it is prompted for.
  --passphrase <file>
        Specify a passphrase file to use for password-based
        encryption. The `-W' option overrides this.

Mktree options:
  -s | --symlink
        Symlink files into the target directory (the default).
  -u | --relative-symlink
        Symlink files int the target directory using relative path
        names.
  -c | --copy
        Copy files into the target directory.
  --overwrite
        Whether to overwrite existing files.
  -p <value> | --pattern <value>
        The pattern used to create the target path.
  --target <directory>
        The target directory. If not specified the current working
        directory is used.

  <query>
        The query string. See the manual page about queries for more
        information.

To select the files to symlink or copy, the same options as for the find command are used. Additionally, there are options that control the target filename and whether to overwrite existing files or not.

The --overwrite option tells chee to overwrite existing files. By default, they are skipped.

The --pattern option is used to determine the target filename. This is a format pattern and the default value will make a filename like this: <year>/<month>/<day>-<hour>-<minute>_<filename>. That is, files are sorted in a directory structure based on their created or lastmodified property. As with the find command, you can specify a pattern at the command line or refer to a pattern from the config file under the key chee.formats.

The --target option specifies the directory to transfer files to. The name that results from --pattern is appended to this. It is by default the current working directory. If a target directory does not exist, it is created.

Only one action option (symlink, relative symlink or copy) should be specified, if more are given, the last option wins.

By default, all encrypted files are skipped. With -d those files are tried to decrypt. The Decryption options can be used to specify how to decrypt. Since there are two encryption methods, it is possible to use both or just one. If there are only options for one method given, the other is not used (meaning these encrypted files are skipped).

The query argument is the query string that is run against the index or a directory (if -f is given). See query concept page for details.

Symlink files with default pattern
$ chee mktree -u --target sorted/ --first 10 'make:nikon*'
RelativeSymlink /home/eike/testdir/pics/repo2/DSC_6248.JPG → /home/eike/testdir/pics/sorted/2015/06/22-17-31_DSC_6248.JPG … Ok
RelativeSymlink /home/eike/testdir/pics/repo2/DSC_6259.JPG → /home/eike/testdir/pics/sorted/2015/06/22-17-48_DSC_6259.JPG … Ok
RelativeSymlink /home/eike/testdir/pics/repo2/DSC_6261.JPG → /home/eike/testdir/pics/sorted/2015/06/22-17-48_DSC_6261.JPG … Ok
RelativeSymlink /home/eike/testdir/pics/repo2/DSC_6262.JPG → /home/eike/testdir/pics/sorted/2015/06/22-17-48_DSC_6262.JPG … Ok
RelativeSymlink /home/eike/testdir/pics/repo2/DSC_6265.JPG → /home/eike/testdir/pics/sorted/2015/06/22-18-02_DSC_6265.JPG … Ok
RelativeSymlink /home/eike/testdir/pics/repo2/DSC_6283.JPG → /home/eike/testdir/pics/sorted/2015/07/07-19-21_DSC_6283.JPG … Ok
RelativeSymlink /home/eike/testdir/pics/repo2/DSC_6285.JPG → /home/eike/testdir/pics/sorted/2015/07/07-19-22_DSC_6285.JPG … Ok
RelativeSymlink /home/eike/testdir/pics/repo2/DSC_6288.JPG → /home/eike/testdir/pics/sorted/2015/07/07-19-22_DSC_6288.JPG … Ok
RelativeSymlink /home/eike/testdir/pics/repo2/DSC_6293.JPG → /home/eike/testdir/pics/sorted/2015/07/09-18-01_DSC_6293.JPG … Ok
RelativeSymlink /home/eike/testdir/pics/repo2/DSC_6305.JPG → /home/eike/testdir/pics/sorted/2015/07/18-14-45_DSC_6305.JPG … Ok
10 files processed in 0:00:00.108

If no pattern is specified, chee uses a default pattern that sorts images according to their creation timestamp. If that’s not available, the last modification timestamp of the file is used. Images are sorted into folders by month and prefixed with the day, hour and minute. The first picture in the example output above was taken on 2015/06/22 17:31.

The resulting directory structure of the example above is:

Structure
$ tree sorted/
sorted/
└── 2015
    ├── 06
    │   ├── 22-17-31_DSC_6248.JPG -> ../../../repo2/DSC_6248.JPG
    │   ├── 22-17-48_DSC_6259.JPG -> ../../../repo2/DSC_6259.JPG
    │   ├── 22-17-48_DSC_6261.JPG -> ../../../repo2/DSC_6261.JPG
    │   ├── 22-17-48_DSC_6262.JPG -> ../../../repo2/DSC_6262.JPG
    │   └── 22-18-02_DSC_6265.JPG -> ../../../repo2/DSC_6265.JPG
    └── 07
        ├── 07-19-21_DSC_6283.JPG -> ../../../repo2/DSC_6283.JPG
        ├── 07-19-22_DSC_6285.JPG -> ../../../repo2/DSC_6285.JPG
        ├── 07-19-22_DSC_6288.JPG -> ../../../repo2/DSC_6288.JPG
        ├── 09-18-01_DSC_6293.JPG -> ../../../repo2/DSC_6293.JPG
        └── 18-14-45_DSC_6305.JPG -> ../../../repo2/DSC_6305.JPG

3 directories, 10 files

A custom pattern can be specified with --pattern. This can get quite complex, but patterns can be bookmarked in the configuration file and refered to by name.

Symlink files using custom pattern
$ chee mktree -u --target sorted/ --first 10 --pattern '~:ext/~[created~;~#cr~fE~;~#l~fE~]/~#file' 'make:nikon*'
RelativeSymlink /home/eike/testdir/pics/repo2/DSC_6248.JPG → /home/eike/testdir/pics/sorted/JPG/Mon/DSC_6248.JPG … Skipped
RelativeSymlink /home/eike/testdir/pics/repo2/DSC_6259.JPG → /home/eike/testdir/pics/sorted/JPG/Mon/DSC_6259.JPG … Skipped
RelativeSymlink /home/eike/testdir/pics/repo2/DSC_6261.JPG → /home/eike/testdir/pics/sorted/JPG/Mon/DSC_6261.JPG … Skipped
RelativeSymlink /home/eike/testdir/pics/repo2/DSC_6262.JPG → /home/eike/testdir/pics/sorted/JPG/Mon/DSC_6262.JPG … Skipped
RelativeSymlink /home/eike/testdir/pics/repo2/DSC_6265.JPG → /home/eike/testdir/pics/sorted/JPG/Mon/DSC_6265.JPG … Skipped
RelativeSymlink /home/eike/testdir/pics/repo2/DSC_6283.JPG → /home/eike/testdir/pics/sorted/JPG/Tue/DSC_6283.JPG … Skipped
RelativeSymlink /home/eike/testdir/pics/repo2/DSC_6285.JPG → /home/eike/testdir/pics/sorted/JPG/Tue/DSC_6285.JPG … Skipped
RelativeSymlink /home/eike/testdir/pics/repo2/DSC_6288.JPG → /home/eike/testdir/pics/sorted/JPG/Tue/DSC_6288.JPG … Skipped
RelativeSymlink /home/eike/testdir/pics/repo2/DSC_6293.JPG → /home/eike/testdir/pics/sorted/JPG/Thu/DSC_6293.JPG … Skipped
RelativeSymlink /home/eike/testdir/pics/repo2/DSC_6305.JPG → /home/eike/testdir/pics/sorted/JPG/Sat/DSC_6305.JPG … Skipped
10 files processed in 0:00:00.69

The pattern results in a folder per extension and weekday. The ~:ext refers to the file extension. Then the timestamp is either taken from the created property, or if that does not exist, from the lastmodified property. The names are abbreviated to cr and l. The ~fE applies a format to the timestamp that results in the weekday. And at last the filename is appended.

Structure
$ tree sorted/
sorted/
└── JPG
    ├── Mon
    │   ├── DSC_6248.JPG -> ../../../repo2/DSC_6248.JPG
    │   ├── DSC_6259.JPG -> ../../../repo2/DSC_6259.JPG
    │   ├── DSC_6261.JPG -> ../../../repo2/DSC_6261.JPG
    │   ├── DSC_6262.JPG -> ../../../repo2/DSC_6262.JPG
    │   └── DSC_6265.JPG -> ../../../repo2/DSC_6265.JPG
    ├── Sat
    │   └── DSC_6305.JPG -> ../../../repo2/DSC_6305.JPG
    ├── Thu
    │   └── DSC_6293.JPG -> ../../../repo2/DSC_6293.JPG
    └── Tue
        ├── DSC_6283.JPG -> ../../../repo2/DSC_6283.JPG
        ├── DSC_6285.JPG -> ../../../repo2/DSC_6285.JPG
        └── DSC_6288.JPG -> ../../../repo2/DSC_6288.JPG

thumb

Create thumbnails.

Usage
Usage: thumb [options] [<query>]

Note: Use `chee help' for detailed help topics. This is a quick option
overview.

  --usage
        Show usage

Find options:
  -f <value> | --file <value>
        A directory to search instead of the index.
  -r | --recursive
        Find files recursively. Only applicable if `-f` is specified.
  -i <value> | --indexed <value>
        Find indexed or not indexed files. Only applicable if `-f' is
        specified.
  -a | --all
        When used with `-f', ignore the default query, otherwise
        select non-existing files.
  --skip <n>
        Drop the first n items. This is applied before `first'.
  --first <n>
        Limit output to the first n items.

Decrypt options:
  -d | --decrypt
        Enable transparent decryption.
  --method password|pubkey
        The encryption method: either pubkey or password. The default
        value is taken from the config file or is `pubkey'.
  -W | --passprompt
        Always prompt for a passphrase. Do not use the
        default-passphrase-file from in the config file. Only
        applicable when password-based encryption is used.
  --key-file <file>
        The file containing the secret key. The openpgp formats (ascii
        and binary) can be used.
  --secret-key-pass <file>
        The passphrase file to access the private key. If not
        specified, it is prompted for.
  --passphrase <file>
        Specify a passphrase file to use for password-based
        encryption. The `-W' option overrides this.

Processing options
  -c | --concurrent
        Process files concurrently.
  -p <value> | --pattern <value>
        The format pattern used to print the result to stdout.
  -o <value> | --outdir <value>
        The directory to place generated images.
  --nameformat <value>
        The format pattern used to create the target file name. It is
        evaluated with the properties of the original file with
        `width' and `height' replaced by the desired target values.
  --size <width>x<height>
        The size to scale to. Default is 100x100.

  <query>
        The query string. See the manual page about queries for more
        information.
Example
chee thumb --size 200 -o ./thumbdir 'date:201410*'

Scales the original image to completely cover the new dimensions whilst retaining the original aspect ratio.

If the new dimensions have a different aspect ratio than the original image, the image will be cropped so that it still covers the new area without leaving any background.

As with scale images are not changed, but new files are written.

The images to scale are selected by a query. If non-image files are selected, they are skipped. This is done by appending a query mimetype:images/* (which can be be changed in the configuration file). Other options for querying are the same as with the find command. See here for more details.

By default, all encrypted files are skipped. With -d those files are tried to decrypt. The Decryption options can be used to specify how to decrypt. Since there are two encryption methods, it is possible to use both or just one. If there are only options for one method given, the other is not used (meaning these encrypted files are skipped).

The output is rendered (like with find) using a format pattern. It can be specfified with --pattern. When evaluating the format pattern, standard properties are retrieved from the scaled image but image metadata (all image properties except width and height) is taken from the original image. Additionall, all properties from the original image are available and prefixed by origin-.

By default, new images are written to a directory in chee’s working directory. With --outdir another dircetory can be specified.

With --nameformat you can specify a format pattern to determine the target filename. By default, a name containing the checksum of the original file and the target size is generated. This pattern is evaluated against the properties of the original file plus target-width and target-height that are set to the dimensions of the scaled image.

With --concurrent the processing is done in parallel. Note, that the order of the result differs from the input list.

The --size option gives the size of the thumbnails to generate. It may be a string like <width>x<height> (e.g. 200x150) or just one number, for example 200 which is the same as 200x200.

scale

Scales images.

Usage
Usage: scale [options] [<query>]

Note: Use `chee help' for detailed help topics. This is a quick option
overview.

  --usage
        Show usage

Find options:
  -f <value> | --file <value>
        A directory to search instead of the index.
  -r | --recursive
        Find files recursively. Only applicable if `-f` is specified.
  -i <value> | --indexed <value>
        Find indexed or not indexed files. Only applicable if `-f' is
        specified.
  -a | --all
        When used with `-f', ignore the default query, otherwise
        select non-existing files.
  --skip <n>
        Drop the first n items. This is applied before `first'.
  --first <n>
        Limit output to the first n items.

Decrypt options:
  -d | --decrypt
        Enable transparent decryption.
  --method password|pubkey
        The encryption method: either pubkey or password. The default
        value is taken from the config file or is `pubkey'.
  -W | --passprompt
        Always prompt for a passphrase. Do not use the
        default-passphrase-file from in the config file. Only
        applicable when password-based encryption is used.
  --key-file <file>
        The file containing the secret key. The openpgp formats (ascii
        and binary) can be used.
  --secret-key-pass <file>
        The passphrase file to access the private key. If not
        specified, it is prompted for.
  --passphrase <file>
        Specify a passphrase file to use for password-based
        encryption. The `-W' option overrides this.

Processing options
  -c | --concurrent
        Process files concurrently.
  -p <value> | --pattern <value>
        The format pattern used to print the result to stdout.
  -o <value> | --outdir <value>
        The directory to place generated images.
  --nameformat <value>
        The format pattern used to create the target file name. It is
        evaluated with the properties of the original file with
        `width' and `height' replaced by the desired target values.
  -m <value> | --multiply <value>
        Scale by a factor of `m'.
  -l <value> | --maxlen <value>
        Scale such that the longest side of the image is not more than
        `maxlen'.

  <query>
        The query string. See the manual page about queries for more
        information.
Example
chee scale --maxlen 1200 -o ./scaledir 'date:201410*'

This command resizes images. As with thumb images are not changed, but new files are written.

The images to scale are selected by a query. If non-image files are selected, they are skipped. This is done by appending a query mimetype:images/* (which can be be changed in the configuration file). Other options for querying are the same as with the find command. See here for more details.

By default, all encrypted files are skipped. With -d those files are tried to decrypt. The Decryption options can be used to specify how to decrypt. Since there are two encryption methods, it is possible to use both or just one. If there are only options for one method given, the other is not used (meaning these encrypted files are skipped).

The output is rendered (like with find) using a format pattern. It can be specfified with --pattern. When evaluating the format pattern, standard properties are retrieved from the scaled image but image metadata (all image properties except width and height) is taken from the original image. Additionall, all properties from the original image are available and prefixed by origin-.

By default, new images are written to a directory in chee’s working directory. With --outdir another dircetory can be specified.

With --nameformat you can specify a format pattern to determine the target filename. By default, a name containing the checksum of the original file and the target size is generated. This pattern is evaluated against the properties of the original file plus target-width and target-height that are set to the dimensions of the scaled image.

With --concurrent the processing is done in parallel. Note, that the order of the result differs from the input list.

The options --maxlen and --multiply specify how to scale. One of them must be specified.

With --maxlen you can specify a maximum height or width. The image is scaled such that the larger side does not exceed maxlen. If an image’s dimension is already below this value, it is not scaled.

With multiply an image is scaled by multiplying its height and width with the given factor.

encrypt

Encrypt files using a password or a public key.

Usage
Usage: encrypt [options] [<query>]

Note: Use `chee help' for detailed help topics. This is a quick option
overview.

  --usage
        Show usage

Find options:
  -f <value> | --file <value>
        A directory to search instead of the index.
  -r | --recursive
        Find files recursively. Only applicable if `-f` is specified.
  -i <value> | --indexed <value>
        Find indexed or not indexed files. Only applicable if `-f' is
        specified.
  -a | --all
        When used with `-f', ignore the default query, otherwise
        select non-existing files.
  --skip <n>
        Drop the first n items. This is applied before `first'.
  --first <n>
        Limit output to the first n items.

Encrypt options:
  -c | --concurrent
        Process files concurrently.
  --method password|pubkey
        The encryption method: either pubkey or password. The default
        value is taken from the config file or is `pubkey'.
  -W | --passprompt
        Always prompt for a passphrase. Do not use the
        default-passphrase-file from in the config file. Only
        applicable when password-based encryption is used.
  --key-file <file>
        The file containing the public key. A key-id must also be
        specified. The openpgp formats (ascii and binary) can be used.
  --key-id <value>
        A key id matching a public key in the `key-file'. Can be part
        of the user-id or key-id and must uniquely identify a key.
  --passphrase <file>
        Specify a passphrase file to use for password-based
        encryption. The `-W' option overrides this.

  <query>
        The query string. See the manual page about queries for more
        information.
Example
chee encrypt date/2016-03--+1m

This example encrypts all photos created in march 2016 using public key encryption.

The Find options are for selecting source images to encrypt. These are the same as with the find command.

The files are encrypted using OpenPGP and there are two possible ways:

  • using a public key, so decryption requires the corresponding private key

  • using a password, where the same is used for decryption

The --method option chooses one of the two. Its value can also be specified in the config file and the default value is pubkey.

For pubkey encryption, a --key-file and --key-id must be specified. The key file must be in OpenPGP format. The key id can be the email address or a finger print (suffix). It must identify the public key in the key file.

For password encryption, the passphrase can be typed in or read from a file. A default password can be set in the configuration file which is used if no --passhprase is given, unless -W is specified that will always prompt for a passphrase.

Please see the configuration chapter for related configuration values and the page about encryption.

decrypt

Dencrypt files using a password or a public key.

Usage
Usage: decrypt [options] [<query>]

Note: Use `chee help' for detailed help topics. This is a quick option
overview.

  --usage
        Show usage

Find options:
  -f <value> | --file <value>
        A directory to search instead of the index.
  -r | --recursive
        Find files recursively. Only applicable if `-f` is specified.
  -i <value> | --indexed <value>
        Find indexed or not indexed files. Only applicable if `-f' is
        specified.
  -a | --all
        When used with `-f', ignore the default query, otherwise
        select non-existing files.
  --skip <n>
        Drop the first n items. This is applied before `first'.
  --first <n>
        Limit output to the first n items.

Decrypt options:
  -c | --concurrent
        Process files concurrently.
  --method password|pubkey
        The encryption method: either pubkey or password. The default
        value is taken from the config file or is `pubkey'.
  -W | --passprompt
        Always prompt for a passphrase. Do not use the
        default-passphrase-file from in the config file. Only
        applicable when password-based encryption is used.
  --key-file <file>
        The file containing the secret key. The openpgp formats (ascii
        and binary) can be used.
  --secret-key-pass <file>
        The passphrase file to access the private key. If not
        specified, it is prompted for.
  --passphrase <file>
        Specify a passphrase file to use for password-based
        encryption. The `-W' option overrides this.

  <query>
        The query string. See the manual page about queries for more
        information.
Example
chee decrypt encrypted?

This example decrypts all encrypted files.

The Find options are for selecting encrypted files to decrypt. These are the same as with the find command.

The files are encrypted using OpenPGP and there are two possible ways:

  • public key, so decryption requires the corresponding private key

  • using a password for decryption

The --method option chooses one of the two. Its value can also be specified in the config file and the default value is pubkey.

For pubkey encryption, a --key-file and --secret-key-pass must be specified. The key file must be in OpenPGP format. The secret-key-pass file must be a file where the first line contains the password to access the private key.

For password based encryption, the passphrase can be typed in or read from a file. A default password can be set in the configuration file which is used if no --passhprase is given, unless -W is specified that will always prompt for a passphrase.

Please see the configuration chapter for related configuration values and the page about encryption.

clean

Removes temporary data.

Usage
Usage: clean [options]

Note: Use `chee help' for detailed help topics. This is a quick option
overview.

  --usage
        Show usage
  -t | --temp
        Remove chee's directory storing other temporary data.
  -d | --decrypt
        Remove the directory containing temporary decrypted data.
  -s | --scaled
        Remove the directory containing scaled images and thumbnails.
  --all
        Remove all temporary data.

Chee stores data in different places. When scaling images or creating thumbnails, these files are stored in a separate directory than other temporary data.

Commands that decrypt files (like view) store the decrypted files in another separate directory. The clean command deletes these directories.

config

Shows the current configuration.

Usage
Usage: config [options]

Note: Use `chee help' for detailed help topics. This is a quick option
overview.

  --usage
        Show usage
  --origin
        Print comments showing the origin of the value.
  --json
        Render the configuration in JSON.
  --all
        Show complete config, with system properties.

The --origin option renders comments on each config value that contain information about where the value was read. It may be a value from the default config or a user defined one.

The --json option renders the config file in JSON format. If --origin is also specified, then comments are rendered which results in non-valid json.

The --all option shows all available config values. By default only the chee configuration is printed.