CLI

CLI

vngcloud <service> <operation> [flags] calls one SDK operation, listed below by service. vngcloud configure prompts for a profile's region and credentials, vngcloud configure set|get|list scripts the same, and vngcloud version (or --version, -v) prints the version.

Services

• Backup
• Billing
• CDN
• Compute
• ContainerRegistry
• DNS
• GlobalLoadBalancer
• IAM
• LoadBalancer
• Monitor
• Network
• Portal
• Pricing
• Project
• Storage
• Tagging
• VKS
• Volume

To find the IDs compute create-server and compute quote-create-server take, see IDs for Create Server.

Global flags

Flag	Meaning
--profile	Profile to use
--region	Region to use
--project-id	Project ID to use
--output	json, table, or text; default from the profile's output, else json
--query	JMESPath expression to filter output
--yes	Confirm a destructive operation
--debug	Log requests to stderr
--read-only	Refuse every write command

--query

Storage object commands query accepted metadata only and never print object bytes. They require explicit S3 region and credentials, reject explicit management --region and --project-id, and do not load IAM credentials or caches. See Storage.

Every list command prints a JSON object whose rows are under Items, with any page fields such as Page and TotalItem beside it, so a --query for a list starts with Items[...]: --query "Items[].Name". --output table and --output text show the rows of Items without the wrapper.

Storage list-objects returns one page with Items, CommonPrefixes, MaxKeys, IsTruncated, and NextContinuationToken. MaxKeys bounds the combined entries and is not a total. Table/text output shows item rows; query page fields explicitly or use JSON to retain the full envelope. Continue only with IsTruncated and its opaque token under unchanged filters. No automatic pagination or cross-page snapshot is provided. See Storage.

Storage copy-object uses --replace --yes for one native server-side copy, retaining the source. --output and --query expose only accepted ETag, LastModified, VersionID, SourceVersionID, and ServerSideEncryption, plus credential-redacted SourceBucket, SourceKey, Bucket, and Key. Unsafe or absent timestamps stay JSON null; accepted timestamps are UTC. Controls are escaped across formats and queries. No object bytes, content length, or local checksum are reported. See Storage and Storage Object Copy.

--cli-input-json

Every operation command except storage put-object and storage get-object, storage list-objects, storage head-object, storage delete-object, and storage copy-object also accepts --cli-input-json '<json>' or --cli-input-json file://input.json: a JSON object whose keys are that operation's Input fields, matched by their exact, case-sensitive Go name (ServerID, never serverid or serverID). A flag given on the same command line is applied after it and wins for that field. Trailing data after the JSON value, and a key that names no field, are both usage errors.

Exit codes

Code	Meaning
0	Success
1	API or network error, or a canceled command
2	Usage or config error: bad flags, a missing --yes, a read-only refusal, a missing region, or an ambiguous project
3	No credentials, a login failure, or a 401 (retried once, except on a toggle write or native object operation, which is sent only once)
4	Not found

Error classes

A failed command prints one JSON line to stderr:

{"error":{"code":"NotFound","message":"server not found","status":404,"operation":"compute.GetServer"}}

status and operation appear only for an API error, whose code is the API's own code, or a status-derived fallback code when the API gives none. Every other error names one class: InvalidUsage, ReadOnly, InvalidConfig, NoCredentials, LoginFailed, ServiceAccountLoginFailed, TokenCacheFailed, RequestFailed, QueryFailed, PageFormat (a public page, such as the CDN IP range FAQ, no longer matches the shape its parser expects; see CDN), UnexpectedStatus (a vMonitor check has a status the SDK does not know, so nothing was sent, a network enable-vpc-private-dns read a VPC dnsStatus it does not know how to act on, so nothing was sent, a compute start-server, stop-server, reboot-server, or resize-server read a server status that call does not act on, or a volume resize-volume read a volume Status other than AVAILABLE or IN-USE, or a CDN write found an unknown CDN status; see Compute, Volume, and CDN), StatusUnconfirmed (a vMonitor or CDN toggle may have landed but a read did not confirm it; see Monitor and CDN), ZoneBusy (a vDNS zone stayed busy past the wait before a write, so nothing was sent), WriteFailed (a vDNS write went to status ERROR, a network create-security-group's post-create wait saw the group reach ERROR, a compute create-server, delete-server, start-server, stop-server, reboot-server, or resize-server whose own post-write wait saw the server reach ERROR, or a volume create-volume, delete-volume, attach-volume, detach-volume, or resize-volume whose own post-write wait saw the volume reach ERROR; see Network, Compute, and Volume), NotSettled (a vDNS write was accepted but did not settle within the wait, a network create-security-group's or update-security-group's wait ran out of time: a create must not be sent again, since a repeat risks a second group, but an update may be sent again, since its PUT always resends the whole resolved group rather than making a new one, or a compute update-server-group's confirm read after its PUT succeeded failed to come back: the update itself already landed and may be sent again the same way; see Compute), or an iam create-policy or update-policy whose write reached the server but the read to confirm it failed: create-policy must not be sent again, since a repeat risks a second policy, but update-policy may be sent again, since its PUT always resends the whole resolved policy rather than making a new one; see IAM, or an iam create-group or update-group whose write reached the server but the read to confirm it failed: create-group must not be sent again, since a repeat risks a second group, but update-group may be sent again, since its own write always resends the whole resolved group rather than making a new one; see IAM), a compute create-server, delete-server, start-server, stop-server, or reboot-server whose wait ran out of time or otherwise failed to read back: create-server must not be sent again, since the server exists, but every other one of these reads first and is safe to run again (see Compute), or a compute resize-server whose wait ran out of time or otherwise failed to read back: check get-server rather than repeating this paid write, since a repeat risks a second charge (see Compute), or a volume create-volume, delete-volume, attach-volume, or detach-volume whose wait ran out of time or otherwise failed to read back: create-volume must not be sent again, since the volume exists, but every other one of these reads first and is safe to run again; see Volume), or a volume resize-volume whose wait ran out of time or otherwise failed to read back: check get-volume rather than repeating this paid write, since a repeat risks a second charge; see Volume, or a network ACL rules or subnets PUT, sent once with no retry, failed in a way that may already have reached the server, a 5xx, a network error, or a timeout: the write is not resent automatically, so read the ACL first before trying the command again; see Network), or a tagging tag-resource or untag-resource whose PUT reached the server but the read to confirm it failed or came back mismatched: the write already replaced the resource's user tags, so read them again before writing once more rather than repeating the command blind; see Tagging), VolumeInUse (a volume delete-volume was refused because a pre-delete read showed the volume attached to a server, before any request), BootVolume (a volume detach-volume targeted a server's own boot volume, before any request), ServerRunning (a volume detach-volume targeted a server that was not STOPPED without --allow-running, before any request; see Volume), OTPRejected (create-channel's or update-channel's own OTP validate step got a wrong or expired code, so no create or update was sent), PriceAboveMax (create-log-project's, a compute create-server's or resize-server's, or a volume create-volume's or resize-volume's own quote priced its order above --max-price, so nothing was sent or ordered), Unpriced (the same paid writes, when the quote is 0: refused whatever --max-price says, so nothing was sent or ordered), SelfChange (an iam write refused because its target is the caller itself, before any request), PrivilegedChange (an iam write refused because its target holds, or would gain, an IAM write right, before any request), ManagedPolicy (an iam update-policy or delete-policy targeted a GreenNode-managed policy, before any request), SystemTag (a tagging tag-resource or untag-resource refused because --key names a system tag, either its vng. prefix or an existing system tag the pre-write read found, so nothing was sent; see Tagging), SystemSecurityGroup (a network update-security-group or delete-security-group targeted a project's system group, so nothing was sent; see Network), SecurityGroupInUse (a network delete-security-group was refused because the group has servers attached or the server itself refused it as in use), ServerGroupInUse (a compute delete-server-group was refused because the group has servers attached, found by a pre-delete list scan, or the server itself refused it as in use; see Compute), ResourceInUse (a network delete-vpc, delete-subnet, delete-route-table, or delete-network-acl was refused because a pre-write read showed it still in use, such as a VPC with subnets, a subnet with servers, a route table a subnet still names, or an ACL a subnet is still associated with, or because the server's own refusal named it in use, including a VPC delete the server keeps refusing with "contains the subnet" for several minutes after that subnet's own delete, or an iam delete-policy targeted a policy still attached to a group, an IAM user, or a service account, or an iam delete-group targeted a group with a member or an attached policy, before any request; see Network, IAM), DefaultResource (a network delete-route-table targeted a VPC's main route table while a subnet names no route table of its own and so relies on it, though the server itself deletes a main table once nothing relies on it; or a write targeted a project's default network ACL or one of an ACL's own default rules), ResourceBusy (a CDN write found the CDN changing, or a network add-route, remove-route, or a network ACL rule or subnet write read a table or ACL that was not ACTIVE and stayed that way past the wait before the write, or saw it change before the send, so nothing was sent; or a network ACL rules or subnets PUT, or a delete-network-acl DELETE, sent once with no retry landed in the ACL's own busy window and got the server's own busy 400 back, which changed nothing, so the command can be run again; see Network), RepositoryNotEmpty (a containerregistry delete-repository was refused because a pre-delete read showed the repository still holds images; see ContainerRegistry), BucketNotEmpty (a storage delete-bucket was refused because a pre-delete read showed the bucket holds objects, so nothing was sent; see Storage), UserNotFound (a containerregistry create-user's own create succeeded but a follow-up list could not confirm the new user by name; the new secret is still written to --secret-file either way; see ContainerRegistry), SecretFileFailed (create-ssh-key's, create-user's, or storage create-s3-key's own create succeeded but writing --secret-file failed afterward, so the CLI deleted the new key or user; see Compute, ContainerRegistry, and Storage), or NotFound (a not-found result that never became an *APIError, such as monitor.GetChannel's page walk finding no matching ID; a real 404 already carries code NotFound through the API error case above). For WriteFailed, NotSettled, and UserNotFound the CLI also prints the Output on stdout; see DNS, Network, CDN, ContainerRegistry, ContainerRegistry, and Tagging. UnexpectedStatus, StatusUnconfirmed, ZoneBusy, WriteFailed, NotSettled, OTPRejected, PriceAboveMax, Unpriced, SelfChange, PrivilegedChange, ManagedPolicy, SystemSecurityGroup, SecurityGroupInUse, ServerGroupInUse, ResourceInUse, DefaultResource, ResourceBusy, RepositoryNotEmpty, BucketNotEmpty, UserNotFound, SecretFileFailed, SystemTag, VolumeInUse, BootVolume, and ServerRunning all exit 1.

ObjectDeleteUnconfirmed means DELETE may have removed the current name; inspect the current key and version history before deciding whether to delete again. It exits 1 ahead of wrapped auth, not-found or context errors. Confirmed deletion followed by metadata output failure also exits 1 and says do not retry.

ObjectCopyUnconfirmed means the copy may have replaced the destination; inspect the destination before deciding whether to repeat the copy. HTTP 200 Error, malformed results, response loss, or a timeout after possible dispatch cannot trigger a retry or source deletion. It exits 1 ahead of wrapped auth, not-found or context errors. A query or stdout failure after confirmed success says copy completed and do not retry, exits 1, and sends no second request. An unconditional rerun can replace another writer's object or create another version.

ObjectWriteUnconfirmed means a PUT may have stored the object; download to a fresh path and compare length and SHA256 before retrying. ObjectExists means create-only PUT refused an existing key. ObjectWriteUnconfirmed and ObjectExists exit 1. Completed-transfer metadata output and local cleanup failures also exit 1 and must not cause a retry.

Read-only

Read-only refuses every write command before any request. Any of these turns it on, and none can turn it off: --read-only; VNGCLOUD_READ_ONLY set to 1 or true; the profile's own read_only config key set to 1 or true (read_only = 1 in the config file).

configure

vngcloud configure keeps its IAM-user prompt order; the table also includes noninteractive keys. configure set <key> <value>, configure get <key>, and configure list script the same file edits and reads.

Key	File
region	config
project_id	config
output	config
read_only	config
root_email	credentials
username	credentials
password	credentials
totp_secret	credentials
vcdn_api_key	credentials
client_id	credentials
client_secret	credentials

configure set <key> - reads the value from stdin instead of argv, so it never appears in ps output or shell history. password, totp_secret, vcdn_api_key, and client_secret can only be set this way; a literal value for any of them is refused with exit code 2. configure get and configure list mask secrets as ****. Stdin is limited to 4096 bytes and drops one trailing LF or CRLF. The interactive configure does not prompt for vcdn_api_key, client_id, or client_secret.

configure and configure set refuse to run, with exit code 2, while read-only is on, so an agent cannot clear a profile's read_only through the CLI; configure get and configure list still work. configure set read_only refuses, with exit code 2, to turn read_only off for a profile that already has it on; clearing it means editing the file by hand.

Use a fresh service-account profile; configure client_id and pipe client_secret to stdin. Never pass the secret in argv or --cli-input-json. Set read_only last; later rotation needs a trusted editor or provisioner. See Configuration for provisioning, recovery, and rotation.

Service-account exchange failures use ServiceAccountLoginFailed, exit 3, or exit 1 for caller cancellation/deadline. Service-account cache failures use TokenCacheFailed, exit 1; bare cache context errors use RequestFailed, exit 1. Partial LoadConfig credentials and refused credentials files use NoCredentials, exit 3; shape and misplaced config keys use InvalidConfig, exit 2. SDK disk caching is opt-in; CLI caching uses ~/.vngcloud/cache by default when a home directory exists. Static tokens and custom providers never enter that disk cache. See Authentication.

Rename table

A flag or operation name the mechanical kebab-case conversion would otherwise get wrong:

Name	CLI form
AttachS3Key	attach-s3-key
CDNID	cdn-id
ClearVPCDHCPOptions	clear-vpc-dhcp-options
CreateS3Key	create-s3-key
DeleteS3Key	delete-s3-key
DetachS3Key	detach-s3-key
ListS3Keys	list-s3-keys
NATID	nat-id
NetworkACLID	network-acl-id
Query	search
SecurityGroupIDs	security-group-id
SetVPCDHCPOptions	set-vpc-dhcp-options
VPCID	vpc-id