Skip to content

Commit db669f7

Browse files
jbureljburel
authored
Merge pull request #2192 from dominikl/cli_import_options
Update CLI import option documentation
2 parents 1b40b78 + 06b5625 commit db669f7

File tree

2 files changed

+156
-41
lines changed

2 files changed

+156
-41
lines changed

‎omero/downloads/cli/help.out

+132-40
Original file line numberDiff line numberDiff line change
@@ -1,49 +1,141 @@
11

2-
Import any number of files into an OMERO instance.
3-
If "-" is the only path, a list of files or directories
4-
is read from standard in. Directories will be searched for
5-
all valid imports.
6-
7-
Session arguments:
8-
Mandatory arguments for creating a session are 1- either the OMERO server hostname,
9-
username and password or 2- the OMERO server hostname and a valid session key.
10-
-s SERVER OMERO server hostname
11-
-u USER OMERO username
12-
-w PASSWORD OMERO password
13-
-k KEY OMERO session key (UUID of an active session)
14-
-p PORT OMERO server port (default: 4064)
2+
Run the Java-based command-line importer
3+
4+
This is a Python wrapper around the Java importer. Login is handled by Python
5+
OMERO.cli. To see more options, use "--javahelp".
6+
7+
Options marked with "**" are passed strictly to Java. If they interfere with
8+
any of the Python arguments, you may need to end precede your arguments with a
9+
"--".
10+
11+
Bulk imports:
12+
13+
Rather than passing one or more files to the import command, a single
14+
dictionary-like file (e.g. yml or json) can be passed to the `--bulk`
15+
argument. Most keys in the bulk file will be treated like additional
16+
command-line arguments. Special keys include:
17+
18+
* columns A list of columns for parsing the value of path
19+
* continue Like the "-c" changes error handling
20+
* dry_run If true, print out additional arguments rather than run them.
21+
If another string other than false, use as a template for
22+
storing the import commands. (e.g. /tmp/%s.sh)
23+
* include Relative path (from the bulk file) of a parent bulk file
24+
* path A file which will be parsed line by line based on its file
25+
ending. Lines containing zero or more keys along with a
26+
single file to be imported. Options for formats include:
27+
- .tsv and .csv files will be parsed by the existing library
28+
- other files will be parsed with shlex
29+
- unless no columns are specified, in which case each line
30+
is treated as a file
31+
32+
Optional Arguments:
33+
In addition to any higher level options
34+
35+
-h, --help show this help message and exit
36+
--javahelp, --java-help Show the Java help text
37+
38+
Login arguments:
39+
Environment variables:
40+
41+
OMERO_USERDIR Set the base directory containing the user's files.
42+
Default: $HOME/omero
43+
OMERO_SESSIONDIR Set the base directory containing local sessions.
44+
Default: $OMERO_USERDIR/sessions
45+
OMERO_TMPDIR Set the base directory containing temporary files.
46+
Default: $OMERO_USERDIR/tmp
47+
OMERO_PASSWORD Set the user's password for creating new sessions.
48+
Ignored if -w or --password is used.
49+
50+
51+
Optional session arguments:
52+
53+
-C, --create Create a new session regardless of existing ones
54+
-s SERVER, --server SERVER OMERO server hostname
55+
-p PORT, --port PORT OMERO server port
56+
-g GROUP, --group GROUP OMERO server default group
57+
-u USER, --user USER OMERO username
58+
-w PASSWORD, --password PASSWORD OMERO password
59+
-k KEY, --key KEY OMERO session key (UUID of an active session)
60+
--sudo ADMINUSER Create session as this admin. Changes meaning of password!
61+
-q, --quiet Quiet mode. Causes most warning and diagnostic messages to be suppressed.
62+
63+
Python arguments:
64+
Optional arguments which are used to configure import.
65+
66+
--bulk [BULK] Bulk YAML file for driving multiple imports
67+
--logprefix [LOGPREFIX] Directory or file prefix for --file and --errs
68+
--file [FILE] File for storing the standard output from the Java process
69+
--errs [ERRS] File for storing the standard error from the Java process
70+
--clientdir CLIENTDIR Path to the directory containing the client JARs. Default: lib/client
71+
--logback LOGBACK Path to a logback xml file. Default: etc/logback-cli.xml
72+
--fetch-jars FETCH_JARS Download this version of OMERO.java jars and exit
73+
--depth DEPTH Number of directories to scan down for files
74+
--skip {all,checksum,minmax,thumbnails,upgrade}
75+
Optional step to skip during import
76+
path Path to be passed to the Java process
1577

1678
Naming arguments:
17-
All naming arguments are optional
18-
-n NAME Image or plate name to use
19-
-x DESCRIPTION Image or plate description to use
20-
--name NAME Image or plate name to use
21-
--description DESCRIPTION Image or plate description to use
22-
23-
Optional arguments:
24-
-h Display this help and exit
25-
-f Display the used files and exit
26-
-c Continue importing after errors
27-
-l READER_FILE Use the list of readers rather than the default
28-
-d DATASET_ID OMERO dataset ID to import image into
29-
-r SCREEN_ID OMERO screen ID to import plate into
30-
-T TARGET target for imports
31-
--report Report errors to the OME team
32-
--upload Upload broken files and log file (if any) with report. Required --report
33-
--logs Upload log file (if any) with report. Required --report
34-
--email EMAIL Email for reported errors. Required --report
35-
--debug LEVEL Turn debug logging on (optional level)
36-
--annotation-ns ANNOTATION_NS Namespace to use for subsequent annotation
37-
--annotation-text ANNOTATION_TEXT Content for a text annotation
38-
--annotation-link ANNOTATION_LINK Comment annotation ID to link all images to
79+
Optional arguments passed strictly to Java.
80+
81+
-n NAME, --name NAME Image or plate name to use (**)
82+
-x DESCRIPTION, --description DESCRIPTION
83+
Image or plate description to use (**)
84+
85+
Feedback arguments:
86+
Optional arguments passed strictly to Java allowing to report errors to the OME team.
87+
88+
--report Report errors to the OME team (**)
89+
--upload Upload broken files and log file (if any) with report. Required --report (**)
90+
--logs Upload log file (if any) with report. Required --report (**)
91+
--email EMAIL Email for reported errors. Required --report (**)
92+
93+
Annotation arguments:
94+
Optional arguments passed strictly to Java allowing to annotate imports.
95+
96+
--annotation-ns ANNOTATION_NS Namespace to use for subsequent annotation (**)
97+
--annotation-text ANNOTATION_TEXT Content for a text annotation (**)
98+
--annotation-link ANNOTATION_LINK Comment annotation ID to link all images to (**)
99+
100+
Java arguments:
101+
Optional arguments passed strictly to Java.
102+
103+
-f Display the used files and exit (**)
104+
-c Continue importing after errors (**)
105+
-l READER_FILE, --readers READER_FILE
106+
Use the list of readers rather than the default (**)
107+
-d DATASET_ID OMERO dataset ID to import image into (**)
108+
-r SCREEN_ID OMERO screen ID to import plate into (**)
109+
-T TARGET, --target TARGET OMERO target specification (**)
110+
--debug LEVEL Turn debug logging on (**)
111+
--output TYPE Set an alternative output style
112+
--encrypted TYPE Whether the import should use SSL or not
113+
114+
Advanced Java arguments:
115+
Optional arguments passed strictly to Java. For more information, see --advanced-help.
116+
117+
--advanced-help Show the advanced help text
118+
--transfer [TYPE] Transfer methods like in-place import
119+
--exclude [TYPE] Exclusion filters for preventing re-import
120+
--checksum-algorithm [TYPE] Alternative hashing mechanisms balancing speed & accuracy
121+
--parallel-upload COUNT Number of file upload threads to run at the same time
122+
--parallel-fileset COUNT Number of fileset candidates to import at the same time
39123

40124
Examples:
41125

42-
$ importer-cli -s localhost -u user -w password -d 50 foo.tiff
43-
$ importer-cli -s localhost -u user -w password -d Dataset:50 foo.tiff
44-
$ importer-cli -f foo.tiff
45-
$ importer-cli -s localhost -u username -w password -d 50 --debug ALL foo.tiff
126+
# Display help
127+
$ omero import -h
128+
# Import foo.tiff using current login
129+
$ omero import ~/Data/my_file.dv
130+
# Import foo.tiff using input credentials
131+
$ omero import -s localhost -u user -w password foo.tiff
132+
# Set Java debugging level to ALL
133+
$ omero import foo.tiff -- --debug=ALL
134+
# Display used files for importing foo.tiff
135+
$ omero import foo.tiff -f
136+
# Limit debugging output
137+
$ omero import -- --debug=ERROR foo.tiff
46138

47139
For additional information, see:
48140
https://docs.openmicroscopy.org/latest/omero/users/cli/import.html
49-
Report bugs at https://www.openmicroscopy.org/forums
141+
Report bugs at https://forum.image.sc/tag/omero-cli

‎omero/users/cli/import.rst

+24-1
Original file line numberDiff line numberDiff line change
@@ -40,7 +40,7 @@ Some of the options available to the import command are:
4040

4141
$ omero import -s SERVER -p PORT -u USER -g GROUP image.tif
4242

43-
.. option:: -d DATASET_ID, -T TARGET, --target TARGET
43+
.. option:: -d DATASET_ID, -r SCREEN_ID, -T TARGET, --target TARGET
4444

4545
To import images into a Dataset::
4646

@@ -50,6 +50,29 @@ Some of the options available to the import command are:
5050

5151
See :doc:`import-target` for more information on import targets.
5252

53+
--logprefix [LOGPREFIX] Directory or file prefix for --file and --errs
54+
--file [FILE] File for storing the standard output from the Java process
55+
--errs [ERRS] File for storing the standard error from the Java process
56+
57+
.. option:: --file FILE
58+
59+
File for storing the standard output from the Java process
60+
61+
.. option:: --errs FILE
62+
63+
File for storing the standard error from the Java process
64+
65+
.. option:: --logprefix DIR
66+
67+
Directory or file prefix for --file and --errs
68+
69+
.. option:: --output TYPE
70+
71+
Set an alternative output style, for example::
72+
73+
$ omero import --output=yaml ...
74+
75+
5376
Scanning folders prior to Import
5477
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
5578

0 commit comments

Comments
 (0)