OMERO Command Line Interface
============================
.. seealso::
:doc:`/users/command-line-interface`
User documentation for the Command Line Interface
:doc:`/developers/command-line-interface`
Developer Documentation for the Command Line Interface
Help for any specific CLI command can be displayed using the :option:`-h`
argument. See :ref:`cli_help` for more information.
When first beginning to work with the OMERO server, the :omerocmd:`db`,
:omerocmd:`config`, and :omerocmd:`admin` commands will be the first you will
need.
Database tools
--------------
Rather than try to provide the functionality of a RDBM tool like ``psql``, the
:omerocmd:`db script` command helps to generate SQL scripts for building your
database. You can then use those scripts from whatever tool is most
comfortable for you::
$ bin/omero db script OMERO4 0 secretpassword
Using OMERO4 for version
Using 0 for patch
Using password from commandline
Saving to /omero/OMERO4__0.sql
$ psql omero < OMERO4__0.sql
Server configuration
--------------------
The :omerocmd:`config` command is responsible for reading / writing
user-specific profiles stored under :file:`etc/grid/config.xml`. To get
the current profile, use the :omerocmd:`config def` command::
$ bin/omero config def
default
You can then examine the current profile keys using :omerocmd:`config get`
and set key-value pairs using :omerocmd:`config set`::
$ bin/omero config get
$ bin/omero config set example "my first value"
$ bin/omero config get
example=my first value
You can use the :envvar:`OMERO_CONFIG` environment variable to point at a
different profile, e.g.::
$ OMERO_CONFIG=another bin/omero config def
another
$ OMERO_CONFIG=another bin/omero config get
$ OMERO_CONFIG=another bin/omero config set example "my second value"
$ OMERO_CONFIG=another bin/omero config get
example=my second value
The values set via :omerocmd:`config set` override those compiled into the
server jars. The default values which are set can be seen in :doc:`config`. To
add several values to a configuration, you can pipe them via standard in using
:omerocmd:`config load`::
$ grep omero.ldap etc/omero.properties | OMERO_CONFIG=ldap bin/omero config load
$ OMERO_CONFIG=ldap bin/omero config get
omero.ldap.attributes=objectClass
omero.ldap.base=ou=example,o=com
omero.ldap.config=false
omero.ldap.groups=
omero.ldap.keyStore=
omero.ldap.keyStorePassword=
omero.ldap.new_user_group=default
omero.ldap.password=
omero.ldap.protocol=
omero.ldap.trustStore=
omero.ldap.trustStorePassword=
omero.ldap.urls=ldap://localhost:389
omero.ldap.username=
omero.ldap.values=person
Each of these values can then be modified to suit your local setup. To
remove one of the key-value pairs, pass no second argument::
$ OMERO_CONFIG=ldap bin/omero config set omero.ldap.trustStore
$ OMERO_CONFIG=ldap bin/omero config set omero.ldap.trustStorePassword
$ OMERO_CONFIG=ldap bin/omero config set omero.ldap.keyStore
$ OMERO_CONFIG=ldap bin/omero config set omero.ldap.keyStorePassword
$ OMERO_CONFIG=ldap bin/omero config get
omero.ldap.attributes=objectClass
omero.ldap.base=ou=example,o=com
omero.ldap.config=false
omero.ldap.groups=
omero.ldap.new_user_group=default
omero.ldap.password=
omero.ldap.protocol=
omero.ldap.urls=ldap://localhost:389
omero.ldap.username=
omero.ldap.values=person
If you will be using a particular profile more frequently you can set it
as your default using the :omerocmd:`config def` command::
$ bin/omero config def ldap
And finally, if you would like to remove a profile, for example to wipe a
given password off of a system, use :omerocmd:`config drop`::
$ bin/omero config drop
Server administration
---------------------
Server start
^^^^^^^^^^^^
Once your database has been properly configured and your config profile
is set to use that database, you are ready to start your server using the
:omerocmd:`admin start` command::
$ bin/omero admin start
.. note::
:omerocmd:`admin start` and :omerocmd:`admin restart` provide a useful
debugging and maintenance option called :option:`--foreground`. Using
this option allows for starting the server up in the foreground, that is
without creating a daemon on UNIX-like systems or service on Windows.
During the lifetime of the server, the prompt from which it was launched
will be blocked.
Server diagnostics
^^^^^^^^^^^^^^^^^^
::
$ bin/omero admin diagnostics
User/group management
---------------------
The :omerocmd:`user` and :omerocmd:`group` commands provide functionalities to
add and manage users and groups on your database.
User creation
^^^^^^^^^^^^^
New users can be added to the database using the :omerocmd:`user add` command::
$ bin/omero user add -h
During the addition of the new user, you will need to specify the first and
last name of the new user and their username as well as the groups the user
belongs to. To add John Smith as a member of group 2 identified as jsmith,
enter::
$ bin/omero user add jsmith John Smith 2
Additional parameters such as the email address, institution, middle name etc
can be passed as optional arguments to the :omerocmd:`user add` command.
.. _ldap_setdn:
Converting non-LDAP users to LDAP authentication
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
If you want to take an existing (non-LDAP) user and 'upgrade' them to using
LDAP you can do so using the :omerocmd:`ldap setdn` command::
$ bin/omero ldap setdn -h
The process is also reversible so that the OMERO password for a user rather
than the LDAP password will be used. See the caveat in the setdn help output
below:
.. literalinclude:: /downloads/ldap/setdn.out
Group creation
^^^^^^^^^^^^^^
New groups can be added to the database using the :omerocmd:`group add`
command::
$ bin/omero group add -h
During the addition of the new group, you need to specify the name of the new
group::
$ bin/omero group add newgroup
The permissions of the group are set to `private` by default. Alternatively you
can specify the permissions using :option:`--perms` or :option:`--type`
optional arguments::
$ bin/omero group add read-only-1 --perms='rwr---'
$ bin/omero group add read-annotate-1 --type=read-annotate
.. seealso::
:doc:`server-permissions`
Description of the three group permissions levels (private, read-only,
read-annotate).
Lists of users/groups on the OMERO server can be queried using the
:omerocmd:`user list` and :omerocmd:`group list` commands::
$ bin/omero user list
$ bin/omero group list
Group management
^^^^^^^^^^^^^^^^
Users can be added to existing groups using the :omerocmd:`user joingroup` or
:omerocmd:`group adduser` commands. Similarly, users can be removed from
existing groups using the :omerocmd:`user leavegroup` or
:omerocmd:`group removeuser` commands::
# Add jsmith to group read-annotate-1
$ bin/omero group adduser jsmith --name=read-annotate-1
# Remove jsmith from group read-annotate-1
$ bin/omero group removeuser jsmith --name=read-annotate-1
# Add jsmith to group read-only-1
$ bin/omero user joingroup read-only-1 --name=jsmith
# Remove jsmith from group read-only-1
$ bin/omero user leavegroup read-only-1 --name=jsmith
By passing the :option:`--as-owner` option, these commands can also be used to manage group owners ::
# Add jsmith to the owner list of group read-annotate-1
$ bin/omero group adduser jsmith --name=read-annotate-1 --as-owner
# Remove jsmith from the owner list of group read-annotate-1
$ bin/omero user leavegroup read-annotate-1 --name=jsmith --as-owner
Group copy
^^^^^^^^^^
To create a copy of a group, you must first create a new group using the
:omerocmd:`group add` command::
$ bin/omero group add read-only-2 --perms='rwr---'
Then you can use the :omerocmd:`group copyusers` command to copy all group
members from one group to another::
$ bin/omero group copyusers read-only-1 read-only-2
To copy the group owners, use the same command with the :option:`--as-owner` optional argument::
$ bin/omero group copyusers read-only-1 read-only-2 --as-owner
Sudo functionality
------------------
Since 5.0.2, the CLI includes a sudo functionality for administrators allowing
them to execute commands as another user. For example, to login as
*username*, the root user can invoke the following command::
$ bin/omero login --sudo root -s servername -u username
Password for root:
The :option:`--sudo` option is available to all commands accepting connection
arguments. For instance to import data for user *username*::
$ bin/omero import --sudo root -s servername -u username image.tiff
.. _cli_omero_fs:
Repository management
---------------------
Since 5.0.3 it is possible to list images, filesets and the repositories that
contain them. At an administrator-only level it is also possible to move
filesets. This functionality is provided by the :omerocmd:`fs` command. See
::
$ bin/omero fs -h
Listing repositories
^^^^^^^^^^^^^^^^^^^^
The :omerocmd:`fs repos` subcommand lists the repositories used by OMERO. For
example
::
bin/omero fs repos
# | Id | UUID | Type | Path
---+----+--------------------------------------+---------+--------------------------
0 | 1 | 83bf5c68-8236-47ff-ae3e-728674eb0103 | Managed | /OMERO/ManagedRepository
1 | 2 | ad899754-bff0-4605-a234-acd4da178f3b | Public | /OMERO
2 | 3 | ScriptRepo | Script | /dist/lib/scripts
The options available to this subcommand are:
.. program:: omero fs repos
.. option:: -h, --help
Display the help for this subcommand.
.. option:: --style <{plain,csv,sql}>
This option determines the output style, tabular `sql` being the default as
in the previous example. The `csv` style is comma-separated values with an
initial header row, `plain` is the same as `csv` but without the header row.
.. option:: --managed
This option lists only Managed repositories.
For example
::
bin/omero fs repos --managed --style=csv
#,Id,UUID,Type,Path
0,1,83bf5c68-8236-47ff-ae3e-728674eb0103,Managed,/OMERO/ManagedRepository
Listing filesets
^^^^^^^^^^^^^^^^
The :omerocmd:`fs sets` subcommand lists filesets by various criteria.
Filesets are bundles of original data imported into OMERO 5 and above, which
represent one or more images. For example
::
bin/omero fs sets
# | Id | Prefix | Images | Files | Transfer
----+-------+-----------------------------------+--------+-------+----------
0 | 79853 | user-3_9/2014-07/22/16-41-04.244/ | 1 | 1 |
1 | 79852 | user-3_9/2014-07/22/10-44-11.235/ | 1 | 1 |
2 | 79851 | user-3_9/2014-07/22/10-44-07.300/ | 1 | 1 |
3 | 79813 | user-3_9/2014-07/21/14-13-02.353/ | 1 | 1 |
4 | 79812 | user-3_9/2014-07/21/14-13-00.182/ | 1 | 1 |
5 | 79811 | user-3_9/2014-07/21/14-12-59.212/ | 1 | 1 |
6 | 79810 | user-3_9/2014-07/21/14-12-57.896/ | 1 | 1 |
7 | 79809 | user-3_9/2014-07/21/14-10-22.436/ | 3 | 600 |
...
24 | 79772 | user-4_5/2014-07/18/17-14-43.631/ | 1 | 1 |
(25 rows, starting at 0 of approx. 50173)
The options available to this subcommand are:
.. program:: omero fs sets
.. option:: -h, --help
Display the help for this subcommand.
.. option:: --style <{plain,csv,sql}>
See :option:`omero fs repos --style`.
.. option:: --limit <LIMIT>
This option specifies the maximum number of return values, the default
is 25.
.. option:: --offset <OFFSET>
This option specifies the number of entries to skip before starting the
listing, the default, 0, is to skip no entries.
.. option:: --order <{newest,oldest,prefix}>
This option determines the order of the rows returned, `newest` is the
default.
.. option:: --without-images
This option lists only those filesets without images, these may be corrupt
filesets.
.. option:: --with-transfer <WITH_TRANSFER [WITH_TRANSFER ...]>
This option lists only those filesets imported using the given in-place
import methods.
.. option:: --check
This option checks each fileset for validity by recalculating each file's
checksum and comparing it with the checksum recorded upon import. This may
be slow. **This option is available to administrators only.**
.. option:: --extended
With this option more details are provided for each returned value.
This may be slow.
For example
::
bin/omero fs sets --order oldest --limit 3 --offset 5 --check
# | Id | Prefix | Images | Files | Transfer | Check
---+----+-----------------------------------+--------+-------+----------+-------
0 | 54 | user-3_9/2014-06/09/09-24-28.037/ | 1 | 1 | | OK
1 | 55 | user-3_9/2014-06/09/09-24-31.354/ | 1 | 1 | | OK
2 | 57 | user-5_4/2014-06/09/11-01-00.557/ | 1 | 1 | | OK
(3 rows, starting at 5 of approx. 78415)
Listing images
^^^^^^^^^^^^^^
The :omerocmd:`fs images` subcommand lists imported images by various criteria.
This subcommand is useful for showing pre-FS (i.e. OMERO 4.4 and before) images
which have their original data archived with them. For example
::
bin/omero fs images
# | Image | Name | FS | # Files | Size
----+--------+-----------------------------------+-------+---------+----------
0 | 102803 | kidney_TFl_1.bmp.ome.tiff | 79853 | 1 | 435.1 KB
1 | 102802 | 4kx4k.jpg | 79852 | 1 | 1.7 MB
2 | 102801 | 2kx2k.jpg | 79851 | 1 | 486.3 KB
3 | 102773 | multi-channel.ome.tif | 79813 | 1 | 220.3 KB
4 | 102772 | multi-channel-z-series.ome.tif | 79812 | 1 | 1.1 MB
5 | 102771 | multi-channel-time-series.ome.tif | 79811 | 1 | 1.5 MB
6 | 102770 | multi-channel-4D-series.ome.tif | 79810 | 1 | 7.4 MB
7 | 102769 | 001_001_000_000.tif [Well B6] | 79809 | 600 | 1.1 GB
...
24 | 102732 | 00027841.png | 79774 | 1 | 235 B
(25 rows, starting at 0 of approx. 117393)
The options available to this subcommand are:
.. program:: omero fs images
.. option:: -h, --help
Display the help for this subcommand.
.. option:: --style {plain,csv,sql}
See :option:`omero fs repos --style`.
.. option:: --limit <LIMIT>
See :option:`omero fs sets --limit`.
.. option:: --offset <OFFSET>
See :option:`omero fs sets --offset`
.. option:: --order <{newest,oldest,prefix}>
See :option:`omero fs sets --order`.
.. option:: --archived
With this option the subcommand lists only images with archived data.
.. option:: --extended
With this option more details are provided for each returned value.
This may be slow.
For example
::
bin/omero fs images --archived --offset 16 --limit 3
# | Image | Name | FS | # Files | Size
---+-------+---------------------------+----+---------+---------
0 | 15481 | UMD001_ORO.svs [Series 1] | | 1 | 12.7 MB
1 | 15478 | biosamplefullframetif.tif | | 1 | 32.0 MB
2 | 10018 | 050118.lei [07-13-a] | | 4 | 4.8 MB
(3 rows, starting at 16 of approx. 833)
Renaming filesets
^^^^^^^^^^^^^^^^^
The :omerocmd:`fs rename` subcommand moves an existing fileset, specified by its
ID, to a new location. **This subcommand is available to administrators only.**
It may be useful to rename an existing fileset after the import template
(:term:`omero.fs.repo.path`) has been changed to match the new template. By
default the files in the fileset and the accompanying import log are moved. For
example, after adding the group name and group ID to template and chnaging the
date format
::
$ bin/omero fs rename 9
Renaming Fileset:9 to pg-0_3/user-0_2/2014-07-23/16-48-20.786/
Moving user-0_2/2014-07/23/16-31-51.070/ to pg-0_3/user-0_2/2014-07-23/16-48-20.786/
Moving user-0_2/2014-07/23/16-31-51.070.log to pg-0_3/user-0_2/2014-07-23/16-48-20.786.log
The ID can be given as a number or in the form `Fileset:ID`.
The options available to this subcommand are:
.. program:: omero fs rename
.. option:: -h, --help
Display the help for this subcommand.
.. option:: --no-move
With this option the files will be left in place to be moved later. Advice
will be given as to which files need to be moved to complete the renaming
process. Note that if the files are not moved then the renamed filesets will
not be accessible until the files have been moved into the new positions.
For example
::
$ bin/omero fs rename Fileset:8 --no-move
Renaming Fileset:8 to pg-0_3/user-0_2/2014-07-23/16-49-23.543/
Done. You will now need to move these files manually:
-----------------------------------------------------
mv /OMERO/ManagedRepository/user-0_2/2014-07/23/16-29-14.809/ /OMERO/ManagedRepository/pg-0_3/user-0_2/2014-07-23/16-49-23.543/
mv /OMERO/ManagedRepository/user-0_2/2014-07/23/16-29-14.809.log /OMERO/ManagedRepository/pg-0_3/user-0_2/2014-07-23/16-49-23.543.log