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 two ways to use the importer: 
 * Either by using the included shell scripts for Linux and Macintosh, 
 * or by calling directly the ``ome.formats.importer.cli.CommandLineImporter`` class from java on the command line (you will also need to include a path to the required support jars - look inside of the importer-cli scripts for an example of how to do this.)

An example of starting the importer from the command line might look
like this:

::

    ./importer-cli ...

From server installation
------------------------

::

    #!sh
    bin/omero -s localhost -u user import ...

This can also be used to detect what a command ''would'' import.

::

    #!sh
    bin/omero import -f /path/to/file

will print on standard out a list of all the files which would be
imported in groups separated by "#" comments.

Command Line options
--------------------

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

::

    Usage:  importer-cli [OPTION]... [DIR|FILE]... 
    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.

    Mandatory arguments:
     -s   OMERO server hostname
     -u   OMERO experimenter name (username)
     -w   OMERO experimenter password
     -k   OMERO session key (can be used in place of -u and -w)
     -f   Display the used files (does not require other mandatory arguments)

    Optional arguments:
     -c   Continue importing after errors
     -a   Archive the original file on the server
     -l   Use the list of readers rather than the default
     -d   OMERO dataset Id to import image into
     -r   OMERO screen Id to import plate into
     -n   Image name to use
     -x   Image description to use
     -p   OMERO server port [defaults to 4064]
     -h   Display this help and exit

     --no_thumbnails                                    Do not perform thumbnailing after import
     --plate_name                                       Plate name to use
     --plate_description                                Plate description to use
     --debug[=ALL|DEBUG|ERROR|FATAL|INFO|TRACE|WARN]    Turn debug logging on (optional level)
     --report                                           Report errors to the OME team
     --upload                                           Upload broken files with report
     --logs                                             Upload log file with report
     --email                                            Email for reported errors
     --annotation_ns                                    Namespace to use for subsequent annotation
     --annotation_text                                  Content for a text annotation (requires namespace)
     --annotation_link                                  Comment annotation ID to link all images to

     e.g. importer-cli -s localhost -u bart -w simpson -d 50 foo.tiff

     Report bugs to <ome-users@lists.openmicroscopy.org.uk>

These options will also be displayed on the command line by passing no
arguments or "-h" 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:

::

    [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