cp

Copies a local file or Storj object to another location locally or in Storj DCS

Usage

./uplink.exe 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

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 cp cheesecake.jpg 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 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 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 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 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.

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

uplink mb sj://new-recipes

Bucket new-recipes created

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

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.)