CLI QuickStart Guide

Install

Before you begin, you’ll need to install the Globus CLI.

Most CLI commands will require authentication to Globus services, so start out by getting logged in:

$ globus login
# follow instructions to get set up

Check `whoami` Data

Once you’re logged in, you can see all sorts of information about your account with the whoami command. The base command shows your current identity:

$ globus whoami
For information on which identities are in session see
  globus session show

demouser@globus.org

Note

The hint about globus session show prints to stderr, while the current username goes to stdout. It only shows in interactive usage, so we’ll omit it from the following examples.

You can get more info using -v/--verbose

$ globus whoami --verbose
Username: demouser@globus.org
Name:     Demo User
ID:       ae332d86-d274-11e5-b885-b31714a110e9
Email:    no-reply@globus.org

Or get a list of your linked identities with --linked-identities:

$ globus whoami --linked-identities
demouser@globus.org
demouser.mcuserpants@globus.org
demodoc@globusid.org

Use a Collection

To interact with Globus Transfer and do some filesystem operations, we’ll need to know the IDs of some Collections on which we have access. Luckily, Globus provides Tutorial Collections which can be used for this purpose!

They have limited capacity and do not guarantee data persistence, but are great for learning and testing. Start by setting their IDs as environment variables:

$ export GLOBUS_TUTORIAL_COLLECTION_ID1="6c54cade-bde5-45c1-bdea-f4bd71dba2cc"
$ export GLOBUS_TUTORIAL_COLLECTION_ID2="31ce9ba0-176d-45a5-add3-f37d233ba47d"

Tip

You can find collection IDs provided by your institution, via the Globus Web App’s search capabilities, via the globus endpoint search command, or by creating them yourself!

Collections are identified uniquely by their IDs, so however you find them, you may want to write down the IDs for later use. Environment variables are a great way of recording this information to make your commands and scripts easier to read and reason about.

Now we have the endpoint IDs for the tutorial endpoints, a directory listing is only a few steps away. First, try to do the listing:

$ globus ls "$GLOBUS_TUTORIAL_COLLECTION_ID1"
The collection you are trying to access data on requires you to grant consent for the Globus CLI to access it.

Please run:

  globus session consent 'urn:globus:auth:scope:transfer.api.globus.org:all[*https://auth.globus.org/scopes/6c54cade-bde5-45c1-bdea-f4bd71dba2cc/data_access]'

to login with the required scopes.

This error message tells us that we need to grant additional consent for this specific collection. As you interact with Globus, you may find other situations in which your consent is required for an action, or in which you need to login an extra time to meet session related security policies.

In this case, we can grant consent by running the command suggested in the error message:

$ globus session consent 'urn:globus:auth:scope:transfer.api.globus.org:all[*https://auth.globus.org/scopes/6c54cade-bde5-45c1-bdea-f4bd71dba2cc/data_access]'
...
You have successfully updated your CLI session.

And then running the ls again:

$ globus ls "$GLOBUS_TUTORIAL_COLLECTION_ID1"

The output is empty!

Let’s create a directory and put a file in it with a transfer:

$ globus mkdir "$GLOBUS_TUTORIAL_COLLECTION_ID1:foo"
The directory was created successfully

$ globus transfer "$GLOBUS_TUTORIAL_COLLECTION_ID1:/home/share/godata/file1.txt" "$GLOBUS_TUTORIAL_COLLECTION_ID1:foo/file1.txt"
Message: The transfer has been accepted and a task has been created and queued for execution
Task ID: b8b66428-befa-11ee-a90e-032e06ca0965

$ globus task wait b8b66428-befa-11ee-a90e-032e06ca0965

Tip

Many Globus Transfer commands take a path in the form of <COLLECTION_ID>:<PATH>, like that globus mkdir command above.

This syntax should be familiar to users of tools like scp and rsync, in which a colon separates the host from the path on that host. Conceptually, a collection is a lot like a host for filesystem operations!

For many commands, when the path is omitted there’s a default which can be used — typically the user’s home directory — just like scp and rsync. Some commands will require an explicit path in order to make sure things are unambiguous.

Now we can see the file and directory with ls:

$ globus ls "$GLOBUS_TUTORIAL_COLLECTION_ID1:foo/"
file1.txt

Explore!

Start exploring the CLI!

Try globus list-commands to see all of the commands in the CLI.

Getting Help and Documentation

Full reference documentation for all CLI commands is available on our documentation site.

You can also view help for any command while using the CLI by passing the --help flag to that command. That will show you any subcommands and options supported by that command.