The Command Line Import

The Command Line Importer tool (CLI) allows you to import images to an OMERO.server from the command line, and is ideally suited for anyone wanting to use a shell-scripted or web-based front-end interface for importing. Based upon the same set of libraries as the standard importer, the command line version supports the same files formats and functions in much the same way. Visit Supported Formats for a detailed list of supported formats.

Starting the Command Line Importer

There are three ways to use the importer from the command line:

• importer-cli shell script, included for Linux and Macintosh only
• ome.formats.importer.cli.CommandLineImporter Java class
• bin/omero import command, from a server installation only

Using the importer using the shell script might look like this:

./importer-cli -s localhost -u user -w pass path/to/file

To use the ome.formats.importer.cli.CommandLineImporter class from java on the command line you will also need to include a classpath to the required support jars. Please look inside of the importer-cli script for an example of how to do this.

With a server installation, from server directory, execute the following command:

bin/omero -s localhost -u user import path/to/file

Note that this method will prompt for any mandatory arguments not provided.

The importer can also be used to detect what files would be imported:

./importer-cli -f /path/to/file

or

bin/omero import -f /path/to/file

will output a list of all the files which would be imported in groups separated by “#” comments. Note that this usage does not require a running server to be available.

Command Line options

The Command Line Importer tool takes a number of mandatory and optional arguments to run, as follows:

 Usage:  importer-cli [OPTION]... [path [path ...]]... 
   or:   importer-cli [OPTION]... - 

Import any number of files into an OMERO instance.
If "-" is the only path, a list of files or directories 
is read from standard in. Directories will be searched for 
all valid imports.

Session arguments:
  Mandatory arguments for creating a session are 1- either the OMERO server hostname,
username and password or 2- the OMERO server hostname and a valid session key.
  -s SERVER	OMERO server hostname
  -u USER	OMERO username
  -w PASSWORD	OMERO password
  -k KEY	OMERO session key (UUID of an active session)
  -p PORT	OMERO server port (default: 4064)

Naming arguments:
All naming arguments are optional
  -n NAME				Image or plate name to use
  -x DESCRIPTION			Image or plate description to use
  --name NAME				Image or plate name to use
  --description DESCRIPTION		Image or plate description to use

Optional arguments:
  -h					Display this help and exit
  -f					Display the used files and exit
  -c					Continue importing after errors
  -l READER_FILE			Use the list of readers rather than the default
  -d DATASET_ID				OMERO dataset ID to import image into
  -r SCREEN_ID				OMERO screen ID to import plate into
  --report				Report errors to the OME team
  --upload				Upload broken files with report
  --logs				Upload log file with report
  --email EMAIL				Email for reported errors
  --debug LEVEL				Turn debug logging on (optional level)
  --annotation_ns ANNOTATION_NS		Namespace to use for subsequent annotation
  --annotation_text ANNOTATION_TEXT	Content for a text annotation (requires namespace)
  --annotation_link ANNOTATION_LINK	Comment annotation ID to link all images to
  --no_thumbnails			Do not perform thumbnailing after import

Examples:

  $ importer-cli -s localhost -u user -w password -d 50 foo.tiff
  $ importer-cli -s localhost -u user -w password -d Dataset:50 foo.tiff
  $ importer-cli -f foo.tiff
  $ importer-cli -s localhost -u username -w password -d 50 --debug ALL foo.tiff

For additional information, see:
http://www.openmicroscopy.org/site/support/omero5/users/command-line-import.html
Report bugs to <ome-users@lists.openmicroscopy.org.uk>

These options will also be displayed on the command line by passing no arguments to the importer.

Note

• Using the --report option sends an automated error report to the QA application. HTTP POST requests are currently used to upload the report. The default parameters (eg. endpoint URL) may be overridden via an INI-formatted configuration file, which is expected to be located within a config directory relative to the CLI importer (see example below).
• The --email option is the OMERO user’s contact email. Note that errors are not sent to this address.

Sample config/importer.config INI file:

[General]
appTitle = OMERO.importer
appVersionNote =
port = 4064
disableUpgradeCheck = false

[Uploader]
TokenURL = http://qa.openmicroscopy.org.uk/qa/initial/
URL = http://qa.openmicroscopy.org.uk/qa/upload_processing/
BugTrackerURL = http://qa.openmicroscopy.org.uk/qa/upload_processing/
forumURL = http://www.openmicroscopy.org/community/

[UI]
forceFileArchiveOn = false
disableImportHistory = false

See also

Advanced import scenarios