Cloud storage
Cloud storage is a file storage capability provided by TCB for users. Users can operate on storage through CLI tools and SDK provided by TCB, such as uploading and downloading files. Files stored in Cloud storage are provided with CDN acceleration by default, enabling users to quickly access files in Cloud storage.
Path Description
localPathis the path of a local file or folder, in the form ofdirectory/filename, such as./index.js,static/css/index.css, etc.cloudPathis the path of a Cloud storage file or folder relative to the root directory, in the form ofdirectory/filename, such asindex.js,static/css/index.js, etc.
On Windows systems, localPath is in the local path format recognized by the system, typically using the \ separator. cloudPath is the cloud file path and must use the / separator.
File Upload
You can use the following command to upload files/folders. When the CLI detects that localPath is a folder, it will automatically upload all files within the folder.
tcb storage upload localPath cloudPath
# Specify upload retry count (0-10, default 1)
tcb storage upload localPath cloudPath --times 3
# Specify retry interval (ms, default 500)
tcb storage upload localPath cloudPath --interval 1000
File Download
You can use the following command to download files/folders. When downloading a folder, the --dir parameter must be specified.
# Download files.
tcb storage download cloudPath localPath
# Download folder
tcb storage download cloudPath localPath --dir
Download all files
When cloudPath is set to /, it means downloading all files in Cloud storage:
tcb storage download / localPath --dir
File Deletion
The tcb storage rm command has been added since v3.0.0 and is the recommended delete command with more powerful features.
The old command tcb storage delete has been deprecated and is retained for backward compatibility. Please use the new command tcb storage rm.
# Deleting a Single File
tcb storage rm cloudPath
# Delete folder (recursive deletion)
tcb storage rm cloudPath --dir
# Force Delete without Confirmation Prompt
tcb storage rm cloudPath --force
# Dry run, only display the files to be deleted, without actual execution
tcb storage rm cloudPath --dry-run
Command Parameters:
| Parameter | Description |
|---|---|
--dir | Target is a folder (recursive deletion) |
--recursive | Same as --dir |
--force | Force deletion without confirmation prompt |
--dry-run | Dry run, only display the files to be deleted, without actual deletion |
List Files
List files in the folder:
tcb storage list [cloudPath]
Copy/Move Files
This feature has been added since v3.0.0.
Copy or move files in the cloud (only at file level, folders not supported):
# Copy Files
tcb storage cp <sourcePath> <destPath>
# Move Files (by copying then deleting the source file)
tcb storage cp <sourcePath> <destPath> --move
# Force overwrite existing target files
tcb storage cp <sourcePath> <destPath> --force
# Skip existing target files
tcb storage cp <sourcePath> <destPath> --skip
Command Parameters:
| Parameter | Description |
|---|---|
--move | Move Files (by copying then deleting the source file) |
--force | Force overwrite existing files |
--skip | Skip existing files |
-e, --env-id <envId> | Environment ID |
Search Files
This feature has been added since v3.0.0.
Search cloud files by filename pattern:
# Basic Search (supports wildcards, such as *.jpg)
tcb storage search <pattern>
# Search in the specified directory
tcb storage search <pattern> --dir images/
# Filter by File Type (e.g., jpg, png, pdf)
tcb storage search <pattern> --type jpg
# Handle pattern as a regular expression
tcb storage search <pattern> --regex
Command Parameters:
| Parameter | Description |
|---|---|
-e, --env-id <envId> | Environment ID |
--dir <dir> | Specify the search directory (searches the root directory if not specified) |
--type <ext> | Filter by file type (e.g., jpg, png, pdf) |
--regex | Handle pattern as a regular expression |
Obtain File Access Link
Obtain temporary access link for a file:
tcb storage url cloudPath
# Specify link valid period (seconds, default: 3600)
tcb storage url cloudPath --expire 7200
Obtain File Information
Obtain basic file information:
tcb storage detail cloudPath
Permission Management
Commands such as tcb storage get-acl, tcb storage set-acl, tcb storage rules get, tcb storage rules update, and other storage permission commands have been deprecated since v3.0.0.
Please migrate to the tcb permission command for resource permission management. Refer to Permission Management for details.
Obtain Access Permissions
tcb storage get-acl
Set Access Permissions
tcb storage set-acl --acl <permission-value>
Optional permission values: READONLY, PRIVATE, ADMINWRITE, ADMINONLY
Obtain Permission Rules
tcb storage rules get
Update Permission Rules
# Use Preset Permissions
tcb storage rules update --acl READONLY
# Use Custom Rules (JSON Format)
tcb storage rules update --acl CUSTOM --rules '[{"role":"anyone","action":"read"}]'
Optional permission values: READONLY, PRIVATE, ADMINWRITE, ADMINONLY, CUSTOM (used for custom rules)
Notes on Deprecated Commands
The following old-format commands (colon-separated) are deprecated, but backward compatibility is maintained: please migrate to the new commands.
| Old Command | New Command |
|---|---|
tcb storage:upload | tcb storage upload |
tcb storage:download | tcb storage download |
tcb storage:delete | tcb storage rm |
tcb storage:list | tcb storage list |
tcb storage:url | tcb storage url |
tcb storage:detail | tcb storage detail |
tcb storage:get-acl | tcb permission |
tcb storage:set-acl | tcb permission |
Command Quick Reference
| Command | Description |
|---|---|
tcb storage upload <local> <cloud> | Upload a file/folder |
tcb storage download <cloud> <local> | Download a file/folder |
tcb storage rm <path> | Delete a file/folder (recommended) |
tcb storage list [path] | List files |
tcb storage cp <src> <dest> | Copy/move files |
tcb storage search <pattern> | Search files |
tcb storage url <path> | Obtain a temporary access link |
tcb storage detail <path> | Obtain file information |
tcb storage get-acl | Obtain access permissions (deprecated, use tcb permission) |
tcb storage set-acl | Set access permissions (deprecated, use tcb permission) |
tcb storage rules get | Obtain permission rules (deprecated, use tcb permission) |
tcb storage rules update | Update permission rules (deprecated, use tcb permission) |
PostgreSQL Environment
The following commands target CloudBase environments using the PostgreSQL architecture, and are available since @cloudbase/cli@3.4.0.
- These commands map to the SDK's PG Storage HTTP API (see
cloudbase-manager-nodePG APIs). - In a PG environment, the legacy flat
tcb storagecommands above (upload/download/delete/rm/list/url/detail/cp/search) are rejected; the CLI suggests the corresponding PG sub-command in its error output. - To create a PG environment:
tcb env create --alias <name> --package <pkg> --postgresql --yes. - To check whether an environment is PG, run
tcb env listand inspect its type.
Command Group Overview
| Command Group | Purpose |
|---|---|
tcb storage buckets | Manage Storage buckets (PG metadata) |
tcb storage policies | Inspect RLS policies in the storage schema |
tcb storage objects | Object CRUD, signing, copy, move, etc. |
In a PG environment, tcb db execute also supports executing PostgreSQL SQL, including SQL for managing buckets and policies (see the PostgreSQL extensions in Relational Database (MySQL)).
tcb storage buckets list
Lists all Storage buckets in the current PG environment.
tcb storage buckets list [-e <envId>] [--json]
--json: Outputs the rawPGExecuteResult(withColumns/Rows).- Table columns:
Id/Name/Public/Size Limit/MIME Types/Created/Updated.
Bucket modifications are performed via
tcb db execute, for example:
tcb storage policies list
Lists RLS policies on the buckets / objects tables under the storage schema.
tcb storage policies list [--table buckets|objects] [-e <envId>] [--json]
| Option | Description |
|---|---|
--table <table> | Filter by table; one of buckets / objects. If omitted, returns policies of both tables |
--json | Outputs the raw PGExecuteResult |
RLS policy changes are performed by running
CREATE POLICY/DROP POLICYviatcb db execute --role postgres.
tcb storage objects upload
Uploads a local file to a Storage bucket.
tcb storage objects upload <localPath> <key> -b <bucketId> [options]
| Option | Description |
|---|---|
<localPath> | Absolute or relative path to a local file (must be a file) |
<key> | Remote object name (must not start with /) |
-b, --bucket <bucketId> | Bucket ID; can be replaced by the env var TCB_BUCKET_ID |
--content-type <mime> | Explicit MIME; if omitted, inferred from extension → magic bytes |
--cache-control <value> | A number is converted to max-age=<n>; a string is used as Cache-Control verbatim |
--metadata <json> | Custom metadata JSON; Base64-encoded into X-Metadata |
--robots-tag <value> | X-Robots-Tag header |
--upsert | Allow overwriting an existing object (POST mode) |
--use-put | Use PUT (always overwrites) |
--json | Outputs the raw SDK return value ({ Id, Key }) |
Examples:
tcb storage objects upload ./hello.txt test/hello.txt -b my-bucket
tcb storage objects upload ./hello.txt test/hello.txt -b my-bucket --content-type text/plain --upsert
tcb storage objects download
Downloads an object from a Storage bucket to local disk.
tcb storage objects download <key> [localPath] -b <bucketId> [options]
| Option | Description |
|---|---|
<key> | Object name |
[localPath] | Local path; if omitted, content is written to stdout. If it points to an existing directory, the basename of key is appended |
-b, --bucket <bucketId> | Bucket ID |
-m, --method <method> | GET (default) / HEAD |
--download <filename> | Triggers a browser download (?download=<filename>) |
--if-none-match <etag> | If-None-Match header (only effective on the authenticated download path) |
--if-modified-since <date> | If-Modified-Since header |
--range <range> | Range header (resumable downloads) |
--overwrite | Allow overwriting localPath if it already exists |
--json | Returns metadata only ({ status, headers }); does not write to disk |
Behavior:
- Logged in → uses the authenticated download path (
downloadAuthenticatedObject); supports private/public buckets. - Not logged in → falls back to
downloadPublicObject; only public buckets are accessible. --method HEADand--jsonmodes never write to disk.
tcb storage objects stat
Queries metadata of an object.
tcb storage objects stat <key> -b <bucketId> [options]
| Option | Description |
|---|---|
-m, --method <method> | GET (default) / HEAD; HEAD is only supported on the authenticated path |
--json | Outputs { status, headers, body }, where body is IObjectInfoHttpPayload |
The table output uses the following column order: id / name / bucket_id / version / size / content_type / cache_control / etag / last_modified / created_at / metadata.
tcb storage objects list
Lists objects in a bucket, with optional prefix filtering, pagination and sorting.
tcb storage objects list -b <bucketId> [options]
| Option | Description |
|---|---|
--prefix <prefix> | Path prefix filter |
--limit <n> | Page size, 1-1000, defaults to 20. Out-of-range values are rejected with INVALID_PARAM (exit 3) |
--cursor <cursor> | Pagination cursor (the previous response's nextCursor) |
--with-delimiter | Use / as folder delimiter |
--sort-by <column> | Sort column; one of name / created_at / updated_at |
--sort-order <order> | Sort direction; one of asc (default) / desc |
--json | Outputs the raw SDK return value (with folders / objects / hasNext / nextCursor) |
listrequires login; otherwise it fails withAUTH_FAILED.
tcb storage objects rm
Deletes objects; up to 20 per call.
tcb storage objects rm <keys...> -b <bucketId> [-y] [--json]
| Option | Description |
|---|---|
<keys...> | 1 to 20 object names; more than 20 is rejected with INVALID_PARAM (exit 3) |
-y, --yes | Skip the deletion confirmation prompt |
--json | Single key uses deleteObject and returns { message }; multiple keys use deleteObjects and return IDeletedObjectInfo[] |
Table columns: Key / Status. Status is DELETED or NOT_FOUND (the server silently skips non-existent objects in batch deletions).
tcb storage objects cp
Copies an object to a new location.
tcb storage objects cp <srcKey> <dstKey> -b <bucketId> [options]
| Option | Description |
|---|---|
-b, --bucket <bucketId> | Source bucket ID |
--dst-bucket <bucketId> | Destination bucket ID; defaults to the source bucket |
--copy-metadata <bool> | Whether to copy the source object's metadata; defaults to true. Only when false do --metadata / --user-metadata take effect |
--metadata <json> | System metadata JSON; merged with the source metadata. COS only recognizes cacheControl / mimetype / contentType |
--user-metadata <json> | User custom metadata JSON; fully replaces the destination user_metadata |
--upsert | Allow overwriting an existing object at the destination |
--json | Outputs the raw SDK return value (ICopyObjectHttpResult) |
Validation:
- Within the same bucket, identical source and destination keys without
--upsert→INVALID_PARAM. --metadata/--user-metadataare only effective when--copy-metadata false; passing them otherwise is rejected by the CLI.
tcb storage objects mv
Moves (renames) an object to a new location; the server performs copy + delete source atomically.
tcb storage objects mv <srcKey> <dstKey> -b <bucketId> [--dst-bucket <bucketId>] [--json]
Within the same bucket, identical source and destination keys are rejected locally with
INVALID_PARAM.
tcb storage objects sign
Generates signed URLs. Defaults to download signing; add --upload to switch to upload signing.
# Download signing
tcb storage objects sign <keys...> -b <bucketId> [--expires-in <seconds>] [--json]
# Upload signing
tcb storage objects sign <key> --upload -b <bucketId> [--upsert] [--json]
| Option | Description |
|---|---|
<keys...> | Download mode: 1-500 keys; upload mode: only 1 key |
--upload | Switches to upload signing mode |
--expires-in <seconds> | Expiration in seconds; >= 1, defaults to 600. Download mode only |
--upsert | Allow overwriting (x-upsert: true). Upload mode only |
--json | Download mode outputs [{ path, signedURL, error }]; upload mode outputs { url, token } |
Mutual-exclusion checks:
--uploadand--expires-inare mutually exclusive.- Passing
--upsertin download mode is rejected. --uploadaccepts only a single key per invocation.
Exit Codes
| Exit Code | Meaning |
|---|---|
3 INVALID_INPUT | Includes INVALID_PARAM / MISSING_PARAM / FLAT_CMD_NOT_AVAILABLE_IN_PG / ENV_NOT_PG |
See exit-codes for details.