ossutil 2.0 introduces a tiered command structure, expanded credential support, richer filtering, and improved output control. This page summarizes the changes to help you assess the upgrade impact.
Command structure
ossutil 2.0 organizes commands into two tiers:
| Tier | Format | Example |
|---|---|---|
| High-level commands | ossutil <command> | ossutil config |
| API-level commands | ossutil api <command> | ossutil api put-bucket-acl |
Configuration
Basic configuration
ossutil 2.0 requires three configuration items: AccessKey ID, AccessKey Secret, and region ID. The region ID is now mandatory because the signature algorithm has been upgraded to Signature Version 4 (V4). For a list of region IDs, see Regions and endpoints.
Configuration file
A single configuration file can hold multiple profiles. To load a specific profile, pass --profile <profile-name>. To inherit settings from another profile, set source-profile in the configuration file.
config command enhancements
The config command now supports interactive configuration and three subcommands:
| Subcommand | Description |
|---|---|
config set / config get | Add, remove, or modify settings |
config list-profiles | Query all existing profiles |
config credential | Set credentials for a specific profile |
New environment variables
ossutil 2.0 adds environment variables for the following parameters: region, endpoint, config-file, and profile. Using environment variables is more secure than passing credentials directly as command-line arguments.
Credentials
ossutil 2.0 expands the supported credential types:
External credentials: Retrieve credentials from a URI or an external process.
OpenID Connect (OIDC) credentials: Authenticate using OIDC tokens.
Instance RAM roles: RAM roles are automatically detected when running in instance RAM role access mode.
Output control
Output formatting
Use --output-format to change the output format:
| Format | Notes |
|---|---|
| JSON | — |
| YAML | — |
| XML | When converting from another format, the root node is always named root. |
The default output uses the raw format (XML or text).
Output filtering
Use --output-query to filter command output.
Filters for batch operations
High-level commands that process multiple objects — such as ls, cp, and rm — support the following filter types:
| Filter type | Description |
|---|---|
| Path, file name, or object name | Match by name pattern |
| List of paths, file names, or object names | Match against a list |
| File size or object size | Filter by size range |
| Last modified time | Filter by modification time |
| Object metadata | Filter by metadata attributes |
Metadata and tag copy control
The --copy-props option controls what is copied during cp operations:
| Value | Behavior |
|---|---|
| Default (not specified) | Copy both metadata and tags |
| Disable metadata and tag copy | Skip metadata and tag copy |
| Copy only metadata | Copy metadata, skip tags |
Addressing style
Use --addressing-style to control how OSS endpoint URLs are constructed. Supported styles are virtual domains, path-style addresses, and CNAME.
Batch operation controls
All batch processing commands share a consistent set of control options:
Specify a key range to query
Limit the number of results returned
Process objects recursively under a directory
Force the operation without confirmation prompts
Usability improvements
Dry run
--dry-run (or -n) simulates a command without making any changes. Use it to validate your command before execution.
Standard input support
ossutil 2.0 reads parameters and options from standard input (stdin), so you can chain commands using the pipe symbol (|).
Command aliases
Commonly used commands support shorter aliases.
Unit suffixes for options
Some options accept values with unit suffixes:
| Option | Example | Value |
|---|---|---|
--max-size | --max-size 1M | 1,048,576 bytes (1024 x 1024) |
--max-age | --max-age 1.5d | 36 hours |
Comma-separated option values
Some options accept multiple values as a comma-separated list. For example:
--tagging key=value,key1=value1is equivalent to:
--tagging key=value --tagging key1=value1Documentation structure
Command-line options are now categorized as global or local options in the documentation for easier reference.
Return codes
Return codes are standardized across all commands. A non-zero return code indicates an error. The specific return code identifies the phase in which the error occurred, making it easier to handle errors programmatically.
Client-side time sync
When the client clock differs from the server clock by more than 15 minutes, OSS returns RequestTimeTooSkewed. ossutil 2.0 detects this error and automatically synchronizes the client time. Note that auto time sync applies to client environments where the client clock is inconsistent with the server.