Nexus CLI Utility

Parent Previous Next

Nexus CLI Utility

A command line utility is included that allows for many Nexus operations to be run from the command line.  These operations include: listing entities on the server, importing entities from files on disk, deleting entities, copy entities between servers and modify the tags on entities.  These functions are implemented as a single command line tool, leveraging sub-commands to perform the individual operations.

Basic Command Usage


nexus [-h] {cp,htmlexport,import,ls,rm,tag} ...


The sub-commands are cp, import, ls, rm, htmlexport and tag.  Help on individual commands may be obtained by combining -h with the sub-command, so:


nexus cp -h


will display help related to the sub-command.  

Notes

Most commands require the URL of a server to be provided.  This is usually in the form:  http://{username}:{password}@{hostname}:{port}.  For example: http://nexus:cei@127.0.0.1:8000.  This URL syntax exposes the username and password of the database in cleartext as such command lines are often visible to all users running on the same system.  If no username or password is supplied (e.g. http://127.0.0.1:8000), the tool will look at the environmental variables:  NEXUS_TOOLS_USERNAME and NEXUS_TOOLS_PASSWORD for the username and password to use, avoiding command line exposure.

For templates, generally only top level templates can be manipulated for operations like deleting and copying and those operations will be applied to the entire tree of templates.

Copy Sub-command (cp)

usage: nexus cp [-h] [--test] [--verbose] [--type {item,template}]

                    [--query query_string]

                    source_server_url destination_server_url


Copy items, sessions, datasets and templates from one Nexus server to another.


positional arguments:

  source_server_url     Nexus server URL. Example:

                        http://nexus:cei@127.0.0.1:8000

  destination_server_url

                        Target Nexus server URL. Example:

                        http://nexus:cei@127.0.0.1:8000


optional arguments:

  -h, --help            show this help message and exit

  --test                Validate the operation, but do not perform it

  --verbose             Include progress and other information

  --type {item,template}

                        Select the object type to copy. Default: item

  --query query_string  Specify a query string. Default: no filter

Description

This tool copies a selected collection of objects (data items or templates) from one server to another.  GUIDs are preserved and any referenced session and dataset objects are copied as well.

Arguments

Options

Various options exist.

Import Sub-command (import)

usage: nexus import [-h] [--disable_encoding_check]

                        [--session_guid [session_guid]]

                        [--session_date [date]]

                        [--session_hostname [hostname]]

                        [--session_platform [platform]]

                        [--session_application [application]]

                        [--session_version [version]]

                        [--session_tags [tag_string]]

                        [--dataset_guid [dataset_guid]]

                        [--dataset_filename [filename]]

                        [--dataset_dirname [directory]]

                        [--dataset_format [format]] [--dataset_parts [count]]

                        [--dataset_elements [count]]

                        [--dataset_tags [tag_string]]

                        [--data_guid [item_guid]] [--data_date [date]]

                        [--data_sequence [number]] [--data_name [name]]

                        [--data_source [name]] [--data_tags [tag_string]]

                        [--data_categories [categoryA [categoryB ...]]]

                        [--ext_image [ext [ext ...]]]

                        [--ext_movie [ext [ext ...]]]

                        [--ext_table [ext [ext ...]]]

                        [--ext_scene [ext [ext ...]]]

                        [--ext_file [ext [ext ...]]]

                        [--ext_text [ext [ext ...]]]

                        [--ext_html [ext [ext ...]]] [--table_col_labels]

                        [--table_row_labels] [--table_numeric]

                        [--table_delimiter [char]] [--table_quote_char [char]]

                        [--verbose] [--test] [--print_options]

                        nexus_server_url [file|directory [file|directory ...]]


Import data items from disk into the Nexus server.


positional arguments:

  nexus_server_url      Nexus server URL. Example:

                        http://nexus:cei@127.0.0.1:8000

  file|directory        File and directory names to import


optional arguments:

  -h, --help            show this help message and exit

  --disable_encoding_check

                        Disable the implicit check for UTF-8 encoding of

                        uploaded files

  --session_guid [session_guid]

                        GUID of an existing Nexus session to use for new data

                        items

  --session_date [date]

                        Creation date for the created session

  --session_hostname [hostname]

                        Hostname for the created session

  --session_platform [platform]

                        Platform name for the created session

  --session_application [application]

                        Application name for the created session

  --session_version [version]

                        Version for the created session

  --session_tags [tag_string]

                        Tags for the created session

  --dataset_guid [dataset_guid]

                        GUID of an existing Nexus dataset to use for new data

                        items

  --dataset_filename [filename]

                        Filename for the created dataset

  --dataset_dirname [directory]

                        Directory name for the created dataset

  --dataset_format [format]

                        Format for the created dataset

  --dataset_parts [count]

                        Number of parts for the created dataset

  --dataset_elements [count]

                        Number of elements for the created dataset

  --dataset_tags [tag_string]

                        Tags for the created dataset

  --data_guid [item_guid]

                        GUID for newly imported items (note only useful when

                        importing a single data item, use with caution)

  --data_date [date]    Creation date for created data items (__timestamp__ is

                        the file timestamp)

  --data_sequence [number]

                        Sequence number for the created data items

  --data_name [name]    Name for created data items (__file__ is the file

                        basename)

  --data_source [name]  Source for created data items (__file__ is the file

                        basename)

  --data_tags [tag_string]

                        Tags for created data items

  --data_categories [categoryA [categoryB ...]]

                        List of space-separated categories to assign the item

                        to.

  --ext_image [ext [ext ...]]

                        Filename extensions to be imported as image. Default:

                        ['png', 'jpg']

  --ext_movie [ext [ext ...]]

                        Filename extensions to be imported as movie. Default:

                        ['mp4']

  --ext_table [ext [ext ...]]

                        Filename extensions to be imported as table. Default:

                        ['csv']

  --ext_scene [ext [ext ...]]

                        Filename extensions to be imported as scene. Default:

                        ['stl', 'ply', 'csf', 'avz']

  --ext_file [ext [ext ...]]

                        Filename extensions to be imported as file. Default:

                        []

  --ext_text [ext [ext ...]]

                        Filename extensions to be imported as text. Default:

                        ['txt']

  --ext_html [ext [ext ...]]

                        Filename extensions to be imported as html. Default:

                        ['htm', 'html']

  --table_col_labels    Input csv files will have a column label row

  --table_row_labels    Input csv files will have a row label column

  --table_numeric       Table items generated from .csv files will have

                        strictly numeric content

  --table_delimiter [char]

                        The delimiter in csv files

  --table_quote_char [char]

                        The quote character in csv files

  --verbose             Enable verbose mode

  --test                Validate the operation, but do not perform it

  --print_options       Print import configuration option values

Description

The tool allows a user to upload data from files into a Nexus database. This is similar to the "Upload files into data items" application in the Nexus web interface. In addition to specifying files or directories to upload, many options for defining exactly how the data should be incorporated into the existing data at the Nexus server are provided. These include specification of session, dataset, tags, what data item type-specific file extensions should be uploaded as, and how tables should be handled.

Item file uploads for files of type 'csv, txt and html' now have to be strictly UTF-8 encoded. On upload, there is a check for UTF-8 encoding which is used to force this requirement. This check is enabled by default and uploads will fail if this check fails. You can disable this check using -disable_encoding_check if you feel that your file is correctly encoded.

The tool takes a list of files and/or directories as arguments. When a directory is specified, the tool will recursively visit its contents, uploading all files that match the file extensions specified with the -ext_* options. 

Arguments

Options

If any of these options are specified multiple times on the command line, only the last one takes effect.

List Sub-command (ls)

usage: nexus ls [-h] [--full] [--long] [--guid] [--header] [--no-header]

                    [--type {item,session,dataset,template,category,group}]

                    [--query query_string]

                    nexus_server_url


List items, sessions, datasets and templates in the Nexus server.


positional arguments:

  nexus_server_url      Nexus server URL. Example:

                        http://nexus:cei@127.0.0.1:8000


optional arguments:

  -h, --help            show this help message and exit

  --full                Increase the level of output detail

  --long                One item per line

  --guid                Include the GUID in the output

  --header              Include headers in the output

  --no-header           Do not include headers in the output

  --type {item,session,dataset,template,category,group}

                        Select the object type to list. Default: item

  --query query_string  Specify a query string. Default: no filter

Description

This tool selects a collection of objects and prints the details of the objects to stdout.

Arguments

Options

Various options exist.

Delete Sub-command (rm)

usage: nexus rm [-h] [--type {item,template}] [--query query_string]

                    [--verbose] [--test]

                    nexus_server_url


Delete items or report templates from the Nexus server. Only top level

templates can be deleted and all of their children will be deleted as well.


positional arguments:

  nexus_server_url      Nexus server URL. Example:

                        http://nexus:cei@127.0.0.1:8000


optional arguments:

  -h, --help            show this help message and exit

  --type {item,template}

                        Select the object type to remove. Default: item

  --query query_string  Specify a query string. Default: no filter

  --verbose             Enable verbose mode

  --test                Validate the operation, but do not perform it

Description

This tool deletes a selected collection of objects (data items or templates) from a server.

Arguments

Options

Various options exist.

HTML export command (htmlexport)

usage: nexus htmlexport [-h] [--query query_string]

                            [--filename top_level_filename]

                            [--no_inline_files] [--verbose]

                            nexus_server_url destination_directory


Export a selected report as offline html from the Nexus server. Note: the

template query will always include a top level check. The report will be

exported into the named destination directory, which must not exist. The

default top level filename will be index.html stored in the destination

directory. The top level filename can be specified on the command line and

should include both filename and extension.


positional arguments:

  nexus_server_url      Nexus server URL. Example:

                        http://nexus:cei@127.0.0.1:8000

  destination_directory

                        Directory to save HTML report into. Must not exist.


optional arguments:

  -h, --help            show this help message and exit

  --query query_string  Query string used to select the report template to

                        export. Default: no filter

  --filename top_level_filename

                        The filename of the top-level file. Default:

                        index.html

  --no_inline_files     Disable the use of data URIs in the output

  --verbose             Enable verbose mode

Description

This tool generates a report on the nexus server and downloads the resulting html into a local directory structure.  Note: some item types will be converted into forms that do not require a running Nexus server.

Arguments

Options

Various options exist.


PDF export command (pdfexport)

usage: nexus pdfexport [-h] [--query query_string] [--verbose] nexus_server_url pdf_filename


Export a selected report in pdf format from the Nexus server. Note: the template query will always include a top level

check. The report will be written into the named file, which must not exist.


positional arguments:

  nexus_server_url      Nexus server URL. Example: http://nexus:cei@127.0.0.1:8000

  pdf_filename          Filename to save the PDF file as. Must not exist.


optional arguments:

  -h, --help            show this help message and exit

  --query query_string  Query string used to select the report template to

                        export. Default: no filter

  --verbose             Enable verbose mode

Description

This tool generates a report on the nexus server and renders the selected report into a local PDF format file.

Arguments

Options

Various options exist.


Tagging command (tag)

usage: nexus tag [-h] [--value VALUE]

                     [--type {item,session,dataset,template}]

                     [--query query_string] [--verbose] [--test]

                     nexus_server_url {add,remove,replace} tagname


Modify item, template, session, and dataset object tags in the Nexus server.


positional arguments:

  nexus_server_url      Nexus server URL. Example:

                        http://nexus:cei@127.0.0.1:8000

  {add,remove,replace}  Tag operation

  tagname               The tag to modify


optional arguments:

  -h, --help            show this help message and exit

  --value VALUE         Tag value if needed

  --type {item,session,dataset,template}

                        Select the object type to list. Default: item

  --query query_string  Specify a query string. Default: no filter

  --verbose             Enable verbose mode

  --test                Validate the operation, but do not perform it

Description

This tool walks a collection of objects (data items, sessions, datasets or templates) selected via a query string and manipulates the tag strings.  Consider a tag of the form tag_name=value, where '=value' is optional.  tag_name is specified via an argument and value may be specified via the --value option.  The resulting tag can be added to, removed from or modified on the selected objects. This tool will not add a tag multiple times to the same object.

Arguments

Options

Various options exist.