Command Line Interface (CLI) Examples

Note

When the Globus CLI is used to interact with a collection, it may find that it has not been granted sufficient permissions to access the collection.

In these cases, the CLI will prompt you to run a login command to grant it the necessary consent.

There are also other cases, such as strict authentication policies, in which the CLI dynamically discovers requirements which require a new login flow.

Being prompted to consent to access a collection or to meet a resource policy is a normal part of CLI usage.

1. Synchronous Filesystem Operations

Demonstrates the synchronous commands of mkdir, rename, and ls.

# Collection ID for Globus Tutorial Collection 1
$ COLLECTION=6c54cade-bde5-45c1-bdea-f4bd71dba2cc

# Make a new directory
$ globus mkdir "$COLLECTION:~/cli_example_dir"
The directory was created successfully

# Rename the directory
$ globus rename "$COLLECTION" "~/cli_example_dir" "~/cli_example_dir_renamed"
File or directory renamed successfully

# Show the directory contents after the changes
# (assuming ~/ was empty before these commands)
$ globus ls $COLLECTION
cli_example_dir_renamed/

2. Single Item Transfers

Submits transfer requests for a file and a directory from one Globus Tutorial Collection to another

# Globus Tutorial Collection IDs
$ COLLECTION1=6c54cade-bde5-45c1-bdea-f4bd71dba2cc
$ COLLECTION2=31ce9ba0-176d-45a5-add3-f37d233ba47d

# transfer file1.txt from one endpoint to another
$ globus transfer "$COLLECTION1:/home/share/godata/file1.txt" "$COLLECTION2:~/file1.txt" \
    --label "CLI single file"
Message: The transfer has been accepted and a task has been created and queued for execution
Task ID: 466a5962-dda0-11e6-9d11-22000a1e3b52

# recursively transfer the godata folder from one endpoint to another
$ globus transfer "$COLLECTION1:/home/share/godata" "$COLLECTION2:~/godata" \
    --recursive --label "CLI single folder"
Message: The transfer has been accepted and a task has been created and queued for execution
Task ID: 47477b62-dda0-11e6-9d11-22000a1e3b52

3. Batch Transfers

Uses a .txt file to request multiple files in one transfer request.

# this is the contents of in.txt:
# a list of source paths followed by destination paths

file1.txt file1.txt
file2.txt file2.txt # inline-comments are also allowed
file3.txt file3.txt
# Globus Tutorial Collection IDs
$ COLLECTION1=6c54cade-bde5-45c1-bdea-f4bd71dba2cc
$ COLLECTION2=31ce9ba0-176d-45a5-add3-f37d233ba47d


# pass `--batch` mode an input .txt file
# all paths from stdin are relative to the paths supplied here
$ globus transfer $COLLECTION1:/home/share/godata/ $COLLECTION2:~/ \
    --label "CLI Batch" \
    --batch in.txt
Message: The transfer has been accepted and a task has been created and queued for execution
Task ID: 306900e0-dda1-11e6-9d11-22000a1e3b52
# Globus Tutorial Collection IDs
$ COLLECTION1=6c54cade-bde5-45c1-bdea-f4bd71dba2cc
$ COLLECTION2=31ce9ba0-176d-45a5-add3-f37d233ba47d

# pass `--batch` mode `-` to mean "read stdin", and make the .txt file the
# input to this command
# all paths from stdin are relative to the paths supplied here
$ globus transfer $COLLECTION1:/home/share/godata/ $COLLECTION2:~/ \
    --label "CLI Batch" \
    --batch - < in.txt
Message: The transfer has been accepted and a task has been created and queued for execution
Task ID: 306900e0-dda1-11e6-9d11-22000a1e3b52

Note that only one task was needed even though there are multiple files to be transferred.

4. Deletions

Submits delete task requests for the files transferred by the previous two examples.

Note that globus delete is asynchronous. Even when the command succeeds and the task is submitted, it is possible for the task to fail. Use globus task show or globus task wait to monitor the task after submission. By contrast, globus rm is synchronous, and waits for the completion of the delete task before exiting.

There are other, nuanced differences. globus delete can take --batch inputs, while globus rm cannot, and globus rm has timeout-related options, which may control how and if it fails when waiting on a task which may take too long.

# Globus Tutorial Collection ID
$ COLLECTION2=31ce9ba0-176d-45a5-add3-f37d233ba47d

# recursive deletion of a single folder
$ globus delete "$COLLECTION2:~/godata" --recursive --label "CLI single delete"
Message: The delete has been accepted and a task has been created and queued for execution
Task ID: a3ec193a-dda1-11e6-9d11-22000a1e3b52
# Globus Tutorial Collection ID
$ COLLECTION2=31ce9ba0-176d-45a5-add3-f37d233ba47d

# recursive deletion of a single folder
$ globus rm "$COLLECTION2:~/godata" --recursive --label "CLI single delete"
Delete task submitted under ID "a3ec193a-dda1-11e6-9d11-22000a1e3b52"
.......

Or, alternatively, the files can be deleted individually via a globus delete --batch invocation or multiple globus rm calls.

# this is the contents of in.txt:
# a list of source paths

file1.txt
file2.txt # inline comments are supported
file3.txt
# Globus Tutorial Collection ID
$ COLLECTION2=31ce9ba0-176d-45a5-add3-f37d233ba47d

# batch deletion of multiple files, passing `in.txt` to `--batch`
$ globus delete "$COLLECTION2:~/" --label "CLI batch delete" --batch in.txt
Message: The delete has been accepted and a task has been created and queued for execution
Task ID: a4761f4a-dda1-11e6-9d11-22000a1e3b52

Because globus rm does not accept --batch inputs, it must be run once per-file.

# Globus Tutorial Collection ID
$ COLLECTION2=31ce9ba0-176d-45a5-add3-f37d233ba47d

$ globus rm "$COLLECTION2:~/file1.txt" --label "CLI rm file1.txt"
Delete task submitted under ID "a3ec193a-dda1-11e6-9d11-22000a1e3b52"
...

$ globus rm "$COLLECTION2:~/file2.txt" --label "CLI rm file2.txt"
Delete task submitted under ID "4ce6a1ef-3b60-4ea7-b915-7a0d244f0081"
.......

$ globus rm "$COLLECTION2:~/file3.txt" --label "CLI rm file3.txt"
Delete task submitted under ID "2124caf4-49f9-41c3-97ab-b7ab2f476b30"
..

5. Task Management

Submits an unauthorized transfer task to demonstrate how to view data on why a task hasn’t completed and then cancel the task

# Globus Tutorial Collection IDs
$ COLLECTION1=6c54cade-bde5-45c1-bdea-f4bd71dba2cc
$ COLLECTION2=31ce9ba0-176d-45a5-add3-f37d233ba47d

# submit a transfer request we do not have permission for
$ globus transfer "$COLLECTION1:/home/share/godata" "$COLLECTION2:/home/share/godata" \
    --recursive --label "Unauthorized Transfer"
Message: The transfer has been accepted and a task has been created and queued for execution
Task ID: 67d6e4ba-dda2-11e6-9d11-22000a1e3b52

# copy and paste the task id for later use
$ task_id=67d6e4ba-dda2-11e6-9d11-22000a1e3b52

# view details about the task
# note the Details field reads PERMISSION_DENIED
$ globus task show $task_id
Label:                Unauthorized Transfer
Task ID:              67d6e4ba-dda2-11e6-9d11-22000a1e3b52
Type:                 TRANSFER
Directories:          1
Files:                3
Status:               ACTIVE
Request Time:         2017-01-18 17:20:28+00:00
Deadline:             2017-01-19 17:20:28+00:00
Details:              PERMISSION_DENIED
Source Endpoint:      Globus Tutorial Collection 1
Destination Endpoint: Globus Tutorial Collection 2

# cancel the task
$ globus task cancel $task_id
The task has been cancelled successfully.

Note the Details field read PERMISSION_DENIED, but the status field was still ACTIVE. Globus will eventually time out such a request when the Deadline is reached, but the user has until then to try to repair any permissions.

6. Bookmarks

Creates a bookmark then demonstrates how they can be used in place of UUIDs

# Collection ID for Globus Tutorial Collection 1
$ COLLECTION=6c54cade-bde5-45c1-bdea-f4bd71dba2cc

# Make a new bookmark at Tutorial Collection 1's godata folder
$ globus bookmark create $COLLECTION:/home/share/godata/ "Example Bookmark"
Bookmark ID: ab45785a-dda3-11e6-9d11-22000a1e3b52

# The bookmark now shows up in the bookmarks list
$ globus bookmark list
Name             | Endpoint ID                           | Bookmark ID                          | Path
---------------- | ------------------------------------- | ------------------------------------ | --------------
Example Bookmark | ddb59aef-6d04-11e5-ba46-22000b92c6ecc | ab45785a-dda3-11e6-9d11-22000a1e3b52 | /home/share/godata/

# The bookmark can now be used to get a path without any UUIDs
$ globus ls "$(globus bookmark show 'Example Bookmark')"
file1.txt
file2.txt
file3.txt

7. Safe Resubmissions

Generates a submission-id that allows for resubmitting a task multiple times while guaranteeing that the actual task will only be carried out once.

Although the globus-cli will automatically handle unreliable networks, this will provide even more robust handling, allowing users to add steps like sleep 60 if the network is down for a prolonged period.

Note that the task ID of the task will differ from the submission ID.

# Globus Tutorial Collection IDs
$ COLLECTION1=6c54cade-bde5-45c1-bdea-f4bd71dba2cc
$ COLLECTION2=31ce9ba0-176d-45a5-add3-f37d233ba47d

# generate and store a UUID for the submission-id
$ sub_id="$(globus task generate-submission-id)"

# submit multiple transfers using the same submission-id
$ globus transfer "$COLLECTION1:/home/share/godata" "$COLLECTION2:~/godata" --recursive \
    --submission-id $sub_id --label "1st submission"
Message: The transfer has been accepted and a task has been created and queued for execution
Task ID: 8b43c4e2-dda5-11e6-9d11-22000a1e3b52

$ globus transfer "$COLLECTION1:/home/share/godata" "$COLLECTION2:~/godata" --recursive \
    --submission-id $sub_id --label "2nd submission"
Message: A transfer with id '8b43c4e3-dda5-11e6-9d11-22000a1e3b52' was already submitted
Task ID: 8b43c4e2-dda5-11e6-9d11-22000a1e3b52

$ globus transfer "$COLLECTION1:/home/share/godata" "$COLLECTION2:~/godata" --recursive \
    --submission-id $sub_id --label "3rd submission"
Message: A transfer with id '8b43c4e3-dda5-11e6-9d11-22000a1e3b52' was already submitted
Task ID: 8b43c4e2-dda5-11e6-9d11-22000a1e3b52

# view the task list to confirm only one task was submitted
$ globus task list
Task ID                              | Status    | Type     | Source Display Name          | Dest Display Name            | Label
------------------------------------ | --------- | -------- | ---------------------------- | ---------------------------- | ---------------------
8b43c4e2-dda5-11e6-9d11-22000a1e3b52 | SUCCEEDED | TRANSFER | Globus Tutorial Collection 1 | Globus Tutorial Collection 2 | 1st submission

Note that only one submission has a success message, but all return the ID for the Task, which only gets carried out once.