Set up Pelican¶

Abstract

The Pelican Platform is the software that powers the OSDF. In this guide, you'll learn:

how to install the Pelican client
basics of using the Pelican client

Install the Pelican client¶

We recommend that you use the Pelican CLI (command line interface) client for most purposes. To install the Pelican CLI, follow the instructions for your operating system:

For additional ways to install the Pelican CLI client, see the Pelican documentation.

Other Pelican clients

There are other Pelican clients for interacting with Pelican federations such as the OSDF. For more information, see the Pelican client documentation.

For the purposes of this website, we assume that you are using the Pelican CLI client!

Confirm installation¶

Let's confirm you have Pelican installed by running the following command:

pelican --version

This command should work regardless of your operating system and will display the version number, as well as some information about the software build.

For example,

$ pelican --version
Version: 7.19.2
Build Date: 2025-09-11T16:10:33Z
Build Commit: 298fba8f7a7801adc35b4a3620d117ad38bb436a
Built By: goreleaser

Test download¶

Next, you should test that you can download a public object from the OSDF. Run the following command:

pelican object get osdf:///pelicanplatform/test/hello-world.txt ./

You may or may not see a progress bar as part of the download - it depends on how quickly the object can be downloaded. For example:

$ pelican object get osdf:///pelicanplatform/test/hello-world.txt ./
hello-world.txt 27.00b / 27.00b [=======================================] Done!

If successful, you should see a new file in your directory called hello-world.txt, with the following contents:

If you are seeing this message, getting an object from OSDF was successful.

Pelican client basics¶

Understanding the test command you ran above is a good introduction to how Pelican works.

Commands¶

Most users will only ever use the pelican object set of commands. To see all the available commands, run this:

pelican object --help

Other pelican commands

You can see the other available sets of commands with

pelican --help

We recommend you avoid using these other commands unless you are specifically told to use one. These other sets of commands are generally used by the admins running a Pelican federation.

If you are interested in learning more about these commands, we recommend reading the Pelican docs.

The most common commands you'll use are

Command	Description
`pelican object ls`	list an object or namespace within a federation
`pelican object get`	download an object from a federation
`pelican object put`	upload an object to a federation

The Pelican URL¶

You usually need to provide a "Pelican URL" that specifies the address of the object or namespace that you are interacting with. For objects in the OSDF, this URL has the following format:

osdf:///<namespace>/<object_name>

The osdf:// prefix tells Pelican to use the OSDF.
The /<namespace>/ part tells Pelican where to find the desired dataset(s).
The <object_name> part tells Pelican the specific object to find.

If you are managing the data in a namespace, understanding the distinction between the namespace part and the object part is important. But otherwise, most end users won't need to know the difference.

Altogether now¶

You now have all the pieces to understand the test command that you ran earlier:

pelican object get osdf:///pelicanplatform/test/hello-world.txt ./

pelican object get is used to download an object from a Pelican federation
osdf:// tells Pelican to use the OSDF
/pelicanplatform/ tells Pelican to look in the pelicanplatform namespace
test/hello-world.txt tells Pelican to look for the object named test/hello-world.txt
./ tells Pelican to download the object to the current directory

What's in an (object's) name?

You may have noticed in the explanation that Pelican sees the object name as test/hello-world.txt but when you downloaded the object, the file was saved as hello-world.txt!

While Pelican uses the bucket-object paradigm (like S3), it knows when and how to translate into the traditional directory-file paradigm when appropriate. In fact, at the Pelican origin serving the pelicanplatform namespace, the test/hello-world.txt object almost certainly maps to a file hello-world.txt inside of a directory test in the connected data storage.