OSSUTIL(1)

πŸ“¦ version 1.7.9, in fedora 43

πŸ‘‘ NAME πŸ‘‘

okay so bestie, meet ossutil β€” the Alibaba Cloud (Aliyun) Object Storage Service (OSS) CLI πŸ’– and yes, this whole page is its manual, OSSUTIL(1). it's giving "your new favorite command-line bestie for everything OSS." periodt.

🌸 DESCRIPTION 🌸

Usage of ossutil:

Usage of ossutil:

that's literally the whole vibe of the description section, no notes πŸ’…. everything juicy is down in OPTIONS, so let's go.

✨ OPTIONS ✨

there are SO many of these and we're doing every single one, no skipping, no cap. buckle up πŸŽ€

  • --maxupspeed= β€” the max upload speed, and the unit is KB/s. the default value is 0, which means unlimited (go feral, no throttle, slay) πŸ¦‹
  • --acr-method= β€” this sets the value of the http header Access-Control-Request-Method, and it's primarily used in the cors-options command.
  • --start-time= β€” the start time, as a timestamp in the Linux/Unix system. like, the number of seconds that have passed since January 1, 1970 (midnight UTC/GMT). the classic epoch vibe ⭐
  • --token-timeout= β€” how long a token stays valid for. unit is s, default value is 3600, and it's primarily used for the AssumeRole parameters in RamRoleArn mode.
  • --ram-role-arn= β€” specifies the ARN of the ram role, primarily used in RamRoleArn mode.
  • --read-timeout= β€” the time that the client read times out. unit is s, default value is 1200.
  • --bucketname= β€” specifies a name of bucket, primarily used in the probe command.
  • --origin= β€” specifies the value of the origin field in the http header.
  • --parallel= β€” how many concurrency tasks to run when working with a file. value range is 1-10000, and by default ossutil will decide the value intelligently all on its own (she's smart, let her cook πŸ‘‘).
  • --download β€” specifies a download action from oss, primarily used in the probe command.
  • --kms-data-encryption= β€” specifies the kms data service encryption algorithm. currently it only supports the value SM4 or being emtpy (their spelling, not mine, and yes we're keeping it exactly πŸ’€).
  • --proxy-user= β€” username of the network proxy, default is empty.
  • --only-current-dir β€” says that only files or objects in the current directory get manipulated, and subdirectories are ignored. no going deeper, we stay on this level πŸ™ˆ
  • --connect-timeout= β€” the time that the client connection times out. unit is s, default value is 120.
  • --storage-class= β€” sets the storage class of the bucket (default: Standard). value range is: Standard/IA/Archive/ColdArchive.
  • --include= β€” Include Pattern of key, e.g. *.jpg ✨
  • --exclude= β€” Exclude Pattern of key, e.g. *.txt 🚫
  • --acl= β€” acl information.
  • --url= β€” specifies a url address, primarily used in the probe command.
  • --mode= β€” specifies the authentication mode. the value can be AK，StsToken，RamRoleArn，EcsRamRole, and the default value is empty.
  • --part-size= β€” Part size, unit is Byte. in default situation, ossutil will calculate the suitable part size according to file size. this option is useful when the user has special needs, or when the user needs to do performance tuning. the value range is: 1-9223372036854775807(Byte).
  • --probe-item= β€” specifies the probe command's probe item. the value can be upload-speed, download-speed, cycle-symlink.
  • --backup-dir= β€” the directory of the backup file used by the sync command.
  • -j, --jobs= β€” how many concurrency tasks run between multi-files (default: 3). value range is: 1-10000.
  • --delete β€” delete.
  • --disable-crc64 β€” disables crc64. in default situation, ossutil turns crc64 check ON when transmitting data.
  • --loglevel= β€” log level, default is empty (meaning no log file output). optional value is: info|debug β€” info will output information logs, debug will output detail logs (including http request and response logs).
  • -p, --password β€” specifies that the accessKeySecret is inputted from the keyboard ⌨️
  • -k, --access-key-secret= β€” AccessKeySecret used while accessing oss. (Notice that the value of the option will cover the value in the config file.)
  • --object= β€” specifies a name of object, primarily used in the probe command.
  • --tagging= β€” Set object tagging, value format is ["TagA=A&TagB=B...]"
  • --output-dir= β€” this option specifies the directory to place the output file in. the output file contains: the report file generated by the cp command when an error happens during a batch copy operation (for more information about the report file, see help of the cp command). the default value of the option is: ossutil_output directory in the current directory.
  • -t, --sts-token= β€” STSToken used while accessing oss (Notice that the value of the option will cover the value in the config file). not necessary.
  • -m, --multipart β€” indicates that the subject of the command is uncompleted Multipart Uploads, instead of objects (which is the subject in the default situation).
  • -r, --recursive β€” operate recursively. for those commands which support this option, when you use them and this option is specified, the command will operate on all matching objects under the bucket; else we will search the specified object and operate on that single object.
  • --disable-empty-referer β€” specifies that the referer field is not allowed to be empty, primarily used in the referer command.
  • --version-id-marker= β€” specifies the marker of object version id when listing objects' all versions.
  • --end-time= β€” the end time, as a timestamp in the Linux/Unix system. like, the number of seconds that have passed since January 1, 1970 (midnight UTC/GMT). ⭐
  • --role-session-name= β€” specifies the session name, primarily used in RamRoleArn mode.
  • --encoding-type= β€” the encoding type of the object name or file name that the user inputs or outputs. currently ossutil only supports url encode, which means the value range of the option is: url. if you don't specify the option, it means the object name or file name that the user inputted or outputted was not encoded. bucket name does not support url encode. Note: if the option is specified, the cloud_url like oss://bucket/object should be inputted as oss://bucket/url_encode(object), and the string oss://bucket/ should not be url encoded.
  • -d, --directory β€” return matching subdirectory names instead of contents of the subdirectory.
  • -u, --update β€” update.
  • --snapshot-path= β€” okay this one is a whole saga, bestie, but it's important so we're doing it properly. πŸ’œ

this option is used to accelerate the incremental upload of batch files, or download of objects, in certain scenarios. if you use the option when uploading files or downloading objects, ossutil will generate files to record the snapshot information in the specified directory. the next time you upload files or download objects with the option, ossutil will read the snapshot information under the specified directory for incremental upload or incremental download.

the snapshot-path you specify must be a local file system directory that can be written in. if the directory does not exist, ossutil creates the files for recording snapshot information; else ossutil will read snapshot information from the path for incremental upload (ossutil will only upload the files which have not been successfully uploaded to oss, or which have been locally modified) or incremental download (ossutil will only download the objects which have not been successfully downloaded, or which have been modified), and update the snapshot information to the directory.

Note: the option records the lastModifiedTime of local files which have been successfully uploaded in the local file system, or the lastModifiedTime of objects which have been successfully downloaded, and compares the lastModifiedTime of local files or objects in the next cp to decide whether to skip the file or object.
if you use this option to achieve incremental upload, please make sure no other user modifies the corresponding object in oss during the two uploads. if you cannot guarantee those scenarios, please use the --update option to achieve incremental upload instead.
In addition, ossutil does not automatically delete snapshot-path snapshot information. in order to avoid too much snapshot information piling up, when the snapshot information is useless, please clean up your own snapshot-path on your own immediately. 🧹
  • --upload β€” specifies an upload action to oss, primarily used in the probe command.
  • --version-id= β€” specifies the object's version id.
  • --disable-dir-object β€” specifies that an oss object is not generated for the directory itself when uploading, primarily used in the cp command.
  • --redundancy-type= β€” specifies the bucket data redundancy type. the value can be LRS, ZRS. LRS is the default value and specifies locally redundant storage; ZRS specifies higher availability of redundant storage.
  • --bigfile-threshold= β€” the threshold of file size. a file size larger than the threshold will use resume upload or download (default: 104857600). value range is: 0-9223372036854775807.
  • --trafic-limit= β€” http request speed limit, unit is bit/s, default value is 0 (unlimited), primarily used in the sign command. (yes it's spelled trafic, we don't fix, we respect 🫢)
  • --local-host= β€” ossutil's ip, such as 127.0.0.1.
  • --sts-region= β€” specifies the region of the sts endpoint, such as cn-shenzhen β€” in this case, cn refers to the country and shenzhen refers to the region β€” used to construct the sts endpoint. when this option defaults, the sts endpoint is sts.aliyuncs.com. primarily used in RamRoleArn mode.
  • -v, --version β€” Show ossutil version (v1.7.9) and exit. bye bestie πŸ‘‹
  • -s, --short-format β€” Show by short format. if the option is not specified, it shows long format by default.
  • --maxdownspeed= β€” max download speed, unit is KB/s, default value is 0 (unlimited) πŸ“
  • --acr-headers= β€” specifies the value of the http header Access-Control-Request-Headers, primarily used in the cors-options command.
  • --enable-symlink-dir β€” specifies uploading link subdirectories. by default they are not uploaded. the probe command can detect whether there is a dead cycle symlink file or directory. πŸ¦‹
  • --disable-encode-slash β€” specifies no encoding of / in the url path section, primarily used in the sign command.
  • --disable-all-symlink β€” specifies that uploading of symlink files and symlink directories under the directory is not allowed. the default value is false.
  • -B, --block-size= β€” specifies the unit of byte display for the du command. the value can be KB, MB, GB, TB.
  • --ua= β€” Specify the user agent in the http request, and the specified value will be added after the default value.
  • --upload-id-marker= β€” the marker of object when listing object or Multipart Uploads.

okay that's part 1, and there's more coming so don't go anywhere πŸ’–πŸŒΈβœ¨

okay bestie the flag buffet is STILL going, grab a snack, we're finishing this πŸ’–

  • -b, --bucket β€” the option that makes absolutely sure the operation is operating on a bucket. like, no confusion, it's a bucket, periodt πŸͺ£
  • -f, --force β€” do the thing silently, no asking the user to confirm first. no "are you sure?" pop-up, it just GOES. use responsibly bestie 😭
  • --upmode= β€” sets the upload mode. default is normal, and the optional values are normal|append|multipart, which mean normal upload, append upload, and multipart upload respectively. it's mostly used in the probe command. lowkey a whole personality selector ✨
  • --kms-masterkey-id= β€” specifies the primary key id inside the kms (key management service). your keys, your kingdom πŸ‘‘
  • --skip-verify-cert β€” says the oss server's digital certificate file will not be verified. it's giving "we trust you, no questions asked" 🫣
  • --timeout= β€” the time out of signurl, unit is seconds, default value is 60, and the value range is 0-9223372036854775807. yes that's a huge number, no we're not questioning it πŸ’€
  • --type= β€” the hash type. Default: crc64, value range is crc64/md5
  • --method= β€” specifies the command's operation type. the values are PUT, GET, DELETE, LIST, etc. pick your fighter βš”οΈ
  • --partition-download= β€” this one is for partition download mode: one command downloads one partition. the value format is "partition number:total count of partitions", such as 1:5, which means the command downloads partition 1 and the total partition count is 5. the partition number is numbered from 1, and the partitioning rules for objects are determined by ossutil. with this option, the objects to be downloaded get split into multiple partitions, which can be downloaded by multiple ossutil commands β€” each ossutil command downloads its own partition, and multiple ossutil commands can be run on different machines in parallel. it's giving teamwork, it's giving girlboss distribution 🌈
  • --proxy-pwd= β€” password of the network proxy, default is empty
  • --limited-num= β€” the limited number of return results. a little portion control πŸ“
  • --checkpoint-dir= β€” Path of the checkpoint directory (default: .ossutil_checkpoint). this directory is used in resume upload or download. when an operation fails, ossutil creates the directory automatically and records the checkpoint information inside it; when the operation succeeds, the directory gets removed. so when you specify this option, please make sure the directory can be removed.
⚠️ bestie READ THAT AGAIN: if you point this at a directory you actually care about, it will get deleted on success. do not send your homework folder in there πŸ™ˆ
  • --meta= β€” set object meta as [header:value#header:value...], e.g., Cache-Control:no-cache#Content-Encoding:gzip
  • -L, --language= β€” set the language of ossutil (default: EN), value range is CH/EN. if you set it to "CH", please make sure your system language is UTF-8. multilingual icon behavior πŸ’…
  • --marker= β€” the marker of the bucket when listing buckets, or the marker of the key when listing objects or Multipart Uploads, or anywhere else a marker is needed. a little bookmark for your soul πŸ”–
  • --range= β€” the range when downloading objects, the form is like: 3-9 or 3- or -9
  • --sse-algorithm= β€” specifies the server side encryption algorithm, value is KMS or AES256. encryption but make it fashion πŸ”
  • -e, --endpoint= β€” base endpoint for the oss endpoint. (Notice that the value of the option will cover the value in the config file.) Take notice that it should be second-level domain (SLD).
  • --retry-times= β€” retry times when it fails (default: 10), value range is 1-500. never give up, never surrender, but also there's a cap πŸ’€
  • -c, --config-file= β€” Path of the ossutil configuration file β€” where to dump config in the config command, or where to load config from in other commands that need credentials.
  • --payer= β€” the payer of the request. you can set this value to "requester" if you want to pay for requester. split the bill energy, but for cloud storage 🧾
  • --addr= β€” specifies a network address, usually a domain, primarily used in the probe command
  • --all-versions β€” specifies the object's all versions. every era of that object, we love a throwback πŸ¦‹
  • --proxy-host= β€” url of the network proxy server, which supports http/https/socks5, such as https://120.79.128.211:3128, socks5://120.79.128.211:1080
  • --disable-ignore-error β€” specifies that errors are not ignored during batch cp. default value is false. flip it and every little error will be seen and felt 😭
  • --ecs-role-name= β€” specifies the authentication mode, primarily used in EcsRamRole mode.
  • --item= β€” specifies the command's function type. the values are LOCATION, PROGRESS, etc. it's giving structured output, it's giving options πŸ“Š
  • -i, --access-key-id= β€” AccessKeyID while accessing oss. (Notice that the value of the option will cover the value in the config file.) keep it secret, keep it safe bestie πŸ”‘
  • -a, --all-type β€” indicate that the subject of the command contains both objects and uncompleted Multipart Uploads. all of it, the whole collection, no crumbs left ✨
  • -h, --help β€” show usage message. when in doubt, -h it out 🫢
  • --version β€” show version

and that's the whole list, bestie, you ate that πŸ‘‘ this little page is from ossutil 1.7.9, dated August 2025, and you can find it filed under OSSUTIL(1) β€” go forth and be iconic with your buckets πŸ’–βœ¨πŸŽ€

πŸ“¦ where this page comes from