Command Line Reference

The primary method of interacting with the Near-Line Data Store is through a command line client, which can be installed using the instructions.

Users must specify a command to the nlds and options and arguments for that command.

nlds [OPTIONS] COMMAND [ARGS]...

As an overview the commands are:

Commands:: find     Find and list files.

get      Get a single file.

getlist Get a number of files specified in a list.

init     Set up the nlds client with a config file on first use.

list     List holdings.

meta     Alter metadata for a holding.

put      Put a single file.

putlist Put a number of files specified in a list.

stat     List transactions.

Each command has its own specific options. The argument is generally the file or filelist that the user wishes to operate on. The full command listing is given below.

nlds

nlds [OPTIONS] COMMAND [ARGS]...

find

Find and list files. If no user or group is given then these values will default to the user:default_user and user:default values in the ~/.nlds-config file.

nlds find [OPTIONS]

Options

-u, --user <user>: The username to find files for.

-g, --group <group>: The group to find files for.

-A, --groupall: Find files that belong to a group, rather than a single user

-l, --label <label>: The label of the holding which the files belong to. This can be a regular expression (regex).

-i, --holding_id <holding_id>: The numeric id of the holding which the files belong to.

-n, --transaction_id <transaction_id>: The UUID transaction id of the transaction to list.

-p, --path <path>: The path of the files to find. This can be a regular expression (regex)

-t, --tag <tag>: The tag(s) of the holding(s) to find files within.

-j, --json: Output the result as JSON.

-1, --simple: Output the list of files, one per line, filepath only.

-U, --url: Output the URL for the file on the object storage.

get

Get a single file. If no user or group is given then these values will default to the user:default_user and user:default values in the ~/.nlds-config file.

nlds get [OPTIONS] FILEPATH

Options

-u, --user <user>: The username to get a file for.

-g, --group <group>: The group to get a file for.

-A, --groupall: Get a file that belongs to a group, rather than a single user

-r, --target <target>: The target path for the retrieved file. Default is to retrieve the file to its original path.

-l, --label <label>: The label of the holding to retrieve the file from. This can be a regular expression (regex).

-b, --job_label <job_label>: An optional label for the GET job, that can be viewed when using the stat command

-i, --holding_id <holding_id>: The id of the holding to retrieve the file from.

-t, --tag <tag>: The tag(s) of the holding to retrieve the file from.

-j, --json <json>: Output the result as JSON.

Arguments

FILEPATH: Required argument

getlist

Get a number of files specified in a list. If no user or group is given then these values will default to the user:default_user and user:default values in the ~/.nlds-config file.

nlds getlist [OPTIONS] FILELIST

Options

-u, --user <user>: The username to get files for.

-g, --group <group>: The group to get files for.

-A, --groupall: Get files that belong to a group, rather than a single user

-r, --target <target>: The target path for the retrieved files. Default is to retrieve files to their original path.

-l, --label <label>: The label of the holding(s) to retrieve files from. This can be a regular expression (regex).

-b, --job_label <job_label>: An optional label for the GET job, that can be viewed when using the stat command

-i, --holding_id <holding_id>: The id of the holding to retrieve files from.

-t, --tag <tag>: The tag(s) of the holding(s) to retrieve files from.

-j, --json <json>: Output the result as JSON.

Arguments

FILELIST: Required argument

init

Set up the NLDS client on first use. Will either create a new config file if one doesn’t exist or fill the ‘authentication’ section with appropriate values if it does.

nlds init [OPTIONS]

Options

-u, --url <url>: Url to use for getting config info. Must start with http(s)://

-k, --insecure: Boolean flag to control whether to turn off verification of ssl certificates during request. Defaults to true, only needs to be False for the staging/test version of the NLDS.

list

List holdings. If no user or group is given then these values will default to the user:default_user and user:default values in the ~/.nlds-config file.

nlds list [OPTIONS]

Options

-u, --user <user>: The username to list holdings for.

-g, --group <group>: The group to list holdings for.

-A, --groupall: List holdings that belong to a group, rather than a single user

-l, --label <label>: The label of the holding(s) to list. This can be a regularexpression (regex).

-i, --holding_id <holding_id>: The numeric id of the holding to list.

-n, --transaction_id <transaction_id>: The UUID transaction id of the transaction to list.

-t, --tag <tag>: The tag(s) of the holding(s) to list.

-j, --json: Output the result as JSON.

meta

Alter metadata for a holding. If no user or group is given then these values will default to the user:default_user and user:default values in the ~/.nlds-config file.

nlds meta [OPTIONS]

Options

-u, --user <user>: The username to use when changing metadata for a holding.

-g, --group <group>: The group to use when changing metadata for a holding.

-l, --label <label>: The label of the holding to change metadata for. This can be a regular expression (regex)

-i, --holding_id <holding_id>: The numeric id of the holding to change metadata for.

-t, --tag <tag>: The tag(s) of the holding(s) to change metadata for.

-L, --new_label <new_label>: The new label for the holding.

-T, --new_tag <new_tag>: The new tag(s) for the holding.

-D, --del_tag <del_tag>: Delete a tag from the holding.

-j, --json: Output the result as JSON.

put

Put a single file.

nlds put [OPTIONS] FILEPATH

Options

-u, --user <user>: The username to put the file for.

-g, --group <group>: The group to put the file for.

-l, --label <label>: The label of the holding to put the file into. If the holding already exists then the file will be added to it. If the holding does not exist then it will be created with the label. If this option is omitted then a new holding with a random label will be created.

-b, --job_label <job_label>: An optional label for the PUT job, that can be viewed when using the stat command

-i, --holding_id <holding_id>: The numeric id of an existing holding to put the file into.

-t, --tag <tag>: The tags of a holding to put the file into. If a holding with the tags already exists then the file will the added to that holding. If the holding does not exist then it will be created with the tags and either a random label or a named label,if the label parameter is also supplied. The set of tags must guarantee uniqueness of the holding.

-j, --json <json>: Output the result as JSON.

Arguments

FILEPATH: Required argument

putlist

Put a number of files specified in a list. If no user or group is given then these values will default to the user:default_user and user:default values in the ~/.nlds-config file.

nlds putlist [OPTIONS] FILELIST

Options

-u, --user <user>: The username to put files for.

-g, --group <group>: The group to put files for.

-l, --label <label>: The label of the holding to put files into. If the holding already exists then the files will be added to it. If the holding does not exist then it will be created with the label. If this option is omitted then a new holding with a random label will be created.

-b, --job_label <job_label>: An optional label for the PUT job, that can be viewed when using the stat command

-i, --holding_id <holding_id>: The numeric id of an existing holding to put files into.

-t, --tag <tag>: The tags of a holding to put files into. If a holding with the tags already exists then the files will the added to that holding. If the holding does not exist then it will be created with the tags and either a random label or a named label,if the label parameter is also supplied. The set of tags must guarantee uniqueness of the holding.

-j, --json <json>: Output the result as JSON.

Arguments

FILELIST: Required argument

stat

List transactions. If no user or group is given then these values will default to the user:default_user and user:default values in the ~/.nlds-config file.

nlds stat [OPTIONS]

Options

-u, --user <user>: The username to list transactions for.

-g, --group <group>: The group to list transactions for.

-A, --groupall: List transactions that belong to a group, rather than a single user

-i, --id <id>: The numeric id of the transaction to list.

-n, --transaction_id <transaction_id>: The UUID transaction id of the transaction to list.

-b, --job_label <job_label>: The job label of the transaction(s) to list.

-a, --api_action <api_action>: The api action of the transactions to list. Options: get | put | getlist | putlist

-s, --state <state>: The state of the transactions to list. Options: INITIALISING | ROUTING | SPLITTING | INDEXING | CATALOG_PUTTING | TRANSFER_PUTTING | CATLOG_ROLLBACK | CATALOG_GETTING | ARCHIVE_GETTING | TRANSFER_GETTING | ARCHIVE_INIT | CATALOG_ARCHIVE_AGGREGATING | ARCHIVE_PUTTING | CATALOG_ARCHIVE_UPDATING | CATALOG_ARCHIVE_ROLLBACK | COMPLETE | FAILED | COMPLETE_WITH_ERRORS | COMPLETE_WITH_WARNINGS

-j, --json: Output the result as JSON.