Update CLI import option documentation

omero/downloads/cli/help.out

@@ -1,49 +1,141 @@
 
-Import any number of files into an OMERO instance.
-If "-" is the only path, a list of files or directories 
-is read from standard in. Directories will be searched for 
-all valid imports.
-
-Session arguments:
-  Mandatory arguments for creating a session are 1- either the OMERO server hostname,
-username and password or 2- the OMERO server hostname and a valid session key.
-  -s SERVER	OMERO server hostname
-  -u USER	OMERO username
-  -w PASSWORD	OMERO password
-  -k KEY	OMERO session key (UUID of an active session)
-  -p PORT	OMERO server port (default: 4064)
+Run the Java-based command-line importer
+
+This is a Python wrapper around the Java importer. Login is handled by Python
+OMERO.cli. To see more options, use "--javahelp".
+
+Options marked with "**" are passed strictly to Java. If they interfere with
+any of the Python arguments, you may need to end precede your arguments with a
+"--".
+
+Bulk imports:
+
+Rather than passing one or more files to the import command, a single
+dictionary-like file (e.g. yml or json) can be passed to the `--bulk`
+argument. Most keys in the bulk file will be treated like additional
+command-line arguments. Special keys include:
+
+ * columns      A list of columns for parsing the value of path
+ * continue     Like the "-c" changes error handling
+ * dry_run      If true, print out additional arguments rather than run them.
+                If another string other than false, use as a template for
+                storing the import commands. (e.g. /tmp/%s.sh)
+ * include      Relative path (from the bulk file) of a parent bulk file
+ * path         A file which will be parsed line by line based on its file
+                ending. Lines containing zero or more keys along with a
+                single file to be imported. Options for formats include:
+                  - .tsv and .csv files will be parsed by the existing library
+                  - other files will be parsed with shlex
+                  - unless no columns are specified, in which case each line
+                    is treated as a file
+
+Optional Arguments:
+  In addition to any higher level options
+
+  -h, --help                            show this help message and exit
+  --javahelp, --java-help               Show the Java help text
+
+Login arguments:
+  Environment variables:
+
+    OMERO_USERDIR     Set the base directory containing the user's files.
+                      Default: $HOME/omero
+    OMERO_SESSIONDIR  Set the base directory containing local sessions.
+                      Default: $OMERO_USERDIR/sessions
+    OMERO_TMPDIR      Set the base directory containing temporary files.
+                      Default: $OMERO_USERDIR/tmp
+    OMERO_PASSWORD    Set the user's password for creating new sessions.
+                      Ignored if -w or --password is used.
+
+
+  Optional session arguments:
+
+  -C, --create                          Create a new session regardless of existing ones
+  -s SERVER, --server SERVER            OMERO server hostname
+  -p PORT, --port PORT                  OMERO server port
+  -g GROUP, --group GROUP               OMERO server default group
+  -u USER, --user USER                  OMERO username
+  -w PASSWORD, --password PASSWORD      OMERO password
+  -k KEY, --key KEY                     OMERO session key (UUID of an active session)
+  --sudo ADMINUSER                      Create session as this admin. Changes meaning of password!
+  -q, --quiet                           Quiet mode. Causes most warning and diagnostic messages to be suppressed.
+
+Python arguments:
+  Optional arguments which are used to configure import.
+
+  --bulk [BULK]                         Bulk YAML file for driving multiple imports
+  --logprefix [LOGPREFIX]               Directory or file prefix for --file and --errs
+  --file [FILE]                         File for storing the standard output from the Java process
+  --errs [ERRS]                         File for storing the standard error from the Java process
+  --clientdir CLIENTDIR                 Path to the directory containing the client JARs.  Default: lib/client
+  --logback LOGBACK                     Path to a logback xml file.  Default: etc/logback-cli.xml
+  --fetch-jars FETCH_JARS               Download this version of OMERO.java jars and exit
+  --depth DEPTH                         Number of directories to scan down for files
+  --skip {all,checksum,minmax,thumbnails,upgrade}
+                                        Optional step to skip during import
+  path                                  Path to be passed to the Java process
 
 Naming arguments:
-All naming arguments are optional
-  -n NAME				Image or plate name to use
-  -x DESCRIPTION			Image or plate description to use
-  --name NAME				Image or plate name to use
-  --description DESCRIPTION		Image or plate description to use
-
-Optional arguments:
-  -h					Display this help and exit
-  -f					Display the used files and exit
-  -c					Continue importing after errors
-  -l READER_FILE			Use the list of readers rather than the default
-  -d DATASET_ID				OMERO dataset ID to import image into
-  -r SCREEN_ID				OMERO screen ID to import plate into
-  -T TARGET				target for imports
-  --report				Report errors to the OME team
-  --upload				Upload broken files and log file (if any) with report. Required --report
-  --logs				Upload log file (if any) with report. Required --report
-  --email EMAIL				Email for reported errors. Required --report
-  --debug LEVEL				Turn debug logging on (optional level)
-  --annotation-ns ANNOTATION_NS		Namespace to use for subsequent annotation
-  --annotation-text ANNOTATION_TEXT	Content for a text annotation
-  --annotation-link ANNOTATION_LINK	Comment annotation ID to link all images to
+  Optional arguments passed strictly to Java.
+
+  -n NAME, --name NAME                  Image or plate name to use (**)
+  -x DESCRIPTION, --description DESCRIPTION
+                                        Image or plate description to use (**)
+
+Feedback arguments:
+  Optional arguments passed strictly to Java allowing to report errors to the OME team.
+
+  --report                              Report errors to the OME team (**)
+  --upload                              Upload broken files and log file (if any) with report. Required --report (**)
+  --logs                                Upload log file (if any) with report. Required --report (**)
+  --email EMAIL                         Email for reported errors. Required --report (**)
+
+Annotation arguments:
+  Optional arguments passed strictly to Java allowing to annotate imports.
+
+  --annotation-ns ANNOTATION_NS         Namespace to use for subsequent annotation (**)
+  --annotation-text ANNOTATION_TEXT     Content for a text annotation (**)
+  --annotation-link ANNOTATION_LINK     Comment annotation ID to link all images to (**)
+
+Java arguments:
+  Optional arguments passed strictly to Java.
+
+  -f                                    Display the used files and exit (**)
+  -c                                    Continue importing after errors (**)
+  -l READER_FILE, --readers READER_FILE
+                                        Use the list of readers rather than the default (**)
+  -d DATASET_ID                         OMERO dataset ID to import image into (**)
+  -r SCREEN_ID                          OMERO screen ID to import plate into (**)
+  -T TARGET, --target TARGET            OMERO target specification (**)
+  --debug LEVEL                         Turn debug logging on (**)
+  --output TYPE                         Set an alternative output style
+  --encrypted TYPE                      Whether the import should use SSL or not
+
+Advanced Java arguments:
+  Optional arguments passed strictly to Java. For more information, see --advanced-help.
+
+  --advanced-help                       Show the advanced help text
+  --transfer [TYPE]                     Transfer methods like in-place import
+  --exclude [TYPE]                      Exclusion filters for preventing re-import
+  --checksum-algorithm [TYPE]           Alternative hashing mechanisms balancing speed & accuracy
+  --parallel-upload COUNT               Number of file upload threads to run at the same time
+  --parallel-fileset COUNT              Number of fileset candidates to import at the same time
 
 Examples:
 
-  $ importer-cli -s localhost -u user -w password -d 50 foo.tiff
-  $ importer-cli -s localhost -u user -w password -d Dataset:50 foo.tiff
-  $ importer-cli -f foo.tiff
-  $ importer-cli -s localhost -u username -w password -d 50 --debug ALL foo.tiff
+  # Display help
+  $ omero import -h
+  # Import foo.tiff using current login
+  $ omero import ~/Data/my_file.dv
+  # Import foo.tiff using input credentials
+  $ omero import -s localhost -u user -w password foo.tiff
+  # Set Java debugging level to ALL
+  $ omero import foo.tiff -- --debug=ALL
+  # Display used files for importing foo.tiff
+  $ omero import foo.tiff -f
+  # Limit debugging output
+  $ omero import -- --debug=ERROR foo.tiff
 
 For additional information, see:
 https://docs.openmicroscopy.org/latest/omero/users/cli/import.html
-Report bugs at https://www.openmicroscopy.org/forums
+Report bugs at https://forum.image.sc/tag/omero-cli

omero/users/cli/import.rst

@@ -40,7 +40,7 @@ Some of the options available to the import command are:
 
         $ omero import -s SERVER -p PORT -u USER -g GROUP image.tif
 
-.. option:: -d DATASET_ID, -T TARGET, --target TARGET
+.. option:: -d DATASET_ID, -r SCREEN_ID, -T TARGET, --target TARGET
 
     To import images into a Dataset::
 
@@ -50,6 +50,29 @@ Some of the options available to the import command are:
 
     See :doc:`import-target` for more information on import targets.
 
+  --logprefix [LOGPREFIX]               Directory or file prefix for --file and --errs
+  --file [FILE]                         File for storing the standard output from the Java process
+  --errs [ERRS]                         File for storing the standard error from the Java process
+
+.. option:: --file FILE
+
+    File for storing the standard output from the Java process
+
+.. option:: --errs FILE
+
+    File for storing the standard error from the Java process
+
+.. option:: --logprefix DIR
+
+    Directory or file prefix for --file and --errs
+
+.. option:: --output TYPE
+
+    Set an alternative output style, for example::
+
+        $ omero import --output=yaml ...
+
+
 Scanning folders prior to Import
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^