Overview

The Shelby CLI provides simple operations for uploading files to the Shelby network.

It is important that the CLI is properly configured with a network and funded account. If not, please visit the Getting Started quick start guide for more information.

`shelby upload`

Uploads a blob or local directory of blobs to Shelby, using the currently active account as the account to upload to. This will charge SHEL tokens.

shelby upload [options] <src> <dst>

Options

Flag	Alias	Type	Required	Default	Description
`--expiration <datetime>`	`-e`	string	yes	-	Expiration timestamp.
`--recursive`	`-r`	flag		false	Upload every file under a directory.
`--assume-yes`		flag		false	Skip interactive cost confirmation. Useful for scripts.
`--output-commitments <file>`		string		-	Persist the generated commitments alongside the upload for later inspection.

If uploading a single blob, <dst> must always be a valid blob name (does not end in /, and no more than 1024 characters).

When uploading a directory recursively, <dst> must end in /.

The --expiration option accepts:

Human language timestamp:
- in 2 days
- next Friday
- next month
- 2025-12-31
UNIX timestamp: 1735689600 (seconds since epoch)
ISO date string: "2025-01-01T00:00:00Z"
Human-readable date: "2025-01-01" or "Jan 1, 2025"

The uploaded file list is created before starting the operation. File sizes are saved as the file list is created. If any files change size between the initial listing and the upload, the upload will fail when it reaches the modified files.

Basic Example

shelby upload local-video.mp4 shelby-output.mp4 -e <UNIX-EPOCH>

Relative Paths

shelby upload ./local-video.mp4 shelby/blob/name.mp4 -e <UNIX-EPOCH>

Other Date Formats

shelby upload local-video.mp4 best-videos/video.mp4 --expiration <UNIX-EPOCH>
shelby upload local-video.mp4 best-videos/video.mp4 -e "2025-12-31"
shelby upload local-video.mp4 best-videos/video.mp4 -e "2025-12-31T00:00:00Z"
shelby upload local-video.mp4 best-videos/video.mp4 -e "2025-12-31T00:00:00-0500"

On UNIXes, the date command can help too:

shelby upload video.mp4 best-videos/video.mp4 -e $(date -d "+1 hour" +%s)

Directory Upload Example

shelby upload -r ./hls_video/ best-videos/hls_video/ --expiration <UNIX-EPOCH>
shelby upload --recursive ./website/ my-site/ -e "2025-12-31"

Canonical Directory Layout

The upload command will use the canonical filesystem layout when uploading directories recursively.

That is, if the source is laid out as:

$ tree .
.
|-- bar
`-- foo
    |-- baz
    `-- buzz

2 directories, 3 files

The blobs uploaded to Shelby will have these blob names:

<account>/<blob-prefix>/bar
<account>/<blob-prefix>/foo/baz
<account>/<blob-prefix>/foo/buzz

Note that there is no <account>/<blob-prefix>/foo blob in shelby as there is no concept of directory in blob storage. It is possible to later upload <account>/<blob-prefix>/foo as a separate blob; this would make it difficult to download the directory tree as a directory tree!

Uploads

On this page