OMERO Command Line Interface
============================

.. seealso::

    :doc:`/sysadmins/command-line-interface`
        System administrator documentation for the Command Line Interface

    :doc:`/developers/command-line-interface`
        Developer documentation for the Command Line Interface

Overview
--------

The |CLI| is a set of Python_ based system-administration, deployment and
advanced user tools. Most of commands work remotely so that the |CLI| can be
used as a client against an OMERO server.

Requirements
^^^^^^^^^^^^

Check you have Python_ installed by typing::

    $ python --version
    Python 2.7.5+

Additionally, Ice_ must be installed on your machine::

    $ python -c "import Ice"

The |CLI| is currently bundled with the OMERO.server. Download the version
corresponding to your system from the :downloads:`OMERO downloads <>` page.

.. note::
	The |CLI| is bundled with the OMERO.server but that does not imply you
	must use that directory as a server. You can download the server zip to a
	number of machines and use the |CLI| commands from each machine to access
	an existing OMERO instance.

Once the server is downloaded, the |CLI| is located under the :file:`bin/`
directory::

    $ cd OMERO.server
    $ bin/omero -h
    OMERO Python Shell. Version 4.4.5-ice33
    Type "help" for more information, "quit" or Ctrl-D to exit
    omero>

.. _cli_help:

Command line help
^^^^^^^^^^^^^^^^^

The |CLI| is divided into several commands which may themselves contain
subcommands. You can investigate the various commands available using the
:option:`-h` or :option:`--help` option::

    $ bin/omero -h

Again, you can use :option:`-h` repeatedly to get more details on each of
these sub-commands::

    $ bin/omero admin -h
    $ bin/omero admin start -h

The :omerocmd:`help` command can be used to get info on other commands or
options::

    $ bin/omero help debug       # debug is an option
    $ bin/omero help admin       # same as bin/omero admin -h

Command line workflow
^^^^^^^^^^^^^^^^^^^^^

There are three ways to use the command line tools:

#.  By explicitly logging in to the server first i.e. by creating a session
    using the :omerocmd:`login` command.
    The connection parameters can be either passed directly in the connection
    string::

        $ bin/omero login username@servername:4064

    or using the :option:`-s`, :option:`-u` and :option:`-p` options::

        $ bin/omero login -s servername -u username -p 4064

    If no argument can be specified, the interface will ask for the
    connection credentials::

        $ bin/omero login
        Previously logged in to localhost:4064 as root
        Server: [localhost]
        Username: [root]
        Password:

    During login, a session is created locally on disk and will remain active
    until you logout or it times out. You can then call the desired command,
    e.g. the :omerocmd:`import` command::

        $ bin/omero import image.tiff

#.  By passing the session arguments directly to the desired command, e.g.::

        $ bin/omero -s servername -u username -p 4064 import image.tiff

#.  By calling the desired command without login arguments. You will be asked
    to login::

        $ bin/omero import image.tiff
        Server: [servername]
        Username: [username]
        Password:

Once you are done with your work, you can terminate the current session if you
wish using the :omerocmd:`logout` command::

    $ bin/omero logout

Import images
-------------

.. program:: omero import

:omerocmd:`import` is probably the first command many users will want to use.
To import a file image.tiff, use::

    $ bin/omero import image.tiff

Many options can be passed to the :omerocmd:`import`. They can be listed using
the :option:`-h` option::

    $ bin/omero import -h

The :option:`-f` option displays all the used files for importing then exits::

    $ bin/omero import -f image.tif
    $ bin/omero import -f images_folder

The :option:`--depth` option sets the number of directories to scan down for
files (default: 4)::

    $ bin/omero import --depth 1 images_folder

Manage tags
-----------

The :omerocmd:`tag` subcommands manage the creation, linking and listing of
tag annotations. All subcommands can be listed using the :option:`-h` option::

    $ bin/omero tag -h

Create tags
^^^^^^^^^^^

To create a new tag annotation, use the :omerocmd:`tag create` command::

    $ bin/omero tag create
    Please enter a name for this tag: my_tag
    Please enter a description for this tag: description of my_tag

To create a tag set containing two existing tags of known identifiers
``1259`` and ``1260``, use the :omerocmd:`tag createset` command::

	$ bin/omero tag createset --tag 1259 1260
	Please enter a name for this tag set: my_tag_set
	Please enter a description for this tag set: description of my_tag_set

For both tags and tag sets, the name and description can be passed using the
:option:`--name` and :option:`--desc` options::

	$ bin/omero tag create --name my_tag --desc 'description of my_tag'
	$ bin/omero tag createset --tag 1259 1260 tag_id_2 --name my_tag_set --desc 'description of my_tag_set'

List tags
^^^^^^^^^

To list all the tags owned by the current user, use the :omerocmd:`tag list`
command::

    $ bin/omero tag list
    +- 1261:'my_tag_set'
    |\
    | +- 1259:'my_tag'
    | +- 1260:'my_tag_2'
    +- 1264:'my_tag_set_2'
    |\
    | +- 1260:'my_tag_2'
    | +- 1263:'my_tag_4'

    Orphaned tags:
    > 1262:'my_tag_3'

To list all the tag sets owned by the current user, use the
:omerocmd:`tag listsets` command::

    $ bin/omero tag listsets
    --------|---------------------------------------------------------------------------------------------------------
    ID      |Name
    --------|---------------------------------------------------------------------------------------------------------
    1261    |my_tag_set
    1264    |my_tag_set_2
    --------|---------------------------------------------------------------------------------------------------------

Link tags
^^^^^^^^^

Tags can be linked to objects on the server using the :omerocmd:`tag link`
command. The object must be specified as ``object_type:object_id``. To link
the tag of identifier ``1260`` to the Image of identifier ``1000``, use::

    $ bin/omero tag link Image:1000 1260

Manage sessions
---------------

The :omerocmd:`sessions` commands manage user sessions stored locally on disk.
Several sessions can be active simultaneously, but only one will be used for a
single invocation of `bin/omero`::

    $ bin/omero sessions -h

Multiple sessions
^^^^^^^^^^^^^^^^^

Stored sessions can be listed using the :omerocmd:`sessions list` command::

    $ bin/omero sessions list
     Server    | User | Group           | Session                              | Active    | Started
    -----------+------+-----------------+--------------------------------------+-----------+--------------------------
     localhost | test | read-annotate-2 | 22fccb8b-d04c-49ec-9d52-116a163728ca | Logged in | Fri Nov 23 14:55:25 2012
     localhost | root | system          | 1f800a16-1dc2-407a-8a85-fb44005306be | True      | Fri Nov 23 14:55:18 2012
    (2 rows)

Sessions keys can then be reused to switch between stored sessions::

    $ bin/omero sessions login -k 22fccb8b-d04c-49ec-9d52-116a163728ca
    Server: [localhost]
    Joined session 1f800a16-1dc2-407a-8a85-fb44005306be (root@localhost:4064).
    $ bin/omero sessions list
     Server    | User | Group           | Session                              | Active    | Started
    -----------+------+-----------------+--------------------------------------+-----------+--------------------------
     localhost | test | read-annotate-2 | 22fccb8b-d04c-49ec-9d52-116a163728ca | True      | Fri Nov 23 14:55:25 2012
     localhost | root | system          | 1f800a16-1dc2-407a-8a85-fb44005306be | Logged in | Fri Nov 23 14:55:18 2012
    (2 rows)

Sessions directory
^^^^^^^^^^^^^^^^^^

By default sessions are saved locally on disk under :file:`~/omero/sessions`.
The location of the current session file can be retrieved using the
:omerocmd:`sessions file` command::

    $ bin/omero sessions file
    /Users/ome/omero/sessions/localhost/root/aec828e1-79bf-41f3-91e6-a4ac76ff1cd5

If you want to use a custom session directory, use the
:option:`--session-dir` argument in the :omerocmd:`sessions` commands::

    $ bin/omero login --session-dir=/tmp
    $ bin/omero sessions list --session-dir=/tmp
    $ bin/omero logout --session-dir=/tmp

Switching current group
^^^^^^^^^^^^^^^^^^^^^^^

The sessions command can be used to switch the group of your current session::

    $ bin/omero group list          # list your groups
    $ bin/omero sessions group 2    # switch to group by ID or Name

Repository management
---------------------

Since 5.0.3 it is possible to list images, filesets and the repositories that
contain them. See :ref:`cli_omero_fs` in the System Administrator documentation
for more information.