OMERO Command Line Interface

See also

OMERO Command Line Interface

System administrator documentation for the Command Line Interface

OMERO Command Line Interface

Developer documentation for the Command Line Interface

Overview

Requirements

The CLI is a set of Python based system-administration and deployment tools.

Check you have Python installed by typing:

$ python --version
Python 2.5.1

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 OMERO downloads page.

Once the server is downloaded, the CLI is located under the 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>

Command line help

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

$ bin/omero -h

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

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

The omero 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:

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

   $ bin/omero login username@servername:4064

   or using the -s, -u and -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 omero import command:

   $ bin/omero import image.tiff

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

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

3. 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 omero logout command:

$ bin/omero logout

Import images

omero 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 omero import. They can be listed using the -h option:

$ bin/omero import -h

Manage sessions

The omero 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 omero 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 ~/omero/sessions. The location of the current session file can be retrieved using the omero 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 --session-dir argument in the omero sessions commands:

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