CLI Storage

CLI: Storage

attach-s3-key

Kind: Write, destructive.

--project-id is the global flag and takes a vStorage project ID from list-projects, not the account's vServer project: the environment variable and the profile setting do not fill it, and the command exits 2 without the flag. Region is a vStorage region name such as HCM04, set only through --cli-input-json. Empty maps the global --region: hcm-3 to HCM04 and han-1 to HAN02. Needs --yes: the key loses its creator's rights on every bucket and acts as the service account, whose rights come only from bucket policies that name its principal (see ensure-service-account-principal), so a running app that uses the key can lose access. --service-account-id is the IAM service account ID as iam list-service-accounts prints it, without the sa- prefix. An attached key still lists the project's buckets and creates buckets whatever the bucket policies say. The data plane follows within 3 seconds. The server refuses with error code 114 (exit 1) and says why: the key is already attached with this service account, or with another one (checked first, so any attach of an attached key gives one of these), StatusCode=404 for an unknown service account, or S3 key not found. The call is sent once and never retried. If it fails with a 5xx or a network error, the message says the change may have happened: run list-s3-keys and read SubUserID, which is empty for an unrestricted key. A rerun that answers "already attached with this service account" means the first try took effect.

Flag	Type	Required
Region (via --cli-input-json only)	string
--project-id	string	yes
--user-key-id	string	yes
--service-account-id	string	yes

vngcloud storage attach-s3-key --project-id <project-id> --user-key-id <user-key-id> --service-account-id <service-account-id> --yes

copy-object

Kind: Write, destructive.

Copy one current object with native server-side CopyObject, retaining the source. Require explicit --source-bucket, --source-key, --bucket, --key, --s3-region, --s3-credentials-file and --replace --yes. Both buckets must belong to the same project and region. Read-only blocks copy. Concurrent writers can change the selected source or destination; diagnostic version IDs do not authorize cleanup. Provider metadata defaults apply without a lossless clone or encryption guarantee. Recorded HCM04 encrypted sources return 501; a copy can remain unencrypted despite destination bucket encryption. HAN02 encryption is unverified. A complete bounded result is required: HTTP 200 Error is not success. Inspect the destination before repeating an unconfirmed copy. GreenNode's exact size limit is unverified; AWS's 5 GB reference is not a measured GreenNode limit. No multipart, fallback, version-history clone, create-only copy, or move is provided. Output and queries expose accepted metadata only. Linux and macOS credential files are supported; no IAM login or ambient credentials are used.

Flag	Type	Required
--bucket	string	yes
--key	string	yes
--replace	bool	yes
--s3-credentials-file	string	yes
--s3-region	string	yes
--source-bucket	string	yes
--source-key	string	yes
--transfer-timeout	duration

vngcloud storage copy-object --s3-region HCM04 --s3-credentials-file ./storage.credentials --source-bucket app-files --source-key archives/bundle.bin --bucket app-backups --key archives/bundle.bin --replace --yes

create-bucket

Kind: Write.

--project-id is the global flag and takes a vStorage project ID from list-projects, not the account's vServer project: the environment variable and the profile setting do not fill it, and the command exits 2 without the flag. Region is a vStorage region name such as HCM04, set only through --cli-input-json. Empty maps the global --region: hcm-3 to HCM04 and han-1 to HAN02. Sends the console body for a bucket without object lock, then reads the bucket back and prints it. A name must be lowercase letters, digits, and hyphens; anything else the server refuses with error code 112. If the create fails in a way that may have reached the server, the message says the bucket may exist: check with get-bucket before running it again. --encryption enables server-managed default encryption before success, also on an existing bucket. Omission or --encryption=false does not disable encryption. Encryption applies to uploads only; objects stored before enabling stay unencrypted, and objects written while enabled stay encrypted after disabling. Create and enable are not atomic; delay uploads until success. BucketEncryptionIncomplete (exit 1) means the bucket exists but setup failed: run get-bucket-encryption, then put-bucket-encryption --enabled=true if needed after fixing the cause. Do not upload backups until a read confirms true.

Flag	Type	Required
Region (via --cli-input-json only)	string
--project-id	string	yes
--bucket	string	yes
--encryption	bool

vngcloud storage create-bucket --project-id <project-id> --bucket <bucket>

create-project

Kind: Write.

Region is a vStorage region name such as HCM04, set only through --cli-input-json. Empty maps the global --region: hcm-3 to HCM04 and han-1 to HAN02. Requires --name, --type, and --quota-gb. Buys a one-month package and charges the account balance at once; auto-renew is always off. Run quote-create-project first: --max-price must be at least the quote; default 0 buys nothing. The cap protects the quote, not the server's debit, because the API has no price lock. Sends one order and never retries. --no-wait skips readiness polling only. On NotSettled or PaymentRequired (exit 1), run storage list-projects in the same region and check pending orders in the console before trying again. Example: vngcloud storage create-project --region hcm-3 --name backups --type Gold --quota-gb 30 --max-price 30000. Prices are VND totals that include VAT; the API gives no VAT breakdown.

Flag	Type	Required
Region (via --cli-input-json only)	string
--name	string	yes
--type	string	yes
--quota-gb	int64	yes
--max-price	float64
--no-wait	bool

vngcloud storage create-project --region hcm-3 --name backups --type Gold --quota-gb 30 --max-price 30000

create-s3-key

Kind: Write.

--project-id is the global flag and takes a vStorage project ID from list-projects, not the account's vServer project: the environment variable and the profile setting do not fill it, and the command exits 2 without the flag. Region is a vStorage region name such as HCM04, set only through --cli-input-json. Empty maps the global --region: hcm-3 to HCM04 and han-1 to HAN02. Needs --secret-file <path>: the server returns the secret once, and the command writes it only to that file, at mode 0600, in the AWS shared credentials format ([default] with aws_access_key_id and aws_secret_access_key), which rclone and the AWS CLI read through AWS_SHARED_CREDENTIALS_FILE. The file holds no region or endpoint. The path must not exist, symlink included, and its directory must exist; both are checked before any request. The printed SecretKey is always [redacted] and SecretFile names the path. If writing the file fails, or the response holds no secret, the command deletes the new key and exits 1 with error code SecretFileFailed; if that delete also fails, the message names the key by its ID so it can be deleted with delete-s3-key. If the create fails in a way that may have reached the server, the message says a key may exist: list the keys and delete any UserKeyID you do not know. With --service-account-id <id> the command creates the key, attaches it to that service account, and only then writes the secret file, so a secret for an unrestricted key never reaches disk. --service-account-id is the IAM service account ID as iam list-service-accounts prints it, without the sa- prefix. It is checked before any request and needs no --yes, since the key is new. If the attach fails for any reason, a 5xx included, the command deletes the key, writes no file, and exits 1 with the attach's error code; if that delete also fails, the message names the key by its ID. The printed SubUserID stays empty because it comes from the create response, and ServiceAccountID names the account; list-s3-keys shows the attach as SubUserID. An attached key still lists the project's buckets and creates buckets whatever the bucket policies say. Set up one bucket in this order: create the bucket, create the service account, run ensure-service-account-principal, write a bucket policy that allows the PrincipalARN, then run this command with --service-account-id. Without the flag the key has the IAM user's rights on every bucket. A key not attached to a service account has the rights of the IAM user that made it on every bucket of the project. Make keys only with an IAM user scoped to vStorage. A project holds at most ten keys.

Flag	Type	Required
Region (via --cli-input-json only)	string
--project-id	string	yes
--secret-file	string	yes
--service-account-id	string

vngcloud storage create-s3-key --project-id <project-id> --secret-file <secret-file>

delete-bucket

Kind: Write, destructive.

--project-id is the global flag and takes a vStorage project ID from list-projects, not the account's vServer project: the environment variable and the profile setting do not fill it, and the command exits 2 without the flag. Region is a vStorage region name such as HCM04, set only through --cli-input-json. Empty maps the global --region: hcm-3 to HCM04 and han-1 to HAN02. Needs --yes: a deleted bucket cannot be restored. It reads the bucket first and refuses one that holds objects with error code BucketNotEmpty (exit 1), sending nothing; empty the bucket with an S3 client, then run it again. A null object count is refused the same way. There is no force option. The server deletes asynchronously, so the command then reads the bucket every second for up to 30 seconds and returns when it is gone; --no-wait skips the wait and returns once the server accepts the delete. If the bucket is still readable when the wait ends, the error code is NotSettled (exit 1): the delete was accepted, so do not repeat it, and check with get-bucket later.

Flag	Type	Required
Region (via --cli-input-json only)	string
--project-id	string	yes
--bucket	string	yes
--no-wait	bool

vngcloud storage delete-bucket --project-id <project-id> --bucket <bucket> --yes

delete-bucket-cors

Kind: Write.

--project-id is the global flag and takes a vStorage project ID from list-projects, not the account's vServer project: the environment variable and the profile setting do not fill it, and the command exits 2 without the flag. Region is a vStorage region name such as HCM04, set only through --cli-input-json. Empty maps the global --region: hcm-3 to HCM04 and han-1 to HAN02. Removes every CORS rule; a bucket with none also succeeds, so a repeat delete succeeds. It needs no --yes, since put-bucket-cors restores rules. A browser's next preflight is refused.

Flag	Type	Required
Region (via --cli-input-json only)	string
--project-id	string	yes
--bucket	string	yes

vngcloud storage delete-bucket-cors --project-id <project-id> --bucket <bucket>

delete-bucket-policy

Kind: Write.

--project-id is the global flag and takes a vStorage project ID from list-projects, not the account's vServer project: the environment variable and the profile setting do not fill it, and the command exits 2 without the flag. Region is a vStorage region name such as HCM04, set only through --cli-input-json. Empty maps the global --region: hcm-3 to HCM04 and han-1 to HAN02. Removes the bucket's policy; a bucket with no policy also succeeds, so a repeat delete succeeds. It needs no --yes, since put-bucket-policy restores a policy. After it, a key attached to a service account has no rights in the bucket. The data plane follows within about a second.

Flag	Type	Required
Region (via --cli-input-json only)	string
--project-id	string	yes
--bucket	string	yes

vngcloud storage delete-bucket-policy --project-id <project-id> --bucket <bucket>

delete-object

Kind: Write, destructive.

Require --yes and explicit --s3-region HCM04 or HAN02, --s3-credentials-file with a private [default] AWS-format access-key pair, --bucket and --key. Delete the current name unconditionally with one bodyless DELETE and no prior read, retry or confirmation request. Read-only from --read-only, VNGCLOUD_READ_ONLY or profile read_only blocks deletion before credentials. Ignore management region, project, auth and ambient S3 credentials; explicit --region and --project-id are refused. Linux and macOS only. No --cli-input-json, body, destination, --replace, version selector, precondition, MFA or retention bypass. --transfer-timeout defaults to 5m and accepts 1s through 1h. --output and --query select metadata only: Bucket, Key, DeleteMarker and VersionID. Echoed identifiers are redacted; absent or filtered DeleteMarker is JSON null and VersionID is empty. HTTP 204 confirms acceptance, not prior existence, permanent erasure, reclaimed quota or an empty bucket. No protection against concurrent writers: deletion can remove a new current object. Enabled versioning can add a delete marker and retain older versions; suspended versioning can remove the null version and add a marker while retaining numbered versions. Repetition can delete newly written data or add another marker. ObjectDeleteUnconfirmed exits 1 with fixed recovery: inspect the current key and version history before deciding whether to delete again. A post-success query or stdout failure says delete completed and do not retry, exits 1 and sends no second request. Requires s3:DeleteObject, without requiring a read or console grant in the client; recorded broader grants do not prove a minimal permission combination. HCM04 uses recorded deletion behavior; HAN02 relies on published S3 compatibility, not fresh live verification. Native create-only copy and move remain unavailable.

Flag	Type	Required
--bucket	string	yes
--key	string	yes
--s3-credentials-file	string	yes
--s3-region	string	yes
--transfer-timeout	duration

vngcloud storage delete-object --s3-region HCM04 --s3-credentials-file ./storage.credentials --bucket app-files --key archives/bundle.bin --yes

delete-project

Kind: Write, destructive.

--project-id is the global flag and takes a vStorage project ID from list-projects, not the account's vServer project: the environment variable and the profile setting do not fill it, and the command exits 2 without the flag. Region is a vStorage region name such as HCM04, set only through --cli-input-json. Empty maps the global --region: hcm-3 to HCM04 and han-1 to HAN02. Needs --yes. Refuses a project that still has buckets with ProjectNotEmpty (exit 1). Stop bucket writers first. The unused value is refunded to the balance. Sends one DELETE and never retries. --no-wait skips removal polling. On NotSettled (exit 1), list projects in the same region and inspect billing before another attempt.

Flag	Type	Required
Region (via --cli-input-json only)	string
--project-id	string	yes
--no-wait	bool

vngcloud storage delete-project --project-id <project-id> --yes

delete-s3-key

Kind: Write, destructive.

--project-id is the global flag and takes a vStorage project ID from list-projects, not the account's vServer project: the environment variable and the profile setting do not fill it, and the command exits 2 without the flag. Region is a vStorage region name such as HCM04, set only through --cli-input-json. Empty maps the global --region: hcm-3 to HCM04 and han-1 to HAN02. Needs --yes: a deleted key stops working at once and cannot be restored. The server answers success for a UserKeyID it does not know, and refuses a repeat delete of a deleted key with error code 114 (exit 1).

Flag	Type	Required
Region (via --cli-input-json only)	string
--project-id	string	yes
--user-key-id	string	yes

vngcloud storage delete-s3-key --project-id <project-id> --user-key-id <user-key-id> --yes

detach-s3-key

Kind: Write, destructive.

--project-id is the global flag and takes a vStorage project ID from list-projects, not the account's vServer project: the environment variable and the profile setting do not fill it, and the command exits 2 without the flag. Region is a vStorage region name such as HCM04, set only through --cli-input-json. Empty maps the global --region: hcm-3 to HCM04 and han-1 to HAN02. Needs --yes: the key has its creator's rights on every bucket of the project again, at once. The server refuses a key that is not attached with error code 114 (exit 1) and the message This S3 key is not attached to any service account.; an unknown key is S3 key not found. The call is sent once and never retried. If it fails with a 5xx or a network error, the message says the change may have happened: run list-s3-keys and read SubUserID. A rerun that answers "not attached" means the first try took effect.

Flag	Type	Required
Region (via --cli-input-json only)	string
--project-id	string	yes
--user-key-id	string	yes

vngcloud storage detach-s3-key --project-id <project-id> --user-key-id <user-key-id> --yes

ensure-service-account-principal

Kind: Write.

--project-id is the global flag and takes a vStorage project ID from list-projects, not the account's vServer project: the environment variable and the profile setting do not fill it, and the command exits 2 without the flag. Region is a vStorage region name such as HCM04, set only through --cli-input-json. Empty maps the global --region: hcm-3 to HCM04 and han-1 to HAN02. --service-account-id is the IAM service account ID as iam list-service-accounts prints it, without the sa- prefix. Makes the service account's storage sub-user if it does not exist and prints SubUserID and PrincipalARN, the value a bucket policy puts in its Principal. It is a write, so a read-only profile refuses it with exit 2 before any request. It needs no --yes: a repeat returns the same sub-user, and the sub-user costs nothing and has no rights until a bucket policy names it. The console API cannot delete a sub-user. It is named from the service account's name, not its ID, so a new service account with the name of a deleted one may get the same principal and inherit any bucket policy that still names it: remove a service account from its bucket policies before deleting it. A response whose sub-user is not a service account's (no :sa- segment) is refused with error code NotServiceAccountPrincipal (exit 1) and prints nothing, so an IAM user's own principal never reaches a policy.

Flag	Type	Required
Region (via --cli-input-json only)	string
--project-id	string	yes
--service-account-id	string	yes

vngcloud storage ensure-service-account-principal --project-id <project-id> --service-account-id <service-account-id>

get-bucket

Kind: Read.

--project-id is the global flag and takes a vStorage project ID from list-projects, not the account's vServer project: the environment variable and the profile setting do not fill it, and the command exits 2 without the flag. Region is a vStorage region name such as HCM04, set only through --cli-input-json. Empty maps the global --region: hcm-3 to HCM04 and han-1 to HAN02.

Flag	Type	Required
Region (via --cli-input-json only)	string
--project-id	string	yes
--bucket	string	yes

vngcloud storage get-bucket --project-id <project-id> --bucket <bucket>

get-bucket-cors

Kind: Read.

--project-id is the global flag and takes a vStorage project ID from list-projects, not the account's vServer project: the environment variable and the profile setting do not fill it, and the command exits 2 without the flag. Region is a vStorage region name such as HCM04, set only through --cli-input-json. Empty maps the global --region: hcm-3 to HCM04 and han-1 to HAN02. Prints {"Rules": [...]}, and an empty list for a bucket with no rules. Each rule has AllowedOrigins and AllowedMethods (GET, PUT, POST, DELETE, HEAD), and optionally AllowedHeaders and MaxAgeSeconds. ExposedHeaders is read-only: the SDK never sends it, so rules put through the CLI read back with it empty.

Flag	Type	Required
Region (via --cli-input-json only)	string
--project-id	string	yes
--bucket	string	yes

vngcloud storage get-bucket-cors --project-id <project-id> --bucket <bucket> --query Rules

get-bucket-encryption

Kind: Read.

--project-id is the global flag and takes a vStorage project ID from list-projects, not the account's vServer project: the environment variable and the profile setting do not fill it, and the command exits 2 without the flag. Region is a vStorage region name such as HCM04, set only through --cli-input-json. Empty maps the global --region: hcm-3 to HCM04 and han-1 to HAN02. Reads server-managed default encryption and prints Enabled. --bucket names the bucket; JSON uses BucketName.

Flag	Type	Required
Region (via --cli-input-json only)	string
--project-id	string	yes
BucketName (via --cli-input-json only)	string
--bucket	string	yes

vngcloud storage get-bucket-encryption --project-id <project-id> --bucket <bucket>

get-bucket-policy

Kind: Read.

--project-id is the global flag and takes a vStorage project ID from list-projects, not the account's vServer project: the environment variable and the profile setting do not fill it, and the command exits 2 without the flag. Region is a vStorage region name such as HCM04, set only through --cli-input-json. Empty maps the global --region: hcm-3 to HCM04 and han-1 to HAN02. Prints {"Policy": "<document as a string>"}, and an empty string for a bucket with no policy. The server re-serializes the document, so compare decoded documents, not bytes. The policy template, which grants object work and nothing on the bucket's settings, is on the SDK page Bucket policy.

Flag	Type	Required
Region (via --cli-input-json only)	string
--project-id	string	yes
--bucket	string	yes

vngcloud storage get-bucket-policy --project-id <project-id> --bucket <bucket>

get-bucket-versioning

Kind: Read.

--project-id is the global flag and takes a vStorage project ID from list-projects, not the account's vServer project: the environment variable and the profile setting do not fill it, and the command exits 2 without the flag. Region is a vStorage region name such as HCM04, set only through --cli-input-json. Empty maps the global --region: hcm-3 to HCM04 and han-1 to HAN02. Prints Enabled and Status, the server's Off, Enabled, or Suspended. A bucket reads Off only until the first put-bucket-versioning; versioning never returns to Off once enabled, and a suspended bucket reads Suspended.

Flag	Type	Required
Region (via --cli-input-json only)	string
--project-id	string	yes
--bucket	string	yes

vngcloud storage get-bucket-versioning --project-id <project-id> --bucket <bucket>

get-object

Kind: Read, local replacement requires --yes.

Require explicit --s3-region HCM04 or HAN02 and --s3-credentials-file with a private [default] AWS-format access-key pair. Ignore management region, project, auth and ambient S3 credentials. Explicit --region and --project-id are refused. Linux and macOS only. No --cli-input-json, stdin, stdout bytes, '-' or file:// paths. --output and --query select metadata only: Bucket, Key, ContentLength, SHA256 and ETag; downloads add Destination. The whole transfer deadline defaults to 5m; --transfer-timeout accepts 1s through 1h. --replace requires --yes; --yes alone preserves the default protection. No automatic retry follows a failed transfer or completed-transfer output failure. Download to required --destination in a trusted existing directory. Default publication never clobbers an occupied path. --replace --yes atomically replaces a regular local file only. Read-only permits download. --max-download-bytes defaults to 5000000000, accepts positive values through 9223372036854775806, and never permits unlimited downloads. Publish only after clean EOF, sync and close. Published cleanup errors preserve the completed file and name local cleanup. ETag is opaque; SHA256 describes received bytes, not an independent remote checksum.

Flag	Type	Required
--bucket	string	yes
--destination	string	yes
--key	string	yes
--max-download-bytes	int64
--replace	bool
--s3-credentials-file	string	yes
--s3-region	string	yes
--transfer-timeout	duration

vngcloud storage get-object --s3-region HCM04 --s3-credentials-file ./storage.credentials --bucket app-files --key archives/bundle.bin --destination ./downloaded.bin

get-project-auto-renew

Kind: Read.

--project-id is the global flag and takes a vStorage project ID from list-projects, not the account's vServer project: the environment variable and the profile setting do not fill it, and the command exits 2 without the flag. Region is a vStorage region name such as HCM04, set only through --cli-input-json. Empty maps the global --region: hcm-3 to HCM04 and han-1 to HAN02. Reads joined project and billing renewal state. --period-months previews 1, 3, 6, or 12 months without changing the configured period. The quoted renewal charge is today's monthly create quote times preview months, VAT included. NextCharge is an estimate for the configured period, not a promised charge date or amount. Pricing failure succeeds with PriceStatus Unavailable and null prices. Tables show unavailable prices and none scheduled when renewal is off.

Flag	Type	Required
--project-id	string	yes
Region (via --cli-input-json only)	string
--period-months	*int

vngcloud storage get-project-auto-renew --region hcm-3 --project-id project-1

head-object

Kind: Read.

Require explicit --s3-region HCM04 or HAN02 and --s3-credentials-file with a private [default] AWS-format access-key pair. Ignore management region, project, auth and ambient S3 credentials. Explicit --region and --project-id are refused. Linux and macOS only. Read-only permits both reads. No --cli-input-json, object body, local destination, version selector, subprocess, or automatic retry. --output and --query select accepted metadata only, never object content. --transfer-timeout defaults to 5m and accepts 1s through 1h. A post-success query or stdout failure says the operation completed and exits 1 without another request. Both regions rely on published S3 compatibility; HCM04 has additional recorded listing evidence. Detailed optional fields and HAN02 V2 pagination remain standards-based assumptions. Require --bucket and --key. Send HEAD only, with no GET fallback. Output contains Bucket, Key, ContentLength, ETag, ContentType, LastModified, Metadata, VersionID and ServerSideEncryption. ContentLength -1 means absent; zero means empty. Optional unsafe, unsupported or oversize metadata is omitted; absent LastModified is null and Metadata is a non-nil map with lowercase names and no x-amz-meta- prefix. VersionID and encryption fields are observations, not locks or attestations; version selection is unavailable. Requires s3:GetObject. Preserve returned 403 as failure and 404 as not found; never infer absence from 403.

Flag	Type	Required
--bucket	string	yes
--key	string	yes
--s3-credentials-file	string	yes
--s3-region	string	yes
--transfer-timeout	duration

vngcloud storage head-object --s3-region HCM04 --s3-credentials-file ./storage.credentials --bucket app-files --key archives/bundle.bin

list-buckets

Kind: Read.

--project-id is the global flag and takes a vStorage project ID from list-projects, not the account's vServer project: the environment variable and the profile setting do not fill it, and the command exits 2 without the flag. Region is a vStorage region name such as HCM04, set only through --cli-input-json. Empty maps the global --region: hcm-3 to HCM04 and han-1 to HAN02. The API returns every bucket in one call; a response with more fails instead of printing a partial list.

Flag	Type	Required
Region (via --cli-input-json only)	string
--project-id	string	yes

vngcloud storage list-buckets --project-id <project-id>

list-objects

Kind: Read.

Require explicit --s3-region HCM04 or HAN02 and --s3-credentials-file with a private [default] AWS-format access-key pair. Ignore management region, project, auth and ambient S3 credentials. Explicit --region and --project-id are refused. Linux and macOS only. Read-only permits both reads. No --cli-input-json, object body, local destination, version selector, subprocess, or automatic retry. --output and --query select accepted metadata only, never object content. --transfer-timeout defaults to 5m and accepts 1s through 1h. A post-success query or stdout failure says the operation completed and exits 1 without another request. Both regions rely on published S3 compatibility; HCM04 has additional recorded listing evidence. Detailed optional fields and HAN02 V2 pagination remain standards-based assumptions. Return one ListObjectsV2 page (JSON keeps the envelope; table/text shows item rows, with explicit queries for page fields): Items, CommonPrefixes, MaxKeys, IsTruncated, NextContinuationToken. Require --bucket; --prefix matches exact UTF-8 bytes up to 1024 bytes, --delimiter is empty or '/', and --continuation-token is opaque UTF-8 up to 8 KiB without control bytes. --max-keys defaults to 1000 and accepts 1 through 1000; it bounds Items plus CommonPrefixes, not a total. Object rows contain Key, Size, ETag, LastModified and StorageClass. Common prefixes are groups, not objects. Optional metadata can be omitted; absent LastModified is null. Use IsTruncated and the returned token with unchanged bucket, prefix and delimiter for the next explicit invocation; even a short page can continue. No --all, automatic pagination, total count, or cross-page snapshot: concurrent changes can cause omissions or repeats. Requires s3:ListBucket on the bucket.

Flag	Type	Required
--bucket	string	yes
--continuation-token	string
--delimiter	string
--max-keys	int
--prefix	string
--s3-credentials-file	string	yes
--s3-region	string	yes
--transfer-timeout	duration

vngcloud storage list-objects --s3-region HCM04 --s3-credentials-file ./storage.credentials --bucket app-files --prefix archives/ --delimiter / --max-keys 100

list-project-types

Kind: Read.

Region is a vStorage region name such as HCM04, set only through --cli-input-json. Empty maps the global --region: hcm-3 to HCM04 and han-1 to HAN02. Prices are VND per month for one month. Shows each type's monthly price at the region's minimum quota, plus the minimum and maximum quota in GB. Prices are VND totals that include VAT; the API gives no VAT breakdown.

Flag	Type	Required
Region (via --cli-input-json only)	string

vngcloud storage list-project-types

list-projects

Kind: Read.

Region is a vStorage region name such as HCM04, set only through --cli-input-json. Empty maps the global --region: hcm-3 to HCM04 and han-1 to HAN02. A vStorage project is a paid package, so the list is empty until one is bought with create-project or in the console. Its ID is the value for --project-id in the bucket commands.

Flag	Type	Required
Region (via --cli-input-json only)	string

vngcloud storage list-projects

list-regions

Kind: Read.

Lists the regions vStorage serves, with their S3 hosts. Needs no project.

No fields.

vngcloud storage list-regions

list-s3-keys

Kind: Read.

--project-id is the global flag and takes a vStorage project ID from list-projects, not the account's vServer project: the environment variable and the profile setting do not fill it, and the command exits 2 without the flag. Region is a vStorage region name such as HCM04, set only through --cli-input-json. Empty maps the global --region: hcm-3 to HCM04 and han-1 to HAN02. Lists the project's keys by UserKeyID and AccessKey. No secret is listed or printed. A key not attached to a service account has the rights of the IAM user that made it on every bucket of the project. Make keys only with an IAM user scoped to vStorage. A project holds at most ten keys.

Flag	Type	Required
Region (via --cli-input-json only)	string
--project-id	string	yes

vngcloud storage list-s3-keys --project-id <project-id>

list-storage-prices

Kind: Read.

Returns Items and Metadata for account-scoped monthly quotes. Unknown costs remain null in JSON and print unknown in table/text. Price per GB is the effective rate at the quoted size, not a marginal tariff. Table/text notes print on stderr. With --allow-partial, incomplete output prints before the error and exits 1, even with --query. Sort before queries with --sort-by name, monthly-price, or unit-price and --descending. Unknown numeric values sort last in either direction. Default MaxRequests is 500 (range 1..2000). Catalog reads and quotes run serially with a ten-minute child deadline and at least 500 ms between request starts. Quotes reserve no future price or capacity. QuotaGB 0 uses the monthly package minimum. Type is an exact catalog name. Region is a JSON-only storage region override; the global --region still configures vServer. The default for hcm-3 is HCM04. PAYG, egress, and request charges are excluded. Published egress rules conflict, so those costs remain unknown.

Flag	Type	Required
Region (via --cli-input-json only)	string
--type	string
--quota-gb	int64
--max-requests	int
--allow-partial	bool
--descending	bool
--sort-by	string

vngcloud storage list-storage-prices

put-bucket-cors

Kind: Write.

--project-id is the global flag and takes a vStorage project ID from list-projects, not the account's vServer project: the environment variable and the profile setting do not fill it, and the command exits 2 without the flag. Region is a vStorage region name such as HCM04, set only through --cli-input-json. Empty maps the global --region: hcm-3 to HCM04 and han-1 to HAN02. Rules come through --cli-input-json, inline or file://<path>, and replace every rule of the bucket. Each rule has AllowedOrigins and AllowedMethods (GET, PUT, POST, DELETE, HEAD), and optionally AllowedHeaders and MaxAgeSeconds. ExposedHeaders is read-only: the SDK never sends it, so rules put through the CLI read back with it empty. The rules are checked before any request: an empty list, a rule with no origin or no method, an origin with more than one *, an unknown method, or a negative MaxAgeSeconds exits 2. The server's own refusals are error code 114 or 400 (exit 1), and a failed put keeps the previous rules. It needs no --yes, since another put or a delete-bucket-cors undoes it. To remove every rule, run delete-bucket-cors.

Flag	Type	Required
Region (via --cli-input-json only)	string
--project-id	string	yes
--bucket	string	yes
Rules (via --cli-input-json only)	[]storage.CORSRule	yes

vngcloud storage put-bucket-cors --project-id <project-id> --bucket <bucket> --cli-input-json '{"Rules":[{"AllowedOrigins":["<origin>"],"AllowedMethods":["GET"]}]}'

put-bucket-encryption

Kind: Write.

--project-id is the global flag and takes a vStorage project ID from list-projects, not the account's vServer project: the environment variable and the profile setting do not fill it, and the command exits 2 without the flag. Region is a vStorage region name such as HCM04, set only through --cli-input-json. Empty maps the global --region: hcm-3 to HCM04 and han-1 to HAN02. Sets server-managed default encryption. Needs --enabled=true or --enabled=false; omitted or null JSON Enabled exits 2 before any request. --bucket names the bucket; JSON uses BucketName. Encryption applies to uploads only; objects stored before enabling stay unencrypted, and objects written while enabled stay encrypted after disabling. S3 copy of an encrypted object fails with 501 NotImplemented, so copy, move, and rename do not work for encrypted data. Confirms the state with one read. On NotSettled (exit 1), read get-bucket-encryption before writing again. Needs no --yes or prompt. A read-only profile refuses the write before any request.

Flag	Type	Required
Region (via --cli-input-json only)	string
--project-id	string	yes
BucketName (via --cli-input-json only)	string	yes
--enabled	*bool	yes
--bucket	string	yes

vngcloud storage put-bucket-encryption --project-id <project-id> --bucket <bucket> --enabled=true

put-bucket-policy

Kind: Write.

--project-id is the global flag and takes a vStorage project ID from list-projects, not the account's vServer project: the environment variable and the profile setting do not fill it, and the command exits 2 without the flag. Region is a vStorage region name such as HCM04, set only through --cli-input-json. Empty maps the global --region: hcm-3 to HCM04 and han-1 to HAN02. --policy takes the document as JSON text or as file://<path>. A put replaces the whole policy. A document that is not a JSON object with a non-empty Statement array is refused with exit 2 before any request. The server refuses a document it cannot parse with error code 400 or 114 (exit 1). The server does not check principals: a policy that names no real principal is accepted and grants nothing, so copy PrincipalARN from ensure-service-account-principal and check access with the attached key. Needs --yes when an Allow statement's Principal contains * (the string, or the AWS string or list): that can let anyone on the internet use the bucket as the statement allows. A Deny statement with * needs no --yes. Other policies need no --yes, since a repeat put or a delete-bucket-policy undoes them. The data plane follows within about a second. The policy template, which grants object work and nothing on the bucket's settings, is on the SDK page Bucket policy.

Flag	Type	Required
Region (via --cli-input-json only)	string
--project-id	string	yes
--bucket	string	yes
--policy	string	yes

vngcloud storage put-bucket-policy --project-id <project-id> --bucket <bucket> --policy file://policy.json

put-bucket-versioning

Kind: Write.

--project-id is the global flag and takes a vStorage project ID from list-projects, not the account's vServer project: the environment variable and the profile setting do not fill it, and the command exits 2 without the flag. Region is a vStorage region name such as HCM04, set only through --cli-input-json. Empty maps the global --region: hcm-3 to HCM04 and han-1 to HAN02. Needs --enabled=true or --enabled=false; without it the command exits 2 before any request, so it never suspends versioning by default. false means Suspended, not Off: the stored versions stay. While versioning is on, overwrites and deletes keep old versions, which use quota and make delete-bucket refuse the bucket. It needs no --yes, since another put reverses it. The change shows on the next get-bucket-versioning.

Flag	Type	Required
Region (via --cli-input-json only)	string
--project-id	string	yes
--bucket	string	yes
--enabled	*bool	yes

vngcloud storage put-bucket-versioning --project-id <project-id> --bucket <bucket> --enabled=true

put-object

Kind: Write, replacement requires --yes.

Require explicit --s3-region HCM04 or HAN02 and --s3-credentials-file with a private [default] AWS-format access-key pair. Ignore management region, project, auth and ambient S3 credentials. Explicit --region and --project-id are refused. Linux and macOS only. No --cli-input-json, stdin, stdout bytes, '-' or file:// paths. --output and --query select metadata only: Bucket, Key, ContentLength, SHA256 and ETag; downloads add Destination. The whole transfer deadline defaults to 5m; --transfer-timeout accepts 1s through 1h. --replace requires --yes; --yes alone preserves the default protection. No automatic retry follows a failed transfer or completed-transfer output failure. Upload one completed regular file through required --body, with a 5000000000-byte cap and private snapshot disk use. Default PUT creates only and refuses an existing key. HAN02 create-only PUT is unavailable; HAN02 permits explicit --replace --yes. Read-only refuses upload before credentials or body access. An unconfirmed write requires download and byte-length/SHA256 comparison before retrying. ETag is opaque; SHA256 describes local bytes, not verified remote content.

Flag	Type	Required
--body	string	yes
--bucket	string	yes
--key	string	yes
--replace	bool
--s3-credentials-file	string	yes
--s3-region	string	yes
--transfer-timeout	duration

vngcloud storage put-object --s3-region HCM04 --s3-credentials-file ./storage.credentials --bucket app-files --key archives/bundle.bin --body ./bundle.bin

put-project-auto-renew

Kind: Write.

--project-id is the global flag and takes a vStorage project ID from list-projects, not the account's vServer project: the environment variable and the profile setting do not fill it, and the command exits 2 without the flag. Region is a vStorage region name such as HCM04, set only through --cli-input-json. Empty maps the global --region: hcm-3 to HCM04 and han-1 to HAN02. Requires explicit --enabled=true or --enabled=false, or a non-null JSON Enabled boolean. Enabling authorizes repeated future charges until disabled. --period-months accepts 1, 3, 6, or 12; omission selects one month when off or keeps the configured period when on. --max-price checks today's estimated renewal charge: monthly quote times months, VAT included. The cap is required for enable and period changes; an unchanged setting needs no new cap. The cap is not saved for later renewals and is not a lifetime spending limit. Disable needs no price or quote; omit --period-months when disabling. Disable does not cancel a charge already in progress. Read-only profiles refuse before any request. Sends one PUT and never retries or prompts. No --yes is required. On NotSettled (exit 1), run get-project-auto-renew and reconcile before a new deliberate setting. AutoRenewRejected, PriceAboveMax, Unpriced, and API failures exit 1; invalid input and read-only exit 2; NotFound exits 4. Another actor can change the setting after confirmation. Read get-project-auto-renew before choosing a cap. Example caps are illustrative. Disable with vngcloud storage put-project-auto-renew --region hcm-3 --project-id project-1 --enabled=false.

Flag	Type	Required
--project-id	string	yes
Region (via --cli-input-json only)	string
--enabled	*bool	yes
--period-months	*int
--max-price	float64

vngcloud storage put-project-auto-renew --region hcm-3 --project-id project-1 --enabled=true --period-months 1 --max-price 30000

quote-create-project

Kind: Read.

Region is a vStorage region name such as HCM04, set only through --cli-input-json. Empty maps the global --region: hcm-3 to HCM04 and han-1 to HAN02. Prices are VND per month for one month. quote-create-project --type Gold --quota-gb 30 prices a package without ordering. The quota must be within the region's limits. The type is the catalog Name, such as Gold or Instant-Archive-2. Name, MaxPrice, and NoWait apply only to purchase and are ignored in JSON input. Example: vngcloud storage quote-create-project --region hcm-3 --type Gold --quota-gb 30. Prices are VND totals that include VAT; the API gives no VAT breakdown.

Flag	Type	Required
Region (via --cli-input-json only)	string
Name (via --cli-input-json only)	string
--type	string	yes
--quota-gb	int64	yes
MaxPrice (via --cli-input-json only)	float64
NoWait (via --cli-input-json only)	bool

vngcloud storage quote-create-project --type <type> --quota-gb <quota-gb>