GLOBUS LS

NAME

globus ls - List endpoint directory contents.

SYNOPSIS

globus ls [OPTIONS] ENDPOINT_ID[:PATH]

DESCRIPTION

List the contents of a directory on an endpoint. If no path is given, the default directory on that endpoint will be used.

If using text output files and directories are printed with one entry per line in alphabetical order. Directories are always displayed with a trailing '/'.

Filtering

--filter takes "filter patterns" subject to the following rules.

Filter patterns must start with "=", "~", "!", or "!~" If none of these are given, "=" will be used

"=" does exact matching "~" does regex matching, supporting globs (*) "!" does inverse "=" matching "!~" does inverse "~" matching

"~*.txt" matches all .txt files, for example

OPTIONS

-a, --all

Show files and directories that start with .

-l, --long

For text output only. Do long form output, kind of like ls -l

--orderby [group|last_modified|name|permissions|size|type|user]:[ASC|DESC]

Sort results by the given field and ordering. ASC for ascending, DESC for descending.

This option can be specified multiple times to sort by multiple fields.

--filter FILTER_PATTERN

Filter results to filenames matching the given pattern.

-r, --recursive

Do a recursive listing, up to the depth limit. Similar to ls -R

--recursive-depth-limit INTEGER

Limit to number of directories to traverse in --recursive listings. A value of 0 indicates that this should behave like a non-recursive ls [default: 3; x>=0]

--local-user TEXT

Optional value passed to identity mapping specifying which local user account to map to. Only usable with Globus Connect Server v5 mapped collections.

-v, --verbose

Control level of output, make it more verbose.

--quiet

Suppress non-essential output. This is higher precedence than --verbose.

-h, --help

Show this message and exit.

-F, --format [unix|json|text]

Output format for stdout. Defaults to text.

--jmespath, --jq TEXT

A JMESPath expression to apply to json output. Forces the format to be json processed by this expression.

--map-http-status TEXT

Map HTTP statuses to any of these exit codes: 0,1,50-99. e.g. "404=50,403=51"

EXAMPLES

List files and dirs in your default directory on an endpoint

$ ep_id=aa752cea-8222-5bc8-acd9-555b090c0ccb
$ globus ls $ep_id

List files and dirs on a specific path on an endpoint

$ ep_id=aa752cea-8222-5bc8-acd9-555b090c0ccb
$ globus ls $ep_id:/share/godata/

Do a globus ls requesting JSON formatted output

$ globus ls $ep_id:/share/godata/ --format=JSON

Take specific fields from the JSON output and format them into unix-friendly columnar output using '--jmespath' to query and '--format UNIX' to format output:

$ ep_id=aa752cea-8222-5bc8-acd9-555b090c0ccb
$  globus ls $ep_id:/share/godata/ \
    --jmespath 'DATA[*].[type, permissions, name, last_modified]' \
    --format UNIX

Filtering

List files and dirs on a specific path on an endpoint, filtering in various ways.

$ ep_id=aa752cea-8222-5bc8-acd9-555b090c0ccb
$ globus ls $ep_id:/share/godata/ --filter '~*.txt'  # all txt files
$ globus ls $ep_id:/share/godata/ --filter '!~file1.*'  # not starting in "file1."
$ globus ls $ep_id:/share/godata/ --filter '~*ile3.tx*'  # anything with "ile3.tx"
$ globus ls $ep_id:/share/godata/ --filter '=file2.txt'  # only "file2.txt"
$ globus ls $ep_id:/share/godata/ --filter 'file2.txt'  # same as '=file2.txt'
$ globus ls $ep_id:/share/godata/ --filter '!=file2.txt'  # anything but "file2.txt"

Compare a grep with a globus ls --filter. These two are the same, but the filter will be faster because it doesn’t require that filenames which are filtered out are returned to the CLI:

$ ep_id=aa752cea-8222-5bc8-acd9-555b090c0ccb
$ globus ls $ep_id:/share/godata/ | egrep '.*\.txt$'  # done with grep, okay
$ globus ls $ep_id:/share/godata/ --filter '~*.txt'  # done with --filter, better

EXIT STATUS

0 on success.

1 if a network or server error occurred, unless --map-http-status has been used to change exit behavior on http error codes.

2 if the command was used improperly.

3 if the command was used on the wrong type of object, e.g. a collection command used on an endpoint.

4 if the command has authentication or authorization requirements which were not met, as in ConsentRequired errors or missing logins.