Ben Summers presents
Spotlight, the way you've always wanted it!

Command line utility

SpotMeta provides a command line utility, spotmeta, for advanced users to use in their own scripts. You can install it using the Preferences panel, or you can use it directly (see the installation section below.

Setting metadata on files or folders

To set metadata on a file, use the command

   spotmeta set <metadata> - <filenames>

The '-' separates the metadata from the filenames, and is optional.

<metadata> is a list of one or more metadata specifications. Each specification either applies a metadata value or removes it.

The name of the key is specified in a type:name format. The types are all single letters.

bBoolean value
dDate (and time)

For example, a text key with name 'Example' would have type:name


If the name of the key is supplied on its own, the value corresponding to that key is removed from the file. If it is followed by an equals sign and a value, the value is applied.

Any metadata values which are not specified in the list are unaltered.

The text value is a simple string. Choices are specified as comma separated strings. Numbers are specified in decimal. Boolean values as 'yes', 'no', '1', or '0'. Date as 'now' or a time specifier in the form YYYYMMDDHHMMSS, unspecified chars defaulting to 19700101120000.

All values are assumed to use the UTF-8 character set.

For example...

   spotmeta set t:Example "c:A Choice=One,Second value" n:Num=0.43565 \
      b:Important=yes "d:Due date=20060120" - file1.txt file2.txt

will remove the text metadata value "Example", set "A Choice" to have values "One" and "Second value", set the number "Num" to 0.43565, set the boolean value "Important" to yes, and the date "Due date" to 20 Jan 2006. This will be applied to the files "file1.txt" and "file2.txt". If those files have other metadata values already applied which are not mentioned in the list, those values will not be altered. (The \ at the end of the first line is the standard UNIX continuation mark, if this is entered all on one line omit the '\' character.)

Note the use of the double quotes whenever a key name or value contains the space character.

Listing metadata applied to files or folders

To list the SpotMeta-editable metadata applied to a file, use the command

   spotmeta list <filenames>

where <filenames> is a list of one or more filenames. The metadata for each file is displayed in type:name format described above, along with the value.

To display all the metadata and to confirm that Spotlight has imported the SpotMeta metadata, use the mdls command.

Displaying a message to the user

The command

   spotmeta telluser <text>

will use the SpotMeta Agent's notification overlay to display a message to the user.


You can install and uninstall the command line utility from the Preferences panel.

This will add a symlink at /usr/bin/spotmeta to the actual utility contained in the application bundle at This is sufficient to provide any user on the system with access to the utility, as long as the bundle is accessible to them. It is recommended you install it in the main Applications folder.

You do not have to install the utility to use it. You could refer to the utility directly, for example


or add the full pathname of the contained bin directory to your PATH environment variable.




How SpotMeta helps you organise your files

Using SpotMeta

Information for Advanced Users


Contact the author

Project status


SpotMeta is an Open Source project, licensed under the GPL.

See note about development status on the contact page.