Use BOS Service via CMD

Users can access BOS services to manage buckets and objects using bos commands. If operations are attempted when the BOS service balance is insufficient, an "Access Denied" error will be displayed.

CMD uses a multi-layer command structure. All commands start with bcecmd, where [options] represents the options supported by BCE CMD, and <service> represents the services supported by CMD (such as BOS). Each service has multiple specific sub-commands.

1$ bcecmd [options] [<service> <command> [parameters [options]]]

Parameter explanation

General options for CMD

• View help: Add -h or --help after any command to view help information for that command.

  Plain Text Copy

  1$ bcecmd -h
  2 $ bcecmd bos -h
  3 $ bcecmd bos ls --help

• View/set configuration information (AK, SK, etc.): -c/--configure

  Plain Text Copy

  1$ bcecmd -c [<conf-path>]

• View version information: -v/--version

  Plain Text Copy

  1$ bcecmd -v

• View debug information: -d/--debug

  Plain Text Copy

  1$ bcecmd -d bos ls bos:/bce-test/pre/

  Note: -d/--debug command cannot be used independently and must be combined with the bos command.

• Use a specified configuration file: --conf-path

  Plain Text Copy

  1$ bcecmd --conf-path ./conf-sample/ bos ls bos:/bce-test/pre/

  Note: if--conf-path command is not used, the configuration in the user’s home directory ~/.go-bcecli is used by default.

Bucket management

Create bucket

Description:Create a null bucket.

Command format: $ bcecmd bos mb bos:/<bucket-name> [--region REGION]

Description:

• You can specify the bucket's region only after enabling the "automatic domain name switching" feature.
• If you do not specify the region to which the bucket belongs, we will use the default region you configured in the CMD (i.e. the default region configured by bcecmd -c, if you have not configured a default region, the default region for CMD will be bj).

Example:

• Do not specify the region to which the bucket belongs for creation

  Example:

  $ bcecmd bos mb bos:/mybucket

  Response example:

  Make bucket: mybucket in region **

• Specify the region to which the bucket belongs for creation

  Example:

  $ bcecmd bos mb bos:/mybucket -r bj

  Response example:

  Make bucket: mybucket in region bj

Bucket deletion

Description:Delete a bucket, and require that there are no objects or unfinished three-step upload parts in the bucket.

Command format: $ bcecmd bos rb bos:/<bucket-name> [-y, --yes] [-f, --force]

Description:

• -y, --yes: Use this option to skip the confirmation step by default.
• -f. -- force: If you need to delete non-null buckets, you can use -f/--force option to force deletion. When using this option, the bucket cannot be null and all objects inside it can be deleted together.

Operation example: $ bcecmd bos rb bos:/mybucket --force

Response example:

1Do you really want to REMOVE bucket bos:/bce-test and all objects in it? (Y/N) **Y**
2Delete object: bos:/mybucket/test1.txt
3Delete object: bos:/mybucket/test2.txt
4Remove bucket: mybucket

List buckets

Description:List all buckets.

Command format: $ bcecmd bos ls [bos:/]

Operation example: $ bcecmd bos ls

Response example:

12015-08-12 10:20:58       bj  bce-doc
22015-08-12 10:21:09       bj  bce-sdk
32016-07-19 11:11:41       bj  bce-temp
42016-07-19 10:53:37       bj  bce-test

Note: The first column in the output shows the bucket creation date, the second column shows the creation time, the third column displays the bucket's region, and the fourth column lists the bucket name.

Manage object

Object upload

Description: BOS CMD supports three upload modes: synchronous upload, single-file upload and batch upload. During upload, you can specify the object storage class as standard storage, [Infrequent Access Storage](BOS/Product Description/Tiered Storage Introduction/Why Tiered Storage Exists.md#Infrequent access storage) or [ Cold Storage](BOS/Product Description/Tiered Storage Introduction/Why Tiered Storage Exists.md#Cold storage). In addition, BOS CMD also supports:

• For files larger than 32 MB, automatically split and upload them in parallel, configuring the number of concurrent upload connections.

When you need to upload data between your local system and BOS, synchronous upload (sync) is the most convenient upload command. Synchronous upload supports batch operations by default, and can synchronize local directories to BOS. If there is a file with the same name on the BOS side and its modification time is newer than that of the local file, synchronous upload will ignore this file and only synchronize new files or modified files. The sync command will list both local and BOS files, and perform the following actions for different situations:

• For added files (exist locally but not on BOS): Upload
• For files that have been uploaded but have been modified (the update time of local files is later than the creation time of BOS side files, or the size of the local file is different from that of the BOS side): Overwrite the upload.
• For files that have been uploaded and have not been modified: Skip without processing
• For files that have already been uploaded but are not present locally, process them differently based on the --delete parameter.
• To activate the sync command, coarse-grained LIST permissions or fine-grained LIST permissions along with GetBucketLocation must be configured.
• The upload progress information is saved in files in the task_progress subdirectory of the specified directory --conf-path. The file names follow the format PID-yyyy-mm-ddTHH:MM:SS e.g., 10516-2025-06-13T16:11:27

Command format:

• Synchronous upload: $ bcecmd bos sync <local_dir> bos:/<bucket_name>/[prefix] [--exclude EXCLUDE] [--include INCLUDE] [--delete] [--exclude-delete EXCLUDE-DELETE] [--dryrun] [--yes] [--quiet] [--storage-class STORAGE-CLASS] [--sync-type SYNC-TYPE] [--concurrency CONCURRENCY] [--restart] [--cache-control cacheControl] [--content-type CONTENT-TYPE] [--expires EXPIRES] [--content-disposition CONTENT-DISPOSITION] [--user-meta USER-META]

  Parameter description:

  • local_dir must be a local directory and cannot be a single file. It also does not support the syntax of wildcard matching, such as <local_dir>/* and <local_dir>/prefix*.
  • On both Windows and Linux, hard-linked files are handled like regular files; soft-linked folders behave like regular folders. However, soft-linked files (symlinks pointing to other files) are treated differently. For soft-linked files, sync operates on the file they point to instead of the symlink itself. Deleting the symlink itself will also trigger sync.
  • --exclude: Files to be skipped during the local-to-BOS sync, supporting wildcard * and multiple configurations. The wildcard * may be parsed by the shell and needs to be enclosed in quotes . To skip tmp files and svn directories in all subdirectories of the current directory: --exclude './*.tmp' --exclude '*/.svn'
  • --include: During execution of local-to-BOS sync, only specified files are synchronized, and the wildcard * and multiple configurations are supported. To synchronize only log and html files in all subdirectories of the current directory: --include './*.log' --include './*.html' --include "./*.log" (Windows requires double quotes only)
  • --delete: Remove files present in BOS but not locally to fully synchronize BOS and local data. By default, a confirmation prompt will appear before executing deletions.
  • --exclude-delete: This option must be used with --delete to exclude specific files or directories when deleting local files. For specific usage, please refer to the usage rules of --exclude.
  • --dryrun: Display the operations to be executed without actually carrying them out.
  • --yes: Delete files without requiring confirmation.
  • --quiet: Perform uploads in synchronization mode without displaying intermediate processes.
  • --storage-class [STORAGE_CLASS]: Specify the storage class of the synchronously uploaded object through the storage-class parameter. When specifying storage-class as STANDARD_IA、COLD, the storage is of infrequent access storage, cold storage, and the specified storage-class is STANDARD or standard storage when storage-class is not specified.

  • --sync-type: The sync type can be time-size, time-size-crc32, only-crc32 and force-overwrite, with the default type of time-size. When bcecmd executes the sync command, it first checks whether the file to be synchronized exists at the destination location. If the file does not exist, it will either upload or download the file. When the file exists at both the source location and destination location, it will determine whether the file needs to be synchronized based on the sync type.

    • time-size: Compare the modification date and size of files at the source and destination locations to determine whether synchronization should be conducted. If the modification date of file at the source location is earlier than that at the destination location, files will not be synchronized. If the modification date of file at the source location is the same as that at the destination location and the file sizes are the same, files will not be synchronized; otherwise, they will be synchronized.
    • time-size-crc32: bcecmd first determines file synchronization necessity via the time-size mode. When the output of time-size indicates that synchronization is required, bcecmd compares the crc32 values of files at source and destination locations. Files can be synchronized only when crc32 values are different.
    • only-crc32: bcecmd only compares the crc32 values of files at source and destination locations. If they are different, files will be synchronized.
    • force-overwrite: When files at the source and destination locations have the same name, bcecmd will forcibly overwrite the file at the destination location with that at the source location.
  • --concurrency: Specify the number of files to be uploaded and downloaded simultaneously during the sync command, with a default value of 10.
  • --restart: Bypass resumable upload and re-upload the file from the beginning.
  • --cache-control: Specify the file caching policy, with common values of private,public, no-cache, and no-store.
  • --expires: Set the cache expiration duration for HTTP pages, with a default of 3 days.
  • --content-type: Specify the file type and encoding format for web content.
  • --content-disposition: Indicate how to display attached files, with common values of inline and attachment.
  • --user-meta: User-defined meta values in the format name1:value1,name2:value2,name3:value3.
  • --traffic-limit: Speed limit for a single link, with a value range of 819200~838860800 in bit/s, i.e., 100KB/s~100MB/s

  Note

  • The sync command requires your AKSK to have the fullcontrol permission.
  • When --delete is used together with filtering (include or exclude), if a file is filtered, even though it exists on the source and destination locations, it will also be deleted. It is because bcecmd only compares unfiltered files.
  • Note that BOS fully supports CRC32 only after January 2018. Therefore, when the selected bcecmd sync-type is time-size-crc32 or only-crc32, if bcecmd fails to retrieve the object CRC32 information from BOS, it will always synchronize these files.

• Single-file upload: $ bcecmd bos cp <local-path> <bos-path> [--storage-class [STORAGE_CLASS]] [--restart] [--quiet] [--yes] [--disable-bar]

• Batch upload: $ bcecmd bos cp <local-path> <bos-path> --recursive [--storage-class [STORAGE_CLASS]] [--restart] [--quiet] [--yes] [--disable-bar]

  Description:

  • When running the command bcecmd bos cp /tmp/file1 bos:/bucket/file2, file2 can be the same as file1. If file2 already exists in the bucket, it will be overwritten.
  • When running the command bcecmd bos cp /tmp/file bos:/bucket/, the name of the local file will automatically be used as the file name in BOS. If a file with the same name exists, it will be overwritten.
  • When executing the command bcecmd bos cp/tmp/file bos:/bucket/prefix [/] -r, if the local file is a file, it will degenerate into a single file upload. If the bos path ends with "/", prefix is treated as the directory, and new files will be saved at the next level of the prefix; if the BOS path does not end with "/", prefix is treated as the object name and uploaded directly.
  • When executing the command bcecmd bos cp /tmp/dir/ bos:/bucket/prefix[/] -r, if the local is a directory, the end of the bos path will create a new directory on the bos side with prefix as the directory name, regardless of whether there is a "/" or not; and copy all objects in dir to the prefix directory.
  • When performing a batch upload, local-path can only be a local directory and end with "/", and bos-path must be bucket/prefix.
  • During object upload, the storage-class parameter can be used to specify the storage class of the object. When storage-class is STANDARD by default, that is, standard storage, with storage-class being STANDARD_IA、COLD, the storage is of infrequent access storage, cold storage class. If the storage-class input parameters are incorrect, it will be stored by following STANDARD, without any error message.
  • --disable-bar: Turn off the progress bar display.

Example:

• Synchronize the sample directory in the current directory to bos:/bce test/test

  Example: bcecmd bos sync ./sample/ bos:/bce-test/test

  Response example:

  Plain Text Copy

  1  Upload: sample/BOS_Batch_Delete.png to bos:/bce-test/test/BOS_Batch_Delete.png
  2  Upload: sample/sample.log to bos:/bce-test/test/sample.log

• List the synchronization operations that will be executed without actually performing them

  Example: bcecmd bos sync ./sample/ bos:/bce-test/test --dryrun

  Response example:

  Plain Text Copy

  1  Upload: sample/BOS_DataImport.png to bos:/bce-test/test/BOS_DataImport.png

• Synchronize upload without outputting any intermediate processes

  Operation example: bcecmd bos sync ./sample/ bos:/bce-test/test --quiet

  Response example: No return

• Synchronize the sample directory to boss:/bce test/test and delete files that BOS has but do not have locally

  Operation example: bcecmd bos sync ./sample/ bos:/bce-test/test --delete

  Response example:

  Plain Text Copy

  1  Delete object: bos:/bce-test/test/sample.log

• Synchronize the sample directory to bos:/bce test/test and store it as an infrequent access storage class

  Example: bcecmd bos sync ./sample/ bos:/bce-test/test --storage-class STANDARD_IA

  Response example:

  Plain Text Copy

  1  Upload: sample/BOS_DataImport.png to bos:/bce-test/test/BOS_DataImport.png

• Synchronize the sample directory to bos:/bce test/test and store it as a cold storage class

  Example: bcecmd bos sync ./sample/ bos:/bce-test/test --storage-class COLD

  Response example:

  Plain Text Copy

  1  Upload: sample/BOS_DataImport.png to bos:/bce-test/test/BOS_DataImport.png

• Single file upload

  Example:

  Plain Text Copy

  1  $ bcecmd bos cp text.txt bos:/mybucket/test.txt

  Response example:

  Plain Text Copy

  1  Upload: test.txt to bos:/mybucket/test.txt

• Batch upload

  Example:

  Plain Text Copy

  1  $ bcecmd bos cp ./temp/ bos:/bce-test -r

  Response example:

  Plain Text Copy

  1  Upload: /home/users/username/temp/BAE.png to bos:/bce-test/BAE.png
  2  Upload: /home/users/username/tem/CreatePolicy.png to bos:/bce-test/CreatePolicy.png
  3  Upload: /home/users/username/tem/BAE_Pro.png to bos:/bce-test/BAE_Pro.png
  4  Upload: /home/users/username/tem/BCD.png to bos:/bce-test/BCD.png
  5  Upload: /home/users/username/tem/04Eng.png to bos:/bce-test/04Eng.png
  6  [5] object uploaded.

• Upload an object and store it as an infrequent access storage class

  Example:

  Plain Text Copy

  1  $ bcecmd bos cp text.txt bos:/mybucket/test.txt --storage-class STANDARD_IA

  Response example:

  Plain Text Copy

  1  Upload: test.txt to bos:/mybucket/test.txt

• Upload an object and store it as a cold storage class

  Example:

  Plain Text Copy

  1  $ bcecmd bos cp text.txt bos:/mybucket/test.txt --storage-class COLD

  Response example:

  Plain Text Copy

  1  Upload: test.txt to bos:/mybucket/test.txt

Object download

Description:BOS CMD supports synchronous download, single-file download and batch file download.

Synchronous downloading supports batch processing by default, allowing BOS data to be synchronized to a local directory. If a local file with the same name exists and has a later modification time than the corresponding file on BOS, it will be skipped during synchronization, and only new or modified files will be downloaded.

The sync command will list both local and BOS files, and perform the following actions for different situations:

• For added files (a file on BOS is not locally available): Download
• For downloaded but modified files (the creation time of the BOS-side file is later than the update time of the local file, or the size of the BOS-side file differs from the local file): Overwrite and download
• For files that have been downloaded and have not been modified: Skip without processing
• For files that have been downloaded locally but no longer exist on BOS: The processing varies based on the --delete parameter.
• The download progress information is saved in files in the task_progress subdirectory of the specified directory --conf-path. The file names follow the format PID-yyyy-mm-ddTHH:MM:SS e.g., 10516-2025-06-13T16:11:27

Command format:

• Synchronous object download: $ bcecmd bos sync <bos-dir> <local-dir> [--exclude EXCLUDE] [--include INCLUDE] [--delete] [--exclude-delete EXCLUDE-DELETE] [--dryrun] [--yes] [--quiet] [--sync-type SYNC-TYPE] [--download-tmp-path DOWNLOAD-TMP-PATH] [--concurrency CONCURRENCY] [--restart] [--rand]

  Description:

  • In synchronous downloads, both "local-dir" and "bos-dir" must be directories and cannot be single files.
  • --exclude: Files to be skipped during the execution of BOS-to-local sync, supporting the wildcard * and multiple configurations . To skip tmp files in bucket sample and svn directories in all directories: --exclude 'bos:/sample/*.tmp' --exclude 'bos:/sample/*/.svn/*'
  • --include: During execution of BOS-to-local sync, only specified files are synchronized, and the wildcard * and multiple configurations are supported. To synchronize only log and html files in bucket sample: --include 'bos:/sample/*.log' --include 'bos:/sample/*.html'
  • --delete: Removes files that exist locally but not on BOS, ensuring the local data aligns completely with BOS. By default, the user will be prompted before deletion is carried out.
  • --exclude-delete: This option must be used with --delete to exclude specific files or directories at the destination location when deleting files exist at destination location but not at source location. For specific usage, please refer to the usage rules of --exclude.
  • --dryrun: Display the operations to be executed without actually carrying them out.
  • --yes: Delete files without requiring confirmation.
  • --quiet: Executes a synchronous download without displaying any intermediate processes.

  • --sync-type: The sync type can be time-size, time-size-crc32, only-crc32 and force-overwrite, with the default type of time-size. When bcecmd executes the sync command, it first checks whether the file to be synchronized exists at the destination location. If the file does not exist, it will either upload or download the file. When the file exists at both the source location and destination location, it will determine whether the file needs to be synchronized based on the sync type.

    • time-size: Compare the modification date and size of files at the source and destination locations to determine whether synchronization should be conducted. If the modification date of file at the source location is earlier than that at the destination location, files will not be synchronized. If the modification date of file at the source location is the same as that at the destination location and the file sizes are the same, files will not be synchronized; otherwise, they will be synchronized.
    • time-size-crc32: bcecmd first determines file synchronization necessity via the time-size mode. When the output of time-size indicates that synchronization is required, bcecmd compares the crc32 values of files at source and destination locations. Files can be synchronized only when crc32 values are different.
    • only-crc32: bcecmd only compares the crc32 values of files at source and destination locations. If they are different, files will be synchronized.
    • force-overwrite: When files at the source and destination locations have the same name, bcecmd will forcibly overwrite the file at the destination location with that at the source location.
  • --download-tmp-path: Specify a custom directory for storing temporary files during resumable downloads. If not specified, the directory where the command is executed will be used as the default.
  • --concurrency: Specify the number of files to be uploaded and downloaded simultaneously during the sync command, with a default value of 10.
  • --restart: Bypass resumable upload and re-upload the file from the beginning.
  • --rand: Download BOS files randomly to a local directory.

  Note

  • When --delete is used together with filtering (include or exclude), if a file is filtered, even though it exists on the source and destination locations, it will also be deleted. It is because bcecmd only compares unfiltered files.
  • Note that BOS fully supports CRC32 only after January 2018. Therefore, when the selected bcecmd sync-type is time-size-crc32 or only-crc32, if bcecmd fails to retrieve the object CRC32 information from BOS, it will always synchronize these files.

• Download a single object: $ bcecmd bos cp <bos-path> <local-path> [--restart] [--storage-class STORAGE-CLASS] [--download-tmp-path DOWNLOAD-TMP-PATH] [--quiet] [--yes] [--disable-bar]

• Batch download object: $ bcecmd bos cp <bos-path> <local-path> --recursive [--restart] [--storage-class STORAGE-CLASS] [--download-tmp-path DOWNLOAD-TMP-PATH] [--quiet] [--yes] [--disable-bar]

  Description:

  • When running the command bcecmd bos cp bos:/bucket/file /tmp/file, the local file name can be customized. If the local file already exists, a confirmation prompt will appear regarding overwriting.
  • When running the command bcecmd bos cp bos:/bucket/file /tmp/, the file name on BOS will automatically be used as the local file name. If the file already exists, a confirmation prompt will appear regarding overwriting.
  • When running the command bcecmd bos cp bos:/bucket/file /tmp/ -r, if it's a single file on BOS, the operation will switch to downloading a single file. If the file exists, a confirmation prompt will appear regarding overwriting.
  • When running the command bcecmd bos cp bos:/bucket/prefix/ /tmp/ -r, an error will occur if the specified local path is an existing file; otherwise, a new local directory will be created if it doesn't exist.
  • For batch downloads, "local-path" can only be a local directory, and "bos-path" must follow the "bucket/prefix" format. If the BOS path points to an object, it will be downloaded as a single object.
  • --restart: Skip resumable upload and re-download the file from the beginning.
  • --storage-class: During downloads, the storage-class parameter has no impact and will be automatically ignored.
  • --download-tmp-path: Specify a custom directory for storing temporary files during resumable downloads. If not specified, the directory where the command is executed will be used as the default.
  • --quiet: Executes a synchronous download without displaying any intermediate processes.
  • --yes: Delete files without requiring confirmation.
  • --disable-bar: Turn off the progress bar display.

Example:

• Synchronize downloading of files from bos:/mybucket/pres/to the temp directory in the current directory

  Example:

  Plain Text Copy

  1  $ bcecmd bos sync bos:/mybucket/pre/ ./temp/

  Response example:

  Plain Text Copy

  1  Download: bos:/mybucket/pre/sts1.png to /home/users/username/temp/sts1.png
  2  Download: bos:/mybucket/pre/sts2.png to /home/users/username/temp/sts2.png
  3  Sync done: bos:/mybucket/pre/ to ./temp/, [2] success [0] failure

• Download object

  Example:

  Plain Text Copy

  1  $ bcecmd bos cp bos:/mybucket/test.txt text.txt

  Response example:

  Plain Text Copy

  1  Download: bos:/mybucket/test.txt to test.txt

• Download object in batch

  Example:

  Plain Text Copy

  1  $ bcecmd bos cp bos:/mybucket/pre/ temp -r

  Response example:

  Plain Text Copy

  1  Download: bos:/mybucket/pre/sts1.png to /home/users/username/tmp/sts1.png
  2  Download: bos:/mybucket/pre/sts2.png to /home/users/username/tmp/sts2.png
  3  [2] objects downloaded.

Copy Object

Description:BOS CMD supports copying files between buckets, including synchronous copy, single-file copy and batch file copy.

Synchronous copying supports batch operations by default. If the destination bucket already contains files with the same names, the operation will skip these files and synchronize only new or modified ones.

The sync command will list the files of both the source and destination buckets, and perform the following actions for different situations:

• For added files (a file in the source bucket does not exist in the destination bucket): Copy
• For files that have been copied but have been modified (the creation time of the source bucket file is later than the update time of the destination bucket file, or the size of the source bucket side file is not consistent with the destination bucket): Overwrite and copy
• For files that have been copied and have not been modified: Skip without processing
• For files in the destination bucket that were copied but do not exist in the source bucket, processing varies depending on the "--delete" parameter.
• The copy progress information is saved in files in the task_progress subdirectory of the specified directory --conf-path. The file names follow the format PID-yyyy-mm-ddTHH:MM:SS e.g., 10516-2025-06-13T16:11:27

Command format:

• Synchronously copy objects: $ bcecmd bos sync <bos-dir> <bos-dir> [--exclude EXCLUDE] [--include INCLUDE] [--delete] [--exclude-delete EXCLUDE-DELETE] [--dryrun] [--yes] [--quiet] [--storage-class STORAGE-CLASS] [--sync-type SYNC-TYPE] [--concurrency CONCURRENCY] [--restart]

  Description:

  • For synchronous copying, "bos-dir" must represent a directory and cannot be a single file.
  • --exclude: Files to be skipped during the execution of BOS-to-BOS sync, supporting the wildcard * and multiple configurations . To skip tmp files in bucket source and svn directories in all directories: --exclude 'bos:/source/*.tmp' --exclude 'bos:/source/*/.svn/*'
  • --include: During execution of BOS-to-BOS sync, only specified files are synchronized, and the wildcard * and multiple configurations are supported. To synchronize only log and html files in bucket source: --include 'bos:/source/*.log' --include 'bos:/source/*.html'
  • --delete: Removes files present in the source bucket but missing in the destination bucket, ensuring complete consistency between source and destination bucket data. The user will be prompted before any action is performed.
  • --exclude-delete: This option must be used with --delete to exclude specific files or directories at the destination location when deleting files exist at destination location but not at source location. For specific usage, please refer to the usage rules of --exclude.
  • --dryrun: Display the operations to be executed without actually carrying them out.
  • --yes: Delete files without requiring confirmation.
  • --quiet: Perform uploads in synchronization mode without displaying intermediate processes.
  • --storage-class [STORAGE_CLASS]: Specify the storage class of the synchronously uploaded object through the storage-class parameter. When specifying storage-class as STANDARD_IA、COLD, the storage is of infrequent access storage, cold storage, and the specified storage-class is STANDARD or standard storage when storage-class is not specified.

  • --sync-type: The sync type can be time-size, time-size-crc32, only-crc32 and force-overwrite, with the default type of time-size. When bcecmd executes the sync command, it first checks whether the file to be synchronized exists at the destination location. If the file does not exist, it will synchronize the file. When the file exists at both the source location and destination location, it will determine whether the file needs to be synchronized based on the sync type.

    • time-size: Compare the modification date and size of files at the source and destination locations to determine whether synchronization should be conducted. If the modification date of file at the source location is earlier than that at the destination location, files will not be synchronized. If the modification date of file at the source location is the same as that at the destination location and the file sizes are the same, files will not be synchronized; otherwise, they will be synchronized.
    • time-size-crc32: bcecmd first determines file synchronization necessity via the time-size mode. When the output of time-size indicates that synchronization is required, bcecmd compares the crc32 values of files at source and destination locations. Files can be synchronized only when crc32 values are different.
    • only-crc32: bcecmd only compares the crc32 values of files at source and destination locations. If they are different, files will be synchronized.
    • force-overwrite: When files at the source and destination locations have the same name, bcecmd will forcibly overwrite the file at the destination location with that at the source location.
  • --concurrency: Specify the number of files to be copied simultaneously during the sync command.
  • --restart: Skip resumable upload and re-copy the file from the beginning.

  Note

  • When --delete is used in conjunction with filters (include or exclude), any filtered files will be deleted, regardless of their existence at both the source and destination, as bcecmd only compares unfiltered files.
  • Note that BOS fully supports CRC32 only after January 2018. Therefore, when the selected bcecmd sync-type is time-size-crc32 or only-crc32, if bcecmd fails to retrieve the object CRC32 information from BOS, it will always synchronize these files.

• Copy a single object: $ bcecmd bos cp <bos-path> <bos-path> [--restart] [--storage-class STORAGE-CLASS] [--quiet] [--yes] [--disable-bar]

• Copy objects in batch: $ bcecmd bos cp <bos-path> <bos-path> --recursive [--restart] [--storage-class STORAGE-CLASS] [--quiet] [--yes] [--disable-bar]

  Description:

  • When executing the command bcecmd bos cp bos:/bucket/obj1 bos:/bucket/obj2, an error will occur if both paths are identical; if the destination path already exists, it will be overwritten.
  • When executing the command bcecmd bos cp bos:/bucket/obj1 bos:/bucket/prefix/, obj1 will be copied into the prefix directory. The destination path must end with a "/"; otherwise, it will be treated as a new file name and create a new file.
  • When executing the command bcecmd bos cp bos:/bucket/obj1 bos:/bucket/prefix/ -r, if the source path is a single file, it simplifies to a single-file copy, and obj1 will be copied into the prefix directory.
  • When executing the command bcecmd bos cp bos:/bucket/prefix1/ bos:/bucket/prefix2/ -r to copy one directory to another, both paths must end with "/"; if the destination path does not end with "/", it will be interpreted as a single file and an error will occur.
  • For batch copy operations, the bos path must adhere to the "bucket/prefix" format.
  • Users must hold appropriate permissions, including read access for the source bucket and write access for the destination bucket.

Example:

• Synchronize copying of files from bos:/mybucket/pres/to bos:/mybucket2/pre/

  Example:

  Plain Text Copy

  1  $ bcecmd bos sync bos:/mybucket/pre/ bos:/mybucket2/pre/

  Response example:

  Plain Text Copy

  1  [-----------------------------------------------------] 100.00% 2.52 MiB p/s 3s
  2  Sync done: bos:/mybucket/pre/ to bos:/mybucket2/pre/, [2] success [0] failure

• Copy a single object

  Example:

  Plain Text Copy

  1  $ bcecmd bos cp bos:/mybucket/test.txt bos:/mybucket2/test.txt

  Response example:

  Plain Text Copy

  1  Copy: bos:/mybucket/test.txt to bos:/mybucket2/test.txt

• Delete objects in batch

  Example:

  Plain Text Copy

  1  $ bcecmd bos cp bos:/mybucket/pre1/ bos:/bce-test/pre/ -r

  Response example:

  Plain Text Copy

  1  [----------------------------------------------------] 100.00% 45.86 MiB p/s 0s
  2  [2] objects remote copied.

List objects

Description: The ls command can list up to 1,000 objects in a bucket. You can filter results by specifying a prefix.ls automatically uses "/" as a delimiter to achieve the effect of simulating a folder.

Command format: $ bcecmd bos ls bos:/<bucket-name>/[prefix]

Operation example:bcecmd bos ls bos:/mybucket/web

Response example:

1                                             PRE  pre/
22016-04-01 16:43:01            8698     STANDARD  web_bos.png
32016-04-01 16:41:49           17188     STANDARD  web_server_bos.png
42016-04-01 16:43:53           24620  STANDARD_IA  webtobos_cors.png
52016-04-01 16:45:53           24623         COLD  cold_abc.png

Description

• -a, --all: Displays all objects when the total count exceeds 1,000.
• -r, --recursive: Hides directory structures and directly displays underlying objects.
• -s, --summarize: Show statistical details like the number of objects and the total size.
• Example: The first column shows the object's creation date, the second column indicates the creation time, the third column specifies the object's size (in bytes), the fourth column highlights the storage class, and the fifth column contains the object's name.
• pre/ signifies a folder and does not display information about creation time or size.

Get object URL

Description: The gen_signed_url command can obtain a URL for a specified object, which can be used to download the object.

Command format $ bcecmd bos gen_signed_url bos:/<bucket-name>/<object-key> [-eTIME]

Description:

• The generated URL can be entered into a browser to directly download the object. Before creating the URL, ensure the configured AK/SK matches the AK/SK of the account associated with the bucket; otherwise, the URL will be invalid and cannot be used to download the object.
• -e: Specifies the expiration time of the URL (in seconds). The value must be greater than or equal to -1, where -1 signifies the URL is permanently valid.
• If no expiration time is set, the URL will default to an expiration time of 1,800 seconds.

Note: There must be no space between the parameter -e and the expiration time.

Example:

• No specify the expiration time

  Example:

  Plain Text Copy

  1  $ bcecmd bos gen_signed_url bos:/bce-test/test/BOS_DataImport.png

  Response example:

  Plain Text Copy

  1  http://bj.bcebos.com/bce-test/test/BOS_DataImport.png?authorization=bce-auth-v1%2Fd35a0b8750114e49b3567e0b0542c2f1%2F2016-08-25T02%3A03%3A57Z%2F1800%2F%2F96d77180ec2cb7e8de522c15ca42bf67c30bae0edb47bad495fe8e7953794a4f

• Specify the expiration time of 100 seconds

  Example:

  Plain Text Copy

  1  $ bcecmd bos gen_signed_url bos:/bce-test/test/BOS_DataImport.png -e100

  Response example:

  Plain Text Copy

  1  http://bj.bcebos.com/bce-test/test/BOS_DataImport.png?authorization=bce-auth-v1%2F637986f41b0046248e3a333817371502%2F2017-08-31T03%3A19%3A42Z%2F100%2F%2F3e77accca7f0206460c662b0a9596b7ec353599214d42b124bb797a48da7359a

• Specify that URL is permanently valid

  Example:

  Plain Text Copy

  1  $ bcecmd bos gen_signed_url bos:/bce-test/test/BOS_DataImport.png -e-1

  Response example:

  Plain Text Copy

  1  http://bj.bcebos.com/bce-test/test/BOS_DataImport.png?authorization=bce-auth-v1%2F637986f41b0046248e3a333817371502%2F2017-08-31T03%3A19%3A42Z%2F-12F%2F3e77accca7f0206460c662b0a9596b7ec353599214d42b124bb797a48da7359a

Delete Object

Command format:

• Delete a single object: $ bcecmd bos rm [-y, --yes] bos:/<bucket-name>/<object-key>
• Batch deletion of objects: $ bcecmd bos rm [-y, --yes] [-r, --recursive] bos:/<bucket-name>/<prefix>

Description:

• -y, --yes: Skip the confirmation step when this option is used.
• -r, --recursive: Delete multiple objects in batches.

Example:

• Delete a single object

  Example:

  Plain Text Copy

  1  $ bcecmd bos rm bos:/bce-temp/s1.png

  Response example:

  Plain Text Copy

  1  Do you really want to REMOVE object bos:/bce-temp/s1.png? (Y/N) **Y**
  2  Delete object: bos:/bce-temp/s1.png

• Delete objects in batches

  Example:

  Plain Text Copy

  1  $ bcecmd bos rm bos:/bce-test/pre/ -r

  Response example:

  Plain Text Copy

  1  Delete object: bos:/bce-test/pre/s1.png
  2  Delete object: bos:/bce-test/pre/s2.png
  3  [2] objects removed on remote.

Retrieve object meta information

Description: The get-object-meta command is used to retrieve the meta information of specific objects in a bucket.

Command format:

• $ bcecmd bosapi get-object-meta --bucket-name BUCKET-NAME --object-name OBJECT-NAME

Description:

• --bucket-name: Bucket name
• --object-name: The name of the object to be queried

Example:

Example:

1$ bcecmd bosapi get-object-meta --bucket-name=100kperf-xitaotao --object-name=water

Response example:

1 2019 / 10 / 10 11: 06: 49 {
2   "CacheControl": "",
3   "ContentDisposition": "",
4   "ContentEncoding": "",
5   "ContentLength": 0,
6   "ContentRange": "",
7   "ContentType": "application/json",
8   "ContentMD5": "1B2M2Y8AsgTpgAmY7PhCfg==",
9   "ContentSha256": "",
10   "Expires": "Sun, 13 Oct 2019 03:06:49 GMT",
11   "LastModified": "Thu, 26 Sep 2019 08:55:32 GMT",
12   "ETag": "d41d8cd98f00b204e9800998ecf8427e",
13   "UserMeta": null,
14   "StorageClass": "COLD",
15   "NextAppendOffset": "",
16   "ObjectType": "",
17   "Crc32": "0"
18 }

Restore objects

Description: The restore command is used to restore specified objects and support batch restoration.

Command format:

• $ bcecmd bos restore bos://${bucket-name}/{object-key} --restore-tier STANDARD --restore-days 7 -r

Description:

• --bucket-name: Bucket name
• --object-key: Name of the object to be restored

• --restore-tier: Restore priority. Expedited: Expedited restoration, indicating completion within 30 minutes.

  Standard: Standard restoration, indicating completion within 2~5 hours. LowCost: Deferred restoration, indicating completion within 12 hours.

• --restore-days: Specifies the duration of the restored state in days, which must be a numeric value greater than 0 and less than 30. The default duration is 7 days, with a maximum limit of 30 days.
• -r: When the object-key is a folder, add the -r parameter to restore all objects under this prefix in batch.

Example:

Example:

1$ bcecmd bos restore bos://testbucket/testobject

BOSAPI management

The BOS API management includes Bucket ACL, default bucket storage class, lifecycle management, and logging. The general command line format is bcecmd bosapi [--help].

Set Bucket ACL

Description: There are two methods to configure Bucket ACL: 1. Use [CannedAcl](BOS/API Reference/Access control.md#Permission control by CannedAcl); 2. Set the bucket ACL by uploading [ACL Configuration File](BOS/API Reference/Access control.md#Permission control by uploading ACL files).

Command format:

1bcecmd bosapi put-bucket-acl --bucket-name BUCKET-NAME [--acl-config-file ACL-CONFIG-FILE] [--canned CANNED]

Description:

• Specify the ACL configuration file using --acl-config-file. For the format of the ACL configuration file, please refer to [Bucket Permission Control](BOS/API Reference/Access control.md#Bucket permission control);
• Set CannedACL using --canned. Currently supported CannedAcl includes private, public read, and public-read-write;
• --acl-config-file and --canned cannot be used simultaneously;
• When configuring CannedACL, if the configuration fails, an error message will be printed. If it succeeds, no message will be output;
• When setting Bucket ACL by uploading an ACL configuration file, the ACL configuration information will be displayed if the setting is successful. If it fails, the file content and the error message will be shown.

Example:

• Permission control by CannedAcl

  Example:

  Plain Text Copy

  1$ bcecmd bosapi put-bucket-acl --bucket-name bucket1 --canned private

  Response example: None

• Set Bucket ACL by uploading the ACL configuration file

  Example:

  Plain Text Copy

  1$ bcecmd bosapi put-bucket-acl --bucket-name bucket1 --acl-config-file acl-config.json

  Response example:

  Plain Text Copy

  1{
  2    "accessControlList": [
  3      {
  4        "grantee": [
  5          {
  6            "id": "e13b12d213213213232323f492323"
  7          }
  8        ],
  9        "permission": [
  10            "READ"
  11        ]
  12      }
  13    ]
  14}

Append Bucket ACL

Description: The Append Bucket ACL function means that new ACL rules are appended to the existing ACL configuration of a specified bucket. These ACL rules are also specified by the [ACL Configuration File](BOS/API Reference/Access control.md#Permission control by uploading ACL files).

Command format:

1bcecmd bosapi append-bucket-acl --bucket-name BUCKET-NAME [--acl-config-file ACL-CONFIG-FILE]

Description:

• Specify the ACL configuration file using --acl-config-file. For the format of the ACL configuration file, please refer to [Bucket Permission Control](BOS/API Reference/Access control.md#Bucket permission control);
• If the ACL rules specified in the ACL configuration file are identical to the existing rules, they will be automatically filtered out, and a prompt message will be displayed.
• When appending Bucket ACL by uploading an ACL configuration file, the ACL configuration information will be displayed if the setting is successful. If it fails, the file content and the error message will be shown.

Example:

• Append Bucket ACL by uploading the ACL configuration file

  Example:

  Plain Text Copy

  1$ bcecmd bosapi append-bucket-acl --bucket-name bucket1 --acl-config-file acl-config.json

  Response example:

  Plain Text Copy

  1{
  2    "accessControlList": [
  3      {
  4        "grantee": [
  5          {
  6            "id": "e13b12d213213213232323f492323"
  7          }
  8        ],
  9        "permission": [
  10            "READ"
  11        ]
  12      },
  13      {
  14        "grantee": [
  15          {
  16            "id": "b13a56d27878788766e4989989212"
  17          }
  18        ],
  19        "permission": [
  20            "READ"
  21        ]
  22      }
  23    ]
  24}

• ACL configuration file example

  The ACL configuration file may contain single or multiple ACL rules, as shown in the examples below:

  Example 1:

  Specify one or more ACL rules using the JSON array format.

  Plain Text Copy

  1[
  2    {
  3        "grantee": [
  4          {
  5            "id": "b13a56d27878788766e4989989212"
  6          }
  7        ],
  8        "permission": [
  9            "READ"
  10        ]
  11    },
  12    {
  13        "grantee": [
  14          {
  15            "id": "c89d235665666655f478823567981"
  16          }
  17        ],
  18        "permission": [
  19            "READ"
  20        ]
  21    },
  22    ......
  23]

  Example 2:

  Use the general JSON format to specify the ACL rules to be appended.

  Plain Text Copy

  1{
  2    "accessControlList": [
  3      {
  4        "grantee": [
  5          {
  6            "id": "e13b12d213213213232323f492323"
  7          }
  8        ],
  9        "permission": [
  10            "FULL_CONTROL"
  11        ]
  12      },
  13      {
  14        "grantee": [
  15          {
  16            "id": "e56d577879621c56a577879677765"
  17          }
  18        ],
  19        "permission": [
  20            "READ"
  21        ]
  22      }
  23    ]
  24}

Retrieve Bucket ACL

Description:Get the ACL configuration of a bucket.

Command format:

1bcecmd bosapi get-bucket-acl --bucket-name BUCKET-NAME

Operation example:

1bcecmd bosapi get-bucket-acl --bucket-name bucket1

Response example:

1{
2  "accessControlList": [
3    {
4      "grantee": [
5        {
6          "id": "e13b12d213213213232323f492323"
7        }
8      ],
9      "permission": [
10        "FULL_CONTROL"
11      ],
12      "condition": {
13        "ipAddress": null,
14        "referer": {
15          "stringLike": null,
16          "stringEquals": null
17        }
18      }
19    }
20  ],
21  "owner": {
22    "id": "e13b12d213213213232323f492323"
23  }
24}

Set lifecycle

Description:Set [lifecycle management rules](BOS/Developer Guide/Data lifecycle management/Intelligent Business Analysis.md) for a specified bucket according to the provided lifecycle management file, or generate a lifecycle management file template.

Command format:

• Generate a transition configuration template: bcecmd bosapi put-lifecycle --template
• Set lifecycle management rules for a bucket using a specified configuration file: bcecmd bosapi put-lifecycle --lifecycle-config-file LIFECYCLE_CONFIG_FILE --bucket-name BUCKET_NAME

Example:

• Generate a transition configuration template

  Example:

  Plain Text Copy

  1$ bcecmd bosapi put-lifecycle --template

  Response example:

  Plain Text Copy

  1{
  2  "rule": [
  3    {
  4      "action": {
  5        "name": "Transition",
  6        "storageClass": "STANDARD_IA"
  7      },
  8      "status": "enabled",
  9      "resource": [
  10        "${bucket_name}/${prefix}/*"
  11      ],
  12      "id": "sample-id",
  13      "condition": {
  14        "time:": {
  15          "dateGreaterThan": "$(lastModified)+P30D"
  16        }
  17      }
  18    }
  19  ]
  20}

• Set lifecycle management rules for bucket1 using the configuration file 1.txt

  Example:

  Plain Text Copy

  1bcecmd bosapi put-lifecycle --lifecycle-config-file lifecycle_bj.json --bucket-name bucket1

  Response example:

  Plain Text Copy

  1{
  2  "rule": [
  3    {
  4      "status": "enabled",
  5      "action": {
  6        "name": "Transition",
  7        "storageClass": "STANDARD_IA"
  8      },
  9      "resource": [
  10        "bucket1/*"
  11      ],
  12      "id": "sample-rule-transition",
  13      "condition": {
  14        "time": {
  15          "dateGreaterThan": "$(lastModified)+P180D"
  16        }
  17      }
  18    }
  19  ]
  20}

  Note: Upon successful configuration, the lifecycle settings file will be returned; otherwise, an error message will be reported.

Get lifecycle configuration

Description:Get the lifecycle configuration of a specified bucket.

Command format: bcecmd bosapi get-lifecycle --bucket-name BUCKET_NAME

Operation example: bcecmd bosapi get-lifecycle --bucket-name bucket1

Response example:

1{
2  "rule": [
3    {
4      "action": {
5        "name": "Transition",
6        "storageClass": "STANDARD_IA"
7      },
8      "status": "enabled",
9      "resource": [
10        "bucket1/prefix1/*"
11      ],
12      "id": "sample-id",
13      "condition": {
14        "time:": {
15          "dateGreaterThan": "$(lastModified)+P30D"
16        }
17      }
18    }
19  ]
20}

Delete lifecycle configuration

Description:Delete the lifecycle management configuration of a specified bucket.

Command format: bcecmd bosapi delete-lifecycle --bucket-name BUCKET_NAME

Operation example: bcecmd bosapi delete-lifecycle --bucket-name bucket1

Response example: None

Set logging rules

Description:Enable [access logging function](BOS/Developer Guide/Bucket Basic Operations/Set access logs.md) for a bucket and save logs to the specified prefix in a target bucket.

Command format: bcecmd bosapi put-logging --target-bucket TARGET_BUCKET --target-prefix TARGET_PREFIX --bucket-name BUCKET_NAME

Operation example: bcecmd bosapi put-logging --target-bucket bucket2 --target-prefix log --bucket-name bucket1

Response example: None

Get logging rules

Description:Get the access logging configuration of a specified bucket.

Command format: bcecmd bosapi get-logging --bucket-name BUCKET_NAME

Operation example: bcecmd bosapi get-logging --bucket-name bucket1

Response example:

1$ bcecmd bosapi get-logging --bucket-name bucket1
2{
3  "status": "enabled",
4  "targetPrefix": "loggin/",
5  "targetBucket": "bucket1"
6}

Delete logging rules

Description:Delete the access log settings of a specified bucket.

Command format: bcecmd bosapi delete-logging --bucket-name BUCKET_NAME

Operation example: bcecmd bosapi delete-logging --bucket-name b1

Response example: None

Set default bucket storage class

Description:Set the default storage class for a specified bucket.

If the object uploaded via API, CLI, or SDK does not have a specified storage class, it follows the default storage class of the bucket. If the specified storage class of the uploaded object differs from the default storage class of the bucket, the storage class of the object shall apply. Storage classes include three types: standard storage (STANDARD), infrequent access storage (STANDARD_IA), cold storage (COLD). For specific usage scenarios and performance details, please refer to [Hierarchical Storage](BOS/Product Description/Tiered Storage Introduction/Why Tiered Storage Exists.md). For setting the default storage class of a bucket via the console, please refer to [Create a Bucket](BOS/Console Operation Guide/Managing Bucket/Create bucket.md).

Command format:

1bcecmd bosapi put-bucket-storage-class --bucket-name BUCKET_NAME --storage-class STORAGE_CLASS

Operation example:

1bcecmd bosapi put-bucket-storage-class --bucket-name bucket1 --storage-class COLD`

Response example: None

Query the default bucket storage class

Description:This command is used to query the default storage class of a bucket. The default storage classes of a bucket include standard storage, infrequent access storage, cold storage and archive storage.

Command format:

1bcecmd bosapi get-bucket-storage-class --bucket-name BUCKET_NAME

Operation example:

1bcecmd bosapi get-bucket-storage-class --bucket-name bucket1

Response example:

1{
2    "storageClass":"COLD"
3}