th object-storage: copy, sync and share files

About

Object Storage keeps files (objects) in buckets. Objects are private unless you make a folder public. In th, an object is written th://BUCKET/KEY; anything else is a path on your computer. A key ending in / is a folder (prefix).

Path	Means
`th://media`	The bucket `media`
`th://media/photos/`	The folder `photos/` in it
`th://media/photos/cat.jpg`	One object
`./photos`, `C:\data`	Files on your computer
`-`	Standard output (as the destination of `cp`)

The file commands use an Object Storage access key: a short-lived one made for you when you are signed in, or the one in TH_OBJECT_STORAGE_KEY_ID / TH_OBJECT_STORAGE_SECRET. Files over 64 MiB are uploaded in parallel parts. See also How Object Storage works.

How-to guides

Copy a folder to a bucket

Shell

th object-storage buckets create my-bucket
th object-storage cp -r ./backups th://my-bucket/backups
th object-storage ls th://my-bucket/backups/

With -r, the contents of ./backups go under backups/. Copy the other way (th://… ./dir) to download.

Keep a folder in sync

Preview what would change: th object-storage sync ./public th://my-bucket/site --dry-run.
Upload new and changed files: run it again without --dry-run. A file is unchanged when its size and MD5 match the object.
Add --delete to also remove objects that are no longer in the folder (after a prompt).

Shell

th object-storage sync ./public th://my-bucket/site --delete

Share a file with a link that expires

Shell

th object-storage sign th://my-bucket/reports/report.pdf --expires 1h
th object-storage sign th://my-bucket/uploads/photo.jpg --method PUT --expires 15m

The first link downloads the file without a key for an hour; the second lets someone upload that one file. Links last at most 7 days.

Make a folder public

Shell

th object-storage buckets public my-bucket --prefix images/
th object-storage buckets public my-bucket

Anyone can then open files under images/ without a key. Without parameters the command prints the current rules; --private --prefix images/ makes the folder private again.

Reads of public files are billed to your Project. Keep personal data out of public folders.

Commands

Command	Description
`th object-storage buckets create`	Creates a bucket.
`th object-storage buckets list`	Lists the Project's Object Storage buckets.
`th object-storage buckets public`	Shows or changes what anyone may read from the bucket without a key.
`th object-storage buckets delete`	Deletes an empty bucket.
`th object-storage ls`	Without an argument lists the Project's buckets.
`th object-storage cp`	Copies files to, from or between buckets.
`th object-storage mv`	Moves files to, from or between buckets.
`th object-storage sync`	Uploads the files of LOCAL_DIR that are new or changed under PREFIX/.
`th object-storage cat`	Writes an object to standard output.
`th object-storage stat`	Shows an object's size, type, ETag, digest and metadata.
`th object-storage sign`	Prints a link that downloads (GET) or uploads (PUT) the object without a key until it expires (at most 7d).
`th object-storage rm`	Deletes an object.

`th object-storage buckets create`

Creates a bucket.

Syntax

Shell

th object-storage buckets create NAME [--region REGION]

NAME is 3-63 characters of a-z, 0-9, dots and hyphens. The region defaults to the configured one (th config set region) when it offers Object Storage, or to the only region that does.

Examples

Create a bucket in the default region

Shell

th object-storage buckets create my-bucket

In a specific region

Shell

th object-storage buckets create my-bucket --region bkk

Positional arguments

Name	Description
`NAME`Required	The bucket name: 3–63 characters of a-z, 0-9, dots and hyphens.

Global parameters

This command also takes the global parameters: --project, --region, --endpoint, --format, --quiet.

`th object-storage buckets list`

Lists the Project's Object Storage buckets.

Syntax

Shell

th object-storage buckets list

Examples

List buckets

Shell

th object-storage buckets list

Global parameters

This command also takes the global parameters: --project, --region, --endpoint, --format, --quiet.

`th object-storage buckets public`

Shows or changes what anyone may read from the bucket without a key.

Syntax

Shell

th object-storage buckets public NAME [--prefix P [--list]] [--private]

--prefix P          make the folder P (e.g. images/) public; --prefix ""
                    makes the whole bucket public
--prefix P --list   also let anyone list that folder
--private --prefix P  make that folder private again
--private           make the whole bucket private (removes every rule)

Without flags it prints the current rules.

Examples

Print the public rules

Shell

th object-storage buckets public my-bucket

Make images/ public

Shell

th object-storage buckets public my-bucket --prefix images/

Also let anyone list images/

Shell

th object-storage buckets public my-bucket --prefix images/ --list

Make the whole bucket private

Shell

th object-storage buckets public my-bucket --private

Positional arguments

Name	Description
`NAME`Required	The bucket name: 3–63 characters of a-z, 0-9, dots and hyphens.

Parameters

Name	Type	Description
`--prefix`	string	Folder (key prefix) the change applies to
`--list`	flag	Also allow listing the public folder
`--private`	flag	Remove the rule for `--prefix`, or all rules

Global parameters

This command also takes the global parameters: --project, --region, --endpoint, --format, --quiet.

`th object-storage buckets delete`

Deletes an empty bucket.

Syntax

Shell

th object-storage buckets delete NAME [--force] [--quiet]

With --force a bucket with objects is deleted at once and its objects are removed in the background. --quiet skips the prompt.

Examples

Delete an empty bucket

Shell

th object-storage buckets delete my-bucket

Delete it with all its objects, no prompt

Shell

th object-storage buckets delete my-bucket --force --quiet

Positional arguments

Name	Description
`NAME`Required	The bucket name: 3–63 characters of a-z, 0-9, dots and hyphens.

Parameters

Name	Type	Default	Description
`--force`	flag		Delete the bucket with all its objects

Global parameters

This command also takes the global parameters: --project, --region, --endpoint, --format, --quiet.

`th object-storage ls`

Without an argument lists the Project's buckets.

Syntax

Shell

th object-storage ls [th://BUCKET[/PREFIX]] [--recursive]

With th://BUCKET lists the objects and folders at the top of the bucket, with th://BUCKET/PREFIX those under PREFIX. --recursive lists every object below, without folders.

Examples

List buckets

Shell

th object-storage ls

Objects and folders under reports/

Shell

th object-storage ls th://my-bucket/reports/

Every object in the bucket

Shell

th object-storage ls th://my-bucket --recursive

Positional arguments

Name	Description
`th://BUCKET[/PREFIX]`Optional	A bucket, optionally with a folder (prefix) in it.

Parameters

Name	Type	Default	Description
`--recursive`	flag		List every object under the prefix
`-r`	flag		Same as `--recursive`

Global parameters

This command also takes the global parameters: --project, --region, --endpoint, --format, --quiet.

`th object-storage cp`

Copies files to, from or between buckets.

Syntax

Shell

th object-storage cp SRC DST [-r] [--content-type TYPE]

Objects are th://BUCKET/KEY; anything else is a local path ("-" as DST writes to stdout).

th object-storage cp photo.jpg th://media/photos/      -> photos/photo.jpg
th object-storage cp th://media/a.pdf ./                -> ./a.pdf
th object-storage cp th://media/a.pdf th://archive/a.pdf (copied inside Object Storage)

With -r, SRC is a folder (or a prefix) and its contents go under DST, like aws s3 cp --recursive. Files over 64 MiB are uploaded in parallel parts. The content type is guessed from the file extension unless given.

Examples

Upload a file into a folder

Shell

th object-storage cp ./report.pdf th://my-bucket/reports/

Upload a folder

Shell

th object-storage cp -r ./backups th://my-bucket/backups

Download a file

Shell

th object-storage cp th://my-bucket/reports/report.pdf ./

Write an object to standard output

Shell

th object-storage cp th://my-bucket/data.json - | jq .

Positional arguments

Name	Description
`SRC`Required	What to copy: a local path or `th://BUCKET/KEY` (a folder or prefix with `-r`).
`DST`Required	Where to copy it: a local path, `th://BUCKET/KEY` or `th://BUCKET/FOLDER/`, or `-` for standard output.

Parameters

Name	Type	Default	Description
`--recursive`	flag		Copy a folder or prefix and everything under it
`-r`	flag		Same as `--recursive`
`--content-type`	string	`by extension`	Content type of uploaded objects

Global parameters

This command also takes the global parameters: --project, --region, --endpoint, --format, --quiet.

`th object-storage mv`

Moves files to, from or between buckets.

Syntax

Shell

th object-storage mv SRC DST [-r] [--content-type TYPE]

Objects are th://BUCKET/KEY; anything else is a local path ("-" as DST writes to stdout).

th object-storage mv photo.jpg th://media/photos/      -> photos/photo.jpg
th object-storage mv th://media/a.pdf ./                -> ./a.pdf
th object-storage mv th://media/a.pdf th://archive/a.pdf (copied inside Object Storage)

Examples

Move an object to another folder

Shell

th object-storage mv th://my-bucket/inbox/a.pdf th://my-bucket/done/

Positional arguments

Name	Description
`SRC`Required	What to copy: a local path or `th://BUCKET/KEY` (a folder or prefix with `-r`).
`DST`Required	Where to copy it: a local path, `th://BUCKET/KEY` or `th://BUCKET/FOLDER/`, or `-` for standard output.

Parameters

Name	Type	Default	Description
`--recursive`	flag		Copy a folder or prefix and everything under it
`-r`	flag		Same as `--recursive`
`--content-type`	string	`by extension`	Content type of uploaded objects

Global parameters

This command also takes the global parameters: --project, --region, --endpoint, --format, --quiet.

`th object-storage sync`

Uploads the files of LOCAL_DIR that are new or changed under PREFIX/.

Syntax

Shell

th object-storage sync LOCAL_DIR th://BUCKET[/PREFIX] [--delete] [--dry-run]

A file is unchanged when its size matches and its MD5 matches the object's ETag (objects uploaded in parts have no MD5 ETag: then a local file newer than the object counts as changed). --delete also deletes objects under PREFIX/ that are no longer in LOCAL_DIR (after a prompt --quiet skips).

Examples

Show what would change

Shell

th object-storage sync ./public th://my-bucket/site --dry-run

Upload changes and remove deleted files

Shell

th object-storage sync ./public th://my-bucket/site --delete

Positional arguments

Name	Description
`LOCAL_DIR`Required	The folder on your computer to upload.
`th://BUCKET[/PREFIX]`Required	A bucket, optionally with a folder (prefix) in it.

Parameters

Name	Type	Default	Description
`--delete`	flag		Delete objects that are not in LOCAL_DIR
`--dry-run`	flag		Only print what would change
`--content-type`	string	`by extension`	Content type of uploaded objects

Global parameters

This command also takes the global parameters: --project, --region, --endpoint, --format, --quiet.

`th object-storage cat`

Writes an object to standard output.

Syntax

Shell

th object-storage cat th://BUCKET/KEY

Examples

Print an object

Shell

th object-storage cat th://my-bucket/config.json

Positional arguments

Name	Description
`th://BUCKET/KEY`Required	An object, such as `th://media/photos/cat.jpg` (a prefix with `-r`).

Global parameters

This command also takes the global parameters: --project, --region, --endpoint, --format, --quiet.

`th object-storage stat`

Shows an object's size, type, ETag, digest and metadata.

Syntax

Shell

th object-storage stat th://BUCKET/KEY

Examples

Size, type, ETag and metadata

Shell

th object-storage stat th://my-bucket/reports/report.pdf

Positional arguments

Name	Description
`th://BUCKET/KEY`Required	An object, such as `th://media/photos/cat.jpg` (a prefix with `-r`).

Global parameters

This command also takes the global parameters: --project, --region, --endpoint, --format, --quiet.

`th object-storage sign`

Prints a link that downloads (GET) or uploads (PUT) the object without a key until it expires (at most 7d).

Syntax

Shell

th object-storage sign th://BUCKET/KEY [--expires 1h] [--method GET|PUT]

Examples

A download link for one hour

Shell

th object-storage sign th://my-bucket/reports/report.pdf --expires 1h

An upload link for 15 minutes

Shell

th object-storage sign th://my-bucket/uploads/photo.jpg --method PUT --expires 15m

Positional arguments

Name	Description
`th://BUCKET/KEY`Required	An object, such as `th://media/photos/cat.jpg` (a prefix with `-r`).

Parameters

Name	Type	Default	Description
`--expires`	string	`1h`	How long the link works: 15m, 1h, 7d (default 1h)
`--method`	string	`GET`	GET (download, default) or PUT (upload)

Global parameters

This command also takes the global parameters: --project, --region, --endpoint, --format, --quiet.

`th object-storage rm`

Deletes an object.

Syntax

Shell

th object-storage rm th://BUCKET/KEY [-r] [--quiet]

With -r deletes every object under the prefix (after a prompt that --quiet skips).

Examples

Delete one object

Shell

th object-storage rm th://my-bucket/tmp/old.log

Delete everything under tmp/, no prompt

Shell

th object-storage rm -r th://my-bucket/tmp/ --quiet

Positional arguments

Name	Description
`th://BUCKET/KEY`Required	An object, such as `th://media/photos/cat.jpg` (a prefix with `-r`).

Parameters

Name	Type	Default	Description
`--recursive`	flag		Delete everything under the prefix
`-r`	flag		Same as `--recursive`

Global parameters

This command also takes the global parameters: --project, --region, --endpoint, --format, --quiet.

Help centre: the th command line