Page Contents

OMERO

Downloads
Feature List
Licensing

Previous topic

OMERO clients overview

Next topic

The Command Line Import

This Page

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

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 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 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

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

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

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

$ bin/omero import --depth 1 images_folder

Manage tags

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

$ bin/omero tag -h

Create tags

To create a new tag annotation, use the omero 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 omero 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 --name and --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 omero 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 omero tag listsets command:

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

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

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 Repository management in the System Administrator documentation for more information.