See also
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.
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>
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
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 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
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 omero logout command:
$ bin/omero logout
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
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
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'
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
--------|---------------------------------------------------------------------------------------------------------
Tags can be linked to objects on the server using the omero 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
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
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)
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
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
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.