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 :bf_doc:`Supported Formats <supported-formats.html>` 
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:

.. literalinclude:: /downloads/cli/help.out

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 :file:`config/importer.config` INI file:

.. literalinclude:: /downloads/cli/import.config

.. seealso:: :doc:`/sysadmins/import-scenarios`