All Products
Search
Document Center

Object Storage Service:Command-line options

Last Updated:Sep 09, 2024

Command-line options take the highest precedence and overwrite the settings in configuration files and environment variables. Command-line options are divided into global options and local options. Global command-line options apply to all commands, whereas local command-line options apply only to specific commands.

Query command-line options

Run the following sample command to query the options for a specific command:

ossutil cp -h

Command output:

Flags:
      --acl string                         The access control list (ACL) of the object, valid value(s): "private","public-read","public-read-write","default"
      --bandwidth-limit SizeSuffix         Bandwidth limit in B/s, or use suffix B|K|M|G|T|P
      --bigfile-threshold SizeSuffix       The threshold of file size, the file size larger than the threshold will use multipart upload, download or copy, or use suffix B|K|M|G|T|P (default 100Mi)
      --cache-control string               The caching behavior of the web page when the object is downloaded
      --checkers int                       Number of checkers to run in parallel (default 16)
      --checkpoint-dir string              The specified directory for breakpoint continuation information
      --checksum                           Only copy the source file with different size and checksum(if available)
      --content-disposition string         The method that is used to access the object
      --content-encoding string            The method that is used to encode the object
      --content-type string                The mime type of object
      --copy-props string                  Determines which properties are copied from the source object, valid value(s): "none","metadata","default"
  -d, --dirs                               Return matching subdirectory names instead of contents of the subdirectory
      --encoding-type string               The encoding type of object name or file name that user inputs, valid value(s): "url"
      --end-with string                    The name of the object from which the list operation ends, include
      --exclude stringArray                Exclude files matching pattern
      --exclude-from stringArray           Read exclude patterns from file
      --expires string                     The expiration time of the cache in UTC
      --files-from stringArray             Read list of source-file names from file, ignores blank and comment line
      --files-from-raw stringArray         Read list of source-file names from file without any processing of lines
      --filter stringArray                 A file-filtering rule
      --filter-from stringArray            Read file filtering rules from a file
  -f, --force                              Operate silently without asking user to confirm the operation
      --include stringArray                Don't exclude files matching pattern
      --include-from stringArray           Read include patterns from file
  -j, --job int                            Amount of concurrency tasks between multi-files (default 3)
      --list-objects                       Use ListObjects instead of ListObjectsV2 to list objects
      --max-age Duration                   Don't transfer any file older than this, in s or suffix ms|s|m|h|d|w|M|y (default off)
      --max-mtime Time                     Don't transfer any file younger than this, UTC time format (default off)
      --max-size SizeSuffix                Don't transfer any file larger than size, in B or suffix B|K|M|G|T|P, 1K(KiB)=1024B
      --metadata strings                   Specifies the object's user metadata, in key=value foramt
      --metadata-directive string          The method that is used to configure the metadata of the destination object, valid value(s): "COPY","REPLACE"
      --metadata-exclude stringArray       Exclude metadata matching pattern
      --metadata-filter stringArray        A metadata-filtering rule
      --metadata-filter-from stringArray   Read metadata filtering rules from a file
      --metadata-include stringArray       Don't exclude metadata matching pattern
      --min-age Duration                   Don't transfer any file younger than this, in s or suffix ms|s|m|h|d|w|M|y (default off)
      --min-mtime Time                     Don't transfer any file older than this, UTC time format (default off)
      --min-size SizeSuffix                Don't transfer any file smaller than size, in B or suffix B|K|M|G|T|P, 1K(KiB)=1024B
      --no-error-report                    Don't generate error report file during batch operation
      --no-progress                        The progress is not displayed
      --output-dir string                  Specifies the directory to place output file in, output file contains: error report file generated during batch operation (default "ossutil_output")
      --page-size int                      The number of results to return in each response to a list operation (default 1000), in the range 1 - 1000
      --parallel int                       Amount of concurrency tasks when work with a file
      --part-size SizeSuffix               The part size, calculated the suitable size according to file size by default, or use suffix B|K|M|G|T|P, in the range 100Ki - 5Gi
  -r, --recursive                          Operate recursively, if the option is specified, the command will operate on all match objects under the bucket, else operate on the single object.
      --request-payer string               The payer of the request. set this value if you want pay for requester, valid value(s): "requester"
      --size-only                          Only copy the source file with different size
      --start-after string                 The name of the object from which the list operation starts, not include
      --storage-class string               The storage class of the object, valid value(s): "Standard","IA","Archive","ColdArchive","DeepColdArchive"
      --tagging strings                    Specifies the tag of the destination object, in key=value foramt
      --tagging-directive string           The method that is used to configure tags for the destination object, valid value(s): "COPY","REPLACE"
  -u, --update                             Only copy when the source file is newer than the destination file

Global Flags:
  -i, --access-key-id string        AccessKeyID while access oss
  -k, --access-key-secret string    AccessKeySecret while access oss
      --addressing-style string     The style in which to address endpoints (default "virtual"), valid value(s): "virtual","path","cname"
  -c, --config-file string          The path of the configuration file (default "~/.ossutilconfig")
      --connect-timeout int         The client connection timed out, the unit is: s (default 10)
  -n, --dry-run                     Do a trial run with no permanent changes
  -e, --endpoint string             The domain names that other services can use to access OSS.
  -h, --help                        help for the command
      --language string             The display text language
      --log-file string             Specifies the log output file. When -, outputs to Stdout
      --loglevel string             The debug message level (default "off"), valid value(s): "off","info","debug"
      --mode string                 Specifies the authentication mode, valid value(s): "AK","StsToken","EcsRamRole","Anonymous"
      --output-format string        The formatting style for command output (default "raw")
      --output-properties strings   The properties of output format
      --output-query string         A JMESPath query to use in filtering the response data
      --profile string              Specific profile from your config file.
      --proxy string                Specifies the proxy server. When 'env', use HTTP_PROXY and HTTPS_PROXY environment variables
  -q, --quiet                       Quiet mode, print as little stuff as possible
      --read-timeout int            The client read timed out, the unit is: s (default 20)
      --region string               The region in which the bucket is located.
      --retry-times int             Retry times when fail (default 10)
      --role-arn string             Specifies the ARN of role
      --role-session-name string    Specifies the session name
      --sign-version string         The version of the signature algorithm (default "v4"), valid value(s): "v1","v4"
      --skip-verify-cert            Specifies that the oss server's digital certificate file will not be verified
  -t, --sts-token string            STSToken while access oss

Use command-line options

In command-line operations, specific commands require additional parameters to specify the operation object or configure options. For these commands, you can set the additional parameters to appropriate values based on specific requirements to achieve the expected goal. Example:

ossutil ls --profile dev

ossutil ls --profile dev specifies that the dev parameter value configures the configuration file. Each option that has a parameter value requires a space or an equal sign (=) between the option name and the parameter value. Examples: --profile dev or --profile=dev. If a parameter value contains spaces, you must enclose the parameter value in quotation marks to ensure that the command parses correctly. Example: --description "OSS bucket list".

Global command-line options

Parameter

Type

Description

-i, --access-key-id

string

The AccessKey ID used to access Object Storage Service (OSS).

-k, --access-key-secret

string

The AccessKey secret used to access OSS.

--addressing-style

string

The addressing style. Valid values:

  • virtual (default): the virtual hosting mode.

  • path: the path mode.

  • cname: the custom domain name mode.

-c, --config-file

string

The path of the configuration file. Default value: ~\\.ossutilconfig.

--connect-timeout

int

The timeout period in seconds for client connections. Default value: 10. Unit: seconds.

-n, --dry-run

/

Performs a trial run without making changes.

-e, --endpoint

string

The endpoint.

-h, --help

/

Displays help information for a specific command.

--language

string

The display language.

--loglevel

string

The log level. Valid values:

  • off (default)

  • info

  • debug

--mode

string

The authentication mode. Valid values:

  • AK: the AccessKey pair.

  • StsToken: the temporary access credential.

  • EcsRamRole: the RAM role attached to the Elastic Compute Service (ECS) instance.

  • Anonymous: anonymous access.

--output-format

string

The output format. Default value: raw.

--output-query

string

The JMESPath query condition.

--profile

string

Specifies the profile in the configuration file.

-q, --quiet

/

Enables the quiet mode to print the least information.

--read-timeout

int

The timeout period in seconds for client read and write requests. Unit: seconds. Default value: 20.

--region

string

The region in which the data center is located. Example: cn-hangzhou.

--retry-times

int

The number of retries when an error occurs. Default value: 10.

--sign-version

string

The version of the signature algorithm. Valid values:

  • v1

  • v4 (default)

--skip-verify-cert

/

Specifies that the digital certificate provided by the server is not verified.

-t, --sts-token

string

The token issued by Security Token Service (STS).

--proxy

string

The proxy server.

Configuration methods:

  • Direct configuration: You can directly specify the proxy server. Examples:

    • http://proxy.example.com:8080

    • https://proxy.example.com:8443

  • env: use the HTTP_PROXY and HTTPS_PROXY environment variables to obtain the proxy server information. You need to configure these environment variables in the operating system. Examples:

    • HTTP_PROXY=http://proxy.example.com:8080

    • HTTPS_PROXY=https://proxy.example.com:8443

    After you configure these environment variables, you can set the value of the proxy server option to env. Then, the system automatically uses the proxy settings specified by these environment variables.

--log-file

string

The log output file. Valid values:

  • -: Logs are exported to stdout.

  • File path: After you specify a specific file path, logs are exported to the file.

If you do not specify a specific file path, logs are exported to the default configuration file.