Synopsis

This document covers the MediaKeg Command-line Interface (CLI) and its usage.

Overview

The MediaKeg CLI is a command-line interface to the MediaKeg runtime library. Using the CLI, the user can execute a variety of tasks, including library creation and management, file search, and import.

General Usage

The MediaKeg CLI accepts several commands covering import and related operations. Most commands accept options and one ore more arguments that are specific to a command. The use pattern for entering a command is as follows:

$ mkeg command [...options] ...arguments

A command is a single or hyphenated word, as the following examples show:

• find
• import
• make-library
• set-default

Command Help

Enter the following to get general usage help and the list of available commands:

$ mkeg -h

For help about a command, enter the command name and the -h option:

$ mkeg -h <command>

For commands with advanced options, use the -H option to to disaply the complete list of options, including advanced:

$ mkeg -H <command>

Note: If a command has advanced options, a message is displayed indicating as such when displaying help using the lowercase -h option.

Command Aliases

The MediaKeg CLI commands have descriptive names that reveal their respective functions. To faciliate more efficent CLI entry, most commands also have a short, less descriptive name called a command alias. For example, the following commands are equivalent:

$ mkeg import -r /Volumes/DCIM
$ mkeg i -r /Volumes/DCIM

In this example, the command alias i is used in place of import to execute the same command. The alias for each command is documented below and is displayed with command help.

When documenting or refering to commands in this and other MediaKeg documentation, the full-form version of the command name is used.

Command Arguments

The command argument is a user-supplied value to a required parameter, which is enclosed in angle brackets when showing command usage.

An argument can also be conditionally required or optional, as described below. When showing usage, aquare brackets indicate optional parameters and angle brackets enclosed in square brackets indicate conditionally required parameters:

 <required> [<conditionally required>] [optional]

Optional Arguments

An argument is used instead of a long option if it fits with the normal use-case for executing a command. For example, the find command accepts a search pattern for an optional argument, as shown by the following example:

$ mkeg find /Volumes/photos cat

In this example, /Volumes/photos is the required <path> argument and cat is an optional [pattern] argument for filtering the results. Strictly speaking, [pattern] is optional, but the normal use case is to set it since the user is trying to find something. Using a long option would have made input more cumbersome, as shown here:

$ mkeg find --pattern=cat /Volumes/photos

Note: The preceeding example is for illustrative purposes only and does not reflective actual command usage.

Conditionally Required Arguments

A conditionally required argument is one whose value is required only if not set elsewhere (such as a configuration setting) or if chained to another (optional) argument or option requiring it to be set. For example, the import command specifies target as a conditionally required argument, as shown here:

$ mkeg import [...options] <source> [<target>]

Normally, a target is required. (Target is the library path to receive assets imported from source.) However, if a default library is configured for the system, then [<target>] can be ommited and the default library path is automatically used in its place, further simplifying user input.

Multiple Arguments

If a command accepts multipe arguments, then arguments must be entered in the correct order. Required arguments always precede conditionally required, which in-turn always preceded optional.

Argument containing spaces, then it must be enclosed in quotes else they will be treated as multiple arguments by the command parser. For example:

$ mkeg import "/Volumes/Nikon D500"

In this example, the actual source would be interpreted as /Volumes/Nikon if not enclosed in quotes, and D500 as the target, which is incorrect, assuming Nikon D500 is a folder name.

Command Options

An option is a CLI entry that optionally modifies the behavior of a command. The MediaKeg CLI supports three (3) types of options, as follows:

• Flag options act like a switch to enable or disable a specific feature or behavior.
• Long options are named inputs that can accept a user-supplied value.
• Tag options let the user set tag values for writing Exif metadata and expanding templates.

By convention, options are entered after the command and before any arguments. However, the MediaKeg CLI parser does not consider order when evaluating options. The user is, therefore, free to enter options in any order desired.

For example, the following commands are functionally equivalent and valid:

$ mkeg import -r --mode=strict /Volumes/D500
$ mkeg -r import --mode=strict /Volumes/D500
$ mkeg import /Volumes/D500 -r --mode=strict

Flag Options

The flag option is like an on/off swtich for a behavior or capability associated with a command and consists of a single character prepended by a dash (-) delimiter, as shown here:

$ mkeg import -r /Volumes/DCIM

In this example, the -r flag instructs the import to include all subdirectories under /Volumes/DCIMin in its search for assets.

Note: Flag options are case-sensitive.

Flags options can be entered in a standalone fashion, or they can be bundled together. The following examples are functionally equivalent:

$ mkeg import -r -x - y /Volumes/DCIM
$ mkeg import -rx -y /Volumes/DCIM
$ mkeg import -rxy /Volumes/DCIM

Flag options also have long-option equivalents, as shown here:

$ mkeg import -r /Volumes/DCIM
$ mkeg import --recursive /Volumes/DCIM

Note: Long options as flag options do not accept arguments.

Long Options

The long option accepts an argument in cases where an option requires a user-supplied value, and consists of one or more alphnumeric characters prepended by a double-dash (--) delimiter. The argument is delimited from the option name using the equals sign (=), as shown here:

$ mkeg import -r --minsize=2048 /Volumes/DCIM

In this example, the minsize option is set to 2048 (the argument), which configures import to reject assets under 2048 bytes (2KB) in size.

Note: As with command arguments, option arguments must be enclosed in "double quotes" if they contains spaces.

Long options accepting no arguments are equivalent to flag options, except that the long option name is more descriptive. (See previous example under Flag options.)

Tag Options

The tag option accepts a user defined parameter and corresponding argument. For example, the name of a metadata tag (parameter) to write and its value (argument). There are two types of tag options, as follows:

• Write tags
• User tags

The remainder of this section discusses each type.

User Tag Option

Note: This section assumes the reader is already familiar with MediaKeg templates and user tokens. To learn more, refer to the MediaKeg Concepts Guide, which covers these topics in detail.

The user tag option is used in conjunction with the import process to expand a library template token with a user-supplied value. The usage pattern is as follows:

/u:<user-tag>=<value>

The following example illustrates usage:

$ mkeg import -r /u:series:ALMS /u:session=Qualifying /Volumes/DCIM

When performing an import operation, the target library must be configured to accept the <user-tag> entered when applying the user tag option. That is, either the layout or the filename template, or both, must contain a user tag correpsonding to the <user-tag> entered.

User tag values are subject to the lettercase rules defined for the library. If the library template containing the corresponding token is configured for original lettercase, then enter the value in the lettercase that you want it to appear in the expanded template.

Write Tag Option

The write tag option enables the user to add or modify Exif metadata as part of an import operation. The usage pattern is as follows:

/w:<exif-tag>=<value>

The <exif-tag> part corresponds to the Exif tag to write, and the <value> part sets the write value. The following example illustrates usage:

$ mkeg import -r /w:artist="Jane Doe" /Volumes/DCIM

In this example, the Artist Exif tag is set to Jane Doe. To help prevent input errors, Exif tag names are case insensitive for known tags, meaning /w:Artist and /w:artist are equivalent. For custom and unknown tags, use proper lettercase when writing tag values. Use the list-tags command to display the list of known tags.

Note: The list of known tags is extensive and it is very unlikely that you will encounter a scenario that involves writing custom or unknown tags.

To add or modify multiple Exif tags, invoke the write tag for each as shown here:

$ mkeg import -r /w:artist="Jane Doe" /w:keywords=cars,racing,alms /Volumes/DCIM

CLI Commands Overview

This section provides a brief overview of the MediaKeg CLI command. The remainder of this document is organized around the commands as listed below and covers each of them in detail, including their respective arguments and options.

Import Commands

Library Commands

Note: Library aliases should not be confused with command aliases. Library aliases are short, easy-to-remember names that resolve to library paths when working with libraries.

Utility Commands

Import Commands

import, i

Use the import command to import media assets from source to target library.

Usage

$ mkeg import [...options] <source> [<target>]

Arguments

The import command accepts a source and target argument. The source is always required, and a target is required if a default alias is not set.

source

The source parameter accepts a file or directory path.

If source is a file, then then it is imported, assuming it is importable. If the file is accompanied by a sidecar, then the sidecar is also imported provided the --include-sidecars option is invoked.

If source is a directory, then all files matching the search criteria are added to the list of files to import. The default search criteria is for files having extensions belonging a list of known types. Enter the following command to list the known types:

$ mkeg list-types

The import command also has several long options for refining search and inclusion critiera.

Use the -r or --maxdepth option to search for files to include in subdirectories of source.

target

The target parameter accepts an alias or the directory path for the library receiving the assets to import:

• If target is a library directory path, then it resolves to the value provided.
• If target is a library alias, then it resolves to the library path associated with the alias.

If a target is not provided, then MediaKeg resolves the library using the default alias, provided one exists.

Use the view-aliases command to view the list of aliases registered for the system.

Use the add-alias command to register an alias with the system.

Use the view-library command to view the library details associated with a target. Using this command without any arguments provides a quick and easy way to view the default library details.

Example:

$ mkeg view-library
$ mkeg resolve # using view-library command alias

Flag Options

The table below summarizes the import commad flag options followed by a detailed explanation of each.

--clobber

The --clobber option overwrites any existing keywords when writing to keywords tag as part of an import operation.

This option has no effect unless the /w:keywords option is used.

-r, --recursive

Use this option to search all subdirectories of source for files to import, if a directory. Use the --maxdepth option instead to limit how deep to search.

This flag has no effect if the source is a file.

--no-reserve

--simulate

Use the --simulate option to simulate an import operation, which causes import to disable file copy operations to the target library. This option can be used to inspect the output (via log files and reports) prior to commiting to a real import. There are several scenarios where this could be helpful, such as after creating a new library with custom templates, specifying timeshift and metadata update options, or when importing a potentially large number of files from an old backup drive.

Note: This option does not simulate issues that might occur during a real import operation, such as access issues, file copy errors, and metadata write errors.

Note: If the option to update Exif tags is enabled as part of import then files are still copied to the staging directory with this option enabled.

-v, --verbose

Use the --verbose option to set the verbosity of output printed to the console during an import operation to verbose. See the --verbosity option for additional details and settings.

Note: The --verbosity option overrides this flag if set to a value other than verbose.

Note: This option does not affect how much information is saved to the import log file, which is always verbose.

See also: --trace, and --verbosity

-x, --include-sidecars

Use the --include-sidecars option to import XMP sidecar files in the import operation. The sidecar must have the same filename (without file extension) and reside in the same directory as the asset to be imported. The sidecar filename is updated to match the name of the imported asset at the target path, as shown here:

Any sidecar references to the paired asset are also updated at the target to reflect renamed asset.

Note: If the sidecar is modified as part of an import operation, then a copy of the orginal is automtically saved to the backup folder when using this option.

For XMP sidecar files to be imported they must meet the following conditions, as is typical of XMP files created by recognized image manipulation and management software like Adobe Lightroom and Capture One:

• The sidecar file must have an .xmp file extension.
• The MIME content-type must be of type application.
• An image by the same name and path as the sidecar must exist (except for file extension).
• The paired asset must be importable.

In other words, the sidecar must be a valid XMP file, and be paired to an image that gets imported in order to also be imported.

-y, --no-prompt

Use the --no-prompot option to disable the confirmation prompt that precedes an import operation.

Note: The confirmation prompt provides the user with the oppotunity to review the import settings prior to executing an import operation. Therefore, it's a good idea to not disable the prompt except certain situations such performing repetitive imports over multiple sources and for automation purposes.

Long Options

The table below summarizes the import long options followed by a detailed explanation of each. The Write column indicates if the option causes import to modify asset binaries.

Note: Modified assets are staged and orginal versions are copied to the backup folder.

--backup

When opting to modify assets during an import operation, copies of the original assets are saved to a backup location. MediaKeg uses the_originals folder located at the root of the target library as the default backup location.

Use the --backup option to set the directory path to an alternate backup location. When using this option, the target library identity (a UUID) is automatically appended to the path value so that the alternate location can service multiple libraries.

Note: The _originals folder is not a replacement for a proper backup solution. Only assets that are modified using the import write option are copied into the _originals folder, and a backup of the entire library should be set up and maintained on a separate drive using backup software.

See the MediaKeg Concepts Guide for more information about the originals folder, including how it organizes assets.

--digest

Use the --digest option to set the hash algorithm for generating the file digests used to detect duplicates and file copy errors. This option also configures the hash algorithm for generating stage filenames and quarantine folder names.

The default algorithim is MD5, which is recommended for most applications.

Note: MD5 is the only option supported for MediaKeg v1.0.0.

--extension

The --extension option accepts a regular expression pattern that file extensions must match when searching for assets to import. The file extension is the basename minus the directory path and file name parts (see --filename option for more details).

When specifying a pattern using this option include just the pattern itself, ignoring any modifiers or enclosing slashes. All patterns using this option are evaluated as case-insensitve (i modifier), and no other modifiers are applied.

Note: The undotted extension name is evaluated when testing for matches using this option, so do not include the leading dot in the regular expression pattern.

The following example scopes an import operation to just those assets having filenames with a .JPG file extension.

mkeg import --extension=^jpg$ /volumes/dcim

See also: -r, --filename

--filename

The --filename option accepts a regular expression pattern that file names must match when searching for assets to import. The filename is the basename minus the directory path and file extension parts, as the following example illustrates:

The default behavior imports all files with extensions matching the most common media formats. This option can be used to further constrain the import selection to just the files matching the regular expression pattern provided.

When specifying a pattern using this option include just the pattern itself, ignoring any modifiers or enclosing slashes. All patterns using this option are evaluated as case-insensitve (i modifier), and no other modifiers are applied.

The following example constrains the import operation to include just the files starting the letters I or i.

mkeg import --filename=^i /volumes/dcim

See also: -r, --extension

--keep-stage

Use the --keep-stage option prevent the stage directory from being deleted upon completion of import. This option is intended for development and diagnostic purposes and is not needed under normal circumstances.

Note: This option does not prevent the stage directory from being deleted at the start of an import operation. If inspection of staged assets is required for any reason, be sure to inspect or copy the directory in its entirety to a different location prior to starting the next import operation.

--keywords

Use this option to write one or more keywords to all assets in the impot collection. The value can be a single keyword or a list. To write multiple keywords use a comma separated list. If the value contains spaces then it must be contained within quotes.

Examples:

$ mkeg --keywords=mammal
$ mkeg --keywords=mammal,canine,dog
$ mkeg --keywords="mamal, canine, dog"
$ mkeg --keywords="mamal, canine, dog, rex"
$ mkeg --keywords="mamal, canine, dog, rex, memorial day"

Any leading or trailing whitespace from the individual keywoards is automatically trimmed. Hence, the second and third examples are equivalent.

When setting new keyword, existing keywords are preserved unless the import clobber opton (--clobber) is invoked. The clobber overwrites existing keywords so that the new value contains only the keywoards matching the --keywords argument.

MediaKeg considers keywords to be case-insensitive when evaluating if previously set or not. If previously set, the keyword will be update to match the case specified using the --keywords tag.

NOTE: The --keywords option is a special case of the write (/w) option.

--level

Use this option to set the import strictness level. The table below summarizes the strictness levels and is followed by a detailed explanation of each level.

Note: Setting strictness level to 0 (Reserved) has the same effect as 2 (Normal).

4 - Brutal

• Media assets abset of metadata indicating date and time of capture or creation are quarantined.
• Subsecond field required.
• Full DeviceID required.
• All metadata operations must succeed, else the import operation aborts.

3 - Strict (Default)

• Relaxes requirement for date and time metadata if can be parsed from filename.

2 - Normal

• Relaxes requirement that all write operations must succeed, and allows assets with successful writes to continue.

1 - Gentle

0 - Reserved

--maxdepth

Default: 0

Use this option to set the maximum search depth under source for assets to import. This option is set to 0 by default, which prevents import from searching for assets in subdirectories of source. Use the -r, --recursive option to search all directories under source.

Example:

$ mkeg import --maxdepth=1 /Volumes/DCIM

The preceding example searches /Volumes/DCIM and all folders up to one (1) level deep.

The following directory tree listing and table illustrate the effect --maxdepth on search results.

/Volumes
├── DCIM
    ├── ASSET0.JPG
    └── D1
        ├── ASSET1.JPG
        ├── D2
            ├── ASSET2.JPG
                    ├── D3
                    ├── ASSET3.JPG

--maxsize

Use this option to exclude assets larger than the specified filesize from being imported. The file size can be expressed using one of the following file size formats:

The units specifier is case insensitive, meaning --maxsize=1T and --maxsize=1t are equivalent.

Note: This option does not apply sidecar files.

Example:

$ mkeg import --maxsize=100M /Volumes/DCIM

The preceding example prevents assets with a file size greater than 100 MB from being imported.

See also: --minsize

--minsize

Use this option to exclude assets smaller than the specified filesize from being imported. See --maxsize for additional usage details.

Note: This option does not apply sidecar files.

See also: --maxsize

--mtime

Use this option to scope import to assets modified after a specified date and time. The date and time value can be directly entered or calculated back from the current time using a duration value.

Direct entry must be in ISO8601 format as shown here:

mkeg import -r --mtime=2018-06-02T12:20:12-07:00 /Volumes/D850

See DateTime Values for more information and examples expressing datetime using the ISO8601 standard.

If a duration value is provided, it must be in ISO8601 or the MediaKeg simplified duration format. The following examples are equivalent and express a datetime setpoint that is 4 days prior to current local time:

mkeg import -r --mtime=p4d /Volumes/D850
mkeg import -r --mtime=4d /Volumes/D850

The first example is in IS08601 format. Although not apperant here, the ISO8601 format can be used to express more complex duration values using a combination of date and time units, whereas the simplified format is constrained to a single unit.

See Duration Values for more information and examples expressing duration values.

--quarantine

When import encounters an indeterminate asset, it copies the asset to the quarantine folder. By default, the quarantine folder is at the root of the target library.

Use this option to set an alternate path to the quarantine folder. When using this option, the target library identity (a UUID) is automatically appended to the path value so that the alternate location can service multiple libraries.

Note: The rollback option does not remove assets copied to an alternate quarantine folder.

--ranks

Sets the number of processes to use for import operations. The value must be between 1 and the processor count for the host system executing the import operation, inclusive.

The default value is 70% of host processor count.

--simulate

Use this option to simulate an import operation.

An import simulation performs all import operations except for ingesting assets to their final destination.

• Full import logs are generated for inspection purposes.
• Staging operations are performed if one or more options to modify assets is invoked.

This option is recommended if the expected result of an import option is in question.

--stage

Use this option to set an alternate path for staging assets when writing Exif properties as part of the import operation. The default path is a hidden folder named .stage located at the root of the target library for each import operation.

The target library identity (a UUID) is appended to the path value when using this option to specify an alternate path.

WARNING: The staging directory is deleted after each import operation. If the delete operation fails, then another attempt is made at the start of the next import operation. User files should never be saved to or stored in the stage directory.

--timeshift

The --timeshift option shifts asset timestamp values by a specified duration. This option is useful in scenarios where the device clock is not set or updated for region at the asset creation time. It can also be used to make minor timestamp adjustments if high accuracy matters.

TODO: This section is incomplete.

TODO: Only one device ID allowed for import set

Note: If the asset contains GPS timestamp information, then the timeshift duration value must be within +/-12 hours of GPS time. GPS timestamps always expressed in UTC. This restriction exists to prevent the user from shifting asset creation date and time to an erroneous value, under the assumption that GPS time is always correct.

--timezone

--trace

Provides trace level output to log files suitable for debugging and troubleshooting purposes.

Note: This option does not affect console output, which is set using the -v flag or —verbosity option. Enabling this option may marginally impair import performance.

See also: -v, and --verbosity

--verbosity

Sets the verbosity of log output displayed to the console, as described by the following table:

See also: -j, -v, and --trace

Note: This option does not effect logfile output, which is always verbose unless the --trace option is enabled.

--force-write

Use this option to allow unknown Exif tags using the /w:<exif-tag>=<value> option and to override read-only tag attribute.

/u:<user-tag>=<value>

The user tag option expands a template user token with the value provided. To use this option, the layout or filename template for the target library must contain a user token corresponding to the tag name.

Unlike flag and long options, multiple user tags can be applied to an import operation, as shown here:

$ mkeg import -r /u:series:ALMS /u:session=Qualifying /Volumes/DCIM

User tags can also be included in an alias entry such that they are automatically applied when an import operation is resolved to the target library using the alias. If a user tag is specified as part of an alias definition and entered via the command-line, then the command-line entry value is applied.

/w:<exif-tag>=<value>

The write tag option sets or modifies Exif properties media assets to be imported. When invoked, the property values supplied are applied to all assets. This option is intended for small batch operations where the user is sure that the Exif properties are settable and correct for all assets to be imported. A typical scenario involves importing assets from an SD card after a day of shooting, where the user may want to set some keywords or add artist name.

Unlike flag and long options, multiple write tags can be applied to an import operation, as shown here:

$ mkeg import -r /w:artist="Jane Doe" /w:keywords=cars,racing,alms /Volumes/DCIM

See write tag option for additional usage details.

When using this option, it's essential to be aware of the following:

• If the Exif tag values to be written or updated also serves as layout or filename template tokens for the target library, then the templates are expanded using the write values (as opposed to their respective tag values before the write operation).
• Writing Exif tags requires that asset to be modified, which means it is no longer a file copy of the source after the import operation is complete (i.e., it will have a different digest signature).
• Assets are copied to a temporary staging folder and then updated in-place at this location. If a write operation fails on one or more images, then the entire import operation is aborted. See --stage for details regarding the location of the staging folder.
• A copy of the original is saved to a backup folder when assets are modified using the write tag option. See --backup for details regarding the location of the backup folder.

Also note that because of the extra steps involved in updating and importing an asset, invoking this option increases the amount of time it takes for an import operation to complete.

Examples

Import files from removeable storage media to a MediaKeg library named Library in the users Pictures folder:

mkeg import "/Volumes/Nikon D500" ~/Pictures/Library

Note: source and target paths containing spaces must be enclosed in quotes as shown for the source argument in the example shown.

Perform the same operation as above using a default library:

mkeg import "/Volumes/Nikon D500"

Recursively search source for files when performing an import operation:

mkeg -r import "/Volumes/Nikon D500"

The examples shown are for macOS. The import command usage pattern is identical for Linux and Windows, but the source and path naming conventions vary by OS.

rollback

The rollback command rolls back (undoes) an import operation.

Note: Rollback is a library file removal operation only. It does not attempt to copy files back to the orginal source or restore source files to their orginal state at the time the target import operation was performed.

Warning: Always ensure you have a back-up copy of the target library or its contents prior to performing a rollback operation. Any files deleted as part of a rollback operation are done so directly, and cannot be recovered from Trash (macOS) or the Recycle Bin (Windows).

Usage

$ mkeg rollback [...options] <target> [timestamp]

Arguments

target

The target parameter accepts an alias or the directory path for the library to perform a rollback operation. The process for resolving the target follows the same rules as the import operation, except that the target must be specified even for the case where a default alias is set.

See import-command for more information about how MediaKeg resolves targets.

timestamp

The timestamp parameter enables targeting a specific import operation to rollback. If no timestamp argument is provided, then the last import operation is targeted for rollback.

Inspection of the .site directory under the target library to rollback can be used to determine the correct timestamp value. The data required to perform a rollback operation is stored in the .journal and .logs directories, which are nested under .site according to year, month, day, and time (see example below). After inspecting the import logs for the information needed to determine which import operation to rollback, construct the timestamp value using the corresponding date and time parts under which the logs are nested.

/library
├── .keg
├── .site
│   └── 2019
│       └── 12
│           └── 12
│               ├── 074100
│               │   ├── .journal
│               │   └── .logs
│               ├── 204024
│               │   ├── .journal
│               │   └── .logs
│               └── 204513
│                   ├── .journal
│                   └── .logs

Timestamp arguments must be in IS08601 date and time format, as shown here:

YYYY-MM-DDThh:mm:ss

Where:

YYYY = four-digit year
MM   = two-digit month (01=January, etc.)
DD   = two-digit day of month (01 through 31)
hh   = two digits of hour (00 through 23) (am/pm NOT allowed)
mm   = two digits of minute (00 through 59)
ss   = two digits of second (00 through 59)

Hence, the corresponding timestamp value for the last import operation shown in the preceeding example is 2019-12-12T20:45:13.

Note: Log timestamps are in UTC time.

Flag Options

The table below summarizes the rollback flag-options, followed by a detailed explanation of each.

-f, --force

Use this option to force a rollback even if the target of the rollback operation if a file having a read-only file attribute.

Long Options

The following table summarizes the rollback long-options, which is followed by a detailed explanation of each.

--simulate

Use the --simulate option to simulate a rollback operation, which causes rollback to disable removing files from the target library. This option can be used to inspect the output (via log files and reports) prior to commiting to a real rollback.

Library Commands

MediaKeg includes several library creation and maintence commands, as follows:

• add-alias
• edit-library
• make-library
• make-template
• remove-alias
• set-default
• view-aliases
• view-library

add-alias, alias

The add-alias command associates an alias with a library path.

A library alias is a short, easy-to-remember name that can be used to resolve a library path when working with libraries. For example, the following commands are equivalent, provided photos is an alias for the library located at /Users/Murphy/Photos/Library:

$ mkeg -r import /Volumes/DCIM photos
$ mkeg -r import /Volumes/DCIM /Users/Murphy/Photos/Library

Library aliases improve the MediaKeg import experince by saving the user from needing to remember and enter the target library path for each import operation. This is expecially helpful when when working with multiple libraries. The list of aliases can be viewed at any time using the view-aliases command.

Usage

$ mkeg add-alias [...options] <alias> <path>

Note: A library alias is valid for and registered to the system it was created using the add-alias command. This is because library paths are relative to the host system, and the path can change depending on how the volume hosting the library is mounted.

Arguments

alias

The name of the alias to add. The name must be alphanumeric and may not contain spaces. The only exception is the hyphen (-) character, which is allowed provided it is not the first character.

path

The library path to associate with the alias.

Flag Options

The table below summarizes the add-alias flag-options followed by a detailed explanation of each.

-d, --default

Sets the alias to be the default alias.

Once a default alias is set, the import command will use the path associated with the default alias for the target argument if a value is not entered.

Note: The default alias can also be set or changed at any time using the set-default command.

-q, --quiet

Suppress alias listing after inserting new entry.

Note: The -q flag also suppresses printing the command header and success message.

Tag Options

The table below summarizes the add-alias tag-options followed by a detailed explanation of each.

/u

Sets one or more user tags to be applied to an import operation when the target is resolved using the alias to be added. The following example illustrates how to associate user tags with the alias to be created:

mkeg add-alias ~/Pictures/Library alms-racing /u:category=racing /u:series=alms

Note: The target library must reference the user tags set using this command for the operation to succeed when using this option.

When an import target is resolved using an alias, any user-tags associated with the alias are automatically applied to the import operation. The following commands are equivalent when applying the alias created in the example above to an import operation:

$ mkeg import -r /Volumes/DCIM ~/Pictures/Library /u:category=racing /u:series=alms
$ mkeg import -r /Volumes/DCIM alms-racing

Had the alias been created using the -d option, the command could be further reduced to:

$ mkeg import -r /Volumes/DCIM

Note: The above example is for illustrative purposes only. In general, it's recommended to not associate user tags with the default alias if the intent is to always have their values expand the library template(s). Instead, enter them directly into the library template.

Note: Any user tags entered via the command-line for the import command supersede those defined by the alias if conflicts exist.

Tip: You can create multiple aliases targeting the same library, where each alias provides different user-tags to be applied to the import operation.

See import-command and MediaKeg Concepts Guide for for more information about user tags.

edit-library, edit

The edit-library command can be used to update certain library properties. Only those properties having no affect on the library layout structure and naming convention can be updated.

Usage

mkeg edit-library [...options] [target]

Arguments

Target

The target library to update.

• If target is a directory path, then the library at path provided is updated.
• If the target is a library alias, then the associated library is updated.
• If the target is not specified, then the default library is updated.

Long Options

The table below summarizes the edit-library long-options followed by a detailed explanation of each.

--artist

Updates the artist name associated with the library content.

--copyright

Updates the copright statment for the library content.

--description

Updates the library description.

--owner

Updates the owner name for the library content.

--title

Updates the library title.

make-library, make

The make-library command makes a new MediaKeg library.

Usage

mkeg make-library [...options] <path> [template]

Arguments

path

The directory path specifying the location of the new library.

• If the directory already exists, then it must be empty else the operation will fail.
• If the no such directory exists, then one is automatically created.

template

The file path to the library template to apply.

• If not set, then the default template is applied.

A template is a user-editable file (YAML) that provides inputs for customizing the library configuration. To create a template from an existing library, use the make-template command.

Flag Options

The table below summarizes the make-library flag-options followed by a detailed explanation of each.

-d, --default

Sets the library alias to default.

Note: This option is only valid if an --alias option argument is provided.

Long Options

The table below summarizes the edit-library long-options followed by a detailed explanation of each.

--alias

This option combines alias creation with new library creation, as a convenience.

Note: Alias entries are not part of the library configuration, and each system running MediaKeg maintains its own list.

See add-alias for more information about aliases, including alias naming rules.

--artist

Sets the artist name associated with the library content.

--copyright

Sets the copright statment for the library content.

--description

Sets the library description.

--owner

Sets the owner name for the library content.

--title

Sets the library title.

The table below summarizes the add-alias tag-options followed by a detailed explanation of each.

/u

Sets a user tag to be applied to an import operation when using the alias to be added.

Note: This option is only valid if an --alias option argument is provided.

Note: Setting one or more user tags requires the library template to reference each tag in its layout and filename template definitions. The default template contains no such references and a custom template must be provided using the [template] argument for the operation to succeed when using this option.

make-template, template

The make-template command creates a library tempalte from an existing library configuration.

Note: This command will be supported in a future release.

remove-alias

The remove-alias command removes the specified library alias from the list associated with the user profile for the host system.

See add-alias for more information.

Usage

mkeg remove-alias <alias>

Note: Removing an alias does not remove or affect the associated library.

Arguments

alias

The library alias to remove.

set-default, default

The set-default command sets the default library alias.

The default library alias is used to resolve a library path when a library target is not specified for commands accepting a target argument, which includes the import command. In other words, setting a default saves the user from needing to enter a target when working with the default library.

Note: The term default library is used throughout this document to refer to the library path assocaited with the default alias.

Consider the following import operation to the library resolved by the photos alias:

mkeg import /Volumes/D850/DCIM photos

By setting photos to be the default library alias, the command can be reduced to:

mkeg import /Volumes/D850/DCIM

Setting a default has no functional effect on a library or library operation, and it is merely a convinence to the user in ther form of reduced typing when frequently working with the same library.

There are a couple of things to be aware of when setting a default:

• Setting a default alias unsets the default flag on any other aliases previously set to default.
• As with all aliases, the default alias is a user profile setting.

See add-alias for more informaiton.

Usage

mkeg set-default <alias>

Arguments

alias

The alias name to set as default.

view-aliases, aliases

The view-aliases command displays the all aliases added to the user profile on the host system.

mkeg view-aliases

view-library, resolve

View library metadata and configuration settings.

Usage

mkeg view-library [...options] [target] 

Tip: The view-library command is a quick way to check if an empty target resolves to a default alias. Simply enter view-library (or resolve) without a target argument and the library information associated with the default if shown, if a default is set.

Arguments

target

The target library to view.

• If target is a directory path, then the library at path provided is shown.
• If the target is a library alias, then the library at the associated path is shown.
• If the target is not specified, then the default library is shown.

The default view displays basic librart properties. Use the all -a, --all option to reveal all library properties in JSON format.

Flag Options

The table below summarizes the view-library flag-options followed by a detailed explanation of each.

-a, --all

View all library property settings in JSON format.

Note: The properties shown are the in-memory view, meaning the default values will appear for any properties not explicitly set in the library configuration file.

Utility Commands

Mkeg provides several diagnostic and maintenance commands, as follows:

• find-files
• list-dirs
• list-tags
• list-types
• self-test
• view-digest
• view-tags
• view-timestamp

find-files, find

Use the find-files command to search a directory hierarchy for files.

The find-files command uses the same search function as import making it an effective method for listing import candidates prior to performing an import operation when used in conjunction with the -i option.

Note: The find-files command does evaluate if a file is a duplicate or has the required timestamp information for import. Use the import --simulate option to determine what will be imported without performing an real operation. The tradeoff of a simulation is that it requires more processing time than find-files and generates log files.

Usage

$ mkeg find-files [...options] <source> [pattern]

Arguments

source

The directory path to search for files.

pattern

Regular expression pattern for filtering results by basename.

The basename includes the file name and its extension. Consider the following example path and the table below for the definition of basename and related terms.

~/Pictures/Library/Samples/img001.jpg

The pattern argument can be used to filter on filename or basename with a properly constructed pattern; however, the --filename and --extension options are provided for consistency with how import applies filters. These options can also be used to in conjunction with each other and the pattern argument, or standalone, to simplify otherwise more complex patterns using just the pattern argument.

Flag Options

The table below summarizes the find flag-options followed by a detailed explanation of each.

-i, --match-import

Include only files with extensions (file types) that import recognizes.

The list of files types recognized by import is specific to the library being targeted as part of the import operation, where each library maintains its own list of known types as a library configuration setting. Use the --target option in conjunction with this option to set the library target.

• If a target is not provided, then the known types if read from the default library.
• If a taget is not provided and no default library is set, then a built-in set of known types is used.

Note: Import only includes files with extensions when searching for files to import. Therefore, when using this option, files without extensions are excluded from the output.

-l, --long

Long listing format (shows full path).

Use this option to display the full file path instead of path relative to source, which is the default behavior.

-r, --recursive

Include subdirectories of path in search for files.

The --recursive option configures find-files to search all subdirectories under path for files to find. To limit how deep search traverses into subdirectories, use the --maxdepth option instead.

Note: The --recursive and --maxdepth options cannot be used together.

-W, --no-warnings

Suppress warning messages from being displayed.

A warning message is displayed in the output when find-files encounters as folder that it cannot access as part of traversing the directory structure for files to find. This could result in unwanted noise if, for example, piping the output to a file. Using this option prevents such warnings from being included in the output.

Long Options

The table below summarizes the find long-options followed by a detailed explanation of each.

--extension

Include only files with extensions matching pattern.

--filename

Include only files with names matching pattern.

--maxdepth

Limit recursive search depth to value specified. Consider the following example:

$ mkeg find-files . --maxdepth=2

In this example, find-files searches the current directory (.) and traverses all of its subdirectories nested up to and including two (2) deep.

• To search just the current directory, modify the example to use --maxdepth=0
• To place no limits on how deep to search, use the -r option instead.

--target

The library target containing the list of known types to use.

See --match-import option for more details.

list-dirs, dirs

The list-dirs command lists the directory paths of MediaKeg special folders.

Usage

$ mkeg list-settings-dirs

list-tags

The list-tags command lists known Exif tags.

Usage

$ mkeg list-tags [pattern]

Arguments

pattern

A case-insenstive regular expression pattern for filtering output to just the tag names matching the expression. See the following table for examples:

Note: For users familiar with regualr expressions, provide just the the pattern component of the regular expression and not the forward-slash delimiters. For example, the CLI automatically converts ^flash$ into /^flash$/i.

Flag Options

The following table summarizes the import flag-options, which is followed by a detailed explanation of each.

-l, --long

Uses this option to display results in long format, which includes details about each tag in table format.

-s, --scene

Use this option to list only scene tags in the output. Scene tags participate in scene detection, whereby all tag values must be congruent with each other for two or more assets to roll-up to the same scene.

TODO: Link needed

-w, --writable

Use this option to filter results to list only writable tags in the output. Writable tags are tags whose values can be updated as as part of the import process.

Note: Write tag support can vary from one file format to another and the write tags listed are generally valid for the most common image formats in use today.

-V, --exclude-virtual

Use this option to excelude virtual tags from output. Virtual tags names always start with an asterisk (*).

Long Options

The table below summarizes the find long-options followed by a detailed explanation of each.

--category

Include only files belonging to one of the following categories:

• audio
• author
• camera
• device
• document
• image
• location
• other
• preview
• time
• unknown
• video

Example:

$ mkeg list-tags --category=time

--scope

Set the tag scope, as described by the following table:

Example:

$ mkeg list-tags --scope=index

Index tags are an ordered list of real or vitual metadata tags to use for the scene filename indicies. Scene tags are real or virtual tags to evaluate for congruency when assigning assets to scenes during an import operation.

--target

MediaKeg supports customizing scene and index tags on a per-library basis. Use this option to list tags as configured for target library.

Example:

$ mkeg list-tags --target=<library alias or path>

See also: MediaKeg Concepts Guide

• index tags
• scene tags

list-types

The list-types command lists known file types (extensions) to find and import when executing the import command .

Usage

$ mkeg list-types [pattern]

Arguments

pattern

A case-insenstive regular expression pattern for filtering output to just the file types (extensions) matching the expression.

Flag Options

The following table summarizes the import flag-options, which is followed by a detailed explanation of each.

-i, --match-import

Include only files with extensions (file types) that import recognizes.

See the the find-files --match-import option for more information.

Note: This option is redundant if --target is specified, and is used for scoping output to the default library.

--long, -l

Uses this option to display results in long format, which MIME info and file description for each file type.

Long Options

The table below summarizes the find long-options followed by a detailed explanation of each.

--mime

Include only files with extentions mapping to one of the following MIME types:

• application
• audio
• image
• video

Example:

$ mkeg list-types --mime=video

--target

MediaKeg supports customizing supported file types on a per-library basis. Use this option to list tags as configured for target library.

Example:

$ mkeg list-types --target=<library alias or path>

See also: MediaKeg Concepts Guide

• file types

self-test, diag

Use the self-test command to execute a built-in self-test that checks MediaKeg for proper installation and function.

Usage

$ mkeg self-test [...options]

Flag Options

The following table summarizes the flag options for the self-test command, and a detailed explanation of each is provided below.

-v, --verbose

Use the --verbose option to enable verbose output in place of progress spinners.

-r, --repair

Use the --repair option to remove and unpack redistributable files to support files folder.

Note: Use the list-dirs command to find the location of the support files folder for the current user and system.

view-digest, hash

The digest command calculates and displays the digest value for the target file.

Usage

mkeg view-digest [...options] <target>

Arguments

target

The target file to calulate and display the digest value. By default, an MD5 hash is calculated and the file extension determines the mode (see below for explanation of modes).

Flag Options

The following table summarizes the flag options for the digest command, and a detailed explanation of each is provided below.

Note: The default digest mode is binary, which import uses to hash all files, with the execption of sidecar files.

-t, --text

Use this option to calculate the digest in text mode. Text-mode reads the file line-by-line when calculating a digest value and normalizes the end-of-line (EOL) marker to produce consistent results independent of operating system.

Long Options

The following table summarizes the flag options for the view-library command, and a detailed explanation of each is provided below.

--method

Use this option to set the hash alogrithm for generating the file digest. MediaKeg uses MD5 by default, which is suitable for most applications.

Note: The fast digest method slightly reduces the effectiveness of duplicate detection by calculating MD5 digest values from partial file data This method sould not be used if the effectiveness of error detection is a concern.

view-tags, tags

Use the view-tags command to view the Exif metadata for an asset.

Usage

$ mkeg view-tags [...options] <path> [pattern]

Arguments

path

The file path for the asset containing the Exif metadata to view.

pattern

A case-insenstive regular expression pattern for filtering output to just the tag names matching the expression.

See list-tags for more information:

Flag Options

The following table summarizes the import flag-options, which is followed by a detailed explanation of each.

-n, --numeric

The -n flag configures the output to display raw numeric values for Exif tags instead of more user-friendly formated values, which is the default.

-V, --exclude-virtual

Use this option to excelude virtual tags from output. Virtual tags names always start with an asterisk (*).

view-timestamp, created

The view-timestamp command displays the creation time for an asset. That is, the date and time the asset was orginally captured or created. The output matches the date and time used to expand layout and filename templates as part of the import process. Refer to the MediaKeg Concepts Guide for more information about how MediaKeg evaluates asset creation time.

Usage

$ mkeg view-timestamp [...options] <path>

Arguments

path

The file path for the asset to evaluate and display timestamp information..

Long Options

The following table summarizes the import long-options, which is followed by a detailed explanation of each.

--timeshift

Use this option to view asset timestamp shifted by the specified duration. This option is useful to help ensure the correctness of a timeshift value before committing to an import operation.

Appendix

Cross-Platform Differences

Regular Expressions

DateTime Formats

following formats:

• ISO8601 formatted combined date-time value
• ISO8601 formatted duration value
• Simply formatted duration value

ISO8601 Date and Time Value

Use an ISO8601 date-time formatted value to set a fixed time reference. The primary benefit of this option is the reference time does not change for successive import operations using the same value, and it does not require calculating a duration value to target a specific time.

The file last modified time and the --mtime values are converted to Coordinated Universal Time (UTC) when evaluating if a file was modified after the time value entered, so this must be taken this into account when entering date-time values.

Note: 2018Z is interpreted as a time component because it is attached to an offset. The current date is used because the date-time value is lacking a year component. The current date is used instead of defaulting to 0001-01-01 in the absence of a year component.

Tip: It's recommended to be explicit about entering date-time values by using one of the boldface options from the table rather than rely on defaults to fill in the missing information.

The regular expressions101 site provides an online validator that can be used to validate ISO8601 date-time values using the following regular expression:

^([+-]\d{6}|\d{4})(?:-?(\d\d)(?:-?(\d\d))?)?(?:T(\d\d)(?::?(\d\d)(?::?(\d\d)(?:[.,](\d{1,9}))?)?)?(?:(Z)|([+-]\d\d)(?::?(\d\d))?)?)?$

Duration Formats

Use an ISO8601 duration formatted value to set the time reference in relative terms. The primary benefit of this option is it's more natural (for example, to include only the assets modified in the past week) and it does not require the user to be aware of potential time-zone change implications. Instead, the duration is subtracted from the current UTC clock time to establish a reference. However, unlike the IS08601 date-time option, the calculated reference time will differ over successive import operation for the same input value.

The regular expressions101 site provides an online validator that can be used to validate ISO8601 duration values using the following regular expression:

^([+|-]?)P(?:(?:(-?\d{1,9})Y)?(?:(-?\d{1,9})M)?(?:(-?\d{1,9})W)?(?:(-?\d{1,9})D)?(?:T(?:(-?\d{1,9})H)?(?:(-?\d{1,9})M)?(?:(-?\d{1,9})(?:[.,](-?\d{1,9}))?S)?)?)$

Simplified Duration Value

Use a MediaKeg duration formatted value to set the time reference in relative terms. The primary benefit of this option is it is easier to work with for persons not familiar with ISO8601 durations and is adequate for most scenarios requiring a relative time reference.

The regular expressions101 site provides an online validator that can be used to validate simply formatted duration values using the following regular expression:

^([+|-]?)(\d+\.?\d*)([Ss|Mm|Hh|Dd|Ww|Yy])$

macOS Examples

The following table illustrates examples of source paths for macOS.

Note: Network shares are mounted as /Volumes/<sharename> in macOS.

Windows Examples

Windows uses the backslash for a path delimiter, and volumes and network shares are mounted as drive letters.

More Information

Related Guides

• MediaKeg Concepts Guide
• MediaKeg Quickstart Guide
• MediaKeg Recipes
• MediaKeg FAQ