Storj IconSTORJ | DCS Docs
cp

cp #

Usage #

./uplink.exe cp [flags] SOURCE DESTINATION
uplink cp [flags] SOURCE DESTINATION
uplink cp [flags] SOURCE DESTINATION

The cp command is used to upload and download objects. The cp command abstracts the complexity of encryption, erasure coding, and distributing pieces of a file to storage nodes.

Flags #

FlagDescription
--access stringthe serialized access, or name of the access to use
-r, --recursivePerform a recursive copy
-t, --transfers intControls how many uploads/downloads to perform in parallel (default 1)
--dry-runPrint what operations would happen but don’t execute them
--progressShow a progress bar when possible (default true)
--range stringDownloads the specified range bytes of an object. For more information about the HTTP Range header, see https://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html#sec14.35
-p, --parallelism intControls how many parallel chunks to upload/download from a file (default 1)
--parallelism-chunk-size SizeControls the size of the chunks for parallelism (default 64.0 MiB)
--expires relative_dateSchedule removal after this time (e.g. ‘+2h’, ’now’, ‘2020-01-02T15:04:05Z0700’)
--help, -hhelp for cp

Examples #

Copy a local file into an existing bucket #

When the cp command is used to copy a file to Storj DCS (upload), the CLI first encrypts the file client-side, then splits it into a minimum of x erasure-coded pieces, and finally, the x pieces are uploaded in parallel to x different storage nodes. x currently equals 80 but is subject to change depending on continuous optimization.

To copy cheesecake.jpg into the existing bucket cakes, use the following command:

./uplink.exe cp cheesecake.jpg sj://cakes 
uplink cp cheesecake.jpg sj://cakes
uplink cp cheesecake.jpg sj://cakes
You cannot use regular expressions to specify which files to copy (e.g. uplink cp cheese* sj://cakes will not work). Also, you can only specify one source at a time (no uplink cp cheesecake.jpg cheesecake.png sj://cakes)

Output:

Copy a file from a bucket to a local drive #

When the cp command is used to copy a file from Storj DCS (download), the CLI first downloads the minimum number of pieces to reconstitute a file (typically 29 pieces), then re-encodes the pieces into a single file, and finally decrypts the file client-side.

To copy a file from a project to a local drive, use:

./uplink.exe cp sj://cakes/cheesecake.jpg ~/Downloads/
uplink cp sj://cakes/cheesecake.jpg ~/Downloads/
uplink cp sj://cakes/cheesecake.jpg ~/Downloads/

Copy a local file into a bucket with an expiration date #

The uploaded object can be set to expire at a certain time. After the expiration date, the file is no longer available and no longer will generate usage charges. To set an expiration date for a file when uploading it, you should use the cp command with the --expires flag:

./uplink.exe cp --expires 2021-12-31T13:00:00+02:00 cheesecake.jpg sj://cakes
uplink cp  --expires 2021-12-31T13:00:00+02:00 cheesecake.jpg sj://cakes
uplink cp  --expires 2021-12-31T13:00:00+02:00 cheesecake.jpg sj://cakes

The date is given in the yyyy-mm-ddThh:mm:ssZhh:mm format defined in ISO 8601. 2021-12-31T13:00:00+02:00 reads “December, 31st at 1pm UTC+2”. A date ending with “Z”, such as 2021-12-31T13:00:00Z, is in UTC.

The command above gives the following output:

Copy an object with parallelism #

If you have enough upstream bandwidth, you can use the multipart functionality to upload objects faster.

To increase upload speed, you can use the cp command with the --parallelism 10 flag (the number you can set according to your preferences and available upstream bandwidth):

./uplink.exe cp --parallelism 10 cheesecake.jpg sj://cakes
uplink cp --parallelism 10 cheesecake.jpg sj://cakes
uplink cp --parallelism 10 cheesecake.jpg sj://cakes

Since our sample object is small, you likely will not notice a difference.

It would be significantly different with big objects like videos or OS images etc. and for upstream bandwidth much greater than 100Mbps.

Recursive copy of objects from local location to the bucket #

You can recursively copy files:

./uplink.exe cp --recursive ~/receipts sj://cakes/
uplink cp --recursive ~/receipts sj://cakes/
uplink cp --recursive ~/receipts sj://cakes/

Sample output:

upload /home/user/receipts/cheescake.jpg to sj://cakes/cheescake.jpg
upload /home/user/receipts/pancake.jpg to sj://cakes/pancake.jpg

Copy an object from one location to another within Storj DCS #

It is possible to copy a file from one Storj DCS location to another Storj DCS location within the same project.

When the cp command is used to copy a file from one Storj DCS location to another Storj DCS location, the object will be copied entirely on the “server” side - this will not count against your egress limits, as the object is not being downloaded.

You need to have at least version 1.54.1 of Uplink installed to support server-side copy

First, to create a new bucket, we will use the mb command, as copying is possible only to an existing bucket.

./uplink.exe mb sj://new-recipes
uplink mb sj://new-recipes
uplink mb sj://new-recipes
Bucket new-recipes created
Nested buckets are not supported, but you can use prefixes, as they would act almost like subfolders.

Now, to copy a file from a bucket within a project to another bucket in the same project with prefix cakes, use:

./uplink.exe cp sj://cakes/cheesecake.jpg sj://new-recipes/cakes/cheesecake.jpg
uplink cp sj://cakes/cheesecake.jpg sj://new-recipes/cakes/cheesecake.jpg
uplink cp sj://cakes/cheesecake.jpg sj://new-recipes/cakes/cheesecake.jpg

Sample Output:

upload sj://cakes/cheesecake.jpg sj://new-recipes/cakes/cheesecake.jpg

There is no progress bar shown since nothing was downloaded or uploaded, as the copying happens on the “server” side (within a Storj DCS project.)