Uploading/Downloading/Copying Objects - cp
Last updated: 2025-11-14 15:30:17
The
cp command is used to upload, download, or copy objects.Note:
If you need to use the upload file command, when you perform authorization policy, set action to
cos:HeadBucket,cos:GetBucket,cos:HeadObject,cos:InitiateMultipartUpload,cos:UploadPart,cos:CompleteMultipartUpload,cos:ListMultipartUploads,cos:ListParts.If you need to use the download file command, when you perform authorization policy, set action to
cos:HeadBucket,cos:GetBucket,cos:HeadObject,cos:GetObject. If you need to use the copy file command, when you perform authorization policy, set the target object action to
cos:GetBucket,cos:HeadObject,cos:InitiateMultipartUpload,cos:PutObject,cos:CompleteMultipartUpload. Set the source object action to cos:HeadBucket,cos:GetBucket,cos:HeadObject,cos:GetObject.Command format
./coscli cp <source_path> <destination_path> [flags]
cp includes the following parameters:Parameter Format | Description | Sample |
source_path | Source file path, which can be a local path or a COS file path. The COS path is accessible by using the bucket alias or bucket name configured in the configuration file as detailed in Download and Installation Configuration. If you use the bucket name for access, you also need to include the endpoint flag. | Local path: ~/example.txt COS file path specified with the bucket alias: cos://bucketalias/example.txt COS file path specified with the bucket name: cos://examplebucket-1250000000/example.txt |
destination_path | Destination file path, which can be a local path or a COS file path. The COS path is accessible by using the bucket alias or bucket name configured in the configuration file as detailed in Download and Installation Configuration. If you use the bucket name for access, you also need to include the endpoint flag. | Local path: ~/example.txt COS file path specified with the bucket alias: cos://bucketalias/example.txt COS file path specified with the bucket name: cos://examplebucket-1250000000/example.txt |
cp includes the following optional flags:Flag Abbreviation | Flag Name | Description |
None | --include | Includes specific objects.(Versions prior to v1.0.4 only filter the local file name during upload, while versions v1.0.4 and later will filter the full path.) For example: upload all files under ./test to COS. The ./test folder contains the aaa folder, which includes the 1.txt file. versions prior to 1.0.4 will match aaa/1.txt 1.0.4 and later versions will match ./test/aaa/1.txt |
None | --exclude | Excludes specific objects.(Versions prior to v1.0.4 only filter the local file name during upload, while versions v1.0.4 and later will filter the full path.) For example: upload all files under ./test to COS. The ./test folder contains the aaa folder, which includes the 1.txt file. versions prior to 1.0.4 will match aaa/1.txt 1.0.4 and later versions will match ./test/aaa/1.txt |
-r | --recursive | Specifies whether to traverse all objects in the directory recursively. |
None | --storage-class | Specifies the storage class of the uploaded file. Default value: STANDARD. For more information, see Storage Class Overview. |
None | --part-size | The part size of the file (default 32 MB, supports up to 5 GB). If you need to adaptively adjust the part size based on file size, set it to 0. |
None | --thread-num | Number of concurrent threads. Default value: 5. |
None | --rate-limiting | Speed limit for a single URL in MB/s. Value range: 0.1–100 MB/s. |
None | --meta | Metadata of the uploaded file, including certain HTTP standard attributes (HTTP Header) and custom metadata prefixed with x-cos-meta- (User Meta). The file metadata is in the format of header:value#header:value, such as Expires:2022-10-12T00:00:00.000Z#Cache-Control:no-cache#Content-Encoding:gzip#x-cos-meta-x:x. |
None | --routines | Specifies the number of files for concurrent upload or download of threads between files, with the default number being 3. |
None | --fail-output | This option determines whether to enable error output of files when uploads or downloads fail (when the default value is true, it is enabled). If it is enabled, failed file transfers will be recorded in the specified directory (if no directory is specified, the default one is ./coscli_output). If it is disabled, only the number of failed files will be output to the console. |
None | --fail-output-path | This option is used to specify the error output folder for recording failed uploads or downloads. By providing a custom folder path, you can control the location and name of the error output folder. If this option is not set, the default error log folder ./coscli_output will be used. |
None | --retry-num | Number of frequency limit retry times (default value is 0; No retry). 1-10 times can be selected. When multiple machines execute download operations at the same COS directory simultaneously, you can specify this parameter to retry and avoid frequency limit errors. |
None | --err-retry-num | Number of error retry times (default value is 0). 1-10 times are specified, or if the value is set to 0, no retry is performed. |
None | --err-retry-interval | Retry interval (only available when --err-retry-num is specified as 1-10). Specify a retry interval of 1-10 seconds. If it is not specified or set to 0, the value of each retry interval will be random among 1-10 seconds. |
None | --only-current-dir | Whether to only upload files in the current directory; ignore subdirectories and their content ( false is set by default; not ignored). |
None | --disable-all-symlink | Whether to ignore the subfiles and subdirectories of all the soft links during upload ( true is set by default; not uploaded). Currently only supported on Linux and MacOS systems |
None | --enable-symlink-dir | Whether to upload subdirectories of soft links ( false is set by default; not uploaded). Currently only supported on Linux and MacOS systems |
None | --disable-crc64 | Whether to disable the CRC64 data validation ( false is set by default; validation enabled). |
None | --disable-checksum | The default is true, verifying only the fragment crc64. When set to false, it verifies the entire file crc64. (coscli V1.0.6 and prior versions default to false) |
None | --move | The source file will be deleted after the file is successfully copied to the target path (only available between cos paths). |
None | --version-id | Download a specified version file, which is only supported in a Bucket with version control enabled (single file only). |
None | --process-log | Whether process log is enabled, the default is true, enabled |
None | --process-log-path | This option is used to specify a dedicated output folder to store process logs. The logs will record information related to file upload or download, including error logs, normal execution logs, retry details. By providing a custom folder path, you can control the location and name of the log output folder. If not set, the default log folder (coscli_output) will be used. |
None | --skip-dir | Defaults to false. When set to true, it skips folders during transmission. |
None | --acl | Set the file's ACL, such as private, public-read. |
None | --grant-read | Grant the authorized entity permission to read the object. The format is id="[OwnerUin]", for example id="100000000001". Use comma (half-width) to separate multiple authorized entities, such as id="100000000001",id="100000000002". |
None | --grant-read-acp | Grant the authorized entity permission to read the object's access control list (ACL). The format is id="[OwnerUin]", for example id="100000000001". Use comma (half-width) to separate multiple authorized entities, such as id="100000000001",id="100000000002". |
None | --grant-write-acp | Grant the authorized entity permission to write to the object's access control list (ACL). The format is id="[OwnerUin]", for example id="100000000001". Use comma (half-width) to separate multiple authorized entities, such as id="100000000001",id="100000000002". |
None | --grant-full-control | Grant the authorized entity all privileges on the operation object. The format is id="[OwnerUin]", for example id="100000000001". Use comma (half-width) to separate multiple authorized entities, such as id="100000000001",id="100000000002". |
None | --tags | The object tag collection supports up to 10 tags (for example, --tags="Key1=Value1&Key2=Value2") |
None | --forbid-overwrite | For buckets with Versioning Not Enabled, when uploading files, specify whether to forbid overwriting objects with the same name. When set to false, default overwrite for objects with the same name. When set to true, it means overwriting an Object with the same name is forbidden. When the bucket is in enabled or paused versioning status, the x-cos-forbid-overwrite header setting is invalid, allowing overwriting objects with the same name. |
None | --encryption-type | Server-side encryption method (SSE-COS/SSE-C). |
None | --server-side-encryption | Server-side encryption algorithm, supports AES256, cos/kms. This field is required when using SSE-COS or SSE-KMS. |
None | --sse-customer-algo | Server-side encryption algorithm, supports AES256. This field is required when using SSE-C. |
None | --sse-customer-key | Base64-encoded server-side encryption key. for example, MDEyMzQ1Njc4OUFCQ0RFRjAxMjM0NTY3ODlBQkNERUY=. This field is required when using SSE-C. |
None | --sse-customer-key-md5 | Base64-encoded MD5 hash value of the server-side encryption key. for example, U5L61r7jcwdNvT7frmUG8g==. This field is required when using SSE-C. |
None | --check-point | Whether to enable checkpoint restart, default is true |
Note:
cp automatically uses concurrent upload/download for large objects.If an object is larger than
--part-size, COSCLI will split the object into multiple parts according to --part-size and use --thread-num threads to concurrently upload/download the object.Each thread maintains a URL. For each URL, you can use the
--rate-limiting parameter to limit the speed of a single URL. When concurrent upload/download is enabled, the total rate is --thread-num * --rate-limiting.If an object is upload/download in parts, checkpoint restart will be enabled by default.
--include and --exclude support standard regular expression syntax, so you can use them to filter out objects that meet specific criteria.When using
zsh, you may need to add double quotes at both ends of the pattern string../coscli cp ~/test/ cos://bucket1/example/ -r --include ".*\\.txt$" --meta=x-cos-meta-a:a#ContentType:text#Expires:2022-10-12T00:00:00.000Z
When using commands in Windows CMD, note that the "——" character (Chinese dash) pasted into CMD will automatically change to "--", and you need to manually enter it.
For other common options of this command (such as switching bucket and user account), see Common Options.
Examples
Upload
Uploading a single object
./coscli cp ~/example.txt cos://bucket1/example.txt
Uploading all files and all folders in the local test Directory to the example Directory in the bucket1 bucket
./coscli cp ~/test/ cos://bucket1/example/ -r
Uploading all .mp4 files under the local test folder and Its subfolders to the example folder in the bucket1 bucket
./coscli cp ~/test/ cos://bucket1/example/ -r --include ".*\\.mp4$"
Uploading all non-.md files in the local test folder and Its subfolders to the example folder in bucket1
./coscli cp ~/test/ cos://bucket1/example/ -r --exclude ".*\\.md$"
Uploading all non-.md and non-.html files in the local test folder and Its subfolders to the example folder in the bucket1 bucket
./coscli cp ~/test/ cos://bucket1/example/ -r --exclude ".*\\.html$|.*\\.md$"
Uploading all objects in the dir directory (containing the dirA, dirB, dirC, and dirD subdirectories) except the dirD directory
./coscli cp dir/ cos://bucket1/example/ -r --exclude "dirD.*"
Uploading all files and folders under the local test directory to the example directory in the bucket1 bucket, and store them as archive type files
./coscli cp ~/test/ cos://bucket1/example/ -r --storage-class ARCHIVE
Uploading the local file.txt file to the bucket1 bucket and setting the single-URL speed limit to 1.3 MB/s
./coscli cp ~/file.txt cos://bucket1/file.txt --rate-limiting 1.3
Download
Downloading a single object
./coscli cp cos://bucket1/example.txt ~/example.txt
Downloading all files and folders under the example directory in the bucket1 bucket to the local test directory
./coscli cp cos://bucket1/example/ ~/test/ -r
Downloading all .mp4 files in the example folder and Its subfolders in bucket1 to the test folder on the local device
./coscli cp cos://bucket1/example/ ~/test/ -r --include ".*\\.mp4$"
Downloading all non-.md files under the example directory and Its subdirectories in bucket1 to the local test directory
./coscli cp cos://bucket1/example/ ~/test/ -r --exclude ".*\\.md$"
Downloading all non-.md and non-.html files under the example folder and Its subfolders in the bucket1 bucket to the local test folder
./coscli cp cos://bucket1/example/ ~/test/ -r --exclude ".*\\.html$|.*\\.md$"
Download xxx Version of example.txt File in bucket1 to test Directory under Local Device
./coscli cp cos://bucket1/example.txt ~/test/ --version-id xxx
Copy
Copying a single object within a bucket
./coscli cp cos://bucket1/example.txt cos://bucket1/example_copy.txt
Copying a single object across buckets
./coscli cp cos://bucket1/example.txt cos://bucket2/example_copy.txt
Copying all files and folders under the example1 folder in bucket1 to the example2 folder in bucket2
./coscli cp cos://bucket1/example1/ cos://bucket2/example2/ -r
Copying all .mp4 data type files under the example1 folder and Its subfolders in the bucket1bucket to the example2 folder in the bucket2 bucket
./coscli cp cos://bucket1/example1/ cos://bucket2/example2/ -r --include ".*\\.mp4$"
Copying all non-.md data type files under the example1 folder and Its subfolders in the bucket1 bucket to the example2 folder in the bucket2 bucket
./coscli cp cos://bucket1/example1/ cos://bucket2/example2/ -r --exclude ".*\\.md$"
Copy xxx Version of example.txt File in bucket1 to bucket2
./coscli cp cos://bucket1/example.txt cos://bucket2/ --version-id xxx
Move test Directory in bucket1 to bucket2
./coscli cp cos://bucket1/test/ cos://bucket2/test/ --move -r
Was this page helpful?
You can also Contact Sales or Submit a Ticket for help.
Yes
No
Feedback