CLI command reference

Every dcloud command, argument and flag.

dcloud command reference

ews, the command's name before 2026-11-18, runs the same CLI until at least 31 December 2027.

Every command below is generated from the same description of the API the CLI itself loads at startup, so this page cannot describe a flag the CLI does not accept or miss one it does.

1185 operations across 40 services, plus 82 routes that are documented as having no command and why.

For how the CLI behaves — signing in, output modes, @file values, exit codes, environment variables — see README.md. This file is only the reference.

Shape

dcloud <service> <resource> <operation> [arguments] [flags]
  • Arguments are the {holes} in the route path, positional in path order. Each is also accepted as a flag, for scripts that build commands programmatically.
  • Flags are the operation query and body fields, kebab-cased. In says which. Booleans take --flag and --no-flag; arrays and key=value maps are repeatable.
  • Required means the schema has no default and is not optional. A server default is shown in the notes rather than applied here — the server fills it in.
  • write means the IAM action is declared access: 'write' in its service descriptor, so the call changes state and the handler records the authorization decision. sensitive marks a read of secret material or source code, which is recorded too.
  • Every value is checked against the schema shown here before anything is sent, so a typo costs no round trip.

Services

Service Base path Resources Operations Routes with no command
ec2 Compute /ec2/api instances nat-gateways vpcs subnets availability-zones instance-type-offerings security-groups key-pairs sessions machine-images snapshot-policies volumes snapshots elastic-ips 76 4
autoscaling Auto Scaling /autoscaling/api launch-templates groups policies scheduled-actions instance-refreshes 25
lb Load balancing /lb/api load-balancers targets services rules 14
rds Postgres /rds/api instances backups query-insights data extensions server-types ca-bundle tls replication replication-slots branches logins 69 1
mysql MySQL /mysql/api clusters snapshots 15
docdb Document Database /docdb/api clusters users backups 22 2
rabbitmq RabbitMQ /rabbitmq/api brokers users exports 21
kafka Apache Kafka /kafka/api clusters topics users replications snapshots 33
cache Caches /cache/api clusters snapshots 15
efs File Storage /efs/api file-systems snapshots 9
eks Kubernetes /eks/api versions clusters deleted-clusters snapshots nodegroups access-entries pod-identity-associations addon-versions addons 44 4
queue Queues /queue/api queues messages 15
scheduler Schedules /scheduler/api schedules 11
errors Error Tracking /errors/api projects keys issues events traces profiles transactions releases alert-rules queries release-health auth-tokens connections 37 1
events Event bus /events/api buses rules archives replays patterns 27
functions Functions /functions/api functions event-source-mappings 12
sandbox Sandboxes /sandbox/api sandboxes files ports pools 20
cloudshell Cloud shell /cloudshell/api environment environments 6
s3 Object Storage /s3/api buckets bucket-objects bucket-access bucket-encryption bucket-remote-copy bucket-replication bucket-versioning bucket-cors bucket-lifecycle access-keys temporary-credentials 53
git Git /git/api repositories branches tags commits files pulls merge-queue releases release-assets security issues labels tag-protection commit-statuses branch-protection deploy-keys webhooks webhook-deliveries access-tokens ssh-keys attachments github 127 6
kms KMS /kms/api ssh-key-pairs keys 21
secrets Secrets /secrets/api secrets groups sources environments 38
ecr Container registry /ecr/api repositories lifecycle-policy expired-images lifecycle-defaults images storage registry-aliases pull-through-cache signing scan-results auth 40
npm npm registry /npm/api packages tokens lifecycle-defaults 15
billing Billing /billing/api summary costs estimates invoices account budgets cost-report cost-views savings budget-proposals payment-methods 41
iam Identity /iam/api users password-policy cli-auth-policy groups roles oidc-providers sso-connections policies grants access-keys agent-sessions members invitations audit-logs audit-destinations 104 28
dns DNS /dns/api zones records query-log dnssec 19
ci CI /ci/api workflows runners runner-groups runner-pools runs dispatch jobs variables environments artifacts 37 26
deploy Apps /deploy/api apps hosting host-database deployments env connections redeploy database cache kafka rabbitmq docdb errors jobs registry-credentials domains 57 8
monitoring Monitoring /monitoring/api metrics custom-metrics alarms checks logs status-pages incidents subscribers 36 1
vpn VPN /vpn/api endpoints apps peers gateways connections 24
privacyvpn Privacy VPN /privacyvpn/api locations accounts 14
email Email /email/api identities messages account suppressions 17
tags Tags & saved views /tags/api tags policy projects topology 15
projects Projects /projects/api projects 10
ai AI Models /ai/api settings assistant-models models model-access usage 8 1
cdn CDN /cdn/api distributions invalidations edge 9
waf Web application firewall /waf/api web-acls managed-rule-groups 7
quotas Service quotas /quotas/api quotas requests preview-access 7
posture Security Posture /posture/api summary controls findings evaluations frameworks reports 15

dcloud ec2

Compute. Base path /ec2/api.

dcloud ec2 instances

Virtual machines

Operation Method Path IAM action Effect
list GET /ec2/api/instances ec2:DescribeInstances read
run POST /ec2/api/instances ec2:RunInstances write
get GET /ec2/api/instances/{id} ec2:DescribeInstances read
set-tags PATCH /ec2/api/instances/{id}/tags tags:TagResource write
wait GET /ec2/api/instances/{id}/wait ec2:DescribeInstances read
get-identity GET /ec2/api/instances/{id}/identity ec2:DescribeInstances read
set-role PUT /ec2/api/instances/{id}/role ec2:AssociateInstanceRole write
remove-role DELETE /ec2/api/instances/{id}/role ec2:DisassociateInstanceRole write
connect-status GET /ec2/api/instances/{id}/connect ec2:DescribeInstances read
add-key POST /ec2/api/instances/{id}/keys ec2:AddInstanceKey write
remove-key DELETE /ec2/api/instances/{id}/keys/{keyPairId} ec2:RemoveInstanceKey write
start-session POST /ec2/api/instances/{id}/sessions ec2:StartSession write
attach-session POST /ec2/api/instances/{id}/sessions/{sessionId}/attach ec2:StartSession write
list-sessions GET /ec2/api/instances/{id}/sessions ec2:DescribeSessions read
end-session DELETE /ec2/api/instances/{id}/sessions/{sessionId} ec2:TerminateSession write
get-user-data GET /ec2/api/instances/{id}/user-data ec2:GetInstanceUserData read, sensitive
install-volume-helper POST /ec2/api/instances/{id}/volume-helper ec2:InstallVolumeHelper write
get-patch-state GET /ec2/api/instances/{id}/patch-state ec2:DescribeInstances read
terminate DELETE /ec2/api/instances/{id} ec2:TerminateInstances write
start PATCH /ec2/api/instances/{id} ec2:StartInstances write
stop PATCH /ec2/api/instances/{id} ec2:StopInstances write
shutdown PATCH /ec2/api/instances/{id} ec2:StopInstances write
reboot PATCH /ec2/api/instances/{id} ec2:RebootInstances write
rename PUT /ec2/api/instances/{id}/name ec2:ModifyInstanceAttribute write
security-groups GET /ec2/api/instances/{id}/security-groups ec2:DescribeInstances read
set-security-groups PUT /ec2/api/instances/{id}/security-groups ec2:ModifyInstanceAttribute write
resize POST /ec2/api/instances/{id}/actions/resize ec2:ModifyInstanceAttribute write

dcloud ec2 instances list

List instances

GET /ec2/api/instances — IAM ec2:DescribeInstances — read

dcloud ec2 instances list [flags]
Flag In Required Notes
--state <pending|running|rebooting|stopping|stopped|shutting-down|terminated> query Only instances in this state
--limit <number> query integer, 1-500 · At most this many, oldest first (default 100)
--offset <number> query integer, 0-1000000 · Skip this many first: the next page is offset + limit (default 0)
--tag <value> query 1-512 chars · Only instances carrying these tags: "env=preview,slot=3" (all must match; a bare key: present)
--name <value> query 1-64 chars · Only instances whose name or id contains this

dcloud ec2 instances run

Launch an instance

POST /ec2/api/instances — IAM ec2:RunInstances — write

dcloud ec2 instances run --region-id <value> [flags]
Flag In Required Notes
--server-type <value> body min 1 chars · An instance type, e.g. performance-2 (ec2 instance-types list). Give this or sizeClass. The provider’s own type names are still accepted, deprecated.
--size-class <s-2|s-4|s-8|s-16|m-4|d-2|d-8|a-2|a-4|a-8|a-16> body A size class instead of a provider type: s-2 (2 vCPU / 4 GiB), s-4 (4 / 8), s-8 (8 / 16), s-16 (16 / 32), m-4 (4 / 32), d-2 (2 dedicated / 8), d-8 (8 dedicated / 32), a-2, a-4, a-8, a-16 (ARM, as s-*); it becomes the smallest type of your provider that fits
--image-id <number> body integer, min 1 · An OS image from the catalog. Give this or machineImageId, not both.
--machine-image-id <value> body /^ewi-[0-9a-f]{6,32}$/ · One of your machine images (ewi-…), to launch a copy of a snapshot.
--region-id <value> body yes min 1 chars · The region to launch in, e.g. de1
--availability-zone-id <value> body /^[a-z]+[0-9]+[a-z]$/ · Zone to run in (de1a = Falkenstein, de1b = Nuremberg); default the subnet’s, else de1a
--vpc-id <value> body uuid · The VPC to join; omitted: the region’s default VPC, created the first time it is needed
--name <value> body max 64 chars · A display name; omitted: none
--ssh-key-pair-id <value> body uuid · A KMS SSH key pair (kms ssh-key-pairs)
--key-pair-id <value> body uuid · Instead of sshKeyPairId: a Compute key pair (ec2 key-pairs); not both
--user-data <value> body A cloud-init script run at first boot, passed through unchanged
--tags <key=value> body repeatable · key=value · Tags for the instance (and its launch volumes); your organization’s required keys must be present
--security-group-ids <value> body repeatable · uuid · Security groups to attach; omitted: none, so the instance is not filtered
--subnet-id <value> body uuid · A subnet of the VPC: the instance gets a fixed private address in its range and runs in its zone
--enable-public-ipv4 body Give the machine a public IPv4 (default true); false: IPv6 only, IPv4 out through the VPC’s NAT gateway if it has one
--os-patching body Keep OS patched: install the platform patch reporter; security updates install nightly and reboots happen in the 02:00–05:00 UTC window. Ubuntu images only.
--connect body Deutsche Cloud Connect (default true): the machine keeps one outbound SSH connection to Deutsche Cloud so the console terminal and adding keys work with no inbound port. false: nothing is installed.
--iam-role-name <value> body 1-64 chars, /^[\w+=,.@-]+$/ · IAM role the machine acts as (needs iam:PassRole on it): it gets 60-minute credentials for it through its instance identity (ews-instance credentials), with no key in user data
--volumes <value> body repeatable · Up to 4 extra volumes made with the instance in its zone, attached once it runs (needs ec2:CreateVolume and ec2:AttachVolume); encrypted and deleted with the instance unless told otherwise. CLI: --volumes '{"sizeGib":40}'
--public-hostname <json> body JSON · Own hosts only: a name in one of your DNS zones (and *.name) that reaches this machine through the site’s front: HTTPS by SNI, SSH through the jump on port 2222. Needs dns:ChangeRecords on that zone; removed at terminate.
--idle-suspend-minutes <number> body integer, 10-10080 · Own hosts only: suspend the machine (memory saved) after this many idle minutes; the next HTTPS request or SSH connection through the front wakes it.
--required-host-tags <json> body JSON · Own hosts only: capability tags the machine’s host must carry (a name or name:value, e.g. fsync:high, cpu:a); only hosts with every one take it, else it waits saying which tag is missing. CLI: --required-host-tags fsync:high

dcloud ec2 instances get

Describe one instance

GET /ec2/api/instances/{id} — IAM ec2:DescribeInstances — read

dcloud ec2 instances get <id>

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<id> --id string /^i-[0-9a-f]{6,32}$/

dcloud ec2 instances set-tags

Relabel an instance in one call: set some tags, remove others

PATCH /ec2/api/instances/{id}/tags — IAM tags:TagResource — write

dcloud ec2 instances set-tags <id> [flags]

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<id> --id string /^i-[0-9a-f]{6,32}$/
Flag In Required Notes
--set <key=value> body repeatable · key=value · Tags to add or overwrite
--remove <value> body repeatable · 1-128 chars · Keys to remove
  • Setting needs tags:TagResource and removing tags:UntagResource on the instance. Answers the tags it has afterwards. Find instances by tag with dcloud ec2 instances list --tag key=value.

dcloud ec2 instances wait

Wait until the instance is running (or stopped, or terminated)

GET /ec2/api/instances/{id}/wait — IAM ec2:DescribeInstances — read

dcloud ec2 instances wait <id> [flags]

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<id> --id string /^i-[0-9a-f]{6,32}$/
Flag In Required Notes
--state <running|stopped|terminated> query Default running
--timeout-seconds <number> query integer, 1-300 · At most this long (default 120, max 300)
  • Answers the instance as soon as it is in the state, or 408 after timeoutSeconds (call again to keep waiting), or 409 if it terminated first. Running means the machine exists and has its addresses.

dcloud ec2 instances get-identity

Instance identity: its role, when the secret was rotated and last used, from where

GET /ec2/api/instances/{id}/identity — IAM ec2:DescribeInstances — read

dcloud ec2 instances get-identity <id>

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<id> --id string /^i-[0-9a-f]{6,32}$/
  • The secret itself is never readable through the API: it lives on the machine in /etc/ews/instance-identity (root, 0600). On the machine, ews-instance credentials trades it for 60-minute credentials of the instance role.

dcloud ec2 instances set-role

Give the instance an IAM role it gets short-lived credentials for

PUT /ec2/api/instances/{id}/role — IAM ec2:AssociateInstanceRole — write

dcloud ec2 instances set-role <id> --iam-role-name <value>

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<id> --id string /^i-[0-9a-f]{6,32}$/
Flag In Required Notes
--iam-role-name <value> body yes 1-64 chars, /^[\w+=,.@-]+$/ · IAM role the machine acts as (needs iam:PassRole on it): it gets 60-minute credentials for it through its instance identity (ews-instance credentials), with no key in user data
  • Also needs iam:PassRole on the role.

dcloud ec2 instances remove-role

Take the instance role away; sessions already issued expire within the hour

DELETE /ec2/api/instances/{id}/role — IAM ec2:DisassociateInstanceRole — write

dcloud ec2 instances remove-role <id>

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<id> --id string /^i-[0-9a-f]{6,32}$/

dcloud ec2 instances connect-status

Deutsche Cloud Connect on this instance: connected or not, who can log in, the keys Deutsche Cloud added

GET /ec2/api/instances/{id}/connect — IAM ec2:DescribeInstances — read

dcloud ec2 instances connect-status <id>

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<id> --id string /^i-[0-9a-f]{6,32}$/
  • state: connected, pending (booting), disconnected (down, or systemctl disable ews-connect on the machine), off (launched with connect: false), not-installed (launched before Connect). enableCommand turns it on from the machine.

dcloud ec2 instances add-key

Add a key pair to a running instance (root and its default user), no reboot

POST /ec2/api/instances/{id}/keys — IAM ec2:AddInstanceKey — write

dcloud ec2 instances add-key <id> --key-pair-id <value> [flags]

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<id> --id string /^i-[0-9a-f]{6,32}$/
Flag In Required Notes
--key-pair-id <value> body yes The key pair to add (ec2 key pairs)
--users <root|default> body repeatable · Whose authorized_keys get it: root, the image’s default user, or both (the default)
  • May check ec2:DescribeKeyPairs instead, decided by server-side state the caller cannot see. A caller needs all of them to be sure of not getting a 403.
  • Through Deutsche Cloud Connect: works while the instance is connected (connect-status). The line in authorized_keys ends in ews-key:<keyPairId>, so remove-key takes out exactly that line. On an instance without Connect: 409 with what is possible.

dcloud ec2 instances remove-key

Remove a key pair Deutsche Cloud added from a running instance

DELETE /ec2/api/instances/{id}/keys/{keyPairId} — IAM ec2:RemoveInstanceKey — write

dcloud ec2 instances remove-key <id> <keyPairId>

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<id> --id string /^i-[0-9a-f]{6,32}$/
<keyPairId> --key-pair-id string uuid

dcloud ec2 instances start-session

Open a terminal on the instance (Deutsche Cloud Connect, no inbound port)

POST /ec2/api/instances/{id}/sessions — IAM ec2:StartSession — write

dcloud ec2 instances start-session <id> [flags]

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<id> --id string /^i-[0-9a-f]{6,32}$/
Flag In Required Notes
--login-user <value> body /^[a-z_][a-z0-9_-]{0,31}$/ · Log in as root (the default) or the image’s default user
  • Answers a single-use ticket valid 60 s and websocketUrl. Open the WebSocket with the subprotocols ews.terminal and ews.ticket.<ticket>; binary frames are the terminal’s bytes, text frames {"type":"resize","cols":…,"rows":…}. dcloud ec2 instances connect <id> does this for you.

dcloud ec2 instances attach-session

A fresh ticket to re-attach to your own session (the shell waits 60 s after a drop)

POST /ec2/api/instances/{id}/sessions/{sessionId}/attach — IAM ec2:StartSession — write

dcloud ec2 instances attach-session <id> <sessionId>

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<id> --id string /^i-[0-9a-f]{6,32}$/
<sessionId> --session-id string /^ses-[0-9a-f]{16}$/

dcloud ec2 instances list-sessions

Terminal sessions on this instance: who, when, how long, bytes

GET /ec2/api/instances/{id}/sessions — IAM ec2:DescribeSessions — read

dcloud ec2 instances list-sessions <id>

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<id> --id string /^i-[0-9a-f]{6,32}$/

dcloud ec2 instances end-session

End a terminal session (your own needs no permission)

DELETE /ec2/api/instances/{id}/sessions/{sessionId} — IAM ec2:TerminateSession — write

dcloud ec2 instances end-session <id> <sessionId>

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<id> --id string /^i-[0-9a-f]{6,32}$/
<sessionId> --session-id string /^ses-[0-9a-f]{16}$/

dcloud ec2 instances get-user-data

Read the cloud-init user data an instance booted with

GET /ec2/api/instances/{id}/user-data — IAM ec2:GetInstanceUserData — read, sensitive

dcloud ec2 instances get-user-data <id>

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<id> --id string /^i-[0-9a-f]{6,32}$/

dcloud ec2 instances install-volume-helper

Get the script that lets an older instance open encrypted volumes

POST /ec2/api/instances/{id}/volume-helper — IAM ec2:InstallVolumeHelper — write

dcloud ec2 instances install-volume-helper <id>

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<id> --id string /^i-[0-9a-f]{6,32}$/
  • For an instance launched before the volume helper existed. Run data.script as root on the instance; it installs the helper with a fresh credential for this instance and reports in, after which encrypted volumes can be attached. Idempotent. data.installed says whether it already reported.

dcloud ec2 instances get-patch-state

OS patch state: pending security updates, reboot needed or scheduled, kernel

GET /ec2/api/instances/{id}/patch-state — IAM ec2:DescribeInstances — read

dcloud ec2 instances get-patch-state <id>

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<id> --id string /^i-[0-9a-f]{6,32}$/
  • data is null for an instance that does not run the patch reporter (launched without osPatching). App boxes always run it.

dcloud ec2 instances terminate

Terminate an instance and delete its machine

DELETE /ec2/api/instances/{id} — IAM ec2:TerminateInstances — write

dcloud ec2 instances terminate <id>

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<id> --id string /^i-[0-9a-f]{6,32}$/

dcloud ec2 instances start

Start a stopped instance

PATCH /ec2/api/instances/{id} — IAM ec2:StartInstances — write

dcloud ec2 instances start <id>

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<id> --id string /^i-[0-9a-f]{6,32}$/
  • Sent automatically: action="start". This is what separates this verb from its siblings on the same route.

dcloud ec2 instances stop

Power off an instance

PATCH /ec2/api/instances/{id} — IAM ec2:StopInstances — write

dcloud ec2 instances stop <id>

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<id> --id string /^i-[0-9a-f]{6,32}$/
  • Sent automatically: action="stop". This is what separates this verb from its siblings on the same route.

dcloud ec2 instances shutdown

Ask the guest OS to shut down cleanly

PATCH /ec2/api/instances/{id} — IAM ec2:StopInstances — write

dcloud ec2 instances shutdown <id>

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<id> --id string /^i-[0-9a-f]{6,32}$/
  • Sent automatically: action="shutdown". This is what separates this verb from its siblings on the same route.

dcloud ec2 instances reboot

Reboot an instance

PATCH /ec2/api/instances/{id} — IAM ec2:RebootInstances — write

dcloud ec2 instances reboot <id>

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<id> --id string /^i-[0-9a-f]{6,32}$/
  • Sent automatically: action="reboot". This is what separates this verb from its siblings on the same route.

dcloud ec2 instances rename

Set or clear an instance display name

PUT /ec2/api/instances/{id}/name — IAM ec2:ModifyInstanceAttribute — write

dcloud ec2 instances rename <id> --name <value>

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<id> --id string /^i-[0-9a-f]{6,32}$/
Flag In Required Notes
--name <value> body yes max 64 chars · nullable · The new display name; null clears it

dcloud ec2 instances security-groups

List the security groups attached to an instance

GET /ec2/api/instances/{id}/security-groups — IAM ec2:DescribeInstances — read

dcloud ec2 instances security-groups <id>

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<id> --id string /^i-[0-9a-f]{6,32}$/

dcloud ec2 instances set-security-groups

Replace the security groups attached to an instance

PUT /ec2/api/instances/{id}/security-groups — IAM ec2:ModifyInstanceAttribute — write

dcloud ec2 instances set-security-groups <id> --security-group-ids <value>

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<id> --id string /^i-[0-9a-f]{6,32}$/
Flag In Required Notes
--security-group-ids <value> body yes repeatable · uuid · The complete new set of groups; an empty list detaches them all

dcloud ec2 instances resize

Change an instance server type

POST /ec2/api/instances/{id}/actions/resize — IAM ec2:ModifyInstanceAttribute — write

dcloud ec2 instances resize <id> --server-type <value>

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<id> --id string /^i-[0-9a-f]{6,32}$/
Flag In Required Notes
--server-type <value> body yes min 1 chars · The new instance type, e.g. performance-4 (provider names still accepted, deprecated)

dcloud ec2 nat-gateways

IPv4 internet access for a VPC’s machines without a public IPv4

Operation Method Path IAM action Effect
list GET /ec2/api/nat-gateways ec2:DescribeNatGateways read
create POST /ec2/api/nat-gateways ec2:CreateNatGateway write
get GET /ec2/api/nat-gateways/{id} ec2:DescribeNatGateways read
delete DELETE /ec2/api/nat-gateways/{id} ec2:DeleteNatGateway write

dcloud ec2 nat-gateways list

List NAT gateways

GET /ec2/api/nat-gateways — IAM ec2:DescribeNatGateways — read

dcloud ec2 nat-gateways list

dcloud ec2 nat-gateways create

Give a VPC a NAT gateway (one per VPC); answers 202 while it is built

POST /ec2/api/nat-gateways — IAM ec2:CreateNatGateway — write

dcloud ec2 nat-gateways create --vpc-id <value> [flags]
Flag In Required Notes
--vpc-id <value> body yes uuid · The VPC to serve
--tags <key=value> body repeatable · key=value · Tags for the new resource, e.g. {"env": "prod", "project": "shop"}. Keys your organization marks required must be present, or the create is refused with the missing keys (GET /tags/api/keys lists them).
  • A platform-run machine with a public IPv4 at a pinned address in the VPC, plus the network route 0.0.0.0/0 to it. Instances launched afterwards with enablePublicIpv4: false route through it on their own; older ones need one command (see the compute docs). One machine: not redundant.

dcloud ec2 nat-gateways get

A NAT gateway: state, egress address, address in the VPC

GET /ec2/api/nat-gateways/{id} — IAM ec2:DescribeNatGateways — read

dcloud ec2 nat-gateways get <id>

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<id> --id string /^nat-[0-9a-f]{6,32}$/

dcloud ec2 nat-gateways delete

Delete a NAT gateway: the route first, then its machine

DELETE /ec2/api/nat-gateways/{id} — IAM ec2:DeleteNatGateway — write

dcloud ec2 nat-gateways delete <id>

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<id> --id string /^nat-[0-9a-f]{6,32}$/
  • Machines without a public IPv4 lose IPv4 internet access. Answers 202.

dcloud ec2 vpcs

Private networks

Operation Method Path IAM action Effect
list GET /ec2/api/vpcs ec2:DescribeVpcs read
create POST /ec2/api/vpcs ec2:CreateVpc write
get GET /ec2/api/vpcs/{id} ec2:DescribeVpcs read
delete DELETE /ec2/api/vpcs/{id} ec2:DeleteVpc write

dcloud ec2 vpcs list

List VPCs

GET /ec2/api/vpcs — IAM ec2:DescribeVpcs — read

dcloud ec2 vpcs list

dcloud ec2 vpcs create

Create a VPC

POST /ec2/api/vpcs — IAM ec2:CreateVpc — write

dcloud ec2 vpcs create --region-id <value> [flags]
Flag In Required Notes
--region-id <value> body yes min 1 chars · The region to create it in, e.g. de1
--name <value> body max 64 chars · A display name; omitted: none
--cidr-block <value> body server default "10.0.0.0/16" · Private IPv4 range (RFC 1918), /8 to /24, starting on its boundary
--tags <key=value> body repeatable · key=value · Tags for the new resource, e.g. {"env": "prod", "project": "shop"}. Keys your organization marks required must be present, or the create is refused with the missing keys (GET /tags/api/keys lists them).

dcloud ec2 vpcs get

Describe one VPC

GET /ec2/api/vpcs/{id} — IAM ec2:DescribeVpcs — read

dcloud ec2 vpcs get <id>

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<id> --id string uuid

dcloud ec2 vpcs delete

Delete a VPC

DELETE /ec2/api/vpcs/{id} — IAM ec2:DeleteVpc — write

dcloud ec2 vpcs delete <id>

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<id> --id string uuid

dcloud ec2 subnets

Subnets within a VPC

Operation Method Path IAM action Effect
list GET /ec2/api/subnets ec2:DescribeSubnets read
create POST /ec2/api/vpcs/{id}/subnets ec2:CreateSubnet write
delete DELETE /ec2/api/subnets/{id} ec2:DeleteSubnet write

dcloud ec2 subnets list

List subnets, optionally filtered by VPC

GET /ec2/api/subnets — IAM ec2:DescribeSubnets — read

dcloud ec2 subnets list [flags]
Flag In Required Notes
--vpc-id <value> query uuid · Only those in this VPC; omitted: all

dcloud ec2 subnets create

Create a subnet: a range of the VPC in one availability zone

POST /ec2/api/vpcs/{id}/subnets — IAM ec2:CreateSubnet — write

dcloud ec2 subnets create <id> --cidr-block <value> [flags]

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<id> --id string uuid
Flag In Required Notes
--cidr-block <value> body yes 9-18 chars · IPv4 range inside the VPC, e.g. 10.0.1.0/24
--availability-zone-id <value> body /^[a-z]+[0-9]+[a-z]$/ · The zone (e.g. de1b); default de1a
--name <value> body max 64 chars · A display name; omitted: none
--tags <key=value> body repeatable · key=value · Tags for the new resource, e.g. {"env": "prod", "project": "shop"}. Keys your organization marks required must be present, or the create is refused with the missing keys (GET /tags/api/keys lists them).
  • An instance launched with subnetId gets an address in the range and runs in the subnet’s zone. Ranges are /16 to /28, inside the VPC and not overlapping another subnet.

dcloud ec2 subnets delete

Delete a subnet no instance holds an address in

DELETE /ec2/api/subnets/{id} — IAM ec2:DeleteSubnet — write

dcloud ec2 subnets delete <id>

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<id> --id string uuid

dcloud ec2 availability-zones

Availability zones: one provider location each (de1a = fsn1, de1b = nbg1)

Operation Method Path IAM action Effect
list GET /ec2/api/availability-zones ec2:DescribeAvailabilityZones read

dcloud ec2 availability-zones list

List the availability zones of a region, with the location behind each

GET /ec2/api/availability-zones — IAM ec2:DescribeAvailabilityZones — read

dcloud ec2 availability-zones list [flags]
Flag In Required Notes
--region-id <value> query 1-32 chars · Only this region’s zones

dcloud ec2 instance-type-offerings

Which instance types each zone sells right now. The provider sells from live stock; refreshed every minute

Operation Method Path IAM action Effect
list GET /ec2/api/instance-type-offerings ec2:DescribeInstanceTypeOfferings read

dcloud ec2 instance-type-offerings list

List instance types per availability zone with inStock and when it last changed (e.g. "arm-2 sold out in de1a, in stock in de1b")

GET /ec2/api/instance-type-offerings — IAM ec2:DescribeInstanceTypeOfferings — read

dcloud ec2 instance-type-offerings list [flags]
Flag In Required Notes
--region-id <value> query 1-32 chars · Region (default: the caller’s)
--availability-zone-id <value> query /^[a-z]+[0-9]+[a-z]$/ · Only this zone
--instance-type <value> query /^[a-z0-9-]{2,24}$/ · Only this instance type, e.g. performance-2

dcloud ec2 security-groups

Firewall rule sets attached to instances

Operation Method Path IAM action Effect
list GET /ec2/api/security-groups ec2:DescribeSecurityGroups read
create POST /ec2/api/security-groups ec2:CreateSecurityGroup write
get GET /ec2/api/security-groups/{id} ec2:DescribeSecurityGroups read
delete DELETE /ec2/api/security-groups/{id} ec2:DeleteSecurityGroup write
authorize-ingress POST /ec2/api/security-groups/{id}/rules ec2:AuthorizeSecurityGroupIngress write
authorize-egress POST /ec2/api/security-groups/{id}/rules ec2:AuthorizeSecurityGroupEgress write
revoke-rule DELETE /ec2/api/security-groups/{id}/rules/{ruleId} ec2:RevokeSecurityGroupIngress write

dcloud ec2 security-groups list

List security groups, optionally filtered by VPC

GET /ec2/api/security-groups — IAM ec2:DescribeSecurityGroups — read

dcloud ec2 security-groups list [flags]
Flag In Required Notes
--vpc-id <value> query uuid · Only those in this VPC; omitted: all

dcloud ec2 security-groups create

Create a security group with optional initial rules

POST /ec2/api/security-groups — IAM ec2:CreateSecurityGroup — write

dcloud ec2 security-groups create --name <value> [flags]
Flag In Required Notes
--name <value> body yes 1-64 chars · A display name
--description <value> body max 255 chars · Free text; omitted: none
--rules <value> body repeatable · Initial rules, each { direction, protocol, fromPort, toPort, cidrIpv4, description } as for adding a rule; omitted: none
--tags <key=value> body repeatable · key=value · Tags for the new resource, e.g. {"env": "prod", "project": "shop"}. Keys your organization marks required must be present, or the create is refused with the missing keys (GET /tags/api/keys lists them).

dcloud ec2 security-groups get

Describe one security group and its rules

GET /ec2/api/security-groups/{id} — IAM ec2:DescribeSecurityGroups — read

dcloud ec2 security-groups get <id>

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<id> --id string uuid

dcloud ec2 security-groups delete

Delete a security group

DELETE /ec2/api/security-groups/{id} — IAM ec2:DeleteSecurityGroup — write

dcloud ec2 security-groups delete <id>

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<id> --id string uuid

dcloud ec2 security-groups authorize-ingress

Add an inbound rule

POST /ec2/api/security-groups/{id}/rules — IAM ec2:AuthorizeSecurityGroupIngress — write

dcloud ec2 security-groups authorize-ingress <id> --protocol <tcp|udp|icmp> [flags]

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<id> --id string uuid
Flag In Required Notes
--protocol <tcp|udp|icmp> body yes The IP protocol the rule matches
--from-port <number> body integer, 0-65535 · First port of the range; omitted: every port. Ignored for ICMP
--to-port <number> body integer, 0-65535 · Last port of the range; omitted: fromPort alone
--cidr-ipv4 <value> body server default "0.0.0.0/0" · Where traffic may come from: a CIDR block or a single address (IPv4 or IPv6); default 0.0.0.0/0
--description <value> body max 255 chars · Free text; omitted: none
  • Sent automatically: direction="inbound". This is what separates this verb from its siblings on the same route.

dcloud ec2 security-groups authorize-egress

Add an outbound rule

POST /ec2/api/security-groups/{id}/rules — IAM ec2:AuthorizeSecurityGroupEgress — write

dcloud ec2 security-groups authorize-egress <id> --protocol <tcp|udp|icmp> [flags]

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<id> --id string uuid
Flag In Required Notes
--protocol <tcp|udp|icmp> body yes The IP protocol the rule matches
--from-port <number> body integer, 0-65535 · First port of the range; omitted: every port. Ignored for ICMP
--to-port <number> body integer, 0-65535 · Last port of the range; omitted: fromPort alone
--cidr-ipv4 <value> body server default "0.0.0.0/0" · Where traffic may go: a CIDR block or a single address (IPv4 or IPv6); default 0.0.0.0/0
--description <value> body max 255 chars · Free text; omitted: none
  • Sent automatically: direction="outbound". This is what separates this verb from its siblings on the same route.

dcloud ec2 security-groups revoke-rule

Remove a rule from a security group

DELETE /ec2/api/security-groups/{id}/rules/{ruleId} — IAM ec2:RevokeSecurityGroupIngress — write

dcloud ec2 security-groups revoke-rule <id> <ruleId>

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<id> --id string uuid
<ruleId> --rule-id string uuid
  • May check ec2:RevokeSecurityGroupEgress instead, decided by server-side state the caller cannot see. A caller needs all of them to be sure of not getting a 403.
  • The route reads the rule direction from the stored row, so which of the two Revoke actions it checks is not visible from the request.

dcloud ec2 key-pairs

SSH public keys registered for launch

Operation Method Path IAM action Effect
import POST /ec2/api/key-pairs ec2:ImportKeyPair write
delete DELETE /ec2/api/key-pairs/{id} ec2:DeleteKeyPair write

dcloud ec2 key-pairs import

Register an existing SSH public key

POST /ec2/api/key-pairs — IAM ec2:ImportKeyPair — write

dcloud ec2 key-pairs import --name <value> --public-key <value> [flags]
Flag In Required Notes
--name <value> body yes 1-64 chars · A display name
--region-id <value> body min 1 chars · Ignored: an SSH key is not regional. Kept for old clients
--public-key <value> body yes min 1 chars · The public key in OpenSSH format, e.g. "ssh-ed25519 AAAA… comment"
--tags <key=value> body repeatable · key=value · Tags for the new resource, e.g. {"env": "prod", "project": "shop"}. Keys your organization marks required must be present, or the create is refused with the missing keys (GET /tags/api/keys lists them).
  • One store with kms ssh-key-pairs (list, generate, sync from a password manager): the pair is the same object there, under the same id.

dcloud ec2 key-pairs delete

Delete a key pair

DELETE /ec2/api/key-pairs/{id} — IAM ec2:DeleteKeyPair — write

dcloud ec2 key-pairs delete <id>

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<id> --id string uuid
  • Refused with 409 while a live instance still names the pair. Machines already launched with it keep the key installed on them.

dcloud ec2 sessions

Terminal sessions on instances (Deutsche Cloud Connect), across the organization

Operation Method Path IAM action Effect
list GET /ec2/api/sessions ec2:DescribeSessions read

dcloud ec2 sessions list

Terminal sessions: who opened which instance, when, for how long

GET /ec2/api/sessions — IAM ec2:DescribeSessions — read

dcloud ec2 sessions list [flags]
Flag In Required Notes
--instance-id <value> query /^i-[0-9a-f]{6,32}$/ · Only sessions on this instance (i-…); omitted: every instance
--open <true|false> query true: only sessions not yet ended; omitted or false: all
--limit <number> query integer, 1-200 · server default 50 · At most this many, newest first (default 50)

dcloud ec2 machine-images

Snapshots of an instance root volume

Operation Method Path IAM action Effect
list GET /ec2/api/machine-images ec2:DescribeImages read
create POST /ec2/api/machine-images ec2:CreateImage write
deregister DELETE /ec2/api/machine-images/{id} ec2:DeregisterImage write

dcloud ec2 machine-images list

List machine images owned by the org

GET /ec2/api/machine-images — IAM ec2:DescribeImages — read

dcloud ec2 machine-images list

dcloud ec2 machine-images create

Snapshot a running instance into a machine image

POST /ec2/api/machine-images — IAM ec2:CreateImage — write

dcloud ec2 machine-images create --instance-id <value> --name <value> [flags]
Flag In Required Notes
--instance-id <value> body yes min 1 chars · The instance to snapshot (i-…), running or stopped
--name <value> body yes 1-64 chars · A display name
--description <value> body max 255 chars · Free text; omitted: none
--tags <key=value> body repeatable · key=value · Tags for the new resource, e.g. {"env": "prod", "project": "shop"}. Keys your organization marks required must be present, or the create is refused with the missing keys (GET /tags/api/keys lists them).

dcloud ec2 machine-images deregister

Delete the provider snapshot and mark the image deregistered

DELETE /ec2/api/machine-images/{id} — IAM ec2:DeregisterImage — write

dcloud ec2 machine-images deregister <id>

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<id> --id string /^ewi-[0-9a-f]{6,32}$/
  • The row survives in the deregistered state — instances point at it — so this is not a delete. A platform base image is refused with 409.

dcloud ec2 snapshot-policies

Scheduled instance snapshots with retention

Operation Method Path IAM action Effect
list GET /ec2/api/snapshot-policies ec2:DescribeSnapshotPolicies read
create POST /ec2/api/snapshot-policies ec2:CreateSnapshotPolicy write
get GET /ec2/api/snapshot-policies/{id} ec2:DescribeSnapshotPolicies read
update PATCH /ec2/api/snapshot-policies/{id} ec2:UpdateSnapshotPolicy write
run POST /ec2/api/snapshot-policies/{id}/run ec2:UpdateSnapshotPolicy write
delete DELETE /ec2/api/snapshot-policies/{id} ec2:DeleteSnapshotPolicy write

dcloud ec2 snapshot-policies list

List snapshot policies

GET /ec2/api/snapshot-policies — IAM ec2:DescribeSnapshotPolicies — read

dcloud ec2 snapshot-policies list

dcloud ec2 snapshot-policies create

Snapshot instances on a schedule and keep the newest N per instance

POST /ec2/api/snapshot-policies — IAM ec2:CreateSnapshotPolicy — write

dcloud ec2 snapshot-policies create --name <value> --interval-hours <number> --start-time <value> --retain-count <number> --region-id <value> [flags]
Flag In Required Notes
--name <value> body yes 1-64 chars · A display name
--description <value> body max 255 chars · nullable · Free text; null clears it
--enabled body A paused policy takes nothing and keeps its images
--target-instance-ids <value> body repeatable · /^i-[0-9a-f]{6,32}$/ · Instances to snapshot (i-…)
--target-tags <key=value> body repeatable · key=value · Also snapshot every instance that carries all of these tags
--interval-hours <number> body yes integer · Hours between runs: 1, 2, 3, 4, 6, 8, 12, 24 or 168 (weekly, on Mondays)
--start-time <value> body yes /^([01]\d|2[0-3]):[0-5]\d$/ · HH:MM UTC; runs fall on this time plus whole intervals
--retain-count <number> body yes integer, 1-100 · Images kept per instance; older ones this policy took are deregistered
--region-id <value> body yes 1-32 chars · The region the policy belongs to, e.g. de1
  • Targets are instance ids, tags, or both; at least one is required. A snapshot of a running instance is crash-consistent, like an EBS snapshot.

dcloud ec2 snapshot-policies get

A snapshot policy, with the images it holds

GET /ec2/api/snapshot-policies/{id} — IAM ec2:DescribeSnapshotPolicies — read

dcloud ec2 snapshot-policies get <id>

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<id> --id string /^esp-[0-9a-f]{6,32}$/

dcloud ec2 snapshot-policies update

Change, pause or resume a snapshot policy

PATCH /ec2/api/snapshot-policies/{id} — IAM ec2:UpdateSnapshotPolicy — write

dcloud ec2 snapshot-policies update <id> [flags]

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<id> --id string /^esp-[0-9a-f]{6,32}$/
Flag In Required Notes
--name <value> body 1-64 chars · A display name
--description <value> body max 255 chars · nullable · Free text; null clears it
--enabled body A paused policy takes nothing and keeps its images
--target-instance-ids <value> body repeatable · /^i-[0-9a-f]{6,32}$/ · Instances to snapshot (i-…)
--target-tags <key=value> body repeatable · key=value · Also snapshot every instance that carries all of these tags
--interval-hours <number> body integer · Hours between runs: 1, 2, 3, 4, 6, 8, 12, 24 or 168 (weekly, on Mondays)
--start-time <value> body /^([01]\d|2[0-3]):[0-5]\d$/ · HH:MM UTC; runs fall on this time plus whole intervals
--retain-count <number> body integer, 1-100 · Images kept per instance; older ones this policy took are deregistered

dcloud ec2 snapshot-policies run

Run a snapshot policy now, outside its schedule

POST /ec2/api/snapshot-policies/{id}/run — IAM ec2:UpdateSnapshotPolicy — write

dcloud ec2 snapshot-policies run <id>

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<id> --id string /^esp-[0-9a-f]{6,32}$/

dcloud ec2 snapshot-policies delete

Delete a snapshot policy; the images it took are kept

DELETE /ec2/api/snapshot-policies/{id} — IAM ec2:DeleteSnapshotPolicy — write

dcloud ec2 snapshot-policies delete <id>

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<id> --id string /^esp-[0-9a-f]{6,32}$/

dcloud ec2 volumes

Block storage you create, attach to an instance, and delete

Operation Method Path IAM action Effect
list GET /ec2/api/volumes ec2:DescribeVolumes read
get GET /ec2/api/volumes/{id} ec2:DescribeVolumes read
create POST /ec2/api/volumes ec2:CreateVolume write
attach POST /ec2/api/volumes/{id}/attach ec2:AttachVolume write
rotate-key POST /ec2/api/volumes/{id}/rotate-key ec2:RotateVolumeKey write
detach POST /ec2/api/volumes/{id}/detach ec2:DetachVolume write
modify PATCH /ec2/api/volumes/{id} ec2:ModifyVolume write
delete DELETE /ec2/api/volumes/{id} ec2:DeleteVolume write

dcloud ec2 volumes list

List volumes

GET /ec2/api/volumes — IAM ec2:DescribeVolumes — read

dcloud ec2 volumes list

dcloud ec2 volumes get

Describe a volume

GET /ec2/api/volumes/{id} — IAM ec2:DescribeVolumes — read

dcloud ec2 volumes get <id>

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<id> --id string /^vol-[0-9a-f]{6,32}$/

dcloud ec2 volumes create

Create a volume in a region

POST /ec2/api/volumes — IAM ec2:CreateVolume — write

dcloud ec2 volumes create --name <value> --size-gib <number> --region-id <value> [flags]
Flag In Required Notes
--name <value> body yes 1-64 chars · A display name
--size-gib <number> body yes integer, 10-10000 · Size in GiB; a restore needs at least the snapshot’s size
--region-id <value> body yes min 1 chars · The region to create it in, e.g. de1
--availability-zone-id <value> body /^[a-z]+[0-9]+[a-z]$/ · The zone it lives in; it attaches only to instances there. Default de1a
--tags <key=value> body repeatable · key=value · Tags for the volume; your organization’s required keys must be present
--encrypted body server default true · Encrypt the volume at rest with a key of its own, held in KMS (default true); a restore follows the snapshot instead
--kms-key-id <value> body uuid · One of your KMS keys to wrap the volume key (needs kms:Encrypt on it); omitted: the platform key. Not with snapshotId
--snapshot-id <value> body /^snap-[0-9a-f]{6,32}$/ · Restore this volume snapshot onto the new volume (same zone, at least its size)
  • Encrypted (LUKS2, key per volume from KMS) unless encrypted is false. An encrypted volume opens at /dev/mapper/ews-vol-<provider volume id> on an instance launched with the volume helper; format and mount that device. kmsKeyId wraps the volume key under one of your KMS keys (needs kms:Encrypt on it); disabling or deleting that key makes the volume unopenable.

dcloud ec2 volumes attach

Attach a volume to an instance in the same region

POST /ec2/api/volumes/{id}/attach — IAM ec2:AttachVolume — write

dcloud ec2 volumes attach <id> --instance-id <value>

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<id> --id string /^vol-[0-9a-f]{6,32}$/
Flag In Required Notes
--instance-id <value> body yes /^i-[0-9a-f]{6,32}$/ · The instance to attach to (i-…), in the volume’s zone and not terminated

dcloud ec2 volumes rotate-key

Replace an encrypted volume’s LUKS passphrase with a new key

POST /ec2/api/volumes/{id}/rotate-key — IAM ec2:RotateVolumeKey — write

dcloud ec2 volumes rotate-key <id>

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<id> --id string /^vol-[0-9a-f]{6,32}$/
  • Answers 202 with the key version. The instance it is attached to finishes the rotation within five minutes; a detached volume finishes when it is next attached. The dm-crypt volume key itself is not changed.

dcloud ec2 volumes detach

Detach a volume from its instance

POST /ec2/api/volumes/{id}/detach — IAM ec2:DetachVolume — write

dcloud ec2 volumes detach <id>

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<id> --id string /^vol-[0-9a-f]{6,32}$/

dcloud ec2 volumes modify

Rename a volume or grow it

PATCH /ec2/api/volumes/{id} — IAM ec2:ModifyVolume — write

dcloud ec2 volumes modify <id> [flags]

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<id> --id string /^vol-[0-9a-f]{6,32}$/
Flag In Required Notes
--name <value> body 1-64 chars · The new name
--size-gib <number> body integer, 10-10000 · The new size in GiB; a volume only grows
  • A volume only grows, attached or not. Afterwards grow the filesystem on the instance (resize2fs, xfs_growfs); see the Compute guide.

dcloud ec2 volumes delete

Delete a detached volume and its data

DELETE /ec2/api/volumes/{id} — IAM ec2:DeleteVolume — write

dcloud ec2 volumes delete <id>

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<id> --id string /^vol-[0-9a-f]{6,32}$/

dcloud ec2 snapshots

Volume snapshots: a volume’s blocks in object storage, restorable into a new volume

Operation Method Path IAM action Effect
list GET /ec2/api/snapshots ec2:DescribeSnapshots read
get GET /ec2/api/snapshots/{id} ec2:DescribeSnapshots read
create POST /ec2/api/volumes/{id}/snapshots ec2:CreateSnapshot write
delete DELETE /ec2/api/snapshots/{id} ec2:DeleteSnapshot write

dcloud ec2 snapshots list

List volume snapshots (optionally of one volume)

GET /ec2/api/snapshots — IAM ec2:DescribeSnapshots — read

dcloud ec2 snapshots list [flags]
Flag In Required Notes
--volume-id <value> query /^vol-[0-9a-f]{6,32}$/ · Only snapshots of this volume; omitted: all

dcloud ec2 snapshots get

Describe a volume snapshot and its progress

GET /ec2/api/snapshots/{id} — IAM ec2:DescribeSnapshots — read

dcloud ec2 snapshots get <id>

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<id> --id string /^snap-[0-9a-f]{6,32}$/

dcloud ec2 snapshots create

Snapshot a volume

POST /ec2/api/volumes/{id}/snapshots — IAM ec2:CreateSnapshot — write

dcloud ec2 snapshots create <id> [flags]

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<id> --id string /^vol-[0-9a-f]{6,32}$/
Flag In Required Notes
--name <value> body 1-64 chars · A display name; omitted: none
--description <value> body max 255 chars · Free text; omitted: none
--stop-instance body server default false · The volume is attached: stop its instance for the snapshot and start it after
--tags <key=value> body repeatable · key=value · Tags for the new resource, e.g. {"env": "prod", "project": "shop"}. Keys your organization marks required must be present, or the create is refused with the missing keys (GET /tags/api/keys lists them).
  • Answers 202; poll the snapshot until state is completed. A helper machine of the platform attaches the volume and copies its raw blocks in 4 MiB chunks to the zone’s snapshot storage; an encrypted volume is copied as LUKS ciphertext, so the helper never holds its key. Unchanged chunks are stored once, so a second snapshot stores only what changed (newBytes). An attached volume is refused with 409 unless stopInstance is true: the instance is stopped, the volume copied, reattached and the instance started again (needs ec2:StopInstances on it).

dcloud ec2 snapshots delete

Delete a volume snapshot and the data no other snapshot uses

DELETE /ec2/api/snapshots/{id} — IAM ec2:DeleteSnapshot — write

dcloud ec2 snapshots delete <id>

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<id> --id string /^snap-[0-9a-f]{6,32}$/

dcloud ec2 elastic-ips

Floating IPv4 addresses

Operation Method Path IAM action Effect
list GET /ec2/api/elastic-ips ec2:DescribeAddresses read
allocate POST /ec2/api/elastic-ips ec2:AllocateAddress write
release DELETE /ec2/api/elastic-ips/{id} ec2:ReleaseAddress write
associate POST /ec2/api/elastic-ips/{id}/associate ec2:AssociateAddress write
disassociate POST /ec2/api/elastic-ips/{id}/disassociate ec2:DisassociateAddress write

dcloud ec2 elastic-ips list

List elastic IPs

GET /ec2/api/elastic-ips — IAM ec2:DescribeAddresses — read

dcloud ec2 elastic-ips list

dcloud ec2 elastic-ips allocate

Allocate an elastic IP in a region

POST /ec2/api/elastic-ips — IAM ec2:AllocateAddress — write

dcloud ec2 elastic-ips allocate --region-id <value> [flags]
Flag In Required Notes
--region-id <value> body yes min 1 chars · The region to allocate the address in, e.g. de1
--tags <key=value> body repeatable · key=value · Tags for the address; omitted: none, and associating it with an instance may copy that instance’s tags

dcloud ec2 elastic-ips release

Release an elastic IP

DELETE /ec2/api/elastic-ips/{id} — IAM ec2:ReleaseAddress — write

dcloud ec2 elastic-ips release <id>

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<id> --id string uuid

dcloud ec2 elastic-ips associate

Attach an elastic IP to an instance

POST /ec2/api/elastic-ips/{id}/associate — IAM ec2:AssociateAddress — write

dcloud ec2 elastic-ips associate <id> --instance-id <value>

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<id> --id string uuid
Flag In Required Notes
--instance-id <value> body yes /^i-[0-9a-f]{6,32}$/ · The instance to attach the address to (i-…)

dcloud ec2 elastic-ips disassociate

Detach an elastic IP from its instance

POST /ec2/api/elastic-ips/{id}/disassociate — IAM ec2:DisassociateAddress — write

dcloud ec2 elastic-ips disassociate <id>

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<id> --id string uuid

Not in the CLI: ec2 routes the surface does not describe

These routes exist and are reachable over HTTP. They are deliberately absent from the description, so there is no command for them. The reason is recorded next to the service so a gap has to be stated out loud and stops being stateable the moment the route goes.

Route Why it has no command
GET /ec2/api/instance-identity/jwks Public key set for verifying instance identity tokens (no caller, no IAM action): a mirror of /api/instance/v1/jwks reachable from functions through their API proxy. Not an operation for the SDKs, CLI or Terraform.
GET /ec2/api/catalog/server-types Authenticated but not IAM-gated — the handler checks no action
GET /ec2/api/catalog/regions Authenticated but not IAM-gated — the handler checks no action
GET /ec2/api/catalog/images Authenticated but not IAM-gated — the handler checks no action

dcloud autoscaling

Auto Scaling. Base path /autoscaling/api.

dcloud autoscaling launch-templates

What a group’s machines are made from; immutable, numbered versions

Operation Method Path IAM action Effect
list GET /autoscaling/api/launch-templates autoscaling:DescribeLaunchTemplates read
create POST /autoscaling/api/launch-templates autoscaling:CreateLaunchTemplate write
get GET /autoscaling/api/launch-templates/{id} autoscaling:DescribeLaunchTemplates read
create-version POST /autoscaling/api/launch-templates/{id}/versions autoscaling:CreateLaunchTemplateVersion write
set-default-version PATCH /autoscaling/api/launch-templates/{id} autoscaling:CreateLaunchTemplateVersion write
delete DELETE /autoscaling/api/launch-templates/{id} autoscaling:DeleteLaunchTemplate write

dcloud autoscaling launch-templates list

List launch templates

GET /autoscaling/api/launch-templates — IAM autoscaling:DescribeLaunchTemplates — read

dcloud autoscaling launch-templates list

dcloud autoscaling launch-templates create

Create a launch template (its version 1)

POST /autoscaling/api/launch-templates — IAM autoscaling:CreateLaunchTemplate — write

dcloud autoscaling launch-templates create --name <value> --region-id <value> --spec <json> [flags]
Flag In Required Notes
--name <value> body yes 1-48 chars, /^[a-zA-Z0-9][a-zA-Z0-9._-]*$/
--region-id <value> body yes 1-32 chars
--description <value> body max 255 chars
--version-description <value> body max 255 chars
--spec <json> body yes JSON · What machines are made from: serverType, imageId or machineImageId, vpcId, sshKeyPairId, userData, securityGroupIds, enablePublicIpv4, osPatching, tags

dcloud autoscaling launch-templates get

Describe a launch template and every version of it

GET /autoscaling/api/launch-templates/{id} — IAM autoscaling:DescribeLaunchTemplates — read

dcloud autoscaling launch-templates get <id>

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<id> --id string /^lt-[0-9a-f]{8}$/

dcloud autoscaling launch-templates create-version

Add a version; groups on $Latest (or $Default, with makeDefault) pick it up

POST /autoscaling/api/launch-templates/{id}/versions — IAM autoscaling:CreateLaunchTemplateVersion — write

dcloud autoscaling launch-templates create-version <id> --spec <json> [flags]

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<id> --id string /^lt-[0-9a-f]{8}$/
Flag In Required Notes
--description <value> body max 255 chars
--spec <json> body yes JSON
--make-default body Make it the version $Default groups launch
  • Machines already running keep the version they were launched from. Start an instance refresh to roll a group onto it.

dcloud autoscaling launch-templates set-default-version

Change which version $Default means

PATCH /autoscaling/api/launch-templates/{id} — IAM autoscaling:CreateLaunchTemplateVersion — write

dcloud autoscaling launch-templates set-default-version <id> --default-version <number>

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<id> --id string /^lt-[0-9a-f]{8}$/
Flag In Required Notes
--default-version <number> body yes integer, min 1 · The version $Default groups launch

dcloud autoscaling launch-templates delete

Delete a launch template no group uses

DELETE /autoscaling/api/launch-templates/{id} — IAM autoscaling:DeleteLaunchTemplate — write

dcloud autoscaling launch-templates delete <id>

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<id> --id string /^lt-[0-9a-f]{8}$/

dcloud autoscaling groups

Auto scaling groups: machines kept at a size, spread across zones

Operation Method Path IAM action Effect
list GET /autoscaling/api/groups autoscaling:DescribeAutoScalingGroups read
create POST /autoscaling/api/groups autoscaling:CreateAutoScalingGroup write
get GET /autoscaling/api/groups/{id} autoscaling:DescribeAutoScalingGroups read
update PATCH /autoscaling/api/groups/{id} autoscaling:UpdateAutoScalingGroup write
set-desired-capacity PUT /autoscaling/api/groups/{id}/desired-capacity autoscaling:SetDesiredCapacity write
terminate-instance POST /autoscaling/api/groups/{id}/instances/{instanceId}/terminate autoscaling:TerminateInstanceInAutoScalingGroup write
set-instance-protection PUT /autoscaling/api/groups/{id}/instances/{instanceId}/protection autoscaling:SetInstanceProtection write
complete-lifecycle-action POST /autoscaling/api/groups/{id}/instances/{instanceId}/complete-lifecycle-action autoscaling:CompleteLifecycleAction write
record-lifecycle-heartbeat POST /autoscaling/api/groups/{id}/instances/{instanceId}/lifecycle-heartbeat autoscaling:RecordLifecycleActionHeartbeat write
put-lifecycle-hook PUT /autoscaling/api/groups/{id}/lifecycle-hooks autoscaling:PutLifecycleHook write
delete-lifecycle-hook DELETE /autoscaling/api/groups/{id}/lifecycle-hooks/{hookName} autoscaling:DeleteLifecycleHook write
delete DELETE /autoscaling/api/groups/{id} autoscaling:DeleteAutoScalingGroup write

dcloud autoscaling groups list

List auto scaling groups with their machine counts

GET /autoscaling/api/groups — IAM autoscaling:DescribeAutoScalingGroups — read

dcloud autoscaling groups list

dcloud autoscaling groups create

Create a group; it launches up to its desired capacity within a minute

POST /autoscaling/api/groups — IAM autoscaling:CreateAutoScalingGroup — write

dcloud autoscaling groups create --name <value> --region-id <value> --launch-template-id <value> --min-size <number> --max-size <number> --availability-zone-ids <value> [flags]
Flag In Required Notes
--name <value> body yes 1-48 chars, /^[a-zA-Z0-9][a-zA-Z0-9._-]*$/
--region-id <value> body yes 1-32 chars
--launch-template-id <value> body yes /^lt-[0-9a-f]{8}$/
--launch-template-version <json> body JSON · $Default (default), $Latest, or a version number
--min-size <number> body yes integer, 0-100
--max-size <number> body yes integer, 0-100
--desired-capacity <number> body integer, 0-100 · Default: minSize
--availability-zone-ids <value> body yes repeatable · /^[a-z]+[0-9]+[a-z]$/ · Zones to spread machines across evenly, e.g. ["de1a","de1b"]
--vpc-id <value> body Default: the region’s default VPC
--subnet-ids <value> body repeatable · At most one per zone; machines in that zone take an address in it
--load-balancer-ids <value> body repeatable · Every machine in service is a target of each
--health-check-type <ec2|lb> body ec2 (machine up, default) or lb (also passes its load balancers’ health checks)
--health-check-grace-period-seconds <number> body integer, 0-7200 · Default 300
--default-cooldown-seconds <number> body integer, 0-3600 · Default 300
--default-instance-warmup-seconds <number> body integer, 0-3600 · Seconds before a new machine’s metrics count; default 300
--instance-types <value> body repeatable · /^[a-z0-9-]{2,24}$/ · Instance types to use, in order, when the first choice is sold out (like AWS overrides), e.g. performance-4. Same CPU architecture as the template; the provider’s own type names are still accepted, deprecated
--capacity-fallback <json> body JSON · Stock fallback; default { otherZones: true, equivalentTypes: false }: a zone that is sold out is skipped for the group’s other zones
--defer-scale-in-until-paid-hour body Cloud machines are billed per started hour: a machine picked for scale-in keeps serving until the last 5 minutes of its paid hour, and the one whose hour ends first is picked. On own hosts (no hourly increment) it leaves at once. Default false
  • Also needs ec2:RunInstances: the group launches machines on its creator’s authority. Machines are spread evenly across availabilityZoneIds and registered with every load balancer in loadBalancerIds once running.

dcloud autoscaling groups get

Describe a group: machines, policies, schedules, refreshes and activity

GET /autoscaling/api/groups/{id} — IAM autoscaling:DescribeAutoScalingGroups — read

dcloud autoscaling groups get <id>

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<id> --id string /^asg-[0-9a-f]{8}$/

dcloud autoscaling groups update

Change sizes, zones, balancers, health checks, template version or suspended processes

PATCH /autoscaling/api/groups/{id} — IAM autoscaling:UpdateAutoScalingGroup — write

dcloud autoscaling groups update <id> [flags]

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<id> --id string /^asg-[0-9a-f]{8}$/
Flag In Required Notes
--launch-template-version <json> body JSON
--min-size <number> body integer, 0-100
--max-size <number> body integer, 0-100
--desired-capacity <number> body integer, 0-100
--availability-zone-ids <value> body repeatable · /^[a-z]+[0-9]+[a-z]$/
--subnet-ids <value> body repeatable
--load-balancer-ids <value> body repeatable
--health-check-type <ec2|lb> body
--health-check-grace-period-seconds <number> body integer, 0-7200
--default-cooldown-seconds <number> body integer, 0-3600
--default-instance-warmup-seconds <number> body integer, 0-3600
--suspended-processes <Launch|Terminate|HealthCheck|ReplaceUnhealthy|AlarmNotification|ScheduledActions> body repeatable · Paused processes, the whole set: Launch, Terminate, HealthCheck, ReplaceUnhealthy, AlarmNotification, ScheduledActions
--instance-types <value> body repeatable · /^[a-z0-9-]{2,24}$/ · Instance types to use, in order, when the first choice is sold out (like AWS overrides), e.g. performance-4. Same CPU architecture as the template; the provider’s own type names are still accepted, deprecated
--capacity-fallback <json> body JSON · What a create may fall back to when the provider is out of stock
--defer-scale-in-until-paid-hour body Cloud machines are billed per started hour: a machine picked for scale-in keeps serving until the last 5 minutes of its paid hour, and the one whose hour ends first is picked. On own hosts (no hourly increment) it leaves at once. Default false

dcloud autoscaling groups set-desired-capacity

Set how many machines the group runs (within min and max)

PUT /autoscaling/api/groups/{id}/desired-capacity — IAM autoscaling:SetDesiredCapacity — write

dcloud autoscaling groups set-desired-capacity <id> --desired-capacity <number>

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<id> --id string /^asg-[0-9a-f]{8}$/
Flag In Required Notes
--desired-capacity <number> body yes integer, 0-100

dcloud autoscaling groups terminate-instance

Terminate one machine; the group replaces it unless told to shrink

POST /autoscaling/api/groups/{id}/instances/{instanceId}/terminate — IAM autoscaling:TerminateInstanceInAutoScalingGroup — write

dcloud autoscaling groups terminate-instance <id> <instanceId> [flags]

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<id> --id string /^asg-[0-9a-f]{8}$/
<instanceId> --instance-id string /^i-[0-9a-f]{6,32}$/
Flag In Required Notes
--decrement-desired-capacity body true: the group shrinks by one; false (default): the group replaces it

dcloud autoscaling groups set-instance-protection

Protect a machine from scale-in, or lift the protection

PUT /autoscaling/api/groups/{id}/instances/{instanceId}/protection — IAM autoscaling:SetInstanceProtection — write

dcloud autoscaling groups set-instance-protection <id> <instanceId> --protected-from-scale-in

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<id> --id string /^asg-[0-9a-f]{8}$/
<instanceId> --instance-id string /^i-[0-9a-f]{6,32}$/
Flag In Required Notes
--protected-from-scale-in body yes Scale-in never picks a protected machine
  • A machine can protect itself while busy (a CI runner during a job) through its instance identity: PUT /api/instance/v1/autoscaling/protection. A group whose excess machines are all protected stays above its desired capacity (scaleInBlockedByProtection in describe).

dcloud autoscaling groups complete-lifecycle-action

Let a machine held by the termination lifecycle hook be terminated now

POST /autoscaling/api/groups/{id}/instances/{instanceId}/complete-lifecycle-action — IAM autoscaling:CompleteLifecycleAction — write

dcloud autoscaling groups complete-lifecycle-action <id> <instanceId> [flags]

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<id> --id string /^asg-[0-9a-f]{8}$/
<instanceId> --instance-id string /^i-[0-9a-f]{6,32}$/
Flag In Required Notes
--result <CONTINUE|ABANDON> body Default CONTINUE; for a termination hook both terminate the machine now

dcloud autoscaling groups record-lifecycle-heartbeat

Hold a leaving machine for one more heartbeat timeout (at most 48 h in all)

POST /autoscaling/api/groups/{id}/instances/{instanceId}/lifecycle-heartbeat — IAM autoscaling:RecordLifecycleActionHeartbeat — write

dcloud autoscaling groups record-lifecycle-heartbeat <id> <instanceId>

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<id> --id string /^asg-[0-9a-f]{8}$/
<instanceId> --instance-id string /^i-[0-9a-f]{6,32}$/

dcloud autoscaling groups put-lifecycle-hook

Create or replace the termination lifecycle hook: a leaving machine waits until it is done

PUT /autoscaling/api/groups/{id}/lifecycle-hooks — IAM autoscaling:PutLifecycleHook — write

dcloud autoscaling groups put-lifecycle-hook <id> --name <value> [flags]

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<id> --id string /^asg-[0-9a-f]{8}$/
Flag In Required Notes
--name <value> body yes 1-48 chars, /^[a-zA-Z0-9][a-zA-Z0-9._-]*$/
--transition <terminating> body terminating (the only one today): a leaving machine waits; default terminating
--heartbeat-timeout-seconds <number> body integer, 30-7200 · How long a leaving machine is held without a heartbeat; default 3600. Heartbeats extend it, up to 48 h
--default-result <CONTINUE|ABANDON> body What the timeout counts as; for a termination hook both terminate. Default CONTINUE
  • The machine reads its state at GET /api/instance/v1/autoscaling/lifecycle and completes it with POST /api/instance/v1/autoscaling/lifecycle/complete, or the API does. One hook per transition.

dcloud autoscaling groups delete-lifecycle-hook

Delete a lifecycle hook; machines it holds go on to termination

DELETE /autoscaling/api/groups/{id}/lifecycle-hooks/{hookName} — IAM autoscaling:DeleteLifecycleHook — write

dcloud autoscaling groups delete-lifecycle-hook <id> <hookName>

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<id> --id string /^asg-[0-9a-f]{8}$/
<hookName> --hook-name string 1-48 chars, /^[a-zA-Z0-9][a-zA-Z0-9._-]*$/

dcloud autoscaling groups delete

Delete a group: its machines are deregistered and terminated, then the group goes

DELETE /autoscaling/api/groups/{id} — IAM autoscaling:DeleteAutoScalingGroup — write

dcloud autoscaling groups delete <id>

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<id> --id string /^asg-[0-9a-f]{8}$/

dcloud autoscaling policies

Scaling policies: target tracking on a metric, or steps on a monitoring alarm

Operation Method Path IAM action Effect
put-target-tracking PUT /autoscaling/api/groups/{id}/policies autoscaling:PutScalingPolicy write
put-step PUT /autoscaling/api/groups/{id}/policies autoscaling:PutScalingPolicy write
delete DELETE /autoscaling/api/groups/{id}/policies/{policyId} autoscaling:DeletePolicy write

dcloud autoscaling policies put-target-tracking

Create or replace a target-tracking policy (keep a metric near a value)

PUT /autoscaling/api/groups/{id}/policies — IAM autoscaling:PutScalingPolicy — write

dcloud autoscaling policies put-target-tracking <id> --name <value> --metric <cpu_percent|network_in_bps|network_out_bps> --target-value <number> [flags]

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<id> --id string /^asg-[0-9a-f]{8}$/
Flag In Required Notes
--name <value> body yes 1-48 chars, /^[a-zA-Z0-9][a-zA-Z0-9._-]*$/
--enabled body
--metric <cpu_percent|network_in_bps|network_out_bps> body yes cpu_percent is 0–100 % of the machine, whatever its vCPU count
--target-value <number> body yes min 1
--disable-scale-in body
  • Sent automatically: type="target_tracking". This is what separates this verb from its siblings on the same route.
  • Capacity follows ceil(warm machines measured × value / target); machines still warming are not measured and not counted twice. Scale-out is immediate; scale-in waits until nothing is warming, for the group’s cooldown and for the metric to be 10 % under target.

dcloud autoscaling policies put-step

Create or replace a step policy driven by any monitoring alarm

PUT /autoscaling/api/groups/{id}/policies — IAM autoscaling:PutScalingPolicy — write

dcloud autoscaling policies put-step <id> --name <value> --alarm-id <value> --adjustment-type <change_in_capacity|exact_capacity|percent_change_in_capacity> --step-adjustments <value> [flags]

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<id> --id string /^asg-[0-9a-f]{8}$/
Flag In Required Notes
--name <value> body yes 1-48 chars, /^[a-zA-Z0-9][a-zA-Z0-9._-]*$/
--enabled body
--alarm-id <value> body yes A monitoring alarm; its ALARM state triggers the steps
--adjustment-type <change_in_capacity|exact_capacity|percent_change_in_capacity> body yes
--step-adjustments <value> body yes repeatable · [{lowerBound, upperBound, adjustment}] over metric − threshold, [lower, upper)
--cooldown-seconds <number> body integer, 0-3600
  • Sent automatically: type="step". This is what separates this verb from its siblings on the same route.

dcloud autoscaling policies delete

Delete a scaling policy

DELETE /autoscaling/api/groups/{id}/policies/{policyId} — IAM autoscaling:DeletePolicy — write

dcloud autoscaling policies delete <id> <policyId>

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<id> --id string /^asg-[0-9a-f]{8}$/
<policyId> --policy-id string /^asp-[0-9a-f]{8}$/

dcloud autoscaling scheduled-actions

Changes to a group’s sizes at set times (cron, UTC) or once

Operation Method Path IAM action Effect
put PUT /autoscaling/api/groups/{id}/scheduled-actions autoscaling:PutScheduledUpdateGroupAction write
delete DELETE /autoscaling/api/groups/{id}/scheduled-actions/{actionId} autoscaling:DeleteScheduledAction write

dcloud autoscaling scheduled-actions put

Create or replace a scheduled action

PUT /autoscaling/api/groups/{id}/scheduled-actions — IAM autoscaling:PutScheduledUpdateGroupAction — write

dcloud autoscaling scheduled-actions put <id> --name <value> [flags]

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<id> --id string /^asg-[0-9a-f]{8}$/
Flag In Required Notes
--name <value> body yes 1-48 chars, /^[a-zA-Z0-9][a-zA-Z0-9._-]*$/
--recurrence <value> body max 100 chars · Five-field cron, UTC, e.g. "0 7 * * 1-5"
--start-time <value> body One-off: when. Recurring: not before
--end-time <value> body Recurring: not after
--min-size <number> body integer, 0-100
--max-size <number> body integer, 0-100
--desired-capacity <number> body integer, 0-100

dcloud autoscaling scheduled-actions delete

Delete a scheduled action

DELETE /autoscaling/api/groups/{id}/scheduled-actions/{actionId} — IAM autoscaling:DeleteScheduledAction — write

dcloud autoscaling scheduled-actions delete <id> <actionId>

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<id> --id string /^asg-[0-9a-f]{8}$/
<actionId> --action-id string /^asa-[0-9a-f]{8}$/

dcloud autoscaling instance-refreshes

Roll a group onto its current launch template version, one surge machine at a time

Operation Method Path IAM action Effect
start POST /autoscaling/api/groups/{id}/instance-refreshes autoscaling:StartInstanceRefresh write
cancel POST /autoscaling/api/groups/{id}/instance-refreshes/cancel autoscaling:CancelInstanceRefresh write

dcloud autoscaling instance-refreshes start

Start replacing every machine not on the group’s current template version

POST /autoscaling/api/groups/{id}/instance-refreshes — IAM autoscaling:StartInstanceRefresh — write

dcloud autoscaling instance-refreshes start <id> [flags]

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<id> --id string /^asg-[0-9a-f]{8}$/
Flag In Required Notes
--instance-warmup-seconds <number> body integer, 0-3600 · Seconds a new machine serves before the next old one goes; default the group’s
  • One extra machine is launched first; an old one is terminated only after the new one has served for the warmup. The group never drops below its desired capacity.

dcloud autoscaling instance-refreshes cancel

Stop the refresh in progress where it is

POST /autoscaling/api/groups/{id}/instance-refreshes/cancel — IAM autoscaling:CancelInstanceRefresh — write

dcloud autoscaling instance-refreshes cancel <id>

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<id> --id string /^asg-[0-9a-f]{8}$/

dcloud lb

Load balancing. Base path /lb/api.

dcloud lb load-balancers

Layer 4/7 load balancers in front of instances or addresses

Operation Method Path IAM action Effect
list GET /lb/api/load-balancers lb:DescribeLoadBalancers read
create POST /lb/api/load-balancers lb:CreateLoadBalancer write
get GET /lb/api/load-balancers/{id} lb:DescribeLoadBalancers read
update PATCH /lb/api/load-balancers/{id} lb:SetWebAcl write
delete DELETE /lb/api/load-balancers/{id} lb:DeleteLoadBalancer write
live GET /lb/api/load-balancers/{id}/live lb:DescribeLoadBalancers read

dcloud lb load-balancers list

List load balancers

GET /lb/api/load-balancers — IAM lb:DescribeLoadBalancers — read

dcloud lb load-balancers list

dcloud lb load-balancers create

Create a load balancer

POST /lb/api/load-balancers — IAM lb:CreateLoadBalancer — write

dcloud lb load-balancers create --name <value> --type <lb11|lb21|lb31|application|dedicated> --region-id <value> [flags]
Flag In Required Notes
--name <value> body yes 1-64 chars · Name shown in the console, 1–64 characters. Not unique: two load balancers may share one. An application load balancer’s platform name is <name>-<id8>.lb.apps.…
--type <lb11|lb21|lb31|application|dedicated> body yes Required (the console's form starts on lb11). lb11/lb21/lb31: a network load balancer of that size (tcp/http/https, VPC targets). application: an HTTP/HTTPS load balancer on the shared Deutsche Cloud fleet: its own name under lb.apps, per-request access logs, live numbers, health checks every second; http on 80 and https on 443 only, public targets only. dedicated: its own address on the Deutsche Cloud fleet, tcp/http/https on any port; public (own IPv4 + IPv6) or private (scheme private + vpcId: an address in the VPC only). In an organization whose load balancers run on its own hosts, only application is accepted (409, code provider_unsupported). Fixed at creation
--scheme <public|private> body dedicated type only (400 on any other type): public (default; its own IPv4 and IPv6, public targets; 400 with vpcId) or private (an address in vpcId only, no public address; targets inside that VPC; 400 without vpcId; 409 when the VPC has no address left, at most 5 private load balancers per VPC). Fixed at creation
--algorithm <round_robin|least_connections> body server default "round_robin" · How new connections are spread over healthy targets: round_robin (default) sends each to the next target, least_connections to the least busy
--region-id <value> body yes min 1 chars · Region id, from dcloud ec2 catalog regions. Unknown: 404. Counts against the region’s load balancer quota (20 standard, 2 on a trial; over it: 409)
--vpc-id <value> body uuid · lb11/lb21/lb31: join this VPC, so targets can be reached by their private address (usePrivateIp). dedicated: required with scheme private, refused with public. application: refused (400). Not found: 404; in another region than regionId: 400. Default: no VPC
--tags <key=value> body repeatable · key=value · Tags to set at creation, e.g. {"env": "prod"}: at most 50; keys lowercase, 1–64 characters; values 1–128 characters without spaces. Keys your organization marks required must be present, or the create is refused (400)
--web-acl-id <value> body uuid · nullable · application type only (400 on any other type): a web ACL (dcloud waf web-acls) every request passes before anything else answers. Needs lb:SetWebAcl, and waf:GetWebAcl on the ACL (403); an ACL not in your organization: 404. Absent or null: none
  • It starts with no services and no targets: add a service (listener) and at least one target before it carries traffic. Refused (400) when an organization tag policy requires tags that are missing.

dcloud lb load-balancers get

One load balancer with its services and targets

GET /lb/api/load-balancers/{id} — IAM lb:DescribeLoadBalancers — read

dcloud lb load-balancers get <id>

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<id> --id string uuid

dcloud lb load-balancers update

Attach a web ACL to an application load balancer, or detach it

PATCH /lb/api/load-balancers/{id} — IAM lb:SetWebAcl — write

dcloud lb load-balancers update <id> --web-acl-id <value>

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<id> --id string uuid
Flag In Required Notes
--web-acl-id <value> body yes uuid · nullable · The web ACL every request passes; null detaches it. Required (send null to detach). application type only (400). An ACL not in your organization: 404; without waf:GetWebAcl on it: 403
  • application type only (400 on lb11/lb21/lb31: put a CDN distribution with the ACL in front instead). Needs waf:GetWebAcl on the ACL. The fleet nodes run it within seconds, after TLS and before routing, redirects and error pages; matches are in the access log and under dcloud waf web-acls logs. Rate rules count exactly (one node serves at a time). No extra charge beyond the web ACL itself.

dcloud lb load-balancers delete

Delete a load balancer

DELETE /lb/api/load-balancers/{id} — IAM lb:DeleteLoadBalancer — write

dcloud lb load-balancers delete <id>

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<id> --id string uuid

dcloud lb load-balancers live

Live numbers of an application or dedicated load balancer, from the fleet nodes

GET /lb/api/load-balancers/{id}/live — IAM lb:DescribeLoadBalancers — read

dcloud lb load-balancers live <id>

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<id> --id string uuid
  • application and dedicated types only: per node, its counters for this load balancer (connections, requests, 429s, 421s, handshakes, statuses, bytes) and every target’s health as the node checks it, with when the node reported. The active node serves the traffic; the standby’s numbers are its own.

dcloud lb targets

Instances or IP addresses a load balancer sends traffic to

Operation Method Path IAM action Effect
add POST /lb/api/load-balancers/{id}/targets lb:AddTarget write
remove DELETE /lb/api/load-balancers/{id}/targets/{targetId} lb:RemoveTarget write

dcloud lb targets add

Add an instance or IP address as a target

POST /lb/api/load-balancers/{id}/targets — IAM lb:AddTarget — write

dcloud lb targets add <id> --type <server|ip> [flags]

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<id> --id string uuid
Flag In Required Notes
--type <server|ip> body yes server for a Deutsche Cloud instance, ip for an address
--instance-id <value> body /^i-[0-9a-f]{6,32}$/ · Instance id (i-…). Required when type is server (400 without). The instance must be in your organization (400 "Instance not found") and in the load balancer’s region (400). application and public dedicated: it needs a public IPv4 (400); private dedicated: it must be in the load balancer’s VPC and have an address there (400)
--ip <value> body IPv4 address. Required when type is ip (400 without). application and public dedicated: a public address that is not the platform’s own (400); private dedicated: inside the VPC’s CIDR (400)
--use-private-ip body lb11/lb21/lb31, server targets: reach the instance over its private network address. Needs a load balancer created with vpcId (400). Refused (400) on application; ignored on dedicated, where the scheme decides (private: VPC address, public: public address). Default false
--target-group <value> body /^a-z0-9?$/ · application load balancers: the target group this target serves (lower-case letters, digits and -, 1–32). Rules forward to a group; requests no rule matches go to default. Default default; any other value is refused (400) on the other types. At most 10 groups and 25 targets per application load balancer (400)

dcloud lb targets remove

Remove a target

DELETE /lb/api/load-balancers/{id}/targets/{targetId} — IAM lb:RemoveTarget — write

dcloud lb targets remove <id> <targetId>

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<id> --id string uuid
<targetId> --target-id string uuid

dcloud lb services

Listeners: a protocol and port mapped to a port on the targets

Operation Method Path IAM action Effect
add POST /lb/api/load-balancers/{id}/services lb:AddService write
update PATCH /lb/api/load-balancers/{id}/services/{serviceId} lb:UpdateService write
renew-certificate POST /lb/api/load-balancers/{id}/services/{serviceId}/renew-certificate lb:UpdateService write
delete DELETE /lb/api/load-balancers/{id}/services/{serviceId} lb:DeleteService write

dcloud lb services add

Add a service (listener)

POST /lb/api/load-balancers/{id}/services — IAM lb:AddService — write

dcloud lb services add <id> --protocol <tcp|http|https> --source-port <number> --destination-port <number> [flags]

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<id> --id string uuid
Flag In Required Notes
--protocol <tcp|http|https> body yes What the load balancer speaks on sourcePort. https terminates TLS and needs a certificate (domains, or certificatePem + privateKeyPem), except on an application load balancer, whose platform name is served by the fleet’s own certificate when neither is given. tcp is refused (400) on application load balancers
--source-port <number> body yes integer, 1-65535 · Port the load balancer listens on, 1–65535; one service per port (400 when taken, and port 80 is taken by an https service that redirects). application: http on 80 and https on 443 only (400). dedicated: not 22, 9901 or 9902 (400), at most 10 services. The console’s form starts on 80 (443 for https)
--destination-port <number> body yes integer, 1-65535 · Port on the targets traffic is sent to, 1–65535. The console’s form starts on 80
--proxyprotocol body Prepend the PROXY protocol header to each connection to a target. Default false. Refused (400) on application load balancers, whose targets get X-Forwarded-For and X-Real-IP instead
--health-check-path <value> body HTTP path probed for health when healthCheckProtocol is http (default /). Not checked here; services update requires a leading / and at most 256 characters
--domains <value> body repeatable · 1-253 chars · https only (400 otherwise): names for a certificate Deutsche Cloud issues and renews over DNS-01, at most 50, each up to 253 characters; lower-cased and de-duplicated. Every name (wildcards allowed) must be in one of your Deutsche Cloud hosted zones (400). Not together with certificatePem (400). application: at most 10 names including its platform name, and none another load balancer on the fleet already serves (400)
--certificate-pem <value> body max 65536 chars · https only, instead of domains: your certificate in PEM, leaf first, then the chain; at most 64 KiB. Must parse and match privateKeyPem (400). Never renewed by the platform
--private-key-pem <value> body max 16384 chars · https, with certificatePem (400 with one but not the other): its unencrypted private key in PEM, at most 16 KiB. lb11/lb21/lb31: handed to the provider and not stored by Deutsche Cloud. application and dedicated: stored sealed under the KMS master key, opened only to configure the fleet
--redirect-http body https only: answer port 80 with a 301 redirect to https. Port 80 must be free and the service may not itself listen on 80 (400). Default false in the API; the console’s form ticks it
--health-check-protocol <http|tcp> body http (default): GET the health-check path, 2xx/3xx is healthy. tcp: a connection is enough
--health-check-interval <number> body integer, 1-60 · Seconds between health checks (default 15): 3–60 on lb11/lb21/lb31 (400 below 3), 1–60 on application and dedicated load balancers
--health-check-timeout <number> body integer, 1-60 · Seconds a health check may take, 1–60 and at most the interval (400 above it; default 10)
--health-check-retries <number> body integer, 0-5 · Failed checks in a row before a target stops taking traffic (0–5, default 3). A dead target keeps traffic for about interval × (retries + 1)
--sticky-sessions body http/https: pin each client to one target with a cookie the load balancer sets (default false; refused with 400 on a tcp service)
--sticky-cookie-name <value> body /^[A-Za-z0-9_-]{1,64}$/ · Name of the sticky-session cookie (default EWSLB)
--sticky-cookie-lifetime <number> body integer, 60-604800 · Seconds the sticky-session cookie lasts (60 s – 7 days, default 300)
--health-check-port <number> body integer, 1-65535 · dedicated type only (400 on the others): the port the health check asks, 1–65535 (default: the target port), e.g. an HTTP health endpoint next to a tcp service
--close-on-unhealthy body dedicated tcp only (400 on the other types and protocols): close open connections to a target whose health check answers no (an HTTP status outside 2xx/3xx, retries times in a row); a check that only times out closes nothing. For a database primary endpoint. Default false
  • An https service terminates TLS and needs a certificate: either domains (Deutsche Cloud issues it over DNS-01, so every name must be in one of your hosted zones; the service is created at the provider once it is issued, about a minute, and certificateStatus goes pending → active) or certificatePem + privateKeyPem (attached at once). A name outside your hosted zones is refused (400): the certificate authority cannot check it over HTTP, because port 80 goes to your targets.

dcloud lb services update

Change a service’s health check or sticky sessions

PATCH /lb/api/load-balancers/{id}/services/{serviceId} — IAM lb:UpdateService — write

dcloud lb services update <id> <serviceId> [flags]

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<id> --id string uuid
<serviceId> --service-id string uuid
Flag In Required Notes
--health-check-protocol <http|tcp> body http (default): GET the health-check path, 2xx/3xx is healthy. tcp: a connection is enough
--health-check-path <value> body 1-256 chars, /^// · HTTP path probed for health when healthCheckProtocol is http: starts with /, at most 256 characters (default /)
--health-check-interval <number> body integer, 1-60 · Seconds between health checks (default 15): 3–60 on lb11/lb21/lb31 (400 below 3), 1–60 on application and dedicated load balancers
--health-check-timeout <number> body integer, 1-60 · Seconds a health check may take, 1–60 and at most the interval (400 above it; default 10)
--health-check-retries <number> body integer, 0-5 · Failed checks in a row before a target stops taking traffic (0–5, default 3). A dead target keeps traffic for about interval × (retries + 1)
--sticky-sessions body http/https: pin each client to one target with a cookie the load balancer sets (default false; refused with 400 on a tcp service)
--sticky-cookie-name <value> body /^[A-Za-z0-9_-]{1,64}$/ · Name of the sticky-session cookie (default EWSLB)
--sticky-cookie-lifetime <number> body integer, 60-604800 · Seconds the sticky-session cookie lasts (60 s – 7 days, default 300)
  • Only the fields sent change; the rules across fields are checked against the service as it then is. healthCheckTimeout may not exceed healthCheckInterval, an interval under 3 s is refused on lb11/lb21/lb31, and sticky sessions are refused (400) on a tcp service. The change reaches the load balancer within seconds; an https service still waiting for its certificate gets it when the certificate is served.

dcloud lb services renew-certificate

Issue the https certificate for the service’s domains again now

POST /lb/api/load-balancers/{id}/services/{serviceId}/renew-certificate — IAM lb:UpdateService — write

dcloud lb services renew-certificate <id> <serviceId>

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<id> --id string uuid
<serviceId> --service-id string uuid
  • For a certificate Deutsche Cloud issues (one added with domains): retries a failed one, or renews early. Renewal is otherwise automatic, under 30 days before expiry. Refused (400) for an uploaded certificate.

dcloud lb services delete

Delete a service (listener)

DELETE /lb/api/load-balancers/{id}/services/{serviceId} — IAM lb:DeleteService — write

dcloud lb services delete <id> <serviceId>

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<id> --id string uuid
<serviceId> --service-id string uuid

dcloud lb rules

application load balancers: route requests by host and path to a target group

Operation Method Path IAM action Effect
add POST /lb/api/load-balancers/{id}/rules lb:AddRule write
remove DELETE /lb/api/load-balancers/{id}/rules/{ruleId} lb:RemoveRule write

dcloud lb rules add

Add a host/path rule forwarding to a target group

POST /lb/api/load-balancers/{id}/rules — IAM lb:AddRule — write

dcloud lb rules add <id> --priority <number> --target-group <value> [flags]

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<id> --id string uuid
Flag In Required Notes
--priority <number> body yes integer, 1-1000 · 1–1000, evaluated lowest first; unique per load balancer (a taken one is refused). At most 50 rules
--host <value> body 1-253 chars · One of the load balancer’s own names (its platform name or a name of its https service). Left out: every name it answers to
--path-prefix <value> body 1-256 chars, /^/[^\s?#]$/ · Matches on path segments: /api matches /api, /api/ and /api/v1, not /apix. Left out: any path
--target-group <value> body yes /^a-z0-9?$/ · The target group that serves matching requests
  • application type only (400 on lb11/lb21/lb31). Rules apply to the http and https services alike, lowest priority first; a request no rule matches goes to the default target group. A rule whose group has no target answers 503 and never falls through to another group (the load balancer’s application.warnings says so). The host must be one of the load balancer’s own names. Live within seconds; no provider work. To change a rule, remove it and add it again. The console suggests priority 10, then 10 above the highest.

dcloud lb rules remove

Remove a rule

DELETE /lb/api/load-balancers/{id}/rules/{ruleId} — IAM lb:RemoveRule — write

dcloud lb rules remove <id> <ruleId>

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<id> --id string uuid
<ruleId> --rule-id string uuid

dcloud rds

Postgres. Base path /rds/api.

dcloud rds instances

Managed Postgres databases, single-node or Patroni clusters

Operation Method Path IAM action Effect
list GET /rds/api/instances rds:DescribeDBInstances read
create POST /rds/api/instances rds:CreateDBInstance write
get GET /rds/api/instances/{id} rds:DescribeDBInstances read
delete DELETE /rds/api/instances/{id} rds:DeleteDBInstance write
start PATCH /rds/api/instances/{id} rds:StartDBInstance write
stop PATCH /rds/api/instances/{id} rds:StopDBInstance write
reboot PATCH /rds/api/instances/{id} rds:RebootDBInstance write
events GET /rds/api/instances/{id}/events rds:DescribeDBInstances read
rotate-master-password POST /rds/api/instances/{id}/master-password/rotate rds:ModifyDBInstance write
modify-backup-settings PATCH /rds/api/instances/{id}/backup-settings rds:ModifyDBInstance write
set-deletion-protection PATCH /rds/api/instances/{id}/deletion-protection rds:ModifyDBInstance write
modify-storage PATCH /rds/api/instances/{id}/storage rds:ModifyDBInstance write
failover POST /rds/api/instances/{id}/failover rds:FailoverDBInstance write
rotate-storage-key POST /rds/api/instances/{id}/rotate-storage-key rds:RotateDBStorageKey write
modify-instance-class PATCH /rds/api/instances/{id}/instance-class rds:ModifyDBInstance write
describe-maintenance GET /rds/api/instances/{id}/maintenance rds:DescribeDBInstances read
modify-maintenance PATCH /rds/api/instances/{id}/maintenance rds:ModifyDBInstance write
logs GET /rds/api/instances/{id}/logs rds:DescribeDBLogFiles read, sensitive
describe-parameters GET /rds/api/instances/{id}/parameters rds:DescribeDBParameters read
modify-parameters PATCH /rds/api/instances/{id}/parameters rds:ModifyDBParameters write
upgrade POST /rds/api/instances/{id}/upgrade rds:ModifyDBInstance write
add-reader POST /rds/api/instances/{id}/readers rds:CreateDBReadReplica write
remove-reader DELETE /rds/api/instances/{id}/readers/{nodeId} rds:DeleteDBReadReplica write
list-nodes GET /rds/api/instances/{id}/nodes rds:DescribeDBInstances read
cluster GET /rds/api/instances/{id}/cluster rds:DescribeDBInstances read

dcloud rds instances list

List database instances

GET /rds/api/instances — IAM rds:DescribeDBInstances — read

dcloud rds instances list [flags]
Flag In Required Notes
--status <available|creating|modifying|backing-up|deleting|failed|stopped|starting|stopping|rebooting|maintenance|waiting-for-capacity|retained> query Only databases in this state
--limit <number> query integer, 1-500 · At most this many (default 100)

dcloud rds instances create

Create a database instance

POST /rds/api/instances — IAM rds:CreateDBInstance — write

dcloud rds instances create --identifier <value> --instance-class <value> [flags]
Flag In Required Notes
--region-id <value> body 1-32 chars · Region to create in (default: the X-EWS-Region header, else de1). fi1 (Helsinki, Finland) needs the organization setting "allow EU outside Germany".
--identifier <value> body yes 3-48 chars, /^[a-z][a-z0-9-]*[a-z0-9]$/ · Name of the database, unique within the organization
--instance-class <value> body yes 1-32 chars · Instance type of every node, from server-types (e.g. performance-2; the provider’s own names are still accepted, deprecated); a cluster needs one with at least 8 GiB of memory
--engine-version <value> body max 16 chars, /^(18|17|16|15|18.7|17.12|17.11|16.16|15.20)$/ · PostgreSQL major (e.g. 17, installed at its current pinned minor) or one of its pinned minors (e.g. 17.11); omitted: PostgreSQL 17
--topology <single|cluster> body server default "single" · single: one node (the default); cluster: three nodes with automatic failover
--db-name <value> body 1-63 chars, /^[a-z][a-z0-9_]*$/ · server default "appdb" · Name of the database created inside the server; appdb when omitted
--master-username <value> body 1-63 chars, /^[a-z][a-z0-9_]*$/ · server default "admin" · Name of the master role, whose password is filed in Secrets; admin when omitted
--allocated-storage-gib <number> body integer, 10-4000 · server default 20 · Size of each node's data volume in GiB; 20 when omitted
--max-allocated-storage-gib <number> body integer, 10-10000 · nullable · Autoscaling ceiling in GiB, not below allocatedStorageGib; null or omitted leaves automatic growth off
--backup-retention-days <number> body integer, 0-35 · server default 7 · Days backups are kept for restores; 0 turns scheduled backups off; 7 when omitted
--tags <key=value> body repeatable · key=value · Tags (key → value) for the database; its nodes' volumes inherit them
--kms-key-id <value> body uuid · KMS key that wraps every node volume's key (needs kms:Encrypt on it); omitted: the platform key
--publicly-accessible body server default false · Whether the database answers on the internet; off by default: reachable only from its VPC
--deletion-protection body server default false · Refuse delete until it is switched off again; off by default
--require-tls body server default true · Refuse clients that do not use TLS, on both ports; on by default
--replication-mode <async|sync> body Cluster only. sync (the default for a cluster): a commit waits for one standby, so a failover loses nothing acknowledged; async: lower commit latency
--zone-placement <spread|single> body Cluster only, fixed after creation. spread (the default for a cluster): members round-robin over the region's zones; single: all in availabilityZoneId
--logical-replication body server default false · wal_level = logical from the first start, for CDC and publications; off by default
--availability-zone-id <value> body /^[a-z]+[0-9]+[a-z]$/ · Zone of a single node or of a single-placement cluster, e.g. de1b; omitted: the region's default zone
--vpc-id <value> body uuid · VPC the database joins; omitted: the organization's default VPC for the region
--subnet-id <value> body uuid · Subnet of that VPC to place the database in; omitted: the VPC's whole range
--capacity-fallback <json> body JSON · What a create may fall back to when the provider is out of stock
--on-stock-out <fail|wait> body When the type is sold out where it goes and no fallback applies: fail at once (default), or wait as waiting-for-capacity (nothing built or billed) until it is back
--capacity-max-wait-hours <number> body integer, 1-168 · With onStockOut wait: give up after this many hours (1–168, default 24)

dcloud rds instances get

Describe one database instance

GET /rds/api/instances/{id} — IAM rds:DescribeDBInstances — read

dcloud rds instances get <id>

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<id> --id string 3-64 chars, /^(?!ewdoc-)[a-z0-9-]+$/
  • encryption.storage is "luks2" (every node's data volume is LUKS2, opened at boot with a per-volume key from KMS) or "none" for a database created before disk encryption; those keep plain volumes and move by restoring into a new database. encryption.backups is "aes-256-cbc" (pgBackRest, encrypted on the database machine before upload) or "none" for a database created before backup encryption.

dcloud rds instances delete

Delete a database instance and its machines

DELETE /rds/api/instances/{id} — IAM rds:DeleteDBInstance — write

dcloud rds instances delete <id> [flags]

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<id> --id string 3-64 chars, /^(?!ewdoc-)[a-z0-9-]+$/
Flag In Required Notes
--final-backup <true|false> query true: take a full backup first and keep the backups for the retention period, as a retained database that can be restored from
  • Refused with 400 while deletion protection is enabled. With finalBackup=true a full backup is taken first; if it fails nothing is deleted. The database then stays as retained (no machines, backups kept) until its retention period ends, and can be restored from. Deleting a retained database removes its backups at once.

dcloud rds instances start

Start a stopped database instance

PATCH /rds/api/instances/{id} — IAM rds:StartDBInstance — write

dcloud rds instances start <id>

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<id> --id string 3-64 chars, /^(?!ewdoc-)[a-z0-9-]+$/
  • Sent automatically: action="start". This is what separates this verb from its siblings on the same route.

dcloud rds instances stop

Stop a running database instance

PATCH /rds/api/instances/{id} — IAM rds:StopDBInstance — write

dcloud rds instances stop <id>

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<id> --id string 3-64 chars, /^(?!ewdoc-)[a-z0-9-]+$/
  • Sent automatically: action="stop". This is what separates this verb from its siblings on the same route.

dcloud rds instances reboot

Reboot a database instance

PATCH /rds/api/instances/{id} — IAM rds:RebootDBInstance — write

dcloud rds instances reboot <id>

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<id> --id string 3-64 chars, /^(?!ewdoc-)[a-z0-9-]+$/
  • Sent automatically: action="reboot". This is what separates this verb from its siblings on the same route.

dcloud rds instances events

The activity stream of a database: the newest events, oldest first

GET /rds/api/instances/{id}/events — IAM rds:DescribeDBInstances — read

dcloud rds instances events <id> [flags]

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<id> --id string 3-64 chars, /^(?!ewdoc-)[a-z0-9-]+$/
Flag In Required Notes
--since <value> query Only events after this ISO time, for polling; omitted: from the first event
--limit <number> query integer, 1-500 · At most this many events (default 200)

dcloud rds instances rotate-master-password

Rotate the master password and file the new version in Secrets

POST /rds/api/instances/{id}/master-password/rotate — IAM rds:ModifyDBInstance — write

dcloud rds instances rotate-master-password <id>

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<id> --id string 3-64 chars, /^(?!ewdoc-)[a-z0-9-]+$/

dcloud rds instances modify-backup-settings

Change backup retention or the daily backup window

PATCH /rds/api/instances/{id}/backup-settings — IAM rds:ModifyDBInstance — write

dcloud rds instances modify-backup-settings <id> [flags]

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<id> --id string 3-64 chars, /^(?!ewdoc-)[a-z0-9-]+$/
Flag In Required Notes
--backup-retention-days <number> body integer, 0-35 · Days backups are kept; 0 turns scheduled backups off; omitted: unchanged
--backup-window <value> body /^([01]\d|2[0-3]):[0-5]\d-([01]\d|2[0-3]):[0-5]\d$/ · When the daily backup runs, HH:MM-HH:MM (only the start is used; 03:00-04:00 by default); omitted: unchanged

dcloud rds instances set-deletion-protection

Turn deletion protection on or off; while on, delete is refused

PATCH /rds/api/instances/{id}/deletion-protection — IAM rds:ModifyDBInstance — write

dcloud rds instances set-deletion-protection <id> --enabled

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<id> --id string 3-64 chars, /^(?!ewdoc-)[a-z0-9-]+$/
Flag In Required Notes
--enabled body yes true: refuse delete; false: allow it again

dcloud rds instances modify-storage

Resize storage or change the autoscaling ceiling

PATCH /rds/api/instances/{id}/storage — IAM rds:ModifyDBInstance — write

dcloud rds instances modify-storage <id> [flags]

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<id> --id string 3-64 chars, /^(?!ewdoc-)[a-z0-9-]+$/
Flag In Required Notes
--allocated-storage-gib <number> body integer, 10-10000 · New size of every node's data volume in GiB; storage only grows. Omitted: unchanged
--max-allocated-storage-gib <number> body integer, 10-10000 · nullable · Autoscaling ceiling in GiB, not below the storage size; null turns automatic growth off; omitted: unchanged

dcloud rds instances failover

Promote a replica and demote the current primary

POST /rds/api/instances/{id}/failover — IAM rds:FailoverDBInstance — write

dcloud rds instances failover <id>

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<id> --id string 3-64 chars, /^(?!ewdoc-)[a-z0-9-]+$/

dcloud rds instances rotate-storage-key

Replace the LUKS passphrase of every node’s data volume with a new key

POST /rds/api/instances/{id}/rotate-storage-key — IAM rds:RotateDBStorageKey — write

dcloud rds instances rotate-storage-key <id>

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<id> --id string 3-64 chars, /^(?!ewdoc-)[a-z0-9-]+$/
  • Answers 202 with each volume’s key version. Each node adds the new key, removes the old one and reports within five minutes; nothing restarts. Nodes built before key rotation existed do not poll for it: replace them or restore into a new database. The dm-crypt volume key itself is not changed.

dcloud rds instances modify-instance-class

Change the machine type; a cluster is resized node by node and stays available

PATCH /rds/api/instances/{id}/instance-class — IAM rds:ModifyDBInstance — write

dcloud rds instances modify-instance-class <id> --instance-class <value>

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<id> --id string 3-64 chars, /^(?!ewdoc-)[a-z0-9-]+$/
Flag In Required Notes
--instance-class <value> body yes 1-32 chars · The new instance type, e.g. performance-8. The provider’s own type names are still accepted, deprecated.

dcloud rds instances describe-maintenance

Versions per node, the pending minor upgrade, the maintenance window and when it next opens

GET /rds/api/instances/{id}/maintenance — IAM rds:DescribeDBInstances — read

dcloud rds instances describe-maintenance <id>

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<id> --id string 3-64 chars, /^(?!ewdoc-)[a-z0-9-]+$/

dcloud rds instances modify-maintenance

Set the maintenance window (UTC) and automatic minor upgrades

PATCH /rds/api/instances/{id}/maintenance — IAM rds:ModifyDBInstance — write

dcloud rds instances modify-maintenance <id> [flags]

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<id> --id string 3-64 chars, /^(?!ewdoc-)[a-z0-9-]+$/
Flag In Required Notes
--maintenance-window <value> body max 32 chars, /^(sun|mon|tue|wed|thu|fri|sat):([01]\d|2[0-3]):[0-5]\d-(sun|mon|tue|wed|thu|fri|sat):([01]\d|2[0-3]):[0-5]\d$/i · UTC, ddd:hh24:mi-ddd:hh24:mi, one hour to one day, e.g. sun:05:00-sun:06:00 (the default); omitted: unchanged
--auto-minor-version-upgrade body Apply new minor versions in the window automatically (on by default); omitted: unchanged

dcloud rds instances logs

The PostgreSQL server log from every node, newest first; filter by text, node or severity. Kept 7 days

GET /rds/api/instances/{id}/logs — IAM rds:DescribeDBLogFiles — read, sensitive

dcloud rds instances logs <id> [flags]

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<id> --id string 3-64 chars, /^(?!ewdoc-)[a-z0-9-]+$/
Flag In Required Notes
--start <value> query ISO time the lines start at; a day before end when omitted
--end <value> query ISO time the lines end at; now when omitted
--contains <value> query max 200 chars · Only lines containing this text
--node <number> query integer, 1-99 · Only this node, by its ordinal (1 for the first); omitted: every node
--severity <debug|info|notice|log|warning|error|fatal|panic> query Only lines of this severity; omitted: all
--limit <number> query integer, 1-1000 · At most this many lines (default 200)

dcloud rds instances describe-parameters

Every settable PostgreSQL parameter: its machine-sized default, your value, what runs now

GET /rds/api/instances/{id}/parameters — IAM rds:DescribeDBParameters — read

dcloud rds instances describe-parameters <id>

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<id> --id string 3-64 chars, /^(?!ewdoc-)[a-z0-9-]+$/

dcloud rds instances modify-parameters

Set or reset PostgreSQL parameters; most apply at once, the answer lists those that wait for a restart

PATCH /rds/api/instances/{id}/parameters — IAM rds:ModifyDBParameters — write

dcloud rds instances modify-parameters <id> --parameters <key=value>

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<id> --id string 3-64 chars, /^(?!ewdoc-)[a-z0-9-]+$/
Flag In Required Notes
--parameters <key=value> body yes repeatable · key=value · Parameter name → value ("32MB", "30s", "on"), or null to return it to its machine-sized default; parameters not named keep their value

dcloud rds instances upgrade

Upgrade to a newer minor now: a cluster rolls node by node with one switchover, a single node restarts once

POST /rds/api/instances/{id}/upgrade — IAM rds:ModifyDBInstance — write

dcloud rds instances upgrade <id> [flags]

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<id> --id string 3-64 chars, /^(?!ewdoc-)[a-z0-9-]+$/
Flag In Required Notes
--engine-version <value> body 1-16 chars · A pinned minor (e.g. 17.11) or a major (e.g. 18, meaning its pinned minor): the database's own major, or a newer one for a major upgrade; omitted: the newest pinned minor of its major

dcloud rds instances add-reader

Add a read replica to a cluster; it serves on the reader endpoint (5433, 6433) once streaming

POST /rds/api/instances/{id}/readers — IAM rds:CreateDBReadReplica — write

dcloud rds instances add-reader <id>

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<id> --id string 3-64 chars, /^(?!ewdoc-)[a-z0-9-]+$/

dcloud rds instances remove-reader

Remove a read replica, its machine and its volume

DELETE /rds/api/instances/{id}/readers/{nodeId} — IAM rds:DeleteDBReadReplica — write

dcloud rds instances remove-reader <id> <nodeId>

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<id> --id string 3-64 chars, /^(?!ewdoc-)[a-z0-9-]+$/
<nodeId> --node-id string

dcloud rds instances list-nodes

List the machines backing a database instance

GET /rds/api/instances/{id}/nodes — IAM rds:DescribeDBInstances — read

dcloud rds instances list-nodes <id>

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<id> --id string 3-64 chars, /^(?!ewdoc-)[a-z0-9-]+$/

dcloud rds instances cluster

Show Patroni cluster membership and replication state

GET /rds/api/instances/{id}/cluster — IAM rds:DescribeDBInstances — read

dcloud rds instances cluster <id>

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<id> --id string 3-64 chars, /^(?!ewdoc-)[a-z0-9-]+$/

dcloud rds backups

pgBackRest backups and point-in-time restores

Operation Method Path IAM action Effect
list GET /rds/api/instances/{id}/backups rds:ListBackups read
create POST /rds/api/instances/{id}/backups rds:CreateBackup write
delete DELETE /rds/api/instances/{id}/backups/{backupId} rds:DeleteBackup write
list-restore-jobs GET /rds/api/instances/{id}/restore-jobs rds:ListBackups read
restore POST /rds/api/instances/{id}/restore rds:RestoreDBInstance write
cancel-restore DELETE /rds/api/restore-jobs/{jobId} rds:RestoreDBInstance write

dcloud rds backups list

List backups and the recoverable window

GET /rds/api/instances/{id}/backups — IAM rds:ListBackups — read

dcloud rds backups list <id>

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<id> --id string 3-64 chars, /^(?!ewdoc-)[a-z0-9-]+$/

dcloud rds backups create

Take a backup now

POST /rds/api/instances/{id}/backups — IAM rds:CreateBackup — write

dcloud rds backups create <id>

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<id> --id string 3-64 chars, /^(?!ewdoc-)[a-z0-9-]+$/
  • On a database whose nodes run backup poller 3 (keepsByHand in the list), the backup is kept until you delete it, at most 20 per database; otherwise it follows the retention window.

dcloud rds backups delete

Delete a backup taken by hand that is kept until deleted

DELETE /rds/api/instances/{id}/backups/{backupId} — IAM rds:DeleteBackup — write

dcloud rds backups delete <id> <backupId>

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<id> --id string 3-64 chars, /^(?!ewdoc-)[a-z0-9-]+$/
<backupId> --backup-id string
  • Older than the retention window, it is expired at once and the node removes it from the repository within a minute; inside the window it follows the window from now on. A backup that follows the window anyway is refused with 409.

dcloud rds backups list-restore-jobs

List restore jobs for a database instance

GET /rds/api/instances/{id}/restore-jobs — IAM rds:ListBackups — read

dcloud rds backups list-restore-jobs <id>

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<id> --id string 3-64 chars, /^(?!ewdoc-)[a-z0-9-]+$/

dcloud rds backups restore

Restore to latest, to a timestamp, or to a labelled backup

POST /rds/api/instances/{id}/restore — IAM rds:RestoreDBInstance — write

dcloud rds backups restore <id> --recovery-target <latest|time|label> [flags]

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<id> --id string 3-64 chars, /^(?!ewdoc-)[a-z0-9-]+$/
Flag In Required Notes
--recovery-target <latest|time|label> body yes Selects which of the other fields apply
--target-identifier <value> body 1-63 chars · Name of the new database the restore creates; a restore never overwrites its source
--instance-class <value> body min 1 chars · Instance type of the new database, e.g. performance-2 (provider names deprecated); omitted: the source's
--topology <single|cluster> body single (the default) or cluster: three nodes, the class needs 8 GiB of memory or more
--kms-key-id <value> body uuid · nullable · KMS key for the new database's disks; null: the platform key; omitted: the source's
--publicly-accessible body Whether the new database answers on the internet; omitted: the source's choice
--tags <key=value> body repeatable · key=value · Tags for the new resource, e.g. {"env": "prod", "project": "shop"}. Keys your organization marks required must be present, or the create is refused with the missing keys (GET /tags/api/keys lists them).
--recovery-target-time <value> body datetime · ISO time to restore to; must lie inside the recoverable window of backups list
--recovery-target-label <value> body 1-128 chars, /^[A-Za-z0-9_-]+$/ · Label of the backup to restore, as backups list shows it (e.g. 20260826-030000F)
  • The body is a union of 3 shapes (latest, time, label). The flags above are the union of every branch, so the server decides which combination is legal.

dcloud rds backups cancel-restore

Withdraw a restore request that has not started

DELETE /rds/api/restore-jobs/{jobId} — IAM rds:RestoreDBInstance — write

dcloud rds backups cancel-restore <jobId>

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<jobId> --job-id string uuid
  • Refused with 409 once the restore is past queued: delete the database it is building instead. Cancelling also removes the placeholder target database, provided nothing has been provisioned for it yet.

dcloud rds query-insights

Sampled statement history (pg_stat_statements, every minute, 7 days), findings with suggested actions, running sessions and the slow query log

Operation Method Path IAM action Effect
get GET /rds/api/instances/{id}/insights rds:DescribeDBQueryInsights read
get-statement GET /rds/api/instances/{id}/insights/statements/{statementId} rds:DescribeDBQueryInsights read
list-tables GET /rds/api/instances/{id}/insights/tables rds:DescribeDBQueryInsights read
list-sessions GET /rds/api/instances/{id}/insights/sessions rds:DescribeDBQueryInsights read
cancel-session POST /rds/api/instances/{id}/insights/sessions/{pid} rds:CancelDBSession write
get-slow-log GET /rds/api/instances/{id}/insights/slow-log rds:DescribeDBQueryInsights read
update-settings PATCH /rds/api/instances/{id}/insights/settings rds:ModifyDBQueryInsights write

dcloud rds query-insights get

Statements of the range with load, trends and findings

GET /rds/api/instances/{id}/insights — IAM rds:DescribeDBQueryInsights — read

dcloud rds query-insights get <id> [flags]

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<id> --id string 3-64 chars, /^(?!ewdoc-)[a-z0-9-]+$/
Flag In Required Notes
--range <1h|24h|7d> query server default "24h" · 1h by the minute, 24h by 15 minutes, 7d by 2 hours
  • Statement text is normalised (no literal values). Each statement carries its sqlfp1 fingerprint, the key Error Tracking links by.

dcloud rds query-insights get-statement

One statement with its generic plan and the index it suggests

GET /rds/api/instances/{id}/insights/statements/{statementId} — IAM rds:DescribeDBQueryInsights — read

dcloud rds query-insights get-statement <id> <statementId>

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<id> --id string 3-64 chars, /^(?!ewdoc-)[a-z0-9-]+$/
<statementId> --statement-id string
  • EXPLAIN (GENERIC_PLAN) of the normalised text, never ANALYZE; a suggested index is a CREATE INDEX CONCURRENTLY to run yourself.

dcloud rds query-insights list-tables

Tables and indexes with findings: sequential scans, unused and duplicate indexes, vacuum overdue

GET /rds/api/instances/{id}/insights/tables — IAM rds:DescribeDBQueryInsights — read

dcloud rds query-insights list-tables <id>

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<id> --id string 3-64 chars, /^(?!ewdoc-)[a-z0-9-]+$/

dcloud rds query-insights list-sessions

Client sessions now: what runs, how long, what it waits for, who blocks it

GET /rds/api/instances/{id}/insights/sessions — IAM rds:DescribeDBQueryInsights — read

dcloud rds query-insights list-sessions <id>

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<id> --id string 3-64 chars, /^(?!ewdoc-)[a-z0-9-]+$/

dcloud rds query-insights cancel-session

Cancel a session’s running statement, or end the session

POST /rds/api/instances/{id}/insights/sessions/{pid} — IAM rds:CancelDBSession — write

dcloud rds query-insights cancel-session <id> <pid> --how <cancel|terminate>

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<id> --id string 3-64 chars, /^(?!ewdoc-)[a-z0-9-]+$/
<pid> --pid number integer, min 1
Flag In Required Notes
--how <cancel|terminate> body yes cancel: the running statement; terminate: the session

dcloud rds query-insights get-slow-log

Slow query log settings and the statements (and plans) it captured

GET /rds/api/instances/{id}/insights/slow-log — IAM rds:DescribeDBQueryInsights — read

dcloud rds query-insights get-slow-log <id> [flags]

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<id> --id string 3-64 chars, /^(?!ewdoc-)[a-z0-9-]+$/
Flag In Required Notes
--range <1h|24h|7d> query server default "24h" · 1h by the minute, 24h by 15 minutes, 7d by 2 hours

dcloud rds query-insights update-settings

Slow query log threshold, auto_explain, keeping values

PATCH /rds/api/instances/{id}/insights/settings — IAM rds:ModifyDBQueryInsights — write

dcloud rds query-insights update-settings <id> [flags]

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<id> --id string 3-64 chars, /^(?!ewdoc-)[a-z0-9-]+$/
Flag In Required Notes
--slow-log-ms <number> body integer, -1-3600000 · Log statements slower than this many ms (log_min_duration_statement); -1 is off
--auto-explain body Also log the plan of slow statements (auto_explain, single-node databases)
--plans-with-values body Show logged statements and plans with their literal values (off by default)

dcloud rds data

Reading what is inside the database: its tables, rows and one read-only query

Operation Method Path IAM action Effect
query-stats GET /rds/api/instances/{id}/query-stats rds:DescribeDBQueryStats read, sensitive
list-relations GET /rds/api/instances/{id}/data/relations rds:QueryDatabase read, sensitive
read-rows GET /rds/api/instances/{id}/data/rows rds:QueryDatabase read, sensitive
run-query POST /rds/api/instances/{id}/data/query rds:QueryDatabase read, sensitive

dcloud rds data query-stats

Top statements by time, calls or rows from pg_stat_statements; installed: false until the extension is on

GET /rds/api/instances/{id}/query-stats — IAM rds:DescribeDBQueryStats — read, sensitive

dcloud rds data query-stats <id> [flags]

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<id> --id string 3-64 chars, /^(?!ewdoc-)[a-z0-9-]+$/
Flag In Required Notes
--order <total_time|mean_time|calls|rows> query server default "total_time" · What the statements are ranked by; total_time when omitted
--limit <number> query integer, 1-100 · server default 25 · At most this many statements; 25 when omitted

dcloud rds data list-relations

List schemas and tables with size and an estimated row count

GET /rds/api/instances/{id}/data/relations — IAM rds:QueryDatabase — read, sensitive

dcloud rds data list-relations <id>

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<id> --id string 3-64 chars, /^(?!ewdoc-)[a-z0-9-]+$/

dcloud rds data read-rows

One page of a table's rows, plus its column types

GET /rds/api/instances/{id}/data/rows — IAM rds:QueryDatabase — read, sensitive

dcloud rds data read-rows <id> --schema <value> --table <value> [flags]

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<id> --id string 3-64 chars, /^(?!ewdoc-)[a-z0-9-]+$/
Flag In Required Notes
--schema <value> query yes 1-63 chars · Schema of the table, e.g. public
--table <value> query yes 1-63 chars · Name of the table
--limit <number> query integer, 1-200 · server default 50 · Rows per page; 50 when omitted
--offset <number> query integer, 0-1000000 · server default 0 · Rows to skip, in primary-key order; 0 when omitted

dcloud rds data run-query

Run one read-only statement in a READ ONLY transaction with a statement timeout

POST /rds/api/instances/{id}/data/query — IAM rds:QueryDatabase — read, sensitive

dcloud rds data run-query <id> --sql <value> [flags]

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<id> --id string 3-64 chars, /^(?!ewdoc-)[a-z0-9-]+$/
Flag In Required Notes
--sql <value> body yes 1-20000 chars · One read-only statement; it runs in a READ ONLY transaction with a 15 s timeout
--limit <number> body integer, 1-500 · server default 200 · At most this many rows are returned; 200 when omitted

dcloud rds extensions

Postgres extensions per database: the supported catalog, what is enabled, and the switches

Operation Method Path IAM action Effect
list GET /rds/api/instances/{id}/extensions rds:DescribeDBExtensions read
enable POST /rds/api/instances/{id}/extensions/{extension}/enable rds:EnableDBExtension write
disable POST /rds/api/instances/{id}/extensions/{extension}/disable rds:DisableDBExtension write

dcloud rds extensions list

List supported extensions with installed and available versions, preload state and whether a restart is pending

GET /rds/api/instances/{id}/extensions — IAM rds:DescribeDBExtensions — read

dcloud rds extensions list <id> [flags]

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<id> --id string 3-64 chars, /^(?!ewdoc-)[a-z0-9-]+$/
Flag In Required Notes
--database <value> query 1-63 chars · Database inside the instance; omitted: the one created with the instance

dcloud rds extensions enable

CREATE EXTENSION in a database; 202 when its library must be preloaded and the database restarted first

POST /rds/api/instances/{id}/extensions/{extension}/enable — IAM rds:EnableDBExtension — write

dcloud rds extensions enable <id> <extension> [flags]

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<id> --id string 3-64 chars, /^(?!ewdoc-)[a-z0-9-]+$/
<extension> --extension string 1-63 chars, /^[a-z0-9_-]+$/
Flag In Required Notes
--database <value> body 1-63 chars · Database to create the extension in; omitted: the one created with the instance

dcloud rds extensions disable

DROP EXTENSION; 409 listing dependent objects unless cascade is true

POST /rds/api/instances/{id}/extensions/{extension}/disable — IAM rds:DisableDBExtension — write

dcloud rds extensions disable <id> <extension> [flags]

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<id> --id string 3-64 chars, /^(?!ewdoc-)[a-z0-9-]+$/
<extension> --extension string 1-63 chars, /^[a-z0-9_-]+$/
Flag In Required Notes
--database <value> body 1-63 chars · Database to drop the extension from; omitted: the one created with the instance
--cascade body server default false · Drop the objects that depend on the extension too; off by default, and a drop with dependents is then refused with 409 listing them

dcloud rds server-types

The instance classes a database can be created with

Operation Method Path IAM action Effect
list GET /rds/api/server-types rds:DescribeDBInstances read

dcloud rds server-types list

List available database instance classes

GET /rds/api/server-types — IAM rds:DescribeDBInstances — read

dcloud rds server-types list

dcloud rds ca-bundle

The platform CA that signs every database server certificate

Operation Method Path IAM action Effect
download GET /rds/api/ca-bundle rds:DescribeDBInstances read

dcloud rds ca-bundle download

Download the CA bundle to use with sslmode=verify-full

GET /rds/api/ca-bundle — IAM rds:DescribeDBInstances — read

dcloud rds ca-bundle download
  • Returns raw bytes with their own content type, written straight to stdout.
  • One CA per installation, so the same file for every database in every org — it is not scoped to an instance on purpose.

dcloud rds tls

Whether a database refuses clients that do not use TLS, and which clients would break

Operation Method Path IAM action Effect
get GET /rds/api/instances/{id}/tls rds:DescribeDBInstances read
set PATCH /rds/api/instances/{id}/tls rds:ModifyDBInstance write

dcloud rds tls get

The TLS requirement and certificate; with clients=true, every client connected without TLS on either port

GET /rds/api/instances/{id}/tls — IAM rds:DescribeDBInstances — read

dcloud rds tls get <id> [flags]

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<id> --id string 3-64 chars, /^(?!ewdoc-)[a-z0-9-]+$/
Flag In Required Notes
--clients <true|false> query server default "false" · Also list the clients connected without TLS right now

dcloud rds tls set

Require TLS (hostssl, PgBouncer require) or stop requiring it, on every node; verified by a plaintext probe

PATCH /rds/api/instances/{id}/tls — IAM rds:ModifyDBInstance — write

dcloud rds tls set <id> --required

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<id> --id string 3-64 chars, /^(?!ewdoc-)[a-z0-9-]+$/
Flag In Required Notes
--required body yes true: refuse plaintext clients on ports 5432 and 6432; false: accept them again. Open sessions are not cut
  • Open sessions are not cut: pg_hba and the pooler are consulted when a connection starts, so a plaintext client breaks at its next reconnect.

dcloud rds replication

Whether a cluster commits synchronously (a failover loses nothing acknowledged) or asynchronously

Operation Method Path IAM action Effect
get GET /rds/api/instances/{id}/replication rds:DescribeDBInstances read
set PATCH /rds/api/instances/{id}/replication rds:ModifyDBInstance write

dcloud rds replication get

The replication mode and whether it holds right now: ok, degraded (no standby acknowledging), async

GET /rds/api/instances/{id}/replication — IAM rds:DescribeDBInstances — read

dcloud rds replication get <id>

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<id> --id string 3-64 chars, /^(?!ewdoc-)[a-z0-9-]+$/

dcloud rds replication set

Make a cluster synchronous or asynchronous (live, no restart), and/or turn logical replication on or off (with a restart)

PATCH /rds/api/instances/{id}/replication — IAM rds:ModifyDBInstance — write

dcloud rds replication set <id> [flags]

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<id> --id string 3-64 chars, /^(?!ewdoc-)[a-z0-9-]+$/
Flag In Required Notes
--replication-mode <async|sync> body Cluster only, applied live. sync: a commit waits for one standby, so a failover loses nothing acknowledged; async: it does not wait. Omitted: unchanged
--logical-replication body wal_level = logical for CDC and publications, applied with a restart; omitted: unchanged
  • Synchronous is not strict: with no standby streaming, the leader keeps accepting writes and the health check reports sync-degraded until one is back. logicalReplication sets wal_level = logical; a cluster restarts member by member with one switchover, a single node restarts once (writes pause for the restart). Turning it off is refused while any logical slot exists.

dcloud rds replication-slots

Logical replication slots for CDC (Debezium, Airbyte) and subscriptions; declared ones survive a failover

Operation Method Path IAM action Effect
list GET /rds/api/instances/{id}/replication-slots rds:DescribeDBInstances read
create POST /rds/api/instances/{id}/replication-slots rds:CreateDBReplicationSlot write
delete DELETE /rds/api/instances/{id}/replication-slots/{slot} rds:DeleteDBReplicationSlot write

dcloud rds replication-slots list

Every logical slot on the leader (declared or made in SQL): active, lag, WAL retained, whether it survives a failover

GET /rds/api/instances/{id}/replication-slots — IAM rds:DescribeDBInstances — read

dcloud rds replication-slots list <id>

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<id> --id string 3-64 chars, /^(?!ewdoc-)[a-z0-9-]+$/

dcloud rds replication-slots create

Declare a logical slot (pgoutput); on a cluster it is kept on every member

POST /rds/api/instances/{id}/replication-slots — IAM rds:CreateDBReplicationSlot — write

dcloud rds replication-slots create <id> --name <value> --database <value> [flags]

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<id> --id string 3-64 chars, /^(?!ewdoc-)[a-z0-9-]+$/
Flag In Required Notes
--name <value> body yes /^[a-z][a-z0-9_]{0,62}$/ · Slot name: a-z, 0-9, _; starts with a letter
--database <value> body yes 1-63 chars · The database the slot decodes
--plugin <pgoutput> body server default "pgoutput" · Output plugin
  • Needs logicalReplication on. Connect the consumer to port 5432 (direct, not the pooler) with a role that has REPLICATION, e.g. the master user. An inactive slot holds WAL until max_slot_wal_keep_size invalidates it; the health check warns from 1 GiB.

dcloud rds replication-slots delete

Drop a logical slot, declared or made in SQL; its consumer has to resynchronise

DELETE /rds/api/instances/{id}/replication-slots/{slot} — IAM rds:DeleteDBReplicationSlot — write

dcloud rds replication-slots delete <id> <slot> [flags]

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<id> --id string 3-64 chars, /^(?!ewdoc-)[a-z0-9-]+$/
<slot> --slot string /^[a-z0-9_]{1,63}$/
Flag In Required Notes
--force <true|false> query server default "false" · true: end the connection reading an active slot first
  • An active slot is refused (409) unless force=true, which ends the connection reading it.

dcloud rds branches

Copy-on-write branches of a database: masked, seconds to create, one per pull request

Operation Method Path IAM action Effect
list GET /rds/api/instances/{id}/branches rds:DescribeDBBranches read
create POST /rds/api/instances/{id}/branches rds:CreateDBBranch write
get GET /rds/api/branches/{branchId} rds:DescribeDBBranches read
get-credentials GET /rds/api/branches/{branchId}/credentials rds:GetDBBranchCredentials read, sensitive
modify PATCH /rds/api/branches/{branchId} rds:ModifyDBBranch write
delete DELETE /rds/api/branches/{branchId} rds:DeleteDBBranch write
get-settings GET /rds/api/instances/{id}/branch-settings rds:DescribeDBBranches read
set-settings PUT /rds/api/instances/{id}/branch-settings rds:ModifyDBBranchSettings write
set-pool PATCH /rds/api/instances/{id}/branch-pool rds:ModifyDBBranchSettings write
refresh-pool POST /rds/api/instances/{id}/branch-pool/refresh rds:ModifyDBBranchSettings write

dcloud rds branches list

A database's branches with where to connect, and its branch pool: machine, base age, masking, operation, space per branch

GET /rds/api/instances/{id}/branches — IAM rds:DescribeDBBranches — read

dcloud rds branches list <id> [flags]

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<id> --id string 3-64 chars, /^(?!ewdoc-)[a-z0-9-]+$/
Flag In Required Notes
--include-deleted <true|false> query Include deleted branches

dcloud rds branches create

Cut a branch: a ZFS clone of the masked pool base, or a restore to a second

POST /rds/api/instances/{id}/branches — IAM rds:CreateDBBranch — write

dcloud rds branches create <id> --name <value> [flags]

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<id> --id string 3-64 chars, /^(?!ewdoc-)[a-z0-9-]+$/
Flag In Required Notes
--name <value> body yes 1-40 chars, /^[a-z0-9][a-z0-9-]*$/ · Branch name: lowercase letters, digits and dashes (pr-42, alice-test)
--recovery-target-time <value> body Branch the database as it was at this second (restored on the pool, minutes); omitted: now, a copy-on-write clone of the pool base (seconds)
--ttl-hours <number> body integer, 1-720 · Hours until the branch is deleted; default 168 (7 days)
  • The first branch of a database builds its branch pool (a restore of the latest backup onto one machine, minutes); later ones take seconds. A base older than the pool’s staleAfterHours (24) or masked with other rules is refreshed first. Every login role gets a new password on the branch (get-credentials).

dcloud rds branches get

One branch: status, data as of, masking, connection, create time

GET /rds/api/branches/{branchId} — IAM rds:DescribeDBBranches — read

dcloud rds branches get <branchId>

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<branchId> --branch-id string /^ewbr-[0-9a-f]{12}$/

dcloud rds branches get-credentials

The branch's passwords (every login role) and a DATABASE_URL for its master user

GET /rds/api/branches/{branchId}/credentials — IAM rds:GetDBBranchCredentials — read, sensitive

dcloud rds branches get-credentials <branchId>

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<branchId> --branch-id string /^ewbr-[0-9a-f]{12}$/

dcloud rds branches modify

Set when the branch is deleted (hours from now, at most 720)

PATCH /rds/api/branches/{branchId} — IAM rds:ModifyDBBranch — write

dcloud rds branches modify <branchId> --ttl-hours <number>

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<branchId> --branch-id string /^ewbr-[0-9a-f]{12}$/
Flag In Required Notes
--ttl-hours <number> body yes integer, 1-720 · Hours from now until the branch is deleted

dcloud rds branches delete

Delete a branch and what was written to it

DELETE /rds/api/branches/{branchId} — IAM rds:DeleteDBBranch — write

dcloud rds branches delete <branchId>

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<branchId> --branch-id string /^ewbr-[0-9a-f]{12}$/

dcloud rds branches get-settings

Masking rules and pull-request branches of a database

GET /rds/api/instances/{id}/branch-settings — IAM rds:DescribeDBBranches — read

dcloud rds branches get-settings <id>

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<id> --id string 3-64 chars, /^(?!ewdoc-)[a-z0-9-]+$/

dcloud rds branches set-settings

Set the masking rules and pull-request branches (replaces both)

PUT /rds/api/instances/{id}/branch-settings — IAM rds:ModifyDBBranchSettings — write

dcloud rds branches set-settings <id> [flags]

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<id> --id string 3-64 chars, /^(?!ewdoc-)[a-z0-9-]+$/
Flag In Required Notes
--masking <value> body repeatable · server default [] · Columns rewritten in the pool base before any branch sees it; none when omitted
--pull-requests <json> body JSON · nullable · server default null · A branch per pull request of a Git repository; null or omitted turns it off
  • No branch is served unmasked: changed rules make the next branch refresh the pool base first. A rule for a column that does not exist is skipped and reported in the activity log.

dcloud rds branches set-pool

How old the pool base may be before a new branch refreshes it

PATCH /rds/api/instances/{id}/branch-pool — IAM rds:ModifyDBBranchSettings — write

dcloud rds branches set-pool <id> --stale-after-hours <number>

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<id> --id string 3-64 chars, /^(?!ewdoc-)[a-z0-9-]+$/
Flag In Required Notes
--stale-after-hours <number> body yes integer, 0-720 · A branch asked for on an older base refreshes it first; 0: always

dcloud rds branches refresh-pool

Restore the latest backup into a new pool base and mask it; existing branches keep theirs

POST /rds/api/instances/{id}/branch-pool/refresh — IAM rds:ModifyDBBranchSettings — write

dcloud rds branches refresh-pool <id>

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<id> --id string 3-64 chars, /^(?!ewdoc-)[a-z0-9-]+$/

dcloud rds logins

Per-person Postgres logins: read-only or read-write roles whose passwords are filed in Secrets

Operation Method Path IAM action Effect
list GET /rds/api/instances/{id}/logins rds:DescribeDBLogins read
create POST /rds/api/instances/{id}/logins rds:CreateDBLogin write
delete DELETE /rds/api/instances/{id}/logins/{loginId} rds:DeleteDBLogin write
modify PATCH /rds/api/instances/{id}/logins/{loginId} rds:ModifyDBLogin write
rotate-password POST /rds/api/instances/{id}/logins/{loginId}/rotate rds:RotateDBLoginPassword write

dcloud rds logins list

List logins with who each is for, whether its role is on the server, and its open sessions

GET /rds/api/instances/{id}/logins — IAM rds:DescribeDBLogins — read

dcloud rds logins list <id>

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<id> --id string 3-64 chars, /^(?!ewdoc-)[a-z0-9-]+$/

dcloud rds logins create

Create a login (read-only by default); the password goes to Secrets, never into the response

POST /rds/api/instances/{id}/logins — IAM rds:CreateDBLogin — write

dcloud rds logins create <id> --name <value> [flags]

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<id> --id string 3-64 chars, /^(?!ewdoc-)[a-z0-9-]+$/
Flag In Required Notes
--name <value> body yes 1-63 chars · The Postgres role name: a-z, 0-9, _
--access <read|readwrite> body server default "read" · read: SELECT on all data (pg_read_all_data); readwrite: also writes (pg_write_all_data); read when omitted
--for-iam-user-id <value> body uuid · IAM user the login is for, shown with it; omitted: nobody in particular
--valid-until <value> body datetime · Expiry (VALID UNTIL), 5 minutes to 2 years ahead; omitted is no expiry
  • Reveal the password with secrets get-value on the returned secretId (secrets:GetSecretValue, audited).

dcloud rds logins delete

Revoke a login: end its sessions, drop its role, delete its secret

DELETE /rds/api/instances/{id}/logins/{loginId} — IAM rds:DeleteDBLogin — write

dcloud rds logins delete <id> <loginId>

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<id> --id string 3-64 chars, /^(?!ewdoc-)[a-z0-9-]+$/
<loginId> --login-id string uuid

dcloud rds logins modify

Set or clear a login's expiry, at least five minutes ahead (to cut off now, revoke)

PATCH /rds/api/instances/{id}/logins/{loginId} — IAM rds:ModifyDBLogin — write

dcloud rds logins modify <id> <loginId> --valid-until <value>

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<id> --id string 3-64 chars, /^(?!ewdoc-)[a-z0-9-]+$/
<loginId> --login-id string uuid
Flag In Required Notes
--valid-until <value> body yes datetime · nullable · New expiry, 5 minutes to 2 years ahead; null removes the expiry
  • Postgres checks VALID UNTIL at connect; the expiry sweep ends sessions still open when it passes.

dcloud rds logins rotate-password

New password for a login, filed as a new version of the same secret (grants carry over)

POST /rds/api/instances/{id}/logins/{loginId}/rotate — IAM rds:RotateDBLoginPassword — write

dcloud rds logins rotate-password <id> <loginId> [flags]

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<id> --id string 3-64 chars, /^(?!ewdoc-)[a-z0-9-]+$/
<loginId> --login-id string uuid
Flag In Required Notes
--end-sessions body server default false · Also end the open sessions, which the old password opened

Not in the CLI: rds routes the surface does not describe

These routes exist and are reachable over HTTP. They are deliberately absent from the description, so there is no command for them. The reason is recorded next to the service so a gap has to be stated out loud and stops being stateable the moment the route goes.

Route Why it has no command
GET /rds/api/etcd/{arch} etcd download for cluster nodes, not a caller

dcloud mysql

MySQL. Base path /mysql/api.

dcloud mysql clusters

Managed MySQL 8.4 (Community Server), 1 node or a 3-node Group Replication group

Operation Method Path IAM action Effect
list GET /mysql/api/clusters mysql:DescribeMysqlClusters read
ca-bundle GET /mysql/api/ca-bundle mysql:DescribeMysqlClusters read
node-types GET /mysql/api/node-types mysql:DescribeMysqlClusters read
create POST /mysql/api/clusters mysql:CreateMysqlCluster write
get GET /mysql/api/clusters/{id} mysql:DescribeMysqlClusters read
restore-window GET /mysql/api/clusters/{id}/restore-window mysql:DescribeMysqlSnapshots read
events GET /mysql/api/clusters/{id}/events mysql:DescribeMysqlClusters read
reboot POST /mysql/api/clusters/{id}/reboot mysql:RebootMysqlNode write
modify PATCH /mysql/api/clusters/{id} mysql:ModifyMysqlCluster write
rotate-password POST /mysql/api/clusters/{id}/password/rotate mysql:RotateMysqlPassword write
delete DELETE /mysql/api/clusters/{id} mysql:DeleteMysqlCluster write
snapshot POST /mysql/api/clusters/{id}/snapshots mysql:CreateMysqlSnapshot write

dcloud mysql clusters list

List MySQL clusters

GET /mysql/api/clusters — IAM mysql:DescribeMysqlClusters — read

dcloud mysql clusters list

dcloud mysql clusters ca-bundle

The platform CA (PEM) the clusters’ certificates chain to

GET /mysql/api/ca-bundle — IAM mysql:DescribeMysqlClusters — read

dcloud mysql clusters ca-bundle

dcloud mysql clusters node-types

The machine types a node can run on, with price and stock

GET /mysql/api/node-types — IAM mysql:DescribeMysqlClusters — read

dcloud mysql clusters node-types

dcloud mysql clusters create

Create a MySQL cluster

POST /mysql/api/clusters — IAM mysql:CreateMysqlCluster — write

dcloud mysql clusters create --identifier <value> --node-type <value> [flags]
Flag In Required Notes
--region-id <value> body 1-32 chars · Region to create in (default: the X-EWS-Region header, else de1). fi1 (Helsinki, Finland) needs the organization setting "allow EU outside Germany".
--identifier <value> body yes 3-40 chars, /^[a-z][a-z0-9-]*[a-z0-9]$/
--node-type <value> body yes 1-32 chars · An instance type from node-types, e.g. performance-2. The provider’s own type names are still accepted, deprecated.
--nodes <json> body JSON · server default 1 · 1: one machine. 3: a Group Replication group across zones behind a private balancer, with automatic failover
--database-name <value> body /^[a-z][a-z0-9_]{0,63}$/ · server default "app" · The database created at first boot
--volume-size-gib <number> body integer, 10-10000 · server default 20 · Each node’s data volume (snapshots are staged on it, so leave room for a copy)
--vpc-id <value> body uuid
--tls body server default true · Clients must use TLS (platform CA). Node-to-node traffic is TLS either way
--kms-key-id <value> body uuid
--snapshot-id <value> body /^ems-[0-9a-f]{12}$/ · Make the cluster from this snapshot; needs mysql:CreateMysqlCluster on the snapshot
--point-in-time <json> body JSON · Make the cluster from another as it was at time (to the second, within its restore window); needs mysql:CreateMysqlCluster on that cluster. Not with snapshotId
--tags <key=value> body repeatable · key=value
  • Private: without vpcId it joins the default VPC, where deployed apps run. creating until every node is ONLINE in one group, usually 3–5 minutes. The admin password is filed in Secrets as MYSQL__PASSWORD. Every table needs a primary key (sql_require_primary_key).

dcloud mysql clusters get

One cluster with its nodes: role, group member state, lag, connections, queries/s, disk

GET /mysql/api/clusters/{id} — IAM mysql:DescribeMysqlClusters — read

dcloud mysql clusters get <id>

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<id> --id string /^ewm-[0-9a-f]{12}$/

dcloud mysql clusters restore-window

The seconds a cluster can be restored to (point in time), and its stored binary logs

GET /mysql/api/clusters/{id}/restore-window — IAM mysql:DescribeMysqlSnapshots — read

dcloud mysql clusters restore-window <id>

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<id> --id string /^ewm-[0-9a-f]{12}$/
  • Each range runs from a snapshot to as far as the uploaded binary logs reach without a gap; the latest point is the end of the last uploaded log (the primary closes one every 5 minutes when there were writes), not now.

dcloud mysql clusters events

Activity: provisioning, group changes and failovers, what the nodes reported

GET /mysql/api/clusters/{id}/events — IAM mysql:DescribeMysqlClusters — read

dcloud mysql clusters events <id> [flags]

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<id> --id string /^ewm-[0-9a-f]{12}$/
Flag In Required Notes
--since <value> query
--limit <number> query integer, 1-500

dcloud mysql clusters reboot

Restart one node, the primary unless nodeId names another; a primary hands its role to a secondary first

POST /mysql/api/clusters/{id}/reboot — IAM mysql:RebootMysqlNode — write

dcloud mysql clusters reboot <id> [flags]

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<id> --id string /^ewm-[0-9a-f]{12}$/
Flag In Required Notes
--node-id <value> body /^ewm-[0-9a-f]{12}-[0-2]$/

dcloud mysql clusters modify

Grow a cluster from 1 to 3 nodes in place, or shrink it from 3 to 1

PATCH /mysql/api/clusters/{id} — IAM mysql:ModifyMysqlCluster — write

dcloud mysql clusters modify <id> --nodes <json>

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<id> --id string /^ewm-[0-9a-f]{12}$/
Flag In Required Notes
--nodes <json> body yes JSON · The node count to go to: 3 (grow) or 1 (shrink)
  • Answers 202 and works in the background (status modifying; Activity shows each step). Growing: two nodes join the running group by clone while node 0 serves, then the cluster address moves to a balancer (new connections refused for some seconds). Shrinking: node 0 becomes the primary, the others leave the group one at a time and are deleted with their volumes, then the address moves back to node 0. Asking again for the same count while modifying resumes a stopped change.

dcloud mysql clusters rotate-password

Replace the admin password with a new Secrets version

POST /mysql/api/clusters/{id}/password/rotate — IAM mysql:RotateMysqlPassword — write

dcloud mysql clusters rotate-password <id>

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<id> --id string /^ewm-[0-9a-f]{12}$/
  • The primary takes it within 30 seconds (ALTER USER … RETAIN CURRENT PASSWORD); the previous password keeps working for an hour, then is discarded.

dcloud mysql clusters delete

Delete a cluster, its machines, volumes, balancer and password

DELETE /mysql/api/clusters/{id} — IAM mysql:DeleteMysqlCluster — write

dcloud mysql clusters delete <id> [flags]

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<id> --id string /^ewm-[0-9a-f]{12}$/
Flag In Required Notes
--final-snapshot <true|false> query true: take a snapshot first and keep it until you delete it; if it fails, nothing is deleted
  • Its daily snapshots go with it; manual ones stay. With finalSnapshot=true a snapshot is taken first and kept until you delete it (counted as a manual snapshot); if it fails, nothing is deleted and the cluster is available again.

dcloud mysql clusters snapshot

Take a snapshot now (a secondary takes it when there is one)

POST /mysql/api/clusters/{id}/snapshots — IAM mysql:CreateMysqlSnapshot — write

dcloud mysql clusters snapshot <id>

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<id> --id string /^ewm-[0-9a-f]{12}$/
  • Answers 202 with the snapshot pending; a node takes it at its next report (within 30 s) and it is available once uploaded.

dcloud mysql snapshots

Encrypted copies of a cluster’s data (clone plugin): daily (kept 7 days) and manual. Restore = a new cluster with snapshotId

Operation Method Path IAM action Effect
list GET /mysql/api/snapshots mysql:DescribeMysqlSnapshots read
get GET /mysql/api/snapshots/{snapshotId} mysql:DescribeMysqlSnapshots read
delete DELETE /mysql/api/snapshots/{snapshotId} mysql:DeleteMysqlSnapshot write

dcloud mysql snapshots list

List snapshots, optionally of one cluster

GET /mysql/api/snapshots — IAM mysql:DescribeMysqlSnapshots — read

dcloud mysql snapshots list [flags]
Flag In Required Notes
--cluster-id <value> query /^ewm-[0-9a-f]{12}$/

dcloud mysql snapshots get

One snapshot: state, size, SHA-256

GET /mysql/api/snapshots/{snapshotId} — IAM mysql:DescribeMysqlSnapshots — read

dcloud mysql snapshots get <snapshotId>

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<snapshotId> --snapshot-id string /^ems-[0-9a-f]{12}$/

dcloud mysql snapshots delete

Delete a snapshot and its stored copy

DELETE /mysql/api/snapshots/{snapshotId} — IAM mysql:DeleteMysqlSnapshot — write

dcloud mysql snapshots delete <snapshotId>

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<snapshotId> --snapshot-id string /^ems-[0-9a-f]{12}$/

dcloud docdb

Document Database. Base path /docdb/api.

dcloud docdb clusters

MongoDB-compatible clusters: FerretDB 2.7 + the DocumentDB extension on managed Postgres 17, 1 node or 3 with failover

Operation Method Path IAM action Effect
list GET /docdb/api/clusters docdb:DescribeDocdbClusters read
server-types GET /docdb/api/server-types docdb:DescribeDocdbClusters read
ca-bundle GET /docdb/api/ca-bundle docdb:DescribeDocdbClusters read
create POST /docdb/api/clusters docdb:CreateDocdbCluster write
get GET /docdb/api/clusters/{id} docdb:DescribeDocdbClusters read
nodes GET /docdb/api/clusters/{id}/nodes docdb:DescribeDocdbClusters read
events GET /docdb/api/clusters/{id}/events docdb:DescribeDocdbClusters read
health GET /docdb/api/clusters/{id}/health docdb:DescribeDocdbClusters read
logs GET /docdb/api/clusters/{id}/logs docdb:DescribeDocdbLogs read, sensitive
rotate-master-password POST /docdb/api/clusters/{id}/master-password/rotate docdb:RotateDocdbMasterPassword write
set-deletion-protection PATCH /docdb/api/clusters/{id}/deletion-protection docdb:ModifyDocdbCluster write
modify-node-type PATCH /docdb/api/clusters/{id}/node-type docdb:ModifyDocdbCluster write
modify-backup-settings PATCH /docdb/api/clusters/{id}/backup-settings docdb:ModifyDocdbCluster write
delete DELETE /docdb/api/clusters/{id} docdb:DeleteDocdbCluster write

dcloud docdb clusters list

List Document Database clusters

GET /docdb/api/clusters — IAM docdb:DescribeDocdbClusters — read

dcloud docdb clusters list

dcloud docdb clusters server-types

The machine types a node can run on, with price and stock

GET /docdb/api/server-types — IAM docdb:DescribeDocdbClusters — read

dcloud docdb clusters server-types

dcloud docdb clusters ca-bundle

The platform CA (PEM) for tlsCAFile

GET /docdb/api/ca-bundle — IAM docdb:DescribeDocdbClusters — read

dcloud docdb clusters ca-bundle

dcloud docdb clusters create

Create a Document Database cluster

POST /docdb/api/clusters — IAM docdb:CreateDocdbCluster — write

dcloud docdb clusters create --identifier <value> --node-type <value> [flags]
Flag In Required Notes
--region-id <value> body 1-32 chars · Region to create in (default: the X-EWS-Region header, else de1). fi1 (Helsinki, Finland) needs the organization setting "allow EU outside Germany".
--identifier <value> body yes 3-40 chars, /^[a-z][a-z0-9-]*[a-z0-9]$/
--node-type <value> body yes 1-32 chars · An instance type from server-types, e.g. performance-2. The provider’s own type names are still accepted, deprecated.
--nodes <json> body JSON · server default 1 · 1: one machine. 3: Postgres with Patroni across zones behind a balancer, automatic failover (8 GiB per node at least)
--master-username <value> body 1-63 chars, /^[a-z][a-z0-9_]*$/ · server default "docdb_admin" · The user the cluster is created with; its password is filed in Secrets
--volume-size-gib <number> body integer, 10-4000 · server default 20
--publicly-accessible body server default false · Reachable from the internet on 27017 (TLS and a password still required)
--vpc-id <value> body uuid
--kms-key-id <value> body uuid
--backup-retention-days <number> body integer, 0-35 · server default 7
--deletion-protection body server default false
--tags <key=value> body repeatable · key=value
  • creating until FerretDB answers on 27017 (TLS only), usually 4–8 minutes. The master password is filed in Secrets as DOCDB__PASSWORD. Every user, including ones made with createUser, has full access to every database (roles are not enforced by FerretDB 2.7). No SQL access: only the MongoDB port is open. Not supported: multi-document transactions (refused with error 115 by the wire guard on clusters made since 2026-11-17; older clusters keep the writes inside one even after an abort) and change streams.

dcloud docdb clusters get

One cluster: status, endpoint, versions (Postgres, FerretDB, DocumentDB) and the connection string template

GET /docdb/api/clusters/{id} — IAM docdb:DescribeDocdbClusters — read

dcloud docdb clusters get <id>

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<id> --id string /^ewdoc-[0-9a-f]{12}$/

dcloud docdb clusters nodes

The machines: role (primary/replica), zone, addresses, disk use, last report

GET /docdb/api/clusters/{id}/nodes — IAM docdb:DescribeDocdbClusters — read

dcloud docdb clusters nodes <id>

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<id> --id string /^ewdoc-[0-9a-f]{12}$/

dcloud docdb clusters events

Activity: provisioning steps, failovers, what the nodes reported

GET /docdb/api/clusters/{id}/events — IAM docdb:DescribeDocdbClusters — read

dcloud docdb clusters events <id> [flags]

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<id> --id string /^ewdoc-[0-9a-f]{12}$/
Flag In Required Notes
--since <value> query
--limit <number> query integer, 1-500

dcloud docdb clusters health

What the health check (every two minutes) found: FerretDB answering on 27017 on each node, replication, disk, certificate

GET /docdb/api/clusters/{id}/health — IAM docdb:DescribeDocdbClusters — read

dcloud docdb clusters health <id>

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<id> --id string /^ewdoc-[0-9a-f]{12}$/

dcloud docdb clusters logs

FerretDB’s log and the Postgres server log from every node, newest first. Kept 7 days

GET /docdb/api/clusters/{id}/logs — IAM docdb:DescribeDocdbLogs — read, sensitive

dcloud docdb clusters logs <id> [flags]

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<id> --id string /^ewdoc-[0-9a-f]{12}$/
Flag In Required Notes
--start <json> query JSON · Default: 24 hours before end
--end <json> query JSON · Default: now
--contains <value> query max 200 chars
--node <number> query integer, 1-99 · A node ordinal
--severity <debug|info|notice|log|warning|error|fatal|panic> query FerretDB INFO is log, WARN is warning
--source <ferretdb|postgres> query ferretdb: FerretDB’s lines only; postgres: the Postgres server log only
--limit <number> query integer, 1-1000 · server default 200

dcloud docdb clusters rotate-master-password

Give the master user a new password, filed as a new version in Secrets

POST /docdb/api/clusters/{id}/master-password/rotate — IAM docdb:RotateDocdbMasterPassword — write

dcloud docdb clusters rotate-master-password <id>

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<id> --id string /^ewdoc-[0-9a-f]{12}$/
  • The old password stops working at once. Apps bound to the cluster (MONGODB_URL) are redeployed with the new one.

dcloud docdb clusters set-deletion-protection

Turn deletion protection on or off; while on, delete is refused

PATCH /docdb/api/clusters/{id}/deletion-protection — IAM docdb:ModifyDocdbCluster — write

dcloud docdb clusters set-deletion-protection <id> --enabled

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<id> --id string /^ewdoc-[0-9a-f]{12}$/
Flag In Required Notes
--enabled body yes

dcloud docdb clusters modify-node-type

Change the machine type; a 3-node cluster is resized node by node and stays available

PATCH /docdb/api/clusters/{id}/node-type — IAM docdb:ModifyDocdbCluster — write

dcloud docdb clusters modify-node-type <id> --node-type <value>

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<id> --id string /^ewdoc-[0-9a-f]{12}$/
Flag In Required Notes
--node-type <value> body yes 1-32 chars · An instance type from server-types, e.g. performance-4; 8 GiB at least for a 3-node cluster. Provider type names still accepted, deprecated.
  • Answers 202; progress on events. A single node is down for one restart (about a minute).

dcloud docdb clusters modify-backup-settings

Change backup retention or the daily backup window

PATCH /docdb/api/clusters/{id}/backup-settings — IAM docdb:ModifyDocdbCluster — write

dcloud docdb clusters modify-backup-settings <id> [flags]

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<id> --id string /^ewdoc-[0-9a-f]{12}$/
Flag In Required Notes
--backup-retention-days <number> body integer, 0-35
--backup-window <value> body /^([01]\d|2[0-3]):[0-5]\d-([01]\d|2[0-3]):[0-5]\d$/ · HH:MM-HH:MM in UTC; only the start is used

dcloud docdb clusters delete

Delete a cluster, its machines, volumes and balancer

DELETE /docdb/api/clusters/{id} — IAM docdb:DeleteDocdbCluster — write

dcloud docdb clusters delete <id> [flags]

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<id> --id string /^ewdoc-[0-9a-f]{12}$/
Flag In Required Notes
--final-backup <true|false> query true: take a full backup first and keep the backups for the retention period, as a retained cluster that can be restored from
  • Refused with 400 while deletion protection is on. With finalBackup=true a full backup is taken first; if it fails nothing is deleted. The cluster then stays as retained (no machines; its backups, the ones taken by hand included, and its master password kept) until its retention period ends, and can be restored from. Without it every backup goes with the cluster. Deleting a retained cluster removes its backups at once.

dcloud docdb users

Logins for a cluster besides the master user, each with its own password in Secrets; every user has full access

Operation Method Path IAM action Effect
list GET /docdb/api/clusters/{id}/users docdb:DescribeDocdbClusters read
create POST /docdb/api/clusters/{id}/users docdb:CreateDocdbUser write
delete DELETE /docdb/api/clusters/{id}/users/{userId} docdb:DeleteDocdbUser write
rotate-password POST /docdb/api/clusters/{id}/users/{userId}/rotate-password docdb:RotateDocdbUserPassword write

dcloud docdb users list

The master user and the cluster’s users, with the Secrets holding their passwords

GET /docdb/api/clusters/{id}/users — IAM docdb:DescribeDocdbClusters — read

dcloud docdb users list <id>

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<id> --id string /^ewdoc-[0-9a-f]{12}$/

dcloud docdb users create

Add a user; its generated password is filed in Secrets

POST /docdb/api/clusters/{id}/users — IAM docdb:CreateDocdbUser — write

dcloud docdb users create <id> --name <value>

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<id> --id string /^ewdoc-[0-9a-f]{12}$/
Flag In Required Notes
--name <value> body yes /^[a-z][a-z0-9_]{1,40}$/ · 2–41 lower-case letters, digits, underscores; not the master user’s name
  • Every user has full read/write access to all databases (FerretDB 2.7 enforces no roles); a role or database in the body is refused. The wire commands createUser, updateUser and dropUser are refused by the cluster: manage users here.

dcloud docdb users delete

Remove a user and its secret; new sign-ins with its password fail at once

DELETE /docdb/api/clusters/{id}/users/{userId} — IAM docdb:DeleteDocdbUser — write

dcloud docdb users delete <id> <userId>

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<id> --id string /^ewdoc-[0-9a-f]{12}$/
<userId> --user-id string uuid
  • Refused with 409 while an app is bound to the cluster as this user.

dcloud docdb users rotate-password

A new password for one user, filed as a new version of its secret

POST /docdb/api/clusters/{id}/users/{userId}/rotate-password — IAM docdb:RotateDocdbUserPassword — write

dcloud docdb users rotate-password <id> <userId>

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<id> --id string /^ewdoc-[0-9a-f]{12}$/
<userId> --user-id string uuid
  • Apps bound to the cluster as this user are redeployed with it.

dcloud docdb backups

Encrypted pgBackRest backups of a cluster, point-in-time and backup (snapshot) restores into a new cluster

Operation Method Path IAM action Effect
list GET /docdb/api/clusters/{id}/backups docdb:ListDocdbBackups read
create POST /docdb/api/clusters/{id}/backups docdb:CreateDocdbBackup write
delete-backup DELETE /docdb/api/clusters/{id}/backups/{backupId} docdb:DeleteDocdbBackup write
restore POST /docdb/api/clusters/{id}/restore docdb:RestoreDocdbCluster write

dcloud docdb backups list

Backups, the recoverable window and this cluster’s restores

GET /docdb/api/clusters/{id}/backups — IAM docdb:ListDocdbBackups — read

dcloud docdb backups list <id>

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<id> --id string /^ewdoc-[0-9a-f]{12}$/

dcloud docdb backups create

Take a full backup now

POST /docdb/api/clusters/{id}/backups — IAM docdb:CreateDocdbBackup — write

dcloud docdb backups create <id>

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<id> --id string /^ewdoc-[0-9a-f]{12}$/
  • Answers 202 requested; the node picks it up within a minute and reports back. Kept until you delete it where keepsByHand is true (at most 20 per cluster); otherwise it follows the retention window.

dcloud docdb backups delete-backup

Delete a backup taken by hand that is kept until deleted

DELETE /docdb/api/clusters/{id}/backups/{backupId} — IAM docdb:DeleteDocdbBackup — write

dcloud docdb backups delete-backup <id> <backupId>

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<id> --id string /^ewdoc-[0-9a-f]{12}$/
<backupId> --backup-id string
  • Older than the retention window, it is expired at once and removed from the repository within a minute; inside the window it follows the window from now on.

dcloud docdb backups restore

Restore into a NEW cluster: to the latest moment, a timestamp in the window, or the end of a backup

POST /docdb/api/clusters/{id}/restore — IAM docdb:RestoreDocdbCluster — write

dcloud docdb backups restore <id> --recovery-target <latest|time|label> [flags]

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<id> --id string /^ewdoc-[0-9a-f]{12}$/
Flag In Required Notes
--recovery-target <latest|time|label> body yes Selects which of the other fields apply
--target-identifier <value> body 3-40 chars, /^[a-z][a-z0-9-]*[a-z0-9]$/ · The new cluster’s name
--node-type <value> body 1-32 chars · Default: the source’s instance type, e.g. performance-2
--nodes <json> body JSON · 1 (default) or 3 nodes, whatever the source has
--kms-key-id <value> body uuid · nullable · CMK for the new disks; null: the platform key; omitted: the source’s
--tags <key=value> body repeatable · key=value · Tags for the new resource, e.g. {"env": "prod", "project": "shop"}. Keys your organization marks required must be present, or the create is refused with the missing keys (GET /tags/api/keys lists them).
--recovery-target-time <value> body datetime
--recovery-target-label <value> body 1-128 chars, /^[A-Za-z0-9_-]+$/
  • The body is a union of 3 shapes (latest, time, label). The flags above are the union of every branch, so the server decides which combination is legal.
  • Answers 202 with the restore job and the new cluster (creating). The source is untouched. The new cluster gets its own master password in Secrets, the source’s users and documents as of the target.

Not in the CLI: docdb routes the surface does not describe

These routes exist and are reachable over HTTP. They are deliberately absent from the description, so there is no command for them. The reason is recorded next to the service so a gap has to be stated out loud and stops being stateable the moment the route goes.

Route Why it has no command
GET /docdb/api/packages/{package}/{arch} FerretDB/DocumentDB package download for cluster nodes, not a caller
GET /docdb/api/guard/{arch} Wire guard binary download for cluster nodes, not a caller

dcloud rabbitmq

RabbitMQ. Base path /rabbitmq/api.

dcloud rabbitmq brokers

Managed RabbitMQ 4 (AMQP 0-9-1 over TLS): one node, or a 3-node cluster across zones with quorum queues

Operation Method Path IAM action Effect
list GET /rabbitmq/api/brokers rabbitmq:DescribeRabbitmqBrokers read
ca-bundle GET /rabbitmq/api/ca-bundle rabbitmq:DescribeRabbitmqBrokers read
node-types GET /rabbitmq/api/node-types rabbitmq:DescribeRabbitmqBrokers read
create POST /rabbitmq/api/brokers rabbitmq:CreateRabbitmqBroker write
get GET /rabbitmq/api/brokers/{id} rabbitmq:DescribeRabbitmqBrokers read
events GET /rabbitmq/api/brokers/{id}/events rabbitmq:DescribeRabbitmqBrokers read
reboot POST /rabbitmq/api/brokers/{id}/reboot rabbitmq:RebootRabbitmqNode write
delete DELETE /rabbitmq/api/brokers/{id} rabbitmq:DeleteRabbitmqBroker write
upgrade POST /rabbitmq/api/brokers/{id}/upgrade rabbitmq:UpgradeRabbitmqBroker write
patch POST /rabbitmq/api/brokers/{id}/patch rabbitmq:UpgradeRabbitmqBroker write
resume-maintenance POST /rabbitmq/api/brokers/{id}/maintenance/resume rabbitmq:UpgradeRabbitmqBroker write
cancel-maintenance POST /rabbitmq/api/brokers/{id}/maintenance/cancel rabbitmq:UpgradeRabbitmqBroker write
export POST /rabbitmq/api/brokers/{id}/exports rabbitmq:CreateRabbitmqExport write

dcloud rabbitmq brokers list

List RabbitMQ brokers

GET /rabbitmq/api/brokers — IAM rabbitmq:DescribeRabbitmqBrokers — read

dcloud rabbitmq brokers list

dcloud rabbitmq brokers ca-bundle

The platform CA (PEM) the brokers’ certificates chain to

GET /rabbitmq/api/ca-bundle — IAM rabbitmq:DescribeRabbitmqBrokers — read

dcloud rabbitmq brokers ca-bundle

dcloud rabbitmq brokers node-types

The machine types a node can run on, with price and stock

GET /rabbitmq/api/node-types — IAM rabbitmq:DescribeRabbitmqBrokers — read

dcloud rabbitmq brokers node-types

dcloud rabbitmq brokers create

Create a RabbitMQ broker

POST /rabbitmq/api/brokers — IAM rabbitmq:CreateRabbitmqBroker — write

dcloud rabbitmq brokers create --identifier <value> --node-type <value> [flags]
Flag In Required Notes
--region-id <value> body 1-32 chars · Region to create in (default: the X-EWS-Region header, else de1). fi1 (Helsinki, Finland) needs the organization setting "allow EU outside Germany".
--identifier <value> body yes 3-40 chars, /^[a-z][a-z0-9-]*[a-z0-9]$/
--node-type <value> body yes 1-32 chars · An instance type from node-types, e.g. performance-2. The provider’s own type names are still accepted, deprecated.
--nodes <json> body JSON · server default 1 · 1: one machine, queues NOT replicated. 3: one cluster across zones behind a private balancer; quorum queues keep serving when a node goes
--volume-size-gib <number> body integer, 10-10000 · server default 20 · Each node’s data volume (messages and quorum-queue logs)
--vpc-id <value> body uuid
--kms-key-id <value> body uuid
--export-id <value> body /^rmd-[0-9a-f]{12}$/ · Make the broker from this definitions export; needs rabbitmq:CreateRabbitmqBroker on the export
--tags <key=value> body repeatable · key=value
--alarm-emails <value> body repeatable · email · server default [] · Who the default alarms in Monitoring email (no quorum, memory/disk alarm, disk); nobody by default
  • Private: without vpcId it joins the default VPC, where deployed apps run. TLS only (AMQPS 5671). creating until every node runs in one cluster and the admin user is in place, usually 3–5 minutes. The admin password is filed in Secrets as RABBITMQ__ADMIN_PASSWORD. Queues declared without a type are quorum queues. With nodes: 1 nothing is replicated.

dcloud rabbitmq brokers get

One broker with its nodes (alarms, memory, disk, partitions), users, message rates and its 20 deepest queues with their leaders

GET /rabbitmq/api/brokers/{id} — IAM rabbitmq:DescribeRabbitmqBrokers — read

dcloud rabbitmq brokers get <id>

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<id> --id string /^rmq-[0-9a-f]{12}$/

dcloud rabbitmq brokers events

Activity: provisioning, nodes going down and back, alarms, users applied, exports, what the nodes reported

GET /rabbitmq/api/brokers/{id}/events — IAM rabbitmq:DescribeRabbitmqBrokers — read

dcloud rabbitmq brokers events <id> [flags]

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<id> --id string /^rmq-[0-9a-f]{12}$/
Flag In Required Notes
--since <value> query
--limit <number> query integer, 1-500

dcloud rabbitmq brokers reboot

Restart one node (the first unless nodeId names another) — with 3 nodes, a failover test

POST /rabbitmq/api/brokers/{id}/reboot — IAM rabbitmq:RebootRabbitmqNode — write

dcloud rabbitmq brokers reboot <id> [flags]

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<id> --id string /^rmq-[0-9a-f]{12}$/
Flag In Required Notes
--node-id <value> body /^rmq-[0-9a-f]{12}-[0-2]$/

dcloud rabbitmq brokers delete

Delete a broker, its machines, volumes, messages, balancer and passwords

DELETE /rabbitmq/api/brokers/{id} — IAM rabbitmq:DeleteRabbitmqBroker — write

dcloud rabbitmq brokers delete <id>

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<id> --id string /^rmq-[0-9a-f]{12}$/
  • Its daily exports go with it; manual ones stay.

dcloud rabbitmq brokers upgrade

Restart the broker onto the newest patch release of its minor, one node at a time

POST /rabbitmq/api/brokers/{id}/upgrade — IAM rabbitmq:UpgradeRabbitmqBroker — write

dcloud rabbitmq brokers upgrade <id>

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<id> --id string /^rmq-[0-9a-f]{12}$/
  • Each node drains first (its quorum queue leaders move, its connections close), pulls the image and restarts, and every quorum queue must have all its members online again before the next node. A node that does not come back pauses the rollout. With one node it is downtime.

dcloud rabbitmq brokers patch

Patch the nodes’ operating system now, one node at a time (a reboot if the kernel asks)

POST /rabbitmq/api/brokers/{id}/patch — IAM rabbitmq:UpgradeRabbitmqBroker — write

dcloud rabbitmq brokers patch <id>

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<id> --id string /^rmq-[0-9a-f]{12}$/
  • Security updates also install nightly by themselves; reboots then happen in the platform window, one node at a time, only while every node runs without alarms.

dcloud rabbitmq brokers resume-maintenance

Resume a paused rolling restart or patch run (its current node starts again)

POST /rabbitmq/api/brokers/{id}/maintenance/resume — IAM rabbitmq:UpgradeRabbitmqBroker — write

dcloud rabbitmq brokers resume-maintenance <id>

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<id> --id string /^rmq-[0-9a-f]{12}$/

dcloud rabbitmq brokers cancel-maintenance

Stop a rolling restart or patch run; nodes already done stay done

POST /rabbitmq/api/brokers/{id}/maintenance/cancel — IAM rabbitmq:UpgradeRabbitmqBroker — write

dcloud rabbitmq brokers cancel-maintenance <id>

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<id> --id string /^rmq-[0-9a-f]{12}$/

dcloud rabbitmq brokers export

Export the broker’s definitions now

POST /rabbitmq/api/brokers/{id}/exports — IAM rabbitmq:CreateRabbitmqExport — write

dcloud rabbitmq brokers export <id>

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<id> --id string /^rmq-[0-9a-f]{12}$/
  • Answers 202 with the export pending; a node takes it at its next report (within 30 s). Users (with password hashes), queues, exchanges, bindings and policies — not messages.

dcloud rabbitmq users

A broker’s users: each password filed in Secrets as RABBITMQ___PASSWORD, permissions on vhost "/"

Operation Method Path IAM action Effect
list GET /rabbitmq/api/brokers/{id}/users rabbitmq:DescribeRabbitmqUsers read
create POST /rabbitmq/api/brokers/{id}/users rabbitmq:CreateRabbitmqUser write
update PATCH /rabbitmq/api/brokers/{id}/users/{userName} rabbitmq:UpdateRabbitmqUser write
rotate-password POST /rabbitmq/api/brokers/{id}/users/{userName}/rotate-password rabbitmq:RotateRabbitmqUserPassword write
delete DELETE /rabbitmq/api/brokers/{id}/users/{userName} rabbitmq:DeleteRabbitmqUser write

dcloud rabbitmq users list

List a broker’s users (admin, yours, the event bus’s)

GET /rabbitmq/api/brokers/{id}/users — IAM rabbitmq:DescribeRabbitmqUsers — read

dcloud rabbitmq users list <id>

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<id> --id string /^rmq-[0-9a-f]{12}$/

dcloud rabbitmq users create

Create a user; its password is filed in Secrets

POST /rabbitmq/api/brokers/{id}/users — IAM rabbitmq:CreateRabbitmqUser — write

dcloud rabbitmq users create <id> --name <value> [flags]

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<id> --id string /^rmq-[0-9a-f]{12}$/
Flag In Required Notes
--name <value> body yes /^[a-z][a-z0-9_.-]{0,63}$/
--tags <|monitoring|management|administrator> body server default "" · Management UI access: "" (messaging only), monitoring, management or administrator
--configure <value> body max 512 chars · server default "." · Regex over the names of the queues and exchanges it may declare or delete on vhost "/" ("" = none, "." = all, "^orders." = a prefix)
--write <value> body max 512 chars · server default "." · Regex over the names of the exchanges and queues it may publish to on vhost "/" ("" = none, "." = all, "^orders." = a prefix)
--read <value> body max 512 chars · server default "." · Regex over the names of the queues it may consume from on vhost "/" ("" = none, "." = all, "^orders." = a prefix)
  • A node applies it within 30 seconds (applied: true).

dcloud rabbitmq users update

Change a user’s tags or permissions

PATCH /rabbitmq/api/brokers/{id}/users/{userName} — IAM rabbitmq:UpdateRabbitmqUser — write

dcloud rabbitmq users update <id> <userName> [flags]

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<id> --id string /^rmq-[0-9a-f]{12}$/
<userName> --user-name string /^[a-z][a-z0-9_.-]{0,63}$/
Flag In Required Notes
--tags <|monitoring|management|administrator> body Management UI access: "" (messaging only), monitoring, management or administrator
--configure <value> body max 512 chars · Regex over the names of the queues and exchanges it may declare or delete on vhost "/" ("" = none, ".*" = all, "^orders." = a prefix)
--write <value> body max 512 chars · Regex over the names of the exchanges and queues it may publish to on vhost "/" ("" = none, ".*" = all, "^orders." = a prefix)
--read <value> body max 512 chars · Regex over the names of the queues it may consume from on vhost "/" ("" = none, ".*" = all, "^orders." = a prefix)

dcloud rabbitmq users rotate-password

Replace a user’s password with a new Secrets version

POST /rabbitmq/api/brokers/{id}/users/{userName}/rotate-password — IAM rabbitmq:RotateRabbitmqUserPassword — write

dcloud rabbitmq users rotate-password <id> <userName>

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<id> --id string /^rmq-[0-9a-f]{12}$/
<userName> --user-name string /^[a-z][a-z0-9_.-]{0,63}$/
  • A node applies it within 30 seconds; the old password stops working then (RabbitMQ keeps one per user). Redeploy the apps that use it.

dcloud rabbitmq users delete

Delete a user and its secret

DELETE /rabbitmq/api/brokers/{id}/users/{userName} — IAM rabbitmq:DeleteRabbitmqUser — write

dcloud rabbitmq users delete <id> <userName>

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<id> --id string /^rmq-[0-9a-f]{12}$/
<userName> --user-name string /^[a-z][a-z0-9_.-]{0,63}$/

dcloud rabbitmq exports

Encrypted definitions exports: daily (kept 7 days) and manual. Restore = a new broker with exportId

Operation Method Path IAM action Effect
list GET /rabbitmq/api/exports rabbitmq:DescribeRabbitmqExports read
get GET /rabbitmq/api/exports/{exportId} rabbitmq:DescribeRabbitmqExports read
delete DELETE /rabbitmq/api/exports/{exportId} rabbitmq:DeleteRabbitmqExport write

dcloud rabbitmq exports list

List exports, optionally of one broker

GET /rabbitmq/api/exports — IAM rabbitmq:DescribeRabbitmqExports — read

dcloud rabbitmq exports list [flags]
Flag In Required Notes
--broker-id <value> query /^rmq-[0-9a-f]{12}$/

dcloud rabbitmq exports get

One export: state, counts, size, SHA-256

GET /rabbitmq/api/exports/{exportId} — IAM rabbitmq:DescribeRabbitmqExports — read

dcloud rabbitmq exports get <exportId>

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<exportId> --export-id string /^rmd-[0-9a-f]{12}$/

dcloud rabbitmq exports delete

Delete an export and its stored copy

DELETE /rabbitmq/api/exports/{exportId} — IAM rabbitmq:DeleteRabbitmqExport — write

dcloud rabbitmq exports delete <exportId>

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<exportId> --export-id string /^rmd-[0-9a-f]{12}$/

dcloud kafka

Apache Kafka. Base path /kafka/api.

dcloud kafka clusters

Managed Apache Kafka 4 (KRaft) over SASL_SSL with SCRAM-SHA-512: one node, or three across zones

Operation Method Path IAM action Effect
list GET /kafka/api/clusters kafka:DescribeKafkaClusters read
ca-bundle GET /kafka/api/ca-bundle kafka:DescribeKafkaClusters read
node-types GET /kafka/api/node-types kafka:DescribeKafkaClusters read
versions GET /kafka/api/versions kafka:DescribeKafkaClusters read
create POST /kafka/api/clusters kafka:CreateKafkaCluster write
get GET /kafka/api/clusters/{id} kafka:DescribeKafkaClusters read
events GET /kafka/api/clusters/{id}/events kafka:DescribeKafkaClusters read
reboot POST /kafka/api/clusters/{id}/reboot kafka:RebootKafkaNode write
upgrade POST /kafka/api/clusters/{id}/upgrade kafka:UpgradeKafkaCluster write
patch POST /kafka/api/clusters/{id}/patch kafka:UpgradeKafkaCluster write
enable-tiered-storage POST /kafka/api/clusters/{id}/tiered-storage kafka:EnableKafkaTieredStorage write
resume-maintenance POST /kafka/api/clusters/{id}/maintenance/resume kafka:UpgradeKafkaCluster write
cancel-maintenance POST /kafka/api/clusters/{id}/maintenance/cancel kafka:UpgradeKafkaCluster write
delete DELETE /kafka/api/clusters/{id} kafka:DeleteKafkaCluster write

dcloud kafka clusters list

List Kafka clusters

GET /kafka/api/clusters — IAM kafka:DescribeKafkaClusters — read

dcloud kafka clusters list

dcloud kafka clusters ca-bundle

The platform CA (PEM) the clusters’ certificates chain to: the clients’ truststore

GET /kafka/api/ca-bundle — IAM kafka:DescribeKafkaClusters — read

dcloud kafka clusters ca-bundle

dcloud kafka clusters node-types

The machine types a node can run on (2 GB and up), with price and stock

GET /kafka/api/node-types — IAM kafka:DescribeKafkaClusters — read

dcloud kafka clusters node-types

dcloud kafka clusters versions

The Apache Kafka releases a new cluster may run

GET /kafka/api/versions — IAM kafka:DescribeKafkaClusters — read

dcloud kafka clusters versions

dcloud kafka clusters create

Create a Kafka cluster

POST /kafka/api/clusters — IAM kafka:CreateKafkaCluster — write

dcloud kafka clusters create --identifier <value> --node-type <value> [flags]
Flag In Required Notes
--region-id <value> body 1-32 chars · Region to create in (default: the X-EWS-Region header, else de1). fi1 (Helsinki, Finland) needs the organization setting "allow EU outside Germany".
--identifier <value> body yes 3-40 chars, /^[a-z][a-z0-9-]*[a-z0-9]$/
--node-type <value> body yes 1-32 chars · An instance type from node-types with at least 2 GB of memory, e.g. performance-2. Provider type names still accepted, deprecated.
--nodes <json> body JSON · server default 1 · 1: one machine, partitions NOT replicated. 3: one KRaft quorum across zones; replication factor 3, min.insync.replicas 2
--engine-version <4.4.0|4.3.2> body server default "4.4.0"
--volume-size-gib <number> body integer, 10-10000 · server default 20 · Each node’s data volume; retention is by time unless retention.bytes is set
--vpc-id <value> body uuid
--kms-key-id <value> body uuid
--tags <key=value> body repeatable · key=value
--snapshot-id <value> body /^kfs-[0-9a-f]{12}$/ · Make the cluster from this definitions snapshot (topics and users with their passwords; no messages); needs kafka:CreateKafkaCluster on the snapshot, and at least the snapshot’s node count
--alarm-emails <value> body repeatable · email · server default [] · Who the default alarms in Monitoring email (no quorum, offline partitions, under min ISR, under-replicated, disk); nobody by default
--tiered-storage body server default false · Tiered storage from the start: topics with remote.storage.enable keep older segments in a bucket of the organization’s object storage (kafka.tiered.gb_month), encrypted on the nodes. Long retention, not a backup
  • Private: without vpcId it joins the default VPC, where deployed apps run. Clients connect with bootstrapServers (every node’s address, port 9093), SASL_SSL and SCRAM-SHA-512, trusting the CA bundle. creating until every node is in the quorum and the admin user is in place, usually 3–5 minutes. The admin password is filed in Secrets as KAFKA__ADMIN_PASSWORD. With nodes: 1 nothing is replicated. Messages are not backed up.

dcloud kafka clusters get

One cluster with its nodes (state, active controller, partition leaders, disk), users, the quorum, partition health and consumer-group lag

GET /kafka/api/clusters/{id} — IAM kafka:DescribeKafkaClusters — read

dcloud kafka clusters get <id>

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<id> --id string /^kfk-[0-9a-f]{12}$/

dcloud kafka clusters events

Activity: provisioning, nodes down and back, the controller moving, under-replicated partitions, users and topics applied, upgrades

GET /kafka/api/clusters/{id}/events — IAM kafka:DescribeKafkaClusters — read

dcloud kafka clusters events <id> [flags]

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<id> --id string /^kfk-[0-9a-f]{12}$/
Flag In Required Notes
--since <value> query
--limit <number> query integer, 1-500

dcloud kafka clusters reboot

Restart one node (the first unless nodeId names another) — with 3 nodes, a failover test

POST /kafka/api/clusters/{id}/reboot — IAM kafka:RebootKafkaNode — write

dcloud kafka clusters reboot <id> [flags]

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<id> --id string /^kfk-[0-9a-f]{12}$/
Flag In Required Notes
--node-id <value> body /^kfk-[0-9a-f]{12}-[0-2]$/

dcloud kafka clusters upgrade

Roll the cluster to a newer Kafka release, one node at a time

POST /kafka/api/clusters/{id}/upgrade — IAM kafka:UpgradeKafkaCluster — write

dcloud kafka clusters upgrade <id> --version <4.4.0|4.3.2>

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<id> --id string /^kfk-[0-9a-f]{12}$/
Flag In Required Notes
--version <4.4.0|4.3.2> body yes
  • Same minor or the next (upgradeTargets); no downgrades. Each node stops with a controlled shutdown, restarts on the new image and must be back in every ISR before the next; the active controller goes last; a node that does not come back pauses the rollout. After the last node the feature versions (metadata.version) are finalised.

dcloud kafka clusters patch

Patch the nodes’ operating system now, one node at a time (a reboot if the kernel asks)

POST /kafka/api/clusters/{id}/patch — IAM kafka:UpgradeKafkaCluster — write

dcloud kafka clusters patch <id>

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<id> --id string /^kfk-[0-9a-f]{12}$/
  • Security updates also install nightly by themselves; reboots then happen in the platform window, one node of a cluster at a time, only while every partition is in sync.

dcloud kafka clusters enable-tiered-storage

Turn tiered storage on: a bucket in the organization’s object storage, then each node restarts with the plugin, one at a time

POST /kafka/api/clusters/{id}/tiered-storage — IAM kafka:EnableKafkaTieredStorage — write

dcloud kafka clusters enable-tiered-storage <id> --enabled

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<id> --id string /^kfk-[0-9a-f]{12}$/
Flag In Required Notes
--enabled body yes true; false is refused (turn it off per topic, or delete the cluster)
  • tieredStorage.state is enabling while the nodes restart (like an upgrade: controlled shutdown, back in every ISR before the next) and on after the last; topics can then set remote.storage.enable. One node: the cluster is down while it restarts. Remote segments are encrypted on the nodes; the bucket (named after the cluster) is read-only in the S3 console and deleted with the cluster. Billed per GB-month stored (kafka.tiered.gb_month).

dcloud kafka clusters resume-maintenance

Resume a paused upgrade or patch run (its current node starts again)

POST /kafka/api/clusters/{id}/maintenance/resume — IAM kafka:UpgradeKafkaCluster — write

dcloud kafka clusters resume-maintenance <id>

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<id> --id string /^kfk-[0-9a-f]{12}$/

dcloud kafka clusters cancel-maintenance

Stop an upgrade or patch run; nodes already done stay done

POST /kafka/api/clusters/{id}/maintenance/cancel — IAM kafka:UpgradeKafkaCluster — write

dcloud kafka clusters cancel-maintenance <id>

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<id> --id string /^kfk-[0-9a-f]{12}$/

dcloud kafka clusters delete

Delete a cluster, its machines, volumes, every topic and message, and its passwords

DELETE /kafka/api/clusters/{id} — IAM kafka:DeleteKafkaCluster — write

dcloud kafka clusters delete <id>

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<id> --id string /^kfk-[0-9a-f]{12}$/

dcloud kafka topics

A cluster’s topics: the ones declared through the API are kept as declared; ones made over the Kafka protocol are listed and can be adopted

Operation Method Path IAM action Effect
list GET /kafka/api/clusters/{id}/topics kafka:DescribeKafkaTopics read
create POST /kafka/api/clusters/{id}/topics kafka:CreateKafkaTopic write
adopt POST /kafka/api/clusters/{id}/topics/{topic}/adopt kafka:CreateKafkaTopic write
update PATCH /kafka/api/clusters/{id}/topics/{topic} kafka:UpdateKafkaTopic write
delete DELETE /kafka/api/clusters/{id}/topics/{topic} kafka:DeleteKafkaTopic write

dcloud kafka topics list

List topics, managed and not, with partitions, replication health and settings

GET /kafka/api/clusters/{id}/topics — IAM kafka:DescribeKafkaTopics — read

dcloud kafka topics list <id>

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<id> --id string /^kfk-[0-9a-f]{12}$/

dcloud kafka topics create

Declare a topic; the cluster creates it within a minute (applied: true)

POST /kafka/api/clusters/{id}/topics — IAM kafka:CreateKafkaTopic — write

dcloud kafka topics create <id> --name <value> [flags]

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<id> --id string /^kfk-[0-9a-f]{12}$/
Flag In Required Notes
--name <value> body yes /^(?!_)[a-zA-Z0-9.-]{1,249}$/
--partitions <number> body integer, 1-1000 · server default 3
--replication-factor <number> body integer, 1-3 · Default 3 on a 3-node cluster, 1 on one node
--configs <json> body JSON · server default {} · Topic settings as Kafka strings; a key left out uses the broker default (7 days retention)

dcloud kafka topics adopt

Make a topic created over the protocol managed, with its current settings

POST /kafka/api/clusters/{id}/topics/{topic}/adopt — IAM kafka:CreateKafkaTopic — write

dcloud kafka topics adopt <id> <topic>

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<id> --id string /^kfk-[0-9a-f]{12}$/
<topic> --topic string /^(?!_)[a-zA-Z0-9.-]{1,249}$/

dcloud kafka topics update

Add partitions or change a managed topic’s settings

PATCH /kafka/api/clusters/{id}/topics/{topic} — IAM kafka:UpdateKafkaTopic — write

dcloud kafka topics update <id> <topic> [flags]

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<id> --id string /^kfk-[0-9a-f]{12}$/
<topic> --topic string /^(?!_)[a-zA-Z0-9.-]{1,249}$/
Flag In Required Notes
--partitions <number> body integer, 1-1000 · Can only grow
--configs <json> body JSON · The whole set: a key left out goes back to the broker default
--delete-remote-data body server default false · Required to turn remote.storage.enable off: every message the topic holds in object storage is deleted (kafka:DeleteKafkaTopicRemoteData)
  • A setting changed over the Kafka protocol is set back and said in Activity.

dcloud kafka topics delete

Delete a managed topic and its messages

DELETE /kafka/api/clusters/{id}/topics/{topic} — IAM kafka:DeleteKafkaTopic — write

dcloud kafka topics delete <id> <topic>

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<id> --id string /^kfk-[0-9a-f]{12}$/
<topic> --topic string /^(?!_)[a-zA-Z0-9.-]{1,249}$/

dcloud kafka users

A cluster’s SCRAM-SHA-512 users: each password filed in Secrets as KAFKA___PASSWORD, permissions as ACL grants

Operation Method Path IAM action Effect
list GET /kafka/api/clusters/{id}/users kafka:DescribeKafkaUsers read
create POST /kafka/api/clusters/{id}/users kafka:CreateKafkaUser write
update PATCH /kafka/api/clusters/{id}/users/{userName} kafka:UpdateKafkaUser write
rotate-password POST /kafka/api/clusters/{id}/users/{userName}/rotate-password kafka:RotateKafkaUserPassword write
delete DELETE /kafka/api/clusters/{id}/users/{userName} kafka:DeleteKafkaUser write

dcloud kafka users list

List a cluster’s users (admin, yours, the event bus’s)

GET /kafka/api/clusters/{id}/users — IAM kafka:DescribeKafkaUsers — read

dcloud kafka users list <id>

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<id> --id string /^kfk-[0-9a-f]{12}$/

dcloud kafka users create

Create a user with ACL grants; its password is filed in Secrets

POST /kafka/api/clusters/{id}/users — IAM kafka:CreateKafkaUser — write

dcloud kafka users create <id> --name <value> [flags]

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<id> --id string /^kfk-[0-9a-f]{12}$/
Flag In Required Notes
--name <value> body yes /^[a-z][a-z0-9_.-]{0,63}$/
--acls <value> body repeatable · server default []
  • The cluster applies it within a minute (applied: true).

dcloud kafka users update

Replace a user’s ACL grants (added before the old ones are removed)

PATCH /kafka/api/clusters/{id}/users/{userName} — IAM kafka:UpdateKafkaUser — write

dcloud kafka users update <id> <userName> --acls <value>

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<id> --id string /^kfk-[0-9a-f]{12}$/
<userName> --user-name string /^[a-z][a-z0-9_.-]{0,63}$/
Flag In Required Notes
--acls <value> body yes repeatable

dcloud kafka users rotate-password

Replace a user’s password with a new Secrets version

POST /kafka/api/clusters/{id}/users/{userName}/rotate-password — IAM kafka:RotateKafkaUserPassword — write

dcloud kafka users rotate-password <id> <userName>

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<id> --id string /^kfk-[0-9a-f]{12}$/
<userName> --user-name string /^[a-z][a-z0-9_.-]{0,63}$/
  • Applied within a minute; new connections need the new password then, open ones live until they reconnect. Redeploy bound apps.

dcloud kafka users delete

Delete a user, its ACLs and its secret

DELETE /kafka/api/clusters/{id}/users/{userName} — IAM kafka:DeleteKafkaUser — write

dcloud kafka users delete <id> <userName>

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<id> --id string /^kfk-[0-9a-f]{12}$/
<userName> --user-name string /^[a-z][a-z0-9_.-]{0,63}$/

dcloud kafka replications

MirrorMaker 2 between two clusters (message-level DR): topics copied with their names, partitions and settings, consumer-group offsets translated onto the copy; lag in Monitoring; manual failover

Operation Method Path IAM action Effect
list GET /kafka/api/replications kafka:DescribeKafkaReplications read
get GET /kafka/api/replications/{replicationId} kafka:DescribeKafkaReplications read
create POST /kafka/api/replications kafka:CreateKafkaReplication write
failover POST /kafka/api/replications/{replicationId}/failover kafka:FailoverKafkaReplication write
delete DELETE /kafka/api/replications/{replicationId} kafka:DeleteKafkaReplication write

dcloud kafka replications list

List replications with their state, lag and failover result

GET /kafka/api/replications — IAM kafka:DescribeKafkaReplications — read

dcloud kafka replications list

dcloud kafka replications get

One replication: state, messages behind per topic, the connectors and their tasks, the groups synced onto the copy

GET /kafka/api/replications/{replicationId} — IAM kafka:DescribeKafkaReplications — read

dcloud kafka replications get <replicationId>

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<replicationId> --replication-id string /^kfr-[0-9a-f]{12}$/

dcloud kafka replications create

Replicate topics and consumer-group offsets from one cluster into another

POST /kafka/api/replications — IAM kafka:CreateKafkaReplication — write

dcloud kafka replications create --name <value> --source-cluster-id <value> --target-cluster-id <value> [flags]
Flag In Required Notes
--name <value> body yes 3-40 chars, /^[a-z][a-z0-9-]*[a-z0-9]$/
--source-cluster-id <value> body yes /^kfk-[0-9a-f]{12}$/ · The cluster copied from
--target-cluster-id <value> body yes /^kfk-[0-9a-f]{12}$/ · The cluster copied into (its nodes run MirrorMaker 2); in the same VPC
--topics <value> body repeatable · /^(*|[a-zA-Z0-9._-]{1,249}*?)$/ · server default ["*"] · Exact names or prefixes ending in *; default every topic, also ones made later
--groups <value> body repeatable · /^(*|[a-zA-Z0-9._-]{1,249}*?)$/ · server default ["*"] · Consumer groups whose offsets are translated onto the copy; default every one
  • Needs kafka:CreateKafkaReplication on the target cluster and kafka:ReplicateKafkaCluster on the source. Both clusters available, in one VPC; the target made after 2026-11-15 (its nodes run the Kafka Connect worker; no extra charge, it uses the target nodes’ memory and CPU). Topic names are kept, so a cycle or two sources writing matching topics into one target is refused. The source gets a read-only user (ews-mirror-…). Copying starts from the oldest retained message; group offsets are synced to the copy every 5 s. At-least-once: a group that moves re-reads a few messages per partition. At most 3 replications into one cluster.

dcloud kafka replications failover

Fail over: copying stops for good; consumers continue on the target from their translated offsets

POST /kafka/api/replications/{replicationId}/failover — IAM kafka:FailoverKafkaReplication — write

dcloud kafka replications failover <replicationId>

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<replicationId> --replication-id string /^kfr-[0-9a-f]{12}$/
  • Works with the source down: the offsets synced last stand. Copying stops within a minute (failed_over); failover.groups lists each group on the copy with its lag there. Move consumers (same group id) and producers to the target’s bootstrap servers. There is no failback: replicate the other way into a fresh cluster.

dcloud kafka replications delete

Delete a replication: copying stops, the copied topics stay on the target, the source’s mirror user goes

DELETE /kafka/api/replications/{replicationId} — IAM kafka:DeleteKafkaReplication — write

dcloud kafka replications delete <replicationId>

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<replicationId> --replication-id string /^kfr-[0-9a-f]{12}$/

dcloud kafka snapshots

Encrypted definitions snapshots (topics with their settings, users with grants and passwords; no messages): daily (kept 7 days) and manual. Restore = a new cluster with snapshotId

Operation Method Path IAM action Effect
list GET /kafka/api/snapshots kafka:DescribeKafkaSnapshots read
get GET /kafka/api/snapshots/{snapshotId} kafka:DescribeKafkaSnapshots read
create POST /kafka/api/clusters/{id}/snapshots kafka:CreateKafkaSnapshot write
delete DELETE /kafka/api/snapshots/{snapshotId} kafka:DeleteKafkaSnapshot write

dcloud kafka snapshots list

List snapshots, optionally of one cluster

GET /kafka/api/snapshots — IAM kafka:DescribeKafkaSnapshots — read

dcloud kafka snapshots list [flags]
Flag In Required Notes
--cluster-id <value> query /^kfk-[0-9a-f]{12}$/

dcloud kafka snapshots get

One snapshot: its topics and user names, size, whether it is partial

GET /kafka/api/snapshots/{snapshotId} — IAM kafka:DescribeKafkaSnapshots — read

dcloud kafka snapshots get <snapshotId>

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<snapshotId> --snapshot-id string /^kfs-[0-9a-f]{12}$/

dcloud kafka snapshots create

Snapshot a cluster’s topics and users now (kept until deleted, 20 per cluster)

POST /kafka/api/clusters/{id}/snapshots — IAM kafka:CreateKafkaSnapshot — write

dcloud kafka snapshots create <id>

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<id> --id string /^kfk-[0-9a-f]{12}$/
  • Topics made over the protocol are taken from the latest cluster view; when it is over 10 minutes old the snapshot is marked partial.

dcloud kafka snapshots delete

Delete a snapshot and its stored copy

DELETE /kafka/api/snapshots/{snapshotId} — IAM kafka:DeleteKafkaSnapshot — write

dcloud kafka snapshots delete <snapshotId>

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<snapshotId> --snapshot-id string /^kfs-[0-9a-f]{12}$/

dcloud cache

Caches. Base path /cache/api.

dcloud cache clusters

Managed Valkey caches, private to one VPC

Operation Method Path IAM action Effect
list GET /cache/api/clusters cache:DescribeCacheClusters read
ca-bundle GET /cache/api/ca-bundle cache:DescribeCacheClusters read
node-types GET /cache/api/node-types cache:DescribeCacheClusters read
create POST /cache/api/clusters cache:CreateCacheCluster write
get GET /cache/api/clusters/{id} cache:DescribeCacheClusters read
events GET /cache/api/clusters/{id}/events cache:DescribeCacheClusters read
modify PATCH /cache/api/clusters/{id} cache:ModifyCacheCluster write
reboot POST /cache/api/clusters/{id}/reboot cache:RebootCacheCluster write
rotate-storage-key POST /cache/api/clusters/{id}/rotate-storage-key cache:RotateCacheStorageKey write
rotate-password POST /cache/api/clusters/{id}/password/rotate cache:RotateCachePassword write
delete DELETE /cache/api/clusters/{id} cache:DeleteCacheCluster write
snapshot POST /cache/api/clusters/{id}/snapshots cache:CreateCacheSnapshot write

dcloud cache clusters list

List caches

GET /cache/api/clusters — IAM cache:DescribeCacheClusters — read

dcloud cache clusters list

dcloud cache clusters ca-bundle

The platform CA (PEM) a TLS cache’s certificate chains to

GET /cache/api/ca-bundle — IAM cache:DescribeCacheClusters — read

dcloud cache clusters ca-bundle

dcloud cache clusters node-types

The machine types a cache can run on, with price and stock

GET /cache/api/node-types — IAM cache:DescribeCacheClusters — read

dcloud cache clusters node-types

dcloud cache clusters create

Create a cache

POST /cache/api/clusters — IAM cache:CreateCacheCluster — write

dcloud cache clusters create --identifier <value> --node-type <value> [flags]
Flag In Required Notes
--region-id <value> body 1-32 chars · Region to create in (default: the X-EWS-Region header, else de1). fi1 (Helsinki, Finland) needs the organization setting "allow EU outside Germany".
--identifier <value> body yes 3-40 chars, /^[a-z][a-z0-9-]*[a-z0-9]$/
--node-type <value> body yes 1-32 chars · An instance type from node-types, e.g. performance-2. The provider’s own type names are still accepted, deprecated.
--eviction-policy <noeviction|allkeys-lru|allkeys-lfu|volatile-lru|volatile-lfu|volatile-ttl> body server default "allkeys-lru"
--vpc-id <value> body uuid
--tags <key=value> body repeatable · key=value
--kms-key-id <value> body uuid
--replicas <number> body integer, 0-2 · server default 0 · Replicas on other hosts, with Sentinel failover behind the same address (0: one node)
--tls body server default true · TLS only on port 6380 (rediss://, platform CA), replication and Sentinels included. false: plaintext on 6379
--snapshot-id <value> body /^ecs-[0-9a-f]{12}$/ · Make the cache from this snapshot; needs cache:CreateCacheCluster on the snapshot
--capacity-fallback <json> body JSON · What a create may fall back to when the provider is out of stock
--on-stock-out <fail|wait> body When the type is sold out where it goes and no fallback applies: fail at once (default), or wait as waiting-for-capacity (nothing built or billed) until it is back
--capacity-max-wait-hours <number> body integer, 1-168 · With onStockOut wait: give up after this many hours (1–168, default 24)
  • Without vpcId the cache joins the default VPC, where deployed apps run. It is creating until the machine reports a healthy Valkey, usually within three minutes. The password is filed in Secrets as VALKEY__PASSWORD.

dcloud cache clusters get

One cache, with its private address, usage and bound apps

GET /cache/api/clusters/{id} — IAM cache:DescribeCacheClusters — read

dcloud cache clusters get <id>

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<id> --id string /^ewc-[0-9a-f]{12}$/

dcloud cache clusters events

The cache’s activity: provisioning steps and what the machine reported

GET /cache/api/clusters/{id}/events — IAM cache:DescribeCacheClusters — read

dcloud cache clusters events <id> [flags]

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<id> --id string /^ewc-[0-9a-f]{12}$/
Flag In Required Notes
--since <value> query
--limit <number> query integer, 1-500

dcloud cache clusters modify

Change the eviction policy (applied live within a minute) or, on own hosts, the replica count

PATCH /cache/api/clusters/{id} — IAM cache:ModifyCacheCluster — write

dcloud cache clusters modify <id> [flags]

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<id> --id string /^ewc-[0-9a-f]{12}$/
Flag In Required Notes
--eviction-policy <noeviction|allkeys-lru|allkeys-lfu|volatile-lru|volatile-lfu|volatile-ttl> body
--replicas <number> body integer, 0-2 · Own hosts only (the address is a virtual IP): 0 → 1 or 2, or back to 0, on a live cache; the URL stays and it serves throughout
  • A replica change answers 202 with the cache modifying until new nodes are in sync and every node runs the new majority (a few minutes); addressKind says whether the cache can (virtual-ip).

dcloud cache clusters reboot

Restart the cache’s machine (data survives on its volume). With replicas: one node, the primary unless nodeId names another — a failover test

POST /cache/api/clusters/{id}/reboot — IAM cache:RebootCacheCluster — write

dcloud cache clusters reboot <id> [flags]

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<id> --id string /^ewc-[0-9a-f]{12}$/
Flag In Required Notes
--node-id <value> body max 64 chars

dcloud cache clusters rotate-storage-key

Replace the encrypted data volume’s LUKS passphrase with a new key

POST /cache/api/clusters/{id}/rotate-storage-key — IAM cache:RotateCacheStorageKey — write

dcloud cache clusters rotate-storage-key <id>

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<id> --id string /^ewc-[0-9a-f]{12}$/
  • Answers 202 with each volume’s key version. The node adds the new key, removes the old one and reports within five minutes; Valkey keeps running. The dm-crypt volume key itself is not changed.

dcloud cache clusters rotate-password

Replace the cache’s password with a new Secrets version

POST /cache/api/clusters/{id}/password/rotate — IAM cache:RotateCachePassword — write

dcloud cache clusters rotate-password <id> [flags]

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<id> --id string /^ewc-[0-9a-f]{12}$/
Flag In Required Notes
--redeploy-apps body server default true
  • The machine takes the new password within a minute; with redeployApps (default) every bound app is then redeployed, which also needs deploy:DeployApp on each.

dcloud cache clusters delete

Delete a cache, its machine, volume and password

DELETE /cache/api/clusters/{id} — IAM cache:DeleteCacheCluster — write

dcloud cache clusters delete <id> [flags]

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<id> --id string /^ewc-[0-9a-f]{12}$/
Flag In Required Notes
--final-snapshot <true|false> query true: take a snapshot first and keep it until you delete it; if it fails, nothing is deleted
  • Refused (409, naming the apps) while an app is bound to it. Its daily snapshots go with it; manual ones stay. With finalSnapshot=true a snapshot is taken first and kept until you delete it (counted as a manual snapshot); if it fails, nothing is deleted and the cache is available again.

dcloud cache clusters snapshot

Take a snapshot now (a replica takes it when there is one)

POST /cache/api/clusters/{id}/snapshots — IAM cache:CreateCacheSnapshot — write

dcloud cache clusters snapshot <id>

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<id> --id string /^ewc-[0-9a-f]{12}$/
  • Answers 202 with the snapshot pending; a node takes it at its next report (within a minute) and it is available once uploaded. Manual snapshots are kept until deleted, also after the cache is.

dcloud cache snapshots

Encrypted point-in-time copies of a cache: daily (kept 7 days) and manual. Restore = a new cache with snapshotId

Operation Method Path IAM action Effect
list GET /cache/api/snapshots cache:DescribeCacheSnapshots read
get GET /cache/api/snapshots/{snapshotId} cache:DescribeCacheSnapshots read
delete DELETE /cache/api/snapshots/{snapshotId} cache:DeleteCacheSnapshot write

dcloud cache snapshots list

List snapshots, optionally of one cache

GET /cache/api/snapshots — IAM cache:DescribeCacheSnapshots — read

dcloud cache snapshots list [flags]
Flag In Required Notes
--cache-id <value> query /^ewc-[0-9a-f]{12}$/

dcloud cache snapshots get

One snapshot: state, size, key count, SHA-256

GET /cache/api/snapshots/{snapshotId} — IAM cache:DescribeCacheSnapshots — read

dcloud cache snapshots get <snapshotId>

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<snapshotId> --snapshot-id string /^ecs-[0-9a-f]{12}$/

dcloud cache snapshots delete

Delete a snapshot and its stored copy

DELETE /cache/api/snapshots/{snapshotId} — IAM cache:DeleteCacheSnapshot — write

dcloud cache snapshots delete <snapshotId>

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<snapshotId> --snapshot-id string /^ecs-[0-9a-f]{12}$/

dcloud efs

File Storage. Base path /efs/api.

dcloud efs file-systems

Shared NFSv4.2 file systems in a VPC: mount from instances and Kubernetes (ReadWriteMany)

Operation Method Path IAM action Effect
list GET /efs/api/file-systems efs:DescribeFileSystems read
create POST /efs/api/file-systems efs:CreateFileSystem write
get GET /efs/api/file-systems/{id} efs:DescribeFileSystems read
events GET /efs/api/file-systems/{id}/events efs:DescribeFileSystems read
update PATCH /efs/api/file-systems/{id} efs:UpdateFileSystem write
delete DELETE /efs/api/file-systems/{id} efs:DeleteFileSystem write

dcloud efs file-systems list

List file systems with their mount address and usage

GET /efs/api/file-systems — IAM efs:DescribeFileSystems — read

dcloud efs file-systems list

dcloud efs file-systems create

Create a file system

POST /efs/api/file-systems — IAM efs:CreateFileSystem — write

dcloud efs file-systems create --name <value> --size-gib <number> --node-type <json> [flags]
Flag In Required Notes
--name <value> body yes 1-63 chars, /^a-z0-9?$/
--size-gib <number> body yes integer, 10-10240
--region-id <value> body 1-32 chars · Region to create in (default: the X-EWS-Region header, else de1). fi1 (Helsinki, Finland) needs the organization setting "allow EU outside Germany".
--availability-zone-id <value> body 1-32 chars
--vpc-id <value> body
--node-type <json> body yes JSON
--kms-key-id <value> body
--tags <key=value> body repeatable · key=value · Tags for the new resource, e.g. {"env": "prod", "project": "shop"}. Keys your organization marks required must be present, or the create is refused with the missing keys (GET /tags/api/keys lists them).
  • name, sizeGib (10–10240), availabilityZoneId (default the region’s default zone), vpcId (default VPC), nodeType (performance-2|performance-4|performance-8; the provider’s own type names are still accepted, deprecated), kmsKeyId. Always encrypted (LUKS2). Status creating → available in a few minutes; mount :/ over NFSv4.2 from anywhere in the VPC.

dcloud efs file-systems get

One file system: status, size, usage, mount command and fstab line

GET /efs/api/file-systems/{id} — IAM efs:DescribeFileSystems — read

dcloud efs file-systems get <id>

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<id> --id string /^fs-[0-9a-f]{12}$/

dcloud efs file-systems events

What happened to the file system and on its machine

GET /efs/api/file-systems/{id}/events — IAM efs:DescribeFileSystems — read

dcloud efs file-systems events <id>

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<id> --id string /^fs-[0-9a-f]{12}$/

dcloud efs file-systems update

Grow a file system online (it never shrinks)

PATCH /efs/api/file-systems/{id} — IAM efs:UpdateFileSystem — write

dcloud efs file-systems update <id> --size-gib <number>

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<id> --id string /^fs-[0-9a-f]{12}$/
Flag In Required Notes
--size-gib <number> body yes integer, 10-10240

dcloud efs file-systems delete

Delete a file system with every file and snapshot in it

DELETE /efs/api/file-systems/{id} — IAM efs:DeleteFileSystem — write

dcloud efs file-systems delete <id>

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<id> --id string /^fs-[0-9a-f]{12}$/
  • Its volume key is destroyed with it: the blocks are unreadable from then on.

dcloud efs snapshots

Read-only point-in-time copies, visible to every client under /.snapshots/

Operation Method Path IAM action Effect
list GET /efs/api/file-systems/{id}/snapshots efs:DescribeSnapshots read
create POST /efs/api/file-systems/{id}/snapshots efs:CreateSnapshot write
delete DELETE /efs/api/file-systems/{id}/snapshots/{snapshot} efs:DeleteSnapshot write

dcloud efs snapshots list

List a file system’s snapshots

GET /efs/api/file-systems/{id}/snapshots — IAM efs:DescribeSnapshots — read

dcloud efs snapshots list <id>

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<id> --id string /^fs-[0-9a-f]{12}$/

dcloud efs snapshots create

Take a snapshot (available within about 15 seconds)

POST /efs/api/file-systems/{id}/snapshots — IAM efs:CreateSnapshot — write

dcloud efs snapshots create <id> --name <value>

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<id> --id string /^fs-[0-9a-f]{12}$/
Flag In Required Notes
--name <value> body yes /^[a-z0-9][a-z0-9-]{0,39}$/
  • Instant and space-sharing (LVM thin). Refused while the volume is 80 % full; at 90 % the oldest snapshot is removed and the activity feed says so.

dcloud efs snapshots delete

Delete a snapshot

DELETE /efs/api/file-systems/{id}/snapshots/{snapshot} — IAM efs:DeleteSnapshot — write

dcloud efs snapshots delete <id> <snapshot>

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<id> --id string /^fs-[0-9a-f]{12}$/
<snapshot> --snapshot string /^[a-z0-9][a-z0-9-]{0,39}$/

dcloud eks

Kubernetes. Base path /eks/api.

dcloud eks versions

The Kubernetes versions, tiers and node server types on offer

Operation Method Path IAM action Effect
list GET /eks/api/versions eks:ListClusters read

dcloud eks versions list

List Kubernetes versions, control-plane tiers and node server types

GET /eks/api/versions — IAM eks:ListClusters — read

dcloud eks versions list

dcloud eks clusters

Kubernetes clusters whose control plane Deutsche Cloud runs

Operation Method Path IAM action Effect
list GET /eks/api/clusters eks:ListClusters read
create POST /eks/api/clusters eks:CreateCluster write
get GET /eks/api/clusters/{cluster} eks:DescribeCluster read
update PATCH /eks/api/clusters/{cluster} eks:UpdateClusterConfig write
upgrade PUT /eks/api/clusters/{cluster}/version eks:UpdateClusterVersion write
retry-upgrade POST /eks/api/clusters/{cluster}/upgrade/retry eks:UpdateClusterVersion write
cancel-upgrade POST /eks/api/clusters/{cluster}/upgrade/cancel eks:UpdateClusterVersion write
restore POST /eks/api/clusters/{cluster}/restore eks:RestoreCluster write
postpone-upgrade POST /eks/api/clusters/{cluster}/forced-upgrade/postpone eks:PostponeClusterUpgrade write
availability GET /eks/api/clusters/{cluster}/availability eks:DescribeCluster read
delete DELETE /eks/api/clusters/{cluster} eks:DeleteCluster write
logs GET /eks/api/clusters/{cluster}/logs eks:GetClusterLogs read
events GET /eks/api/clusters/{cluster}/events eks:DescribeCluster read
kubeconfig GET /eks/api/clusters/{cluster}/kubeconfig eks:DescribeCluster read
token POST /eks/api/clusters/{cluster}/token eks:AccessKubernetesApi write
admin-credentials POST /eks/api/clusters/{cluster}/admin-credentials eks:GetClusterAdminCredentials write

dcloud eks clusters list

List clusters

GET /eks/api/clusters — IAM eks:ListClusters — read

dcloud eks clusters list

dcloud eks clusters create

Create a cluster

POST /eks/api/clusters — IAM eks:CreateCluster — write

dcloud eks clusters create --name <value> [flags]
Flag In Required Notes
--region-id <value> body 1-32 chars · Region to create in (default: the X-EWS-Region header, else de1). fi1 (Helsinki, Finland) needs the organization setting "allow EU outside Germany".
--name <value> body yes /^a-z?$/ · Cluster name, unique in the organization (409 when taken): lowercase letters, digits and hyphens, starting with a letter, at most 40 characters
--version <1.36|1.37> body Kubernetes minor; default the regular channel
--tier <dev|standard> body dev: one control-plane machine, no SLA. standard: three, highly available
--vpc-id <value> body VPC the node groups join; default VPC if unset
--allowed-cidrs <value> body repeatable · cidrv4 · CIDRs allowed to reach the public endpoint, e.g. ["203.0.113.0/24"]
--endpoint-public-access body The endpoint answers on its public address (to allowedCidrs); default true
--endpoint-private-access body The endpoint answers inside the VPC; default true
--deletion-protection body true: a delete is refused (409) until it is turned off. Default false
--nodegroup <json> body JSON · A first node group, created once the control plane is up
--addons <value> body repeatable · Add-ons to install. Default: metrics-server. [] installs none
--logging <json> body JSON · Default: audit only
--tags <key=value> body repeatable · key=value · Tags for the new resource, e.g. {"env": "prod", "project": "shop"}. Keys your organization marks required must be present, or the create is refused with the missing keys (GET /tags/api/keys lists them).
  • tier dev runs one control-plane machine, standard three. The creator gets a ClusterAdmin access entry. nodegroup creates a first node group once the control plane is up and also needs eks:CreateNodegroup (and iam:PassRole when nodeRole is set). 409 when the name is taken.

dcloud eks clusters get

One cluster: endpoint, version, status, control-plane readiness

GET /eks/api/clusters/{cluster} — IAM eks:DescribeCluster — read

dcloud eks clusters get <cluster>

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<cluster> --cluster string /^(ewk-[0-9a-f]{12}|a-z?)$/

dcloud eks clusters update

Change the networks allowed to reach the API endpoint, or deletion protection

PATCH /eks/api/clusters/{cluster} — IAM eks:UpdateClusterConfig — write

dcloud eks clusters update <cluster> [flags]

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<cluster> --cluster string /^(ewk-[0-9a-f]{12}|a-z?)$/
Flag In Required Notes
--allowed-cidrs <value> body repeatable · cidrv4 · CIDRs allowed to reach the public endpoint, e.g. ["203.0.113.0/24"]
--endpoint-public-access body The endpoint answers on its public address (to allowedCidrs); default true
--endpoint-private-access body The endpoint answers inside the VPC; default true
--deletion-protection body true: a delete is refused (409) until it is turned off. Unchanged when absent
--autoscaler <json> body JSON · The cluster autoscaler’s settings; it acts on node groups with autoscaling on
--logging <json> body JSON · Control-plane log types shipped to monitoring: api, audit, authenticator, controllerManager, scheduler

dcloud eks clusters upgrade

Upgrade the control plane to the next Kubernetes minor

PUT /eks/api/clusters/{cluster}/version — IAM eks:UpdateClusterVersion — write

dcloud eks clusters upgrade <cluster> --version <1.36|1.37>

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<cluster> --cluster string /^(ewk-[0-9a-f]{12}|a-z?)$/
Flag In Required Notes
--version <1.36|1.37> body yes The next Kubernetes minor, one above the cluster’s
  • One minor at a time, never down. Each control-plane machine is replaced by one at the new minor, one at a time; the API answers throughout (dev tier too). The cluster is updating until every machine runs the new minor; then upgrade node groups with nodegroups upgrade. 409 while the cluster is not active or its control plane is not settled.

dcloud eks clusters retry-upgrade

Ask again, now, for the pre-upgrade snapshot a held upgrade waits for

POST /eks/api/clusters/{cluster}/upgrade/retry — IAM eks:UpdateClusterVersion — write

dcloud eks clusters retry-upgrade <cluster>

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<cluster> --cluster string /^(ewk-[0-9a-f]{12}|a-z?)$/
  • An upgrade replaces no machine until its own pre-upgrade etcd snapshot is verified; when that snapshot fails the upgrade is held (upgrade.held on the cluster) and Deutsche Cloud retries every 15 minutes. This asks now: at most once per 5 minutes, 409 while one is being taken or when nothing is held.

dcloud eks clusters cancel-upgrade

Cancel a control-plane upgrade before its first machine is replaced

POST /eks/api/clusters/{cluster}/upgrade/cancel — IAM eks:UpdateClusterVersion — write

dcloud eks clusters cancel-upgrade <cluster>

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<cluster> --cluster string /^(ewk-[0-9a-f]{12}|a-z?)$/
  • The cluster goes back to the minor its control plane runs (upgrade.canCancel). 409 once a machine runs the new minor (the upgrade can only go on), and for Deutsche Cloud’s upgrade after the end of support.

dcloud eks clusters restore

Restore the control plane from one of the cluster’s etcd snapshots

POST /eks/api/clusters/{cluster}/restore — IAM eks:RestoreCluster — write

dcloud eks clusters restore <cluster> --snapshot-id <value> --confirm <value>

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<cluster> --cluster string /^(ewk-[0-9a-f]{12}|a-z?)$/
Flag In Required Notes
--snapshot-id <value> body yes /^etcds-[0-9a-f]{12}$/ · A verified snapshot of this cluster (dcloud eks snapshots list)
--confirm <value> body yes 1-100 chars · The cluster’s name, to confirm: every object created after the snapshot is lost
  • Every Kubernetes object returns to the snapshot; objects created since are gone. A pre-restore snapshot is taken first, so a restore can be undone. Then every control-plane machine is replaced: the API is down until the first new one has restored etcd (about 5–10 minutes), worker nodes keep running their pods and reconnect, kubeconfigs keep working (same CA and endpoint). Only verified snapshots; confirm must be the cluster’s name. 409 unless the cluster is active (one restore at a time, none during an upgrade or a deletion). A customer’s restore is excluded from the SLA for its first 30 minutes.

dcloud eks clusters postpone-upgrade

Postpone Deutsche Cloud’s control-plane upgrade after end of support, once, by 14 days

POST /eks/api/clusters/{cluster}/forced-upgrade/postpone — IAM eks:PostponeClusterUpgrade — write

dcloud eks clusters postpone-upgrade <cluster>

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<cluster> --cluster string /^(ewk-[0-9a-f]{12}|a-z?)$/
  • Thirty days after a minor’s end of support Deutsche Cloud upgrades the control plane one minor, on a Tuesday–Thursday at 10:00 Berlin time announced at least seven days ahead (forcedUpgrade on the cluster). Once announced and until it starts, the owners may move it 14 days later, once; a second move goes through Deutsche Cloud support. 409 when none is scheduled, it was postponed already, or it has started.

dcloud eks clusters availability

The month’s measured API availability, SLA result and credit, each unavailable minute and which measurement saw it, and the outside probes

GET /eks/api/clusters/{cluster}/availability — IAM eks:DescribeCluster — read

dcloud eks clusters availability <cluster> [flags]

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<cluster> --cluster string /^(ewk-[0-9a-f]{12}|a-z?)$/
Flag In Required Notes
--month <value> query /^\d{4}-(0[1-9]|1[0-2])$/ · YYYY-MM (UTC); default: this month
  • A minute is unavailable when no control-plane machine reported a serving API (agent), or a strict majority (at least two) of Deutsche Cloud’s outside probe locations failed GET /readyz (outside). A minute with no machine report at all while at least two outside locations all got answers is Deutsche Cloud’s blind spot: listed with source ews-blind-spot, counted as available (blindSpotMinutes). probes is the last decided minute per location; platformAddresses are the addresses those requests come from, let through the endpoint while it is public.

dcloud eks clusters delete

Delete a cluster, its control plane, node groups and nodes

DELETE /eks/api/clusters/{cluster} — IAM eks:DeleteCluster — write

dcloud eks clusters delete <cluster> [flags]

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<cluster> --cluster string /^(ewk-[0-9a-f]{12}|a-z?)$/
Flag In Required Notes
--permanent <true|false> query true: nothing is kept (no final snapshot, volumes deleted), the cluster cannot be restored. Default: restorable for 7 days
  • 409 while deletion protection is on. By default a final etcd snapshot is taken and the cluster can be restored for 7 days (deleted-clusters restore): its settings, key material and PersistentVolumes’ volumes are kept, detached and free. permanent=true keeps nothing.

dcloud eks clusters logs

Control-plane logs: the Kubernetes audit log, API server, authenticator, controller manager, scheduler

GET /eks/api/clusters/{cluster}/logs — IAM eks:GetClusterLogs — read

dcloud eks clusters logs <cluster> [flags]

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<cluster> --cluster string /^(ewk-[0-9a-f]{12}|a-z?)$/
Flag In Required Notes
--type <api|audit|authenticator|controllerManager|scheduler> query Only this log type: api, audit, authenticator, controllerManager or scheduler. Default: every type
--since <value> query ISO time, inclusive. Default: one hour before until
--until <value> query ISO time, inclusive. Default: now
--contains <value> query max 200 chars · Only lines whose message contains this text, ignoring case; at most 200 characters
--limit <number> query integer, 1-1000 · At most this many lines, newest first, 1–1000; default 200
  • Kept 7 days. Only the types turned on in the cluster’s logging (audit by default; change it with clusters update --logging) are collected. The audit log leaves out reads by the cluster’s own components that succeeded; every write, every refusal and every request by a person or a workload is in it.

dcloud eks clusters events

The cluster’s activity: provisioning steps, changes, control-plane reports

GET /eks/api/clusters/{cluster}/events — IAM eks:DescribeCluster — read

dcloud eks clusters events <cluster> [flags]

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<cluster> --cluster string /^(ewk-[0-9a-f]{12}|a-z?)$/
Flag In Required Notes
--since <value> query Only events strictly after this ISO time (for polling). Default: from the first
--limit <number> query integer, 1-500 · At most this many events, oldest first, 1–500; default 200

dcloud eks clusters kubeconfig

The endpoint and CA a kubeconfig entry needs

GET /eks/api/clusters/{cluster}/kubeconfig — IAM eks:DescribeCluster — read

dcloud eks clusters kubeconfig <cluster>

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<cluster> --cluster string /^(ewk-[0-9a-f]{12}|a-z?)$/
  • dcloud eks update-kubeconfig writes the entry from this, with dcloud eks get-token as its exec plugin.

dcloud eks clusters token

A 10-minute Kubernetes API token for the cluster, as an ExecCredential

POST /eks/api/clusters/{cluster}/token — IAM eks:AccessKubernetesApi — write

dcloud eks clusters token <cluster>

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<cluster> --cluster string /^(ewk-[0-9a-f]{12}|a-z?)$/
  • Needs eks:AccessKubernetesApi AND an access entry on the cluster (403 otherwise). The token carries your Deutsche Cloud identity as ews:<username> and your access entries as groups; aud is the cluster id.

dcloud eks clusters admin-credentials

Break glass: a one-hour cluster-admin client certificate

POST /eks/api/clusters/{cluster}/admin-credentials — IAM eks:GetClusterAdminCredentials — write

dcloud eks clusters admin-credentials <cluster>

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<cluster> --cluster string /^(ewk-[0-9a-f]{12}|a-z?)$/
  • For when Deutsche Cloud sign-in or RBAC is broken. Cannot be revoked, so it lasts an hour; every issuance is in the audit log and on the cluster’s Activity.

dcloud eks deleted-clusters

Deleted clusters that can still be restored (7 days)

Operation Method Path IAM action Effect
list GET /eks/api/deleted-clusters eks:ListClusters read
restore POST /eks/api/deleted-clusters/{cluster}/restore eks:RestoreCluster write
purge POST /eks/api/deleted-clusters/{cluster}/purge eks:DeleteCluster write

dcloud eks deleted-clusters list

List deleted clusters that can be restored, with their expiry and kept volumes

GET /eks/api/deleted-clusters — IAM eks:ListClusters — read

dcloud eks deleted-clusters list

dcloud eks deleted-clusters restore

Restore a deleted cluster from its final etcd snapshot

POST /eks/api/deleted-clusters/{cluster}/restore — IAM eks:RestoreCluster — write

dcloud eks deleted-clusters restore <cluster> --confirm <value>

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<cluster> --cluster string 1-100 chars, /^[a-z0-9][a-z0-9-]*$/
Flag In Required Notes
--confirm <value> body yes 1-100 chars · The deleted cluster’s name, to confirm
  • The cluster comes back under the same id and name with its settings, node groups, access entries, add-ons and pod identity associations. Deutsche Cloud builds the control plane again from the final snapshot (same CA and keys, the same endpoint name, behind a new load balancer whose address may change; kubeconfigs keep working), then the node groups’ nodes; the kept volumes attach again when their pods run; Service load balancers get new addresses. Billed and counted in the quota from the restore on. 409 when the name is taken by another cluster, the quota is full, the VPC is gone or the 7 days are over. confirm must be the cluster’s name.

dcloud eks deleted-clusters purge

Delete what a deleted cluster kept, now: final snapshot, key material, volumes

POST /eks/api/deleted-clusters/{cluster}/purge — IAM eks:DeleteCluster — write

dcloud eks deleted-clusters purge <cluster> --confirm <value>

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<cluster> --cluster string 1-100 chars, /^[a-z0-9][a-z0-9-]*$/
Flag In Required Notes
--confirm <value> body yes 1-100 chars · The deleted cluster’s name, to confirm: its final snapshot, key material and kept volumes are deleted now, irreversibly
  • Irreversible: the cluster can no longer be restored. Otherwise this happens on its own 7 days after the deletion. confirm must be the cluster’s name.

dcloud eks snapshots

etcd snapshots of a cluster’s control plane, taken by Deutsche Cloud

Operation Method Path IAM action Effect
list GET /eks/api/clusters/{cluster}/snapshots eks:ListClusterSnapshots read
create POST /eks/api/clusters/{cluster}/snapshots eks:CreateClusterSnapshot write

dcloud eks snapshots list

List the cluster’s etcd snapshots and its backup status

GET /eks/api/clusters/{cluster}/snapshots — IAM eks:ListClusterSnapshots — read

dcloud eks snapshots list <cluster>

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<cluster> --cluster string /^(ewk-[0-9a-f]{12}|a-z?)$/
  • Deutsche Cloud takes one every hour (kept 7 days, the first of each UTC day 30 days), before every upgrade and restore, and on deletion (kept 7 days); on-demand ones are kept 30 days, the 10 newest. Each is checked by restoring it into a scratch directory on the machine (verifiedAt), sealed under Deutsche Cloud’s master key in its object storage. The newest verified one is never deleted. backup.status is stale without a verified snapshot for 2 hours, not-enabled for a control plane built before backups (replace it to enable them). Snapshots cannot be downloaded.

dcloud eks snapshots create

Take an etcd snapshot now

POST /eks/api/clusters/{cluster}/snapshots — IAM eks:CreateClusterSnapshot — write

dcloud eks snapshots create <cluster>

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<cluster> --cluster string /^(ewk-[0-9a-f]{12}|a-z?)$/
  • One in flight and at most one per 10 minutes (409 otherwise). evicts names the on-demand snapshot this one pushes out of the 10 kept. The snapshot is pending until the leading control-plane machine has taken, checked and uploaded it, usually within a minute.

dcloud eks nodegroups

Sets of compute instances that join a cluster as nodes

Operation Method Path IAM action Effect
list GET /eks/api/clusters/{cluster}/nodegroups eks:ListNodegroups read
create POST /eks/api/clusters/{cluster}/nodegroups eks:CreateNodegroup write
get GET /eks/api/clusters/{cluster}/nodegroups/{name} eks:DescribeNodegroup read
update PATCH /eks/api/clusters/{cluster}/nodegroups/{name} eks:UpdateNodegroupConfig write
upgrade PUT /eks/api/clusters/{cluster}/nodegroups/{name}/version eks:UpdateNodegroupVersion write
delete DELETE /eks/api/clusters/{cluster}/nodegroups/{name} eks:DeleteNodegroup write

dcloud eks nodegroups list

List a cluster’s node groups with their nodes

GET /eks/api/clusters/{cluster}/nodegroups — IAM eks:ListNodegroups — read

dcloud eks nodegroups list <cluster>

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<cluster> --cluster string /^(ewk-[0-9a-f]{12}|a-z?)$/

dcloud eks nodegroups create

Add a node group

POST /eks/api/clusters/{cluster}/nodegroups — IAM eks:CreateNodegroup — write

dcloud eks nodegroups create <cluster> --name <value> --instance-type <value> --min-size <number> --desired-size <number> --max-size <number> [flags]

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<cluster> --cluster string /^(ewk-[0-9a-f]{12}|a-z?)$/
Flag In Required Notes
--name <value> body yes /^a-z?$/ · Node group name, unique in the cluster (409 when taken): lowercase letters, digits and hyphens, starting with a letter, at most 32 characters
--drain-timeout-minutes <number> body integer, 5-1440 · Upgrades: minutes a node’s drain may wait on PodDisruptionBudgets; default 60
--force-after-timeout body Upgrades: after the timeout, remove the node anyway (true) or pause the upgrade (false, default)
--autoscaling body Let the cluster autoscaler change desiredSize between minSize and maxSize (pending pods grow the group, underused nodes shrink it)
--zones <value> body repeatable · /^[a-z]+[0-9]+[a-z]$/ · Availability zones the nodes spread over, balanced (e.g. ["de1a","de1b"]); default the region’s default zone. Applies to nodes created from then on
--instance-types <value> body repeatable · /^[a-z0-9-]{2,24}$/ · Instance types to buy, in order, when instanceType is sold out in a zone (same CPU architecture), e.g. performance-8
--capacity-fallback <json> body JSON · Stock fallback; default off. otherZones: zones outside zones may be used; equivalentTypes: an equivalent server type may be bought
--instance-type <value> body yes 1-32 chars · An instance type, e.g. performance-4. The provider’s own type names are still accepted, deprecated.
--labels <key=value> body repeatable · key=value · Kubernetes labels on every node, e.g. {"workload":"web"}; at most 20. kubernetes.io/, k8s.io/ and eks.ews.cloud/ keys are refused (400). Default none
--taints <value> body repeatable · Kubernetes taints on every node: { key, value?, effect: NoSchedule | PreferNoSchedule | NoExecute }; at most 10. Default none
--node-role <value> body 1-128 chars · Name of an IAM role the nodes act as; needs iam:PassRole on it
--tags <key=value> body repeatable · key=value · Tags for the new resource, e.g. {"env": "prod", "project": "shop"}. Keys your organization marks required must be present, or the create is refused with the missing keys (GET /tags/api/keys lists them).
--min-size <number> body yes integer, 0-100 · Fewest nodes, 0–100; the cluster autoscaler never goes below it. minSize ≤ desiredSize ≤ maxSize, else 400
--desired-size <number> body yes integer, 0-100 · Nodes to run now, 0–100; with autoscaling on, the cluster autoscaler changes it between minSize and maxSize
--max-size <number> body yes integer, 1-100 · Most nodes, 1–100; what the quotas count (nodes per node group, and nodes per cluster summed over its node groups; 20 and 50 by default): 409 QuotaExceeded above them
  • The nodes run the cluster’s Kubernetes version and appear in Compute, locked to the node group. nodeRole needs iam:PassRole on that role.

dcloud eks nodegroups get

One node group and its nodes

GET /eks/api/clusters/{cluster}/nodegroups/{name} — IAM eks:DescribeNodegroup — read

dcloud eks nodegroups get <cluster> <name>

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<cluster> --cluster string /^(ewk-[0-9a-f]{12}|a-z?)$/
<name> --name string /^a-z?$/

dcloud eks nodegroups update

Scale a node group or change its labels and taints

PATCH /eks/api/clusters/{cluster}/nodegroups/{name} — IAM eks:UpdateNodegroupConfig — write

dcloud eks nodegroups update <cluster> <name> [flags]

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<cluster> --cluster string /^(ewk-[0-9a-f]{12}|a-z?)$/
<name> --name string /^a-z?$/
Flag In Required Notes
--min-size <number> body integer, 0-100 · Fewest nodes, 0–100; the cluster autoscaler never goes below it. minSize ≤ desiredSize ≤ maxSize, else 400, checked against the sizes not sent. Unchanged when absent
--desired-size <number> body integer, 0-100 · Nodes to run now, 0–100; with autoscaling on, the cluster autoscaler changes it between minSize and maxSize. Scaling down drains the nodes it removes. Unchanged when absent
--max-size <number> body integer, 1-100 · Most nodes, 1–100; what the quotas count (nodes per node group, and nodes per cluster summed over its node groups; 20 and 50 by default): 409 QuotaExceeded above them; only growth is checked, shrinking is always allowed. Unchanged when absent
--labels <key=value> body repeatable · key=value · Replaces the node labels as a whole; at most 20, kubernetes.io/, k8s.io/ and eks.ews.cloud/ keys refused (400). {} removes them all. Unchanged when absent
--taints <value> body repeatable · Replaces the node taints as a whole: { key, value?, effect: NoSchedule | PreferNoSchedule | NoExecute }; at most 10. [] removes them all. Unchanged when absent
--instance-type <value> body 1-32 chars · Instance type for nodes created from now on, e.g. performance-4 (provider names still accepted, deprecated); nodes already running keep theirs until they are replaced. A group stopped after failed nodes starts again
--drain-timeout-minutes <number> body integer, 5-1440 · Upgrades: minutes a node’s drain may wait on PodDisruptionBudgets; default 60
--force-after-timeout body Upgrades: after the timeout, remove the node anyway (true) or pause the upgrade (false, default)
--autoscaling body Let the cluster autoscaler change desiredSize between minSize and maxSize (pending pods grow the group, underused nodes shrink it)
--zones <value> body repeatable · /^[a-z]+[0-9]+[a-z]$/ · Availability zones the nodes spread over, balanced (e.g. ["de1a","de1b"]); default the region’s default zone. Applies to nodes created from then on
--instance-types <value> body repeatable · /^[a-z0-9-]{2,24}$/ · Instance types to buy, in order, when instanceType is sold out in a zone (same CPU architecture), e.g. performance-8
--capacity-fallback <json> body JSON · Stock fallback; default off. otherZones: zones outside zones may be used; equivalentTypes: an equivalent server type may be bought
  • Scaling down drains the nodes it removes (respecting PodDisruptionBudgets) first.

dcloud eks nodegroups upgrade

Upgrade a node group to the cluster’s Kubernetes minor

PUT /eks/api/clusters/{cluster}/nodegroups/{name}/version — IAM eks:UpdateNodegroupVersion — write

dcloud eks nodegroups upgrade <cluster> <name> [flags]

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<cluster> --cluster string /^(ewk-[0-9a-f]{12}|a-z?)$/
<name> --name string /^a-z?$/
Flag In Required Notes
--version <1.36|1.37> body Kubernetes minor for the nodes; default the cluster’s, never above it
  • Surge replacement: one extra node at the new minor, then one node behind is drained and removed, until none is behind. PodDisruptionBudgets are respected for the group’s drainTimeoutMinutes (default 60) per node; then the upgrade pauses at that node, or with forceAfterTimeout the node goes anyway. Never above the control plane’s minor.

dcloud eks nodegroups delete

Delete a node group and its nodes

DELETE /eks/api/clusters/{cluster}/nodegroups/{name} — IAM eks:DeleteNodegroup — write

dcloud eks nodegroups delete <cluster> <name>

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<cluster> --cluster string /^(ewk-[0-9a-f]{12}|a-z?)$/
<name> --name string /^a-z?$/

dcloud eks access-entries

Which IAM users, groups and roles may use kubectl on a cluster, and how

Operation Method Path IAM action Effect
list GET /eks/api/clusters/{cluster}/access-entries eks:ListAccessEntries read
create POST /eks/api/clusters/{cluster}/access-entries eks:CreateAccessEntry write
get GET /eks/api/clusters/{cluster}/access-entries/{id} eks:DescribeAccessEntry read
update PATCH /eks/api/clusters/{cluster}/access-entries/{id} eks:UpdateAccessEntry write
delete DELETE /eks/api/clusters/{cluster}/access-entries/{id} eks:DeleteAccessEntry write
associate-policy POST /eks/api/clusters/{cluster}/access-entries/{id}/policies eks:AssociateAccessPolicy write
disassociate-policy DELETE /eks/api/clusters/{cluster}/access-entries/{id}/policies/{policy} eks:DisassociateAccessPolicy write

dcloud eks access-entries list

List a cluster’s access entries and their access policies

GET /eks/api/clusters/{cluster}/access-entries — IAM eks:ListAccessEntries — read

dcloud eks access-entries list <cluster>

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<cluster> --cluster string /^(ewk-[0-9a-f]{12}|a-z?)$/

dcloud eks access-entries create

Give an IAM user, group or role an access entry

POST /eks/api/clusters/{cluster}/access-entries — IAM eks:CreateAccessEntry — write

dcloud eks access-entries create <cluster> --principal-type <user|group|role> --principal <value> [flags]

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<cluster> --cluster string /^(ewk-[0-9a-f]{12}|a-z?)$/
Flag In Required Notes
--principal-type <user|group|role> body yes What principal names: user, group or role (IAM)
--principal <value> body yes 1-128 chars · The IAM user name, group name or role name; 404 when none has it, 409 when it already has an entry on the cluster
--username <value> body 1-100 chars, /^[A-Za-z0-9][A-Za-z0-9:._@-]*$/ · Kubernetes username the entry’s tokens carry, prefixed ews: by the cluster (RBAC sees ews:); 1–100 letters, digits and : . _ @ -, not starting system:. Default: the IAM user name of whoever gets the token
--kubernetes-groups <value> body repeatable · 1-100 chars, /^[A-Za-z0-9][A-Za-z0-9:._@-]*$/ · Extra Kubernetes groups the entry’s tokens carry, for your own RBAC bindings; at most 20, each 1–100 letters, digits and : . _ @ -, not starting system: or ews:. Default none
--policies <value> body repeatable · Access policies to associate at once
  • policies associates access policies at once and also needs eks:AssociateAccessPolicy. A person also needs eks:AccessKubernetesApi in IAM to get a token.

dcloud eks access-entries get

One access entry and its access policies

GET /eks/api/clusters/{cluster}/access-entries/{id} — IAM eks:DescribeAccessEntry — read

dcloud eks access-entries get <cluster> <id>

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<cluster> --cluster string /^(ewk-[0-9a-f]{12}|a-z?)$/
<id> --id string

dcloud eks access-entries update

Change an access entry’s Kubernetes username or extra groups

PATCH /eks/api/clusters/{cluster}/access-entries/{id} — IAM eks:UpdateAccessEntry — write

dcloud eks access-entries update <cluster> <id> [flags]

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<cluster> --cluster string /^(ewk-[0-9a-f]{12}|a-z?)$/
<id> --id string
Flag In Required Notes
--username <value> body 1-100 chars, /^[A-Za-z0-9][A-Za-z0-9:._@-]*$/ · nullable · Kubernetes username the entry’s tokens carry, prefixed ews: by the cluster (RBAC sees ews:); 1–100 letters, digits and : . _ @ -, not starting system:. null clears it (tokens then carry the IAM user name of whoever gets them); unchanged when absent
--kubernetes-groups <value> body repeatable · 1-100 chars, /^[A-Za-z0-9][A-Za-z0-9:._@-]*$/ · Extra Kubernetes groups the entry’s tokens carry, for your own RBAC bindings; at most 20, each 1–100 letters, digits and : . _ @ -, not starting system: or ews:. Replaces the list; [] clears it; unchanged when absent

dcloud eks access-entries delete

Remove an access entry

DELETE /eks/api/clusters/{cluster}/access-entries/{id} — IAM eks:DeleteAccessEntry — write

dcloud eks access-entries delete <cluster> <id>

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<cluster> --cluster string /^(ewk-[0-9a-f]{12}|a-z?)$/
<id> --id string

dcloud eks access-entries associate-policy

Grant an access entry an access policy, cluster-wide or in namespaces

POST /eks/api/clusters/{cluster}/access-entries/{id}/policies — IAM eks:AssociateAccessPolicy — write

dcloud eks access-entries associate-policy <cluster> <id> --policy <ClusterAdmin|Admin|Edit|View> [flags]

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<cluster> --cluster string /^(ewk-[0-9a-f]{12}|a-z?)$/
<id> --id string
Flag In Required Notes
--policy <ClusterAdmin|Admin|Edit|View> body yes ClusterAdmin (cluster-admin), Admin (admin), Edit (edit) or View (view): the Kubernetes ClusterRole it binds
--namespaces <value> body repeatable · /^a-z0-9?$/ · Namespaces it applies in; cluster-wide when empty. ClusterAdmin is always cluster-wide
  • Associating a policy again replaces its namespaces.

dcloud eks access-entries disassociate-policy

Remove an access policy from an access entry

DELETE /eks/api/clusters/{cluster}/access-entries/{id}/policies/{policy} — IAM eks:DisassociateAccessPolicy — write

dcloud eks access-entries disassociate-policy <cluster> <id> <policy>

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<cluster> --cluster string /^(ewk-[0-9a-f]{12}|a-z?)$/
<id> --id string
<policy> --policy string

dcloud eks pod-identity-associations

Which service accounts of a cluster act as which IAM roles (pods get S3 credentials with no stored key)

Operation Method Path IAM action Effect
list GET /eks/api/clusters/{cluster}/pod-identity-associations eks:ListPodIdentityAssociations read
create POST /eks/api/clusters/{cluster}/pod-identity-associations eks:CreatePodIdentityAssociation write
delete DELETE /eks/api/clusters/{cluster}/pod-identity-associations/{id} eks:DeletePodIdentityAssociation write

dcloud eks pod-identity-associations list

List a cluster’s pod identity associations

GET /eks/api/clusters/{cluster}/pod-identity-associations — IAM eks:ListPodIdentityAssociations — read

dcloud eks pod-identity-associations list <cluster>

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<cluster> --cluster string /^(ewk-[0-9a-f]{12}|a-z?)$/

dcloud eks pod-identity-associations create

Let pods of a service account act as an IAM role

POST /eks/api/clusters/{cluster}/pod-identity-associations — IAM eks:CreatePodIdentityAssociation — write

dcloud eks pod-identity-associations create <cluster> --namespace <value> --service-account <value> --role <value>

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<cluster> --cluster string /^(ewk-[0-9a-f]{12}|a-z?)$/
Flag In Required Notes
--namespace <value> body yes /^a-z0-9?$/ · Namespace of the service account
--service-account <value> body yes max 253 chars, /^a-z0-9?(.a-z0-9?)*$/ · Service account whose pods get the role
--role <value> body yes 1-128 chars · Name of the IAM role the pods act as; needs iam:PassRole on it
  • Also needs iam:PassRole on the role. Pods created afterwards get AWS_ROLE_ARN, AWS_WEB_IDENTITY_TOKEN_FILE and AWS_ENDPOINT_URL_STS/S3, so AWS SDKs work unchanged. 409 when the service account already has one.

dcloud eks pod-identity-associations delete

Remove a pod identity association

DELETE /eks/api/clusters/{cluster}/pod-identity-associations/{id} — IAM eks:DeletePodIdentityAssociation — write

dcloud eks pod-identity-associations delete <cluster> <id>

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<cluster> --cluster string /^(ewk-[0-9a-f]{12}|a-z?)$/
<id> --id string
  • Credentials already issued run out within the hour.

dcloud eks addon-versions

The managed add-ons Deutsche Cloud offers and their versions

Operation Method Path IAM action Effect
list GET /eks/api/addon-versions eks:DescribeAddonVersions read

dcloud eks addon-versions list

List add-ons, their versions and the Kubernetes minors each supports

GET /eks/api/addon-versions — IAM eks:DescribeAddonVersions — read

dcloud eks addon-versions list [flags]
Flag In Required Notes
--kubernetes-version <1.36|1.37> query Only versions that support this Kubernetes minor

dcloud eks addons

Managed add-ons on a cluster: metrics-server, Traefik ingress, cert-manager and external-dns on Deutsche Cloud DNS

Operation Method Path IAM action Effect
list GET /eks/api/clusters/{cluster}/addons eks:ListAddons read
create POST /eks/api/clusters/{cluster}/addons eks:CreateAddon write
get GET /eks/api/clusters/{cluster}/addons/{name} eks:DescribeAddon read
update PATCH /eks/api/clusters/{cluster}/addons/{name} eks:UpdateAddon write
delete DELETE /eks/api/clusters/{cluster}/addons/{name} eks:DeleteAddon write

dcloud eks addons list

List a cluster’s add-ons, with the system components Deutsche Cloud runs (system: true)

GET /eks/api/clusters/{cluster}/addons — IAM eks:ListAddons — read

dcloud eks addons list <cluster>

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<cluster> --cluster string /^(ewk-[0-9a-f]{12}|a-z?)$/

dcloud eks addons create

Install a managed add-on

POST /eks/api/clusters/{cluster}/addons — IAM eks:CreateAddon — write

dcloud eks addons create <cluster> --name <metrics-server|traefik|cert-manager|external-dns> [flags]

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<cluster> --cluster string /^(ewk-[0-9a-f]{12}|a-z?)$/
Flag In Required Notes
--name <metrics-server|traefik|cert-manager|external-dns> body yes metrics-server, traefik, cert-manager or external-dns
--version <value> body max 32 chars · Default: the newest that supports the cluster’s Kubernetes
--config <key=<json>> body repeatable · key= · The add-on’s options. traefik: replicas, proxyProtocol, loadBalancerType, defaultIngressClass. cert-manager: zones, email. external-dns: zones (required), policy, sources. metrics-server: none
  • The DNS add-ons (external-dns, cert-manager with zones) also need dns:ChangeRecords on every zone they list: the cluster may then change records there, without any stored credential. 409 when the cluster already has it.

dcloud eks addons get

One add-on: version, options, status, workloads ready, upgrade available

GET /eks/api/clusters/{cluster}/addons/{name} — IAM eks:DescribeAddon — read

dcloud eks addons get <cluster> <name>

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<cluster> --cluster string /^(ewk-[0-9a-f]{12}|a-z?)$/
<name> --name string

dcloud eks addons update

Change an add-on’s version or options

PATCH /eks/api/clusters/{cluster}/addons/{name} — IAM eks:UpdateAddon — write

dcloud eks addons update <cluster> <name> [flags]

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<cluster> --cluster string /^(ewk-[0-9a-f]{12}|a-z?)$/
<name> --name string
Flag In Required Notes
--version <value> body max 32 chars · Another version from DescribeAddonVersions
--config <key=<json>> body repeatable · key= · Replaces the options as a whole
  • Versions come from addon-versions list; upgrades are never automatic. A cluster upgrade is refused while an add-on’s version does not support the next Kubernetes minor.

dcloud eks addons delete

Remove an add-on

DELETE /eks/api/clusters/{cluster}/addons/{name} — IAM eks:DeleteAddon — write

dcloud eks addons delete <cluster> <name>

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<cluster> --cluster string /^(ewk-[0-9a-f]{12}|a-z?)$/
<name> --name string
  • Its workloads and EWS-made objects go; its CRDs and your resources of them (Certificates, IngressRoutes) stay.

Not in the CLI: eks routes the surface does not describe

These routes exist and are reachable over HTTP. They are deliberately absent from the description, so there is no command for them. The reason is recorded next to the service so a gap has to be stated out loud and stops being stateable the moment the route goes.

Route Why it has no command
GET /eks/api/oidc/.well-known/openid-configuration Public OIDC discovery for cluster API servers, not a caller operation
GET /eks/api/oidc/keys Public JWKS for cluster API servers
GET /eks/api/oidc/clusters/{id}/.well-known/openid-configuration Public discovery of a cluster’s service-account issuer, not a caller operation
GET /eks/api/oidc/clusters/{id}/keys Public JWKS of a cluster’s service-account issuer

dcloud queue

Queues. Base path /queue/api.

dcloud queue queues

Message queues with visibility timeouts and dead-letter queues, SQS-style

Operation Method Path IAM action Effect
list GET /queue/api/queues queue:ListQueues read
create POST /queue/api/queues queue:CreateQueue write
get GET /queue/api/queues/{name} queue:GetQueueAttributes read
metrics GET /queue/api/queues/{name}/metrics queue:GetQueueAttributes read
set-attributes PATCH /queue/api/queues/{name} queue:SetQueueAttributes write
purge POST /queue/api/queues/{name}/purge queue:PurgeQueue write
redrive POST /queue/api/queues/{name}/redrive queue:StartMessageMoveTask write
delete DELETE /queue/api/queues/{name} queue:DeleteQueue write

dcloud queue queues list

List queues with their message counts

GET /queue/api/queues — IAM queue:ListQueues — read

dcloud queue queues list

dcloud queue queues create

Create a queue

POST /queue/api/queues — IAM queue:CreateQueue — write

dcloud queue queues create --name <value> [flags]
Flag In Required Notes
--name <value> body yes max 80 chars, /^[A-Za-z0-9_-]+(.fifo)?$/ · Name of the queue, unique in the organization and region; a FIFO queue’s name ends in .fifo
--fifo body Create a FIFO queue, which delivers each message group in order and deduplicates sends; cannot be changed later (default false)
--tags <key=value> body repeatable · key=value · Tags for the new resource, e.g. {"env": "prod", "project": "shop"}. Keys your organization marks required must be present, or the create is refused with the missing keys (GET /tags/api/keys lists them).
--visibility-timeout-seconds <number> body integer, 0-43200 · Seconds a received message stays hidden from other consumers before it can be received again; 30 for a new queue
--retention-seconds <number> body integer, 60-1209600 · Seconds a message is kept before it is deleted unreceived; applies to messages sent afterwards; 4 days for a new queue
--delay-seconds <number> body integer, 0-900 · Seconds a newly sent message stays invisible before it can be received; 0 for a new queue
--receive-wait-seconds <number> body integer, 0-20 · Seconds a receive waits for a message when it names no wait of its own; 0 answers at once; 0 for a new queue
--maximum-message-bytes <number> body integer, 1024-262144 · Largest message the queue accepts, in bytes, counting the body and attributes; 256 KiB for a new queue
--dead-letter-queue <json> body JSON · nullable · Another queue of the organization (name) that receives a message after it has been received maxReceiveCount times without being deleted; null removes it; none for a new queue
--content-based-deduplication body FIFO queues only: a send without messageDeduplicationId is deduplicated by the SHA-256 of its body; false for a new queue
  • Unset attributes take the defaults: visibility timeout 30 s, retention 4 days, no delay, no long polling, 256 KiB messages. deadLetterQueue names another queue of the organization; after maxReceiveCount receives a message moves there. 409 QueueAlreadyExists when the name is taken. fifo: true makes a FIFO queue (the name must end in .fifo, and a .fifo name requires it; fixed at creation): sends name a messageGroupId, each group is delivered in order with one batch in flight at a time, and sends are deduplicated for five minutes by messageDeduplicationId, or by the body with contentBasedDeduplication. A FIFO queue's dead-letter queue must be FIFO.

dcloud queue queues get

One queue: its attributes and visible, in-flight and delayed message counts

GET /queue/api/queues/{name} — IAM queue:GetQueueAttributes — read

dcloud queue queues get <name>

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<name> --name string max 80 chars, /^[A-Za-z0-9_-]+(.fifo)?$/

dcloud queue queues metrics

Message counts over time (about 180 points over the range)

GET /queue/api/queues/{name}/metrics — IAM queue:GetQueueAttributes — read

dcloud queue queues metrics <name> [flags]

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<name> --name string max 80 chars, /^[A-Za-z0-9_-]+(.fifo)?$/
Flag In Required Notes
--hours <number> query integer, 1-336 · How far back, in hours (default 3, at most 14 days)

dcloud queue queues set-attributes

Change a queue’s attributes or its dead-letter queue

PATCH /queue/api/queues/{name} — IAM queue:SetQueueAttributes — write

dcloud queue queues set-attributes <name> [flags]

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<name> --name string max 80 chars, /^[A-Za-z0-9_-]+(.fifo)?$/
Flag In Required Notes
--visibility-timeout-seconds <number> body integer, 0-43200 · Seconds a received message stays hidden from other consumers before it can be received again; 30 for a new queue
--retention-seconds <number> body integer, 60-1209600 · Seconds a message is kept before it is deleted unreceived; applies to messages sent afterwards; 4 days for a new queue
--delay-seconds <number> body integer, 0-900 · Seconds a newly sent message stays invisible before it can be received; 0 for a new queue
--receive-wait-seconds <number> body integer, 0-20 · Seconds a receive waits for a message when it names no wait of its own; 0 answers at once; 0 for a new queue
--maximum-message-bytes <number> body integer, 1024-262144 · Largest message the queue accepts, in bytes, counting the body and attributes; 256 KiB for a new queue
--dead-letter-queue <json> body JSON · nullable · Another queue of the organization (name) that receives a message after it has been received maxReceiveCount times without being deleted; null removes it; none for a new queue
--content-based-deduplication body FIFO queues only: a send without messageDeduplicationId is deduplicated by the SHA-256 of its body; false for a new queue
  • Only the fields sent change. deadLetterQueue: null removes the dead-letter queue.

dcloud queue queues purge

Delete every message in a queue, keeping the queue

POST /queue/api/queues/{name}/purge — IAM queue:PurgeQueue — write

dcloud queue queues purge <name>

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<name> --name string max 80 chars, /^[A-Za-z0-9_-]+(.fifo)?$/

dcloud queue queues redrive

Move a dead-letter queue’s messages back to their source queues

POST /queue/api/queues/{name}/redrive — IAM queue:StartMessageMoveTask — write

dcloud queue queues redrive <name> [flags]

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<name> --name string max 80 chars, /^[A-Za-z0-9_-]+(.fifo)?$/
Flag In Required Notes
--destination <value> body max 80 chars, /^[A-Za-z0-9_-]+(.fifo)?$/ · Queue to move every message to (default: each message goes back to the queue it was dead-lettered from)
  • Without destination each message returns to the queue it was dead-lettered from; with one, all go there. Needs queue:SendMessage on every destination too. Messages arrive as new deliveries (receive count 0). In-flight messages, and ones whose source queue is gone, stay. Runs to completion and answers { taskId, moved, remaining }.

dcloud queue queues delete

Delete a queue and every message in it

DELETE /queue/api/queues/{name} — IAM queue:DeleteQueue — write

dcloud queue queues delete <name>

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<name> --name string max 80 chars, /^[A-Za-z0-9_-]+(.fifo)?$/
  • Refused (409) while another queue uses it as its dead-letter queue.

dcloud queue messages

Sending, receiving and acknowledging messages on a queue

Operation Method Path IAM action Effect
send POST /queue/api/queues/{name}/messages queue:SendMessage write
send-batch POST /queue/api/queues/{name}/messages/batch queue:SendMessage write
receive POST /queue/api/queues/{name}/receive queue:ReceiveMessage write
delete DELETE /queue/api/queues/{name}/messages/{receiptHandle} queue:DeleteMessage write
delete-batch POST /queue/api/queues/{name}/messages/delete-batch queue:DeleteMessage write
change-visibility POST /queue/api/queues/{name}/messages/visibility queue:ChangeMessageVisibility write
change-visibility-batch POST /queue/api/queues/{name}/messages/visibility-batch queue:ChangeMessageVisibility write

dcloud queue messages send

Send one message

POST /queue/api/queues/{name}/messages — IAM queue:SendMessage — write

dcloud queue messages send <name> --body <value> [flags]

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<name> --name string max 80 chars, /^[A-Za-z0-9_-]+(.fifo)?$/
Flag In Required Notes
--body <value> body yes min 1 chars · The message content, as text
--delay-seconds <number> body integer, 0-900 · Seconds the message stays invisible before it can be received; standard queues only (default: the queue’s delay)
--attributes <key=value> body repeatable · key=value · Name–value string pairs delivered with the message (default none)
--message-group-id <value> body /^[A-Za-z0-9!"#$%&'()*+,-./:;<=>?@[\]^_`{|}~]{1,128}$/ · FIFO queues: required; messages of one group are delivered in order, one batch at a time. Ignored on a standard queue
--message-deduplication-id <value> body /^[A-Za-z0-9!"#$%&'()*+,-./:;<=>?@[\]^_`{|}~]{1,128}$/ · FIFO queues only: a send repeating this id within five minutes is accepted but not stored again. Required unless the queue has content-based deduplication
  • body is text (no control characters besides tab, LF, CR); attributes are up to 10 string pairs. delaySeconds (0–900) keeps it invisible that long (standard queues only). On a FIFO queue messageGroupId is required, and messageDeduplicationId too unless the queue has contentBasedDeduplication; a repeat within five minutes answers the original messageId with duplicate: true. Answers 201 with messageId, md5OfBody and, on FIFO, sequenceNumber.

dcloud queue messages send-batch

Send up to 10 messages at once, with a result per entry

POST /queue/api/queues/{name}/messages/batch — IAM queue:SendMessage — write

dcloud queue messages send-batch <name> --entries <value>

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<name> --name string max 80 chars, /^[A-Za-z0-9_-]+(.fifo)?$/
Flag In Required Notes
--entries <value> body yes repeatable · The messages to send, each a single send’s fields plus an id of your choosing, unique in the batch, that matches it to its result
  • Each entry carries a caller-chosen id, unique in the batch, used to match results. Answers { successful, failed }: an entry too large for the queue fails alone, as on SQS. A batch over 256 KiB in all, or a queue at capacity, fails the whole call.

dcloud queue messages receive

Receive up to 10 messages, hiding them for the visibility timeout

POST /queue/api/queues/{name}/receive — IAM queue:ReceiveMessage — write

dcloud queue messages receive <name> [flags]

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<name> --name string max 80 chars, /^[A-Za-z0-9_-]+(.fifo)?$/
Flag In Required Notes
--max-messages <number> body integer, 1-10 · Most messages to return (default 1)
--visibility-timeout-seconds <number> body integer, 0-43200 · Seconds the received messages stay hidden from other consumers (default: the queue’s visibility timeout)
--wait-seconds <number> body integer, 0-20 · Seconds to wait for a message when none is available; 0 answers at once (default: the queue’s receive wait)
  • waitSeconds (0–20) long-polls until a message arrives. Each message carries a receiptHandle: delete it with messages delete once processed, or it becomes visible again when the timeout ends. Changes state: received messages are hidden from other consumers.

dcloud queue messages delete

Delete a processed message by its receipt handle

DELETE /queue/api/queues/{name}/messages/{receiptHandle} — IAM queue:DeleteMessage — write

dcloud queue messages delete <name> <receiptHandle>

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<name> --name string max 80 chars, /^[A-Za-z0-9_-]+(.fifo)?$/
<receiptHandle> --receipt-handle string 1-200 chars
  • Fails with ReceiptHandleIsInvalid when the message was received again since this receipt was issued.

dcloud queue messages delete-batch

Delete up to 10 processed messages by receipt handle

POST /queue/api/queues/{name}/messages/delete-batch — IAM queue:DeleteMessage — write

dcloud queue messages delete-batch <name> --entries <value>

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<name> --name string max 80 chars, /^[A-Za-z0-9_-]+(.fifo)?$/
Flag In Required Notes
--entries <value> body yes repeatable · The messages to delete, each a receiptHandle from the receive plus an id of your choosing, unique in the batch, that matches it to its result
  • Answers { successful, failed } per entry id; a failed entry does not fail the call.

dcloud queue messages change-visibility

Extend or shorten how long a received message stays hidden

POST /queue/api/queues/{name}/messages/visibility — IAM queue:ChangeMessageVisibility — write

dcloud queue messages change-visibility <name> --receipt-handle <value> --visibility-timeout-seconds <number>

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<name> --name string max 80 chars, /^[A-Za-z0-9_-]+(.fifo)?$/
Flag In Required Notes
--receipt-handle <value> body yes 1-200 chars · The receipt handle the message was last received with
--visibility-timeout-seconds <number> body yes integer, 0-43200 · Seconds from now the message stays hidden; 0 makes it receivable again at once
  • 0 makes the message visible again at once.

dcloud queue messages change-visibility-batch

Change the visibility timeout of up to 10 received messages

POST /queue/api/queues/{name}/messages/visibility-batch — IAM queue:ChangeMessageVisibility — write

dcloud queue messages change-visibility-batch <name> --entries <value>

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<name> --name string max 80 chars, /^[A-Za-z0-9_-]+(.fifo)?$/
Flag In Required Notes
--entries <value> body yes repeatable · The messages to change, each a receiptHandle and visibilityTimeoutSeconds as for a single change plus an id of your choosing, unique in the batch, that matches it to its result
  • Answers { successful, failed } per entry id; a failed entry (MessageNotInflight, ReceiptHandleIsInvalid) does not fail the call.

dcloud scheduler

Schedules. Base path /scheduler/api.

dcloud scheduler schedules

Schedules (cron, rate, one-time) that invoke an HTTP endpoint, a queue, a CI workflow or an app job, with retries and a dead-letter queue

Operation Method Path IAM action Effect
list GET /scheduler/api/schedules scheduler:ListSchedules read
preview GET /scheduler/api/preview scheduler:ListSchedules read
create POST /scheduler/api/schedules scheduler:CreateSchedule write
get GET /scheduler/api/schedules/{name} scheduler:GetSchedule read
update PATCH /scheduler/api/schedules/{name} scheduler:UpdateSchedule write
delete DELETE /scheduler/api/schedules/{name} scheduler:DeleteSchedule write
invoke POST /scheduler/api/schedules/{name}/invocations scheduler:InvokeSchedule write
invocations GET /scheduler/api/schedules/{name}/invocations scheduler:ListInvocations read
invocation GET /scheduler/api/schedules/{name}/invocations/{id} scheduler:ListInvocations read
signing-secret GET /scheduler/api/schedules/{name}/signing-secret scheduler:GetScheduleSigningSecret read, sensitive
rotate-signing-secret POST /scheduler/api/schedules/{name}/signing-secret/rotate scheduler:RotateScheduleSigningSecret write

dcloud scheduler schedules list

List schedules with their next runs, health and last invocation

GET /scheduler/api/schedules — IAM scheduler:ListSchedules — read

dcloud scheduler schedules list

dcloud scheduler schedules preview

Show when an expression would fire, in a time zone, without saving anything

GET /scheduler/api/preview — IAM scheduler:ListSchedules — read

dcloud scheduler schedules preview --expression <value> [flags]
Flag In Required Notes
--expression <value> query yes 1-256 chars · cron(minute hour day-of-month month day-of-week), rate(n minutes|hours|days) or at(yyyy-mm-ddThh:mm:ss)
--timezone <value> query 1-64 chars · server default "UTC" · IANA time zone the expression is read in, e.g. Europe/Berlin
--start-date <json> query JSON
--end-date <json> query JSON
--count <number> query integer, 1-50 · server default 10

dcloud scheduler schedules create

Create a schedule

POST /scheduler/api/schedules — IAM scheduler:CreateSchedule — write

dcloud scheduler schedules create --name <value> --expression <value> --target <json> [flags]
Flag In Required Notes
--name <value> body yes 1-64 chars, /^[A-Za-z0-9][A-Za-z0-9_.-]*$/
--description <value> body max 512 chars · nullable
--expression <value> body yes 1-256 chars · cron(minute hour day-of-month month day-of-week), rate(n minutes|hours|days) or at(yyyy-mm-ddThh:mm:ss)
--timezone <value> body 1-64 chars · IANA time zone the expression is read in, e.g. Europe/Berlin
--start-date <json> body JSON · nullable · Nothing fires before this (ISO 8601)
--end-date <json> body JSON · nullable · Nothing fires after this (ISO 8601)
--state <enabled|disabled> body
--flexible-window-minutes <number> body integer, 0-1440 · Fire at a random moment up to this many minutes after each tick (0 = exactly on it)
--catch-up <none|latest|all> body Ticks missed while the scheduler was down: none skips them, latest (default) fires the most recent once, all fires each (≤ 100, within maxEventAgeSeconds)
--action-after-completion <none|delete> body For at(): keep the schedule after it fired (none) or delete it
--target <json> body yes JSON
--role-name <value> body 1-128 chars · nullable · IAM role the invocations act as; needs iam:PassRole on it. Required for queue, ci and app_job targets and for a dead-letter queue
--retry-max-attempts <number> body integer, 0-20
--retry-backoff-seconds <number> body integer, 5-3600 · First retry after this, doubling each time (±20 %, at most 15 minutes)
--max-event-age-seconds <number> body integer, 60-86400 · An invocation older than this is not attempted again
--dead-letter-queue <value> body max 80 chars, /^[A-Za-z0-9_-]+(.fifo)?$/ · nullable · Queue a finally-failed invocation is sent to (as the role)
--failure-alarm <json> body JSON · nullable · Creates and keeps a monitoring alarm on this schedule’s failed invocations; null removes it
  • May check iam:PassRole or monitoring:PutMetricAlarm instead, decided by server-side state the caller cannot see. A caller needs all of them to be sure of not getting a 403.
  • expression: cron(minute hour day-of-month month day-of-week) on the wall clock of timezone, rate(n minutes|hours|days), or at(yyyy-mm-ddThh:mm:ss). target is one of: {type:"http", url, method?, headers?, input?, timeoutSeconds?} (signed with the schedule’s secret: X-EWS-Signature-256 = sha256 HMAC of "."); {type:"queue", queueName, input?, messageGroupId?}; {type:"ci", repositoryId, path, ref?, inputs?} (workflow_dispatch / on.manual); {type:"app_job", appId, jobName} (runs an existing app job through the deploy agent; the invocation waits for its exit code); {type:"function", functionName, input?} (POSTs input to the function; 2xx is success). queue, ci, app_job and function act as roleName (also needs iam:PassRole on it); so does a deadLetterQueue. Every invocation is attempted 1 + retryMaxAttempts times with exponential backoff (5xx, 429, timeouts, a failed job run), never past maxEventAgeSeconds; a final failure goes to deadLetterQueue. failureAlarm creates a monitoring alarm on EWS/Scheduler InvocationsFailed for this schedule. 409 when the name is taken.

dcloud scheduler schedules get

Read a schedule

GET /scheduler/api/schedules/{name} — IAM scheduler:GetSchedule — read

dcloud scheduler schedules get <name>

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<name> --name string 1-64 chars, /^[A-Za-z0-9][A-Za-z0-9_.-]*$/

dcloud scheduler schedules update

Change a schedule, or enable or disable it (state)

PATCH /scheduler/api/schedules/{name} — IAM scheduler:UpdateSchedule — write

dcloud scheduler schedules update <name> [flags]

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<name> --name string 1-64 chars, /^[A-Za-z0-9][A-Za-z0-9_.-]*$/
Flag In Required Notes
--description <value> body max 512 chars · nullable
--expression <value> body 1-256 chars · cron(minute hour day-of-month month day-of-week), rate(n minutes|hours|days) or at(yyyy-mm-ddThh:mm:ss)
--timezone <value> body 1-64 chars · IANA time zone the expression is read in, e.g. Europe/Berlin
--start-date <json> body JSON · nullable · Nothing fires before this (ISO 8601)
--end-date <json> body JSON · nullable · Nothing fires after this (ISO 8601)
--state <enabled|disabled> body
--flexible-window-minutes <number> body integer, 0-1440 · Fire at a random moment up to this many minutes after each tick (0 = exactly on it)
--catch-up <none|latest|all> body Ticks missed while the scheduler was down: none skips them, latest (default) fires the most recent once, all fires each (≤ 100, within maxEventAgeSeconds)
--action-after-completion <none|delete> body For at(): keep the schedule after it fired (none) or delete it
--target <json> body JSON
--role-name <value> body 1-128 chars · nullable · IAM role the invocations act as; needs iam:PassRole on it. Required for queue, ci and app_job targets and for a dead-letter queue
--retry-max-attempts <number> body integer, 0-20
--retry-backoff-seconds <number> body integer, 5-3600 · First retry after this, doubling each time (±20 %, at most 15 minutes)
--max-event-age-seconds <number> body integer, 60-86400 · An invocation older than this is not attempted again
--dead-letter-queue <value> body max 80 chars, /^[A-Za-z0-9_-]+(.fifo)?$/ · nullable · Queue a finally-failed invocation is sent to (as the role)
--failure-alarm <json> body JSON · nullable · Creates and keeps a monitoring alarm on this schedule’s failed invocations; null removes it
  • May check iam:PassRole or monitoring:PutMetricAlarm or monitoring:DeleteAlarms instead, decided by server-side state the caller cannot see. A caller needs all of them to be sure of not getting a 403.
  • The name cannot change. Changing the expression, time zone or dates, or enabling it, recomputes the next run from now (a disabled spell is not caught up). target is one of: {type:"http", url, method?, headers?, input?, timeoutSeconds?} (signed with the schedule’s secret: X-EWS-Signature-256 = sha256 HMAC of "."); {type:"queue", queueName, input?, messageGroupId?}; {type:"ci", repositoryId, path, ref?, inputs?} (workflow_dispatch / on.manual); {type:"app_job", appId, jobName} (runs an existing app job through the deploy agent; the invocation waits for its exit code); {type:"function", functionName, input?} (POSTs input to the function; 2xx is success). queue, ci, app_job and function act as roleName (also needs iam:PassRole on it); so does a deadLetterQueue. Every invocation is attempted 1 + retryMaxAttempts times with exponential backoff (5xx, 429, timeouts, a failed job run), never past maxEventAgeSeconds; a final failure goes to deadLetterQueue.

dcloud scheduler schedules delete

Delete a schedule, its invocations and the failure alarm it owns

DELETE /scheduler/api/schedules/{name} — IAM scheduler:DeleteSchedule — write

dcloud scheduler schedules delete <name>

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<name> --name string 1-64 chars, /^[A-Za-z0-9][A-Za-z0-9_.-]*$/

dcloud scheduler schedules invoke

Run a schedule now, through the same role, retries and dead-letter queue

POST /scheduler/api/schedules/{name}/invocations — IAM scheduler:InvokeSchedule — write

dcloud scheduler schedules invoke <name>

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<name> --name string 1-64 chars, /^[A-Za-z0-9][A-Za-z0-9_.-]*$/
  • 202 with the invocation (status pending); read it back with invocation.

dcloud scheduler schedules invocations

List a schedule’s invocations, newest first: status, attempts, the target’s answer

GET /scheduler/api/schedules/{name}/invocations — IAM scheduler:ListInvocations — read

dcloud scheduler schedules invocations <name> [flags]

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<name> --name string 1-64 chars, /^[A-Za-z0-9][A-Za-z0-9_.-]*$/
Flag In Required Notes
--limit <number> query integer, 1-200 · server default 50
--status <pending|running|waiting|retry_wait|succeeded|failed|dead_lettered|dropped> query

dcloud scheduler schedules invocation

Read one invocation with its log: each attempt, the answer and the output

GET /scheduler/api/schedules/{name}/invocations/{id} — IAM scheduler:ListInvocations — read

dcloud scheduler schedules invocation <name> <id>

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<name> --name string 1-64 chars, /^[A-Za-z0-9][A-Za-z0-9_.-]*$/
<id> --id string uuid

dcloud scheduler schedules signing-secret

Reveal the secret HTTP invocations are signed with (audited)

GET /scheduler/api/schedules/{name}/signing-secret — IAM scheduler:GetScheduleSigningSecret — read, sensitive

dcloud scheduler schedules signing-secret <name>

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<name> --name string 1-64 chars, /^[A-Za-z0-9][A-Za-z0-9_.-]*$/

dcloud scheduler schedules rotate-signing-secret

Replace the signing secret; the previous one also signs for 24 hours

POST /scheduler/api/schedules/{name}/signing-secret/rotate — IAM scheduler:RotateScheduleSigningSecret — write

dcloud scheduler schedules rotate-signing-secret <name>

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<name> --name string 1-64 chars, /^[A-Za-z0-9][A-Za-z0-9_.-]*$/

dcloud errors

Error Tracking. Base path /errors/api.

dcloud errors projects

Projects: a DSN for the Sentry SDKs, retention, rate limit and alerts

Operation Method Path IAM action Effect
list GET /errors/api/projects errors:ListProjects read
create POST /errors/api/projects errors:CreateProject write
get GET /errors/api/projects/{id} errors:ListProjects read
update PATCH /errors/api/projects/{id} errors:UpdateProject write
delete DELETE /errors/api/projects/{id} errors:DeleteProject write
usage GET /errors/api/projects/{id}/usage errors:ListProjects read

dcloud errors projects list

List projects with their DSNs, unresolved issues and events of the last 24 hours

GET /errors/api/projects — IAM errors:ListProjects — read

dcloud errors projects list

dcloud errors projects create

Create a project and its first DSN key

POST /errors/api/projects — IAM errors:CreateProject — write

dcloud errors projects create --name <value> [flags]
Flag In Required Notes
--name <value> body yes 1-64 chars
--platform <javascript-nextjs|javascript|node|python|go|other> body server default "other"
--slug <value> body /^[a-z0-9][a-z0-9-]{0,49}$/
  • The answer carries the DSN to put into the Sentry SDK (Sentry.init({ dsn })).

dcloud errors projects get

Read a project, its keys and DSNs

GET /errors/api/projects/{id} — IAM errors:ListProjects — read

dcloud errors projects get <id>

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<id> --id string uuid

dcloud errors projects update

Change a project: name, platform, retention, rate limit, client IP, alerts

PATCH /errors/api/projects/{id} — IAM errors:UpdateProject — write

dcloud errors projects update <id> [flags]

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<id> --id string uuid
Flag In Required Notes
--name <value> body 1-64 chars
--platform <javascript-nextjs|javascript|node|python|go|other> body
--retention-days <json> body JSON
--rate-limit-per-minute <number> body integer, 1-1000000 · nullable
--store-client-ip body
--alert-email body
--alert-email-addresses <value> body repeatable · email
--alert-webhook-url <value> body url · nullable

dcloud errors projects delete

Delete a project: its keys stop working at once, its issues and events go

DELETE /errors/api/projects/{id} — IAM errors:DeleteProject — write

dcloud errors projects delete <id>

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<id> --id string uuid

dcloud errors projects usage

What the ingest received for the project in the last 30 days, by category and outcome

GET /errors/api/projects/{id}/usage — IAM errors:ListProjects — read

dcloud errors projects usage <id>

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<id> --id string uuid

dcloud errors keys

DSN keys of a project

Operation Method Path IAM action Effect
create POST /errors/api/projects/{id}/keys errors:UpdateProject write
revoke DELETE /errors/api/projects/{id}/keys/{keyId} errors:UpdateProject write

dcloud errors keys create

Add a DSN key

POST /errors/api/projects/{id}/keys — IAM errors:UpdateProject — write

dcloud errors keys create <id> [flags]

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<id> --id string uuid
Flag In Required Notes
--label <value> body 1-64 chars · server default "Key"
--rate-limit-per-minute <number> body integer, 1-1000000 · nullable · server default null

dcloud errors keys revoke

Revoke a DSN key; the ingest refuses it within seconds

DELETE /errors/api/projects/{id}/keys/{keyId} — IAM errors:UpdateProject — write

dcloud errors keys revoke <id> <keyId>

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<id> --id string uuid
<keyId> --key-id string uuid

dcloud errors issues

Issues: events grouped by fingerprint, with counts, users, first and last seen

Operation Method Path IAM action Effect
list GET /errors/api/projects/{id}/issues errors:ListIssues read
update PATCH /errors/api/projects/{id}/issues errors:UpdateIssue write
delete DELETE /errors/api/projects/{id}/issues errors:DeleteIssue write
get GET /errors/api/issues/{issueId} errors:ListIssues read

dcloud errors issues list

List a project’s issues

GET /errors/api/projects/{id}/issues — IAM errors:ListIssues — read

dcloud errors issues list <id> [flags]

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<id> --id string uuid
Flag In Required Notes
--query <value> query max 500 chars
--sort <last_seen|first_seen|events|users> query server default "last_seen"
--environment <value> query max 64 chars
--period <1h|24h|7d|14d|30d|90d> query
--limit <number> query integer, 1-100 · server default 25
--offset <number> query integer, 0-100000 · server default 0
  • query takes Sentry’s search syntax: is:unresolved|resolved|ignored|all (default unresolved), level:, environment:, release:, assigned:me|none, any tag as key:value, and free text over title, culprit and location.

dcloud errors issues update

Resolve, reopen, ignore or assign issues

PATCH /errors/api/projects/{id}/issues — IAM errors:UpdateIssue — write

dcloud errors issues update <id> --ids <value> --action <json>

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<id> --id string uuid
Flag In Required Notes
--ids <value> body yes repeatable · integer, min 1
--action <json> body yes JSON

dcloud errors issues delete

Delete issues and their events

DELETE /errors/api/projects/{id}/issues — IAM errors:DeleteIssue — write

dcloud errors issues delete <id> --ids <value>

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<id> --id string uuid
Flag In Required Notes
--ids <value> body yes repeatable · integer, min 1

dcloud errors issues get

Read an issue with its 14-day hourly counts and tag distribution

GET /errors/api/issues/{issueId} — IAM errors:ListIssues — read

dcloud errors issues get <issueId>

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<issueId> --issue-id string 1-80 chars, /^(\d+|[A-Za-z0-9][A-Za-z0-9-]*-[0-9A-Za-z]+)$/

dcloud errors events

Events of an issue: stack traces (source-mapped), breadcrumbs, request, tags, contexts

Operation Method Path IAM action Effect
list GET /errors/api/issues/{issueId}/events errors:GetEvents read
latest GET /errors/api/issues/{issueId}/events/latest errors:GetEvents read
get GET /errors/api/projects/{id}/events/{eventId} errors:GetEvents read

dcloud errors events list

List an issue’s events, newest first

GET /errors/api/issues/{issueId}/events — IAM errors:GetEvents — read

dcloud errors events list <issueId> [flags]

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<issueId> --issue-id string 1-80 chars, /^(\d+|[A-Za-z0-9][A-Za-z0-9-]*-[0-9A-Za-z]+)$/
Flag In Required Notes
--limit <number> query integer, 1-100 · server default 25
--before <value> query datetime

dcloud errors events latest

Read an issue’s latest event in full

GET /errors/api/issues/{issueId}/events/latest — IAM errors:GetEvents — read

dcloud errors events latest <issueId>

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<issueId> --issue-id string 1-80 chars, /^(\d+|[A-Za-z0-9][A-Za-z0-9-]*-[0-9A-Za-z]+)$/

dcloud errors events get

Read one event in full

GET /errors/api/projects/{id}/events/{eventId} — IAM errors:GetEvents — read

dcloud errors events get <id> <eventId>

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<id> --id string uuid
<eventId> --event-id string

dcloud errors traces

Performance traces: a trace’s transactions with their spans as a waterfall, and its errors

Operation Method Path IAM action Effect
get GET /errors/api/traces/{traceId} errors:GetEvents read

dcloud errors traces get

Read a trace: its transactions and spans on one time axis, and the errors in it

GET /errors/api/traces/{traceId} — IAM errors:GetEvents — read

dcloud errors traces get <traceId>

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<traceId> --trace-id string /^[0-9a-fA-F]{32}$/

dcloud errors profiles

Profiles: where a transaction spent its time, as a flame graph and by function

Operation Method Path IAM action Effect
get GET /errors/api/profiles/{eventId} errors:GetEvents read
list GET /errors/api/projects/{id}/profiles errors:GetEvents read
flamegraph GET /errors/api/projects/{id}/profiles/flamegraph errors:GetEvents read

dcloud errors profiles get

Read a transaction’s profile: its call tree (flame graph) and its functions by self time

GET /errors/api/profiles/{eventId} — IAM errors:GetEvents — read

dcloud errors profiles get <eventId>

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<eventId> --event-id string /^[0-9a-fA-F]{32}$|^[0-9a-fA-F-]{36}$/

dcloud errors profiles list

List a project’s continuous profile chunks in a window (last 15 min, hour, day or custom): filters, samples per minute, the chunks

GET /errors/api/projects/{id}/profiles — IAM errors:GetEvents — read

dcloud errors profiles list <id> [flags]

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<id> --id string uuid
Flag In Required Notes
--window <15m|1h|24h|custom> query server default "1h" · Last 15 minutes, hour or day, or custom with from/to
--from <value> query datetime · Custom window start (ISO 8601)
--to <value> query datetime · Custom window end (ISO 8601)
--environment <value> query max 200 chars · Only chunks of this environment
--release <value> query max 200 chars · Only chunks of this release
--runtime <node|browser|python> query node, browser or python
--profiler <value> query /^[0-9a-fA-F-]{32,36}$/ · Only this profiler (one per process or page)
--thread <value> query max 100 chars · Thread id (default: the busiest)
--my-code <0|1|true|false> query Only in-app frames ("only my code")
--compare <0|1|true|false> query Also the previous window of the same length, per function

dcloud errors profiles flamegraph

Merge a project’s continuous profiles in a window into one flame graph, with its slowest functions by self time (optionally only in-app frames, or compared with the previous window)

GET /errors/api/projects/{id}/profiles/flamegraph — IAM errors:GetEvents — read

dcloud errors profiles flamegraph <id> [flags]

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<id> --id string uuid
Flag In Required Notes
--window <15m|1h|24h|custom> query server default "1h" · Last 15 minutes, hour or day, or custom with from/to
--from <value> query datetime · Custom window start (ISO 8601)
--to <value> query datetime · Custom window end (ISO 8601)
--environment <value> query max 200 chars · Only chunks of this environment
--release <value> query max 200 chars · Only chunks of this release
--runtime <node|browser|python> query node, browser or python
--profiler <value> query /^[0-9a-fA-F-]{32,36}$/ · Only this profiler (one per process or page)
--thread <value> query max 100 chars · Thread id (default: the busiest)
--my-code <0|1|true|false> query Only in-app frames ("only my code")
--compare <0|1|true|false> query Also the previous window of the same length, per function

dcloud errors transactions

Transactions of a project by name and operation: counts, durations, failure rate

Operation Method Path IAM action Effect
list GET /errors/api/projects/{id}/transactions errors:GetEvents read

dcloud errors transactions list

List a project’s transactions by name: count (sampled and extrapolated), p50/p75/p95 duration and failure rate

GET /errors/api/projects/{id}/transactions — IAM errors:GetEvents — read

dcloud errors transactions list <id> [flags]

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<id> --id string uuid
Flag In Required Notes
--range <24h|7d> query server default "24h"
--limit <number> query integer, 1-200 · server default 50

dcloud errors releases

Releases created by sentry-cli and the bundler plugins

Operation Method Path IAM action Effect
list GET /errors/api/releases errors:ListReleases read

dcloud errors releases list

List releases

GET /errors/api/releases — IAM errors:ListReleases — read

dcloud errors releases list [flags]
Flag In Required Notes
--project-id <value> query uuid

dcloud errors alert-rules

Alert rules of a project: a trigger (new issue, frequency, users, crash-free rate), filters, and mail or webhook actions (Slack, Teams, Discord, JSON)

Operation Method Path IAM action Effect
list GET /errors/api/projects/{id}/alert-rules errors:ListAlertRules read
create POST /errors/api/projects/{id}/alert-rules errors:PutAlertRule write
update PATCH /errors/api/projects/{id}/alert-rules/{ruleId} errors:PutAlertRule write
delete DELETE /errors/api/projects/{id}/alert-rules/{ruleId} errors:DeleteAlertRule write
test POST /errors/api/projects/{id}/alert-rules/{ruleId}/test errors:PutAlertRule write

dcloud errors alert-rules list

List a project’s alert rules and their latest firings

GET /errors/api/projects/{id}/alert-rules — IAM errors:ListAlertRules — read

dcloud errors alert-rules list <id>

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<id> --id string uuid

dcloud errors alert-rules create

Create an alert rule

POST /errors/api/projects/{id}/alert-rules — IAM errors:PutAlertRule — write

dcloud errors alert-rules create <id> --name <value> --trigger <json> --actions <value> [flags]

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<id> --id string uuid
Flag In Required Notes
--name <value> body yes 1-120 chars
--enabled body server default true
--trigger <json> body yes JSON
--filters <json> body JSON · server default {"levels":[],"environments":[],"tags":[]}
--actions <value> body yes repeatable
--throttle-minutes <number> body integer, 1-10080 · server default 30

dcloud errors alert-rules update

Change an alert rule, or turn it on or off

PATCH /errors/api/projects/{id}/alert-rules/{ruleId} — IAM errors:PutAlertRule — write

dcloud errors alert-rules update <id> <ruleId> [flags]

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<id> --id string uuid
<ruleId> --rule-id string uuid
Flag In Required Notes
--name <value> body 1-120 chars
--enabled body server default true
--trigger <json> body JSON
--filters <json> body JSON · server default {"levels":[],"environments":[],"tags":[]}
--actions <value> body repeatable
--throttle-minutes <number> body integer, 1-10080 · server default 30

dcloud errors alert-rules delete

Delete an alert rule and its history

DELETE /errors/api/projects/{id}/alert-rules/{ruleId} — IAM errors:DeleteAlertRule — write

dcloud errors alert-rules delete <id> <ruleId>

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<id> --id string uuid
<ruleId> --rule-id string uuid

dcloud errors alert-rules test

Send the rule’s alert now with sample data, to check its mail and webhooks

POST /errors/api/projects/{id}/alert-rules/{ruleId}/test — IAM errors:PutAlertRule — write

dcloud errors alert-rules test <id> <ruleId>

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<id> --id string uuid
<ruleId> --rule-id string uuid

dcloud errors queries

Database statements from db spans: time share, calls, slowest calls, N+1, by the fingerprint the database’s query insights use

Operation Method Path IAM action Effect
list GET /errors/api/projects/{id}/queries errors:GetEvents read
get GET /errors/api/queries errors:GetEvents read

dcloud errors queries list

List a project’s database statements by total time: calls, mean and slowest call, time share, N+1 transactions

GET /errors/api/projects/{id}/queries — IAM errors:GetEvents — read

dcloud errors queries list <id> [flags]

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<id> --id string uuid
Flag In Required Notes
--range <24h|7d> query server default "24h"
--limit <number> query integer, 1-200 · server default 50

dcloud errors queries get

Read one statement across the organization’s projects: per project, slowest calls, N+1 transactions and where it ran

GET /errors/api/queries — IAM errors:GetEvents — read

dcloud errors queries get --fp <value> [flags]
Flag In Required Notes
--fp <value> query yes /^sqlfp1:[0-9a-f]{16}$/ · The statement fingerprint, sqlfp1:<16 hex>, as the Queries tab and the database’s query insights show it
--project <value> query uuid
--range <24h|7d> query server default "24h"

dcloud errors release-health

Release health of a project: crash-free sessions and users, adoption, per release

Operation Method Path IAM action Effect
list GET /errors/api/projects/{id}/release-health errors:GetEvents read

dcloud errors release-health list

List a project’s releases with their sessions, crash-free sessions and users, adoption and new issues

GET /errors/api/projects/{id}/release-health — IAM errors:GetEvents — read

dcloud errors release-health list <id> [flags]

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<id> --id string uuid
Flag In Required Notes
--range <24h|14d> query server default "14d"
--limit <number> query integer, 1-200 · server default 50

dcloud errors auth-tokens

Tokens for sentry-cli and withSentryConfig

Operation Method Path IAM action Effect
create POST /errors/api/auth-tokens errors:UploadSourceMaps write
create-upload-token POST /errors/api/projects/{id}/upload-token errors:UploadSourceMaps write

dcloud errors auth-tokens create

Create a SENTRY_AUTH_TOKEN (an access key of yours capped to errors:*), shown once

POST /errors/api/auth-tokens — IAM errors:UploadSourceMaps — write

dcloud errors auth-tokens create [flags]
Flag In Required Notes
--description <value> body 1-200 chars · server default "sentry-cli"
--expires-in-days <number> body integer, 1-3650
  • May check iam:CreateAccessKey instead, decided by server-side state the caller cannot see. A caller needs all of them to be sure of not getting a 403.
  • sentry-cli reads the URL and organization from the token: SENTRY_AUTH_TOKEN alone redirects it here.

dcloud errors auth-tokens create-upload-token

A short-lived SENTRY_AUTH_TOKEN for one project: source-map upload only, at most an hour

POST /errors/api/projects/{id}/upload-token — IAM errors:UploadSourceMaps — write

dcloud errors auth-tokens create-upload-token <id> [flags]

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<id> --id string uuid
Flag In Required Notes
--ttl-seconds <number> body integer, 60-3600 · server default 3600 · Lifetime, at most an hour (and never beyond the caller’s own credential)
  • For builds elsewhere: a GitHub workflow exchanges its OIDC token at the STS for a temporary access key, then asks for this token, so no static secret lives in GitHub (docs/errors.md, "Builds on GitHub Actions"). Never outlives the calling key; revoked at expiry.

dcloud errors connections

Apps and CI environments connected to a project, its managed key and Secrets entry, rotation, upload tokens

Operation Method Path IAM action Effect
get GET /errors/api/projects/{id}/connections errors:ListProjects read
connect-ci POST /errors/api/projects/{id}/ci-bindings ci:PutEnvironment write
disconnect-ci DELETE /errors/api/projects/{id}/ci-bindings/{bindingId} ci:PutEnvironment write
rotate-key POST /errors/api/projects/{id}/rotate-key errors:UpdateProject write
revoke-previous-key POST /errors/api/projects/{id}/rotate-key/revoke-previous errors:UpdateProject write
extend-grace POST /errors/api/projects/{id}/rotate-key/extend errors:UpdateProject write

dcloud errors connections get

What is connected: apps, CI environments, the managed key and secret, the last upload tokens (no secrets)

GET /errors/api/projects/{id}/connections — IAM errors:ListProjects — read

dcloud errors connections get <id>

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<id> --id string uuid

dcloud errors connections connect-ci

Connect a repository’s CI environment: its jobs exchange their OIDC token for an upload token

POST /errors/api/projects/{id}/ci-bindings — IAM ci:PutEnvironment — write

dcloud errors connections connect-ci <id> --repository-id <value> --environment <value> [flags]

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<id> --id string uuid
Flag In Required Notes
--repository-id <value> body yes uuid · Git repository id
--environment <value> body yes 1-255 chars · CI environment name, as a job’s environment: names it; created when missing
--sentry-environment <value> body 1-64 chars, /^[^\s/]+$/ · nullable · SENTRY_ENVIRONMENT; omitted: the app’s secrets environment, else production
  • May check errors:UpdateProject instead, decided by server-side state the caller cannot see. A caller needs all of them to be sure of not getting a 403.
  • A job with environment: <name> and permissions: id-token: write requests an OIDC token with the audience errors. and posts it to /errors/api/upload-token/exchange. Pull-request runs are refused; the token is revoked when the run ends.

dcloud errors connections disconnect-ci

Disconnect a CI environment

DELETE /errors/api/projects/{id}/ci-bindings/{bindingId} — IAM ci:PutEnvironment — write

dcloud errors connections disconnect-ci <id> <bindingId>

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<id> --id string uuid
<bindingId> --binding-id string uuid

dcloud errors connections rotate-key

Rotate the managed DSN key: new key, every connected app rebuilt, the old key revoked after the grace

POST /errors/api/projects/{id}/rotate-key — IAM errors:UpdateProject — write

dcloud errors connections rotate-key <id> [flags]

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<id> --id string uuid
Flag In Required Notes
--grace-seconds <number> body integer, 600-604800 · server default 86400 · Seconds the previous key keeps working; it is revoked after that once every connected app runs a build made after the rotation
  • The previous key is revoked once the grace is over AND every connected app runs a build made after the rotation; a failed rebuild holds it. Image and compose apps are listed under rebuildYourself: their browser bundles keep the old DSN until rebuilt.

dcloud errors connections revoke-previous-key

Revoke the rotated-out key now (its events are refused from then on)

POST /errors/api/projects/{id}/rotate-key/revoke-previous — IAM errors:UpdateProject — write

dcloud errors connections revoke-previous-key <id>

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<id> --id string uuid

dcloud errors connections extend-grace

Move the rotated-out key’s revocation

POST /errors/api/projects/{id}/rotate-key/extend — IAM errors:UpdateProject — write

dcloud errors connections extend-grace <id> --grace-seconds <number>

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<id> --id string uuid
Flag In Required Notes
--grace-seconds <number> body yes integer, 600-604800

Not in the CLI: errors routes the surface does not describe

These routes exist and are reachable over HTTP. They are deliberately absent from the description, so there is no command for them. The reason is recorded next to the service so a gap has to be stated out loud and stops being stateable the moment the route goes.

Route Why it has no command
POST /errors/api/upload-token/exchange Unauthenticated: a CI job’s OIDC token is the credential (like the STS exchange); documented in docs/errors.md

dcloud events

Event bus. Base path /events/api.

dcloud events buses

Event buses: the default bus receives the platform’s own events, custom buses your PutEvents

Operation Method Path IAM action Effect
list GET /events/api/buses events:ListEventBuses read
create POST /events/api/buses events:CreateEventBus write
get GET /events/api/buses/{bus} events:DescribeEventBus read
delete DELETE /events/api/buses/{bus} events:DeleteEventBus write
put-events POST /events/api/buses/{bus}/events events:PutEvents write
events GET /events/api/buses/{bus}/events events:DescribeEventBus read

dcloud events buses list

List event buses with their rule counts (the default bus always exists)

GET /events/api/buses — IAM events:ListEventBuses — read

dcloud events buses list

dcloud events buses create

Create a custom event bus

POST /events/api/buses — IAM events:CreateEventBus — write

dcloud events buses create --name <value> [flags]
Flag In Required Notes
--name <value> body yes 1-64 chars, /^[A-Za-z0-9][A-Za-z0-9_.-]*$/
--description <value> body max 512 chars · nullable

dcloud events buses get

Read an event bus

GET /events/api/buses/{bus} — IAM events:DescribeEventBus — read

dcloud events buses get <bus>

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<bus> --bus string 1-64 chars, /^[A-Za-z0-9][A-Za-z0-9_.-]*$/

dcloud events buses delete

Delete a custom event bus with its rules and their deliveries

DELETE /events/api/buses/{bus} — IAM events:DeleteEventBus — write

dcloud events buses delete <bus>

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<bus> --bus string 1-64 chars, /^[A-Za-z0-9][A-Za-z0-9_.-]*$/

dcloud events buses put-events

Send up to 10 events to a bus; each is matched against its rules

POST /events/api/buses/{bus}/events — IAM events:PutEvents — write

dcloud events buses put-events <bus> --entries <value>

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<bus> --bus string 1-64 chars, /^[A-Za-z0-9][A-Za-z0-9_.-]*$/
Flag In Required Notes
--entries <value> body yes repeatable
  • entries: [{source, detailType, detail, resources?, time?}]. Sources starting with ews. are the platform’s. Answers per entry: {eventId, matchedRules} or {errorCode, errorMessage}; failedEntryCount counts the latter.

dcloud events buses events

Recent events kept on a bus (7 days): every PutEvents event, and platform events that matched a rule

GET /events/api/buses/{bus}/events — IAM events:DescribeEventBus — read

dcloud events buses events <bus> [flags]

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<bus> --bus string 1-64 chars, /^[A-Za-z0-9][A-Za-z0-9_.-]*$/
Flag In Required Notes
--limit <number> query integer, 1-100 · server default 25

dcloud events rules

Rules: an event pattern and up to 5 targets (queues, functions, HTTPS endpoints)

Operation Method Path IAM action Effect
list GET /events/api/buses/{bus}/rules events:ListRules read
create POST /events/api/buses/{bus}/rules events:PutRule write
get GET /events/api/buses/{bus}/rules/{rule} events:DescribeRule read
update PATCH /events/api/buses/{bus}/rules/{rule} events:PutRule write
delete DELETE /events/api/buses/{bus}/rules/{rule} events:DeleteRule write
deliveries GET /events/api/buses/{bus}/rules/{rule}/deliveries events:ListDeliveries read
signing-secret GET /events/api/buses/{bus}/rules/{rule}/signing-secret events:GetRuleSigningSecret read, sensitive
rotate-signing-secret POST /events/api/buses/{bus}/rules/{rule}/signing-secret/rotate events:RotateRuleSigningSecret write

dcloud events rules list

List the rules of a bus with their targets and 24 h delivery counts

GET /events/api/buses/{bus}/rules — IAM events:ListRules — read

dcloud events rules list <bus>

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<bus> --bus string 1-64 chars, /^[A-Za-z0-9][A-Za-z0-9_.-]*$/

dcloud events rules create

Create a rule

POST /events/api/buses/{bus}/rules — IAM events:PutRule — write

dcloud events rules create <bus> --name <value> --event-pattern <key=<json>> [flags]

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<bus> --bus string 1-64 chars, /^[A-Za-z0-9][A-Za-z0-9_.-]*$/
Flag In Required Notes
--name <value> body yes 1-64 chars, /^[A-Za-z0-9][A-Za-z0-9_.-]*$/
--description <value> body max 512 chars · nullable
--event-pattern <key=<json>> body yes repeatable · key= · EventBridge event pattern, e.g. {"source":["ews.ec2"],"detail":{"eventName":["RunInstances"]}}. Matchers: exact values, prefix, suffix, equals-ignore-case, anything-but, exists, numeric, wildcard ("*"); "$or": [{…}, {…}] at any level
--state <enabled|disabled> body
--targets <value> body repeatable · Where matching events go (replaces all on update)
  • May check events:PutTargets or iam:PassRole or iam:GetAuditLogs instead, decided by server-side state the caller cannot see. A caller needs all of them to be sure of not getting a 403.
  • eventPattern is an EventBridge pattern over the envelope {version, id, detail-type, source, account, time, region, resources, detail}: values are lists of matchers — exact values, {prefix}, {suffix}, {equals-ignore-case}, {anything-but}, {exists}, {numeric:[">",0,"<=",5]}, {wildcard:"img/*.png"} — objects nest, and "$or": [{…}, {…}] at any level matches when one branch does. Platform events: source ews. with detail-type "EWS API Call" (every successful write; detail.eventName, detail.resource, detail.userIdentity), "Alarm State Change" (ews.monitoring), "Scheduled Invocation Failed" (ews.scheduler), "Deployment State Change" (ews.deploy). targets: up to 5 of {id, type:"queue", queueName, messageGroupId?}, {id, type:"function", functionName, path?}, {id, type:"http", url, method?, headers?, timeoutSeconds?} (signed: X-EWS-Signature-256 = sha256 HMAC of "." with the rule’s secret), each with roleName (required for queue and function; needs iam:PassRole), one of inputPath ($.detail, $.resources[0]), input (constant) or inputTransformer ({inputPathsMap?: {name: "$.detail.x"}, inputTemplate: "text or JSON with <$.detail.x>, , <ews.events.rule-name>, <ews.events.event.json>"}), retryMaxAttempts (0–185, default 185), maxEventAgeSeconds (60–86400), deadLetterQueue. Delivery is at least once; X-EWS-Event-Id / the ews-event-id message attribute is the idempotency key. A rule on the default bus sees the organization’s API activity and also needs iam:GetAuditLogs. 409 when the name is taken.

dcloud events rules get

Read a rule, its targets and 24 h delivery counts

GET /events/api/buses/{bus}/rules/{rule} — IAM events:DescribeRule — read

dcloud events rules get <bus> <rule>

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<bus> --bus string 1-64 chars, /^[A-Za-z0-9][A-Za-z0-9_.-]*$/
<rule> --rule string 1-64 chars, /^[A-Za-z0-9][A-Za-z0-9_.-]*$/

dcloud events rules update

Change a rule’s pattern, description, state or targets (targets replace all)

PATCH /events/api/buses/{bus}/rules/{rule} — IAM events:PutRule — write

dcloud events rules update <bus> <rule> [flags]

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<bus> --bus string 1-64 chars, /^[A-Za-z0-9][A-Za-z0-9_.-]*$/
<rule> --rule string 1-64 chars, /^[A-Za-z0-9][A-Za-z0-9_.-]*$/
Flag In Required Notes
--description <value> body max 512 chars · nullable
--event-pattern <key=<json>> body repeatable · key= · EventBridge event pattern, e.g. {"source":["ews.ec2"],"detail":{"eventName":["RunInstances"]}}. Matchers: exact values, prefix, suffix, equals-ignore-case, anything-but, exists, numeric, wildcard ("*"); "$or": [{…}, {…}] at any level
--state <enabled|disabled> body
--targets <value> body repeatable · The full list of targets; omitted keeps them
  • May check events:EnableRule or events:DisableRule or events:PutTargets or events:RemoveTargets or iam:PassRole or iam:GetAuditLogs instead, decided by server-side state the caller cannot see. A caller needs all of them to be sure of not getting a 403.
  • state alone needs only events:EnableRule / events:DisableRule. targets: up to 5 of {id, type:"queue", queueName, messageGroupId?}, {id, type:"function", functionName, path?}, {id, type:"http", url, method?, headers?, timeoutSeconds?} (signed: X-EWS-Signature-256 = sha256 HMAC of "." with the rule’s secret), each with roleName (required for queue and function; needs iam:PassRole), one of inputPath ($.detail, $.resources[0]), input (constant) or inputTransformer ({inputPathsMap?: {name: "$.detail.x"}, inputTemplate: "text or JSON with <$.detail.x>, , <ews.events.rule-name>, <ews.events.event.json>"}), retryMaxAttempts (0–185, default 185), maxEventAgeSeconds (60–86400), deadLetterQueue. Delivery is at least once; X-EWS-Event-Id / the ews-event-id message attribute is the idempotency key. A rule on the default bus sees the organization’s API activity and also needs iam:GetAuditLogs.

dcloud events rules delete

Delete a rule and its delivery history

DELETE /events/api/buses/{bus}/rules/{rule} — IAM events:DeleteRule — write

dcloud events rules delete <bus> <rule>

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<bus> --bus string 1-64 chars, /^[A-Za-z0-9][A-Za-z0-9_.-]*$/
<rule> --rule string 1-64 chars, /^[A-Za-z0-9][A-Za-z0-9_.-]*$/

dcloud events rules deliveries

List a rule’s deliveries, newest first: event, target, status, attempts, the target’s answer

GET /events/api/buses/{bus}/rules/{rule}/deliveries — IAM events:ListDeliveries — read

dcloud events rules deliveries <bus> <rule> [flags]

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<bus> --bus string 1-64 chars, /^[A-Za-z0-9][A-Za-z0-9_.-]*$/
<rule> --rule string 1-64 chars, /^[A-Za-z0-9][A-Za-z0-9_.-]*$/
Flag In Required Notes
--limit <number> query integer, 1-200 · server default 50
--status <pending|running|retry_wait|succeeded|failed|dead_lettered|dropped> query

dcloud events rules signing-secret

Reveal the secret HTTP targets are signed with (audited)

GET /events/api/buses/{bus}/rules/{rule}/signing-secret — IAM events:GetRuleSigningSecret — read, sensitive

dcloud events rules signing-secret <bus> <rule>

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<bus> --bus string 1-64 chars, /^[A-Za-z0-9][A-Za-z0-9_.-]*$/
<rule> --rule string 1-64 chars, /^[A-Za-z0-9][A-Za-z0-9_.-]*$/

dcloud events rules rotate-signing-secret

Replace the signing secret; the previous one also signs for 24 hours

POST /events/api/buses/{bus}/rules/{rule}/signing-secret/rotate — IAM events:RotateRuleSigningSecret — write

dcloud events rules rotate-signing-secret <bus> <rule>

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<bus> --bus string 1-64 chars, /^[A-Za-z0-9][A-Za-z0-9_.-]*$/
<rule> --rule string 1-64 chars, /^[A-Za-z0-9][A-Za-z0-9_.-]*$/

dcloud events archives

Archives: keep a bus’s events (all, or those matching a pattern) for 1–3650 days, to replay later

Operation Method Path IAM action Effect
list GET /events/api/archives events:ListArchives read
create POST /events/api/archives events:CreateArchive write
get GET /events/api/archives/{archive} events:DescribeArchive read
update PATCH /events/api/archives/{archive} events:UpdateArchive write
delete DELETE /events/api/archives/{archive} events:DeleteArchive write
events GET /events/api/archives/{archive}/events events:DescribeArchive read

dcloud events archives list

List archives with the events and bytes they hold

GET /events/api/archives — IAM events:ListArchives — read

dcloud events archives list

dcloud events archives create

Create an archive on a bus

POST /events/api/archives — IAM events:CreateArchive — write

dcloud events archives create --name <value> --event-bus <value> [flags]
Flag In Required Notes
--name <value> body yes 1-48 chars, /^[A-Za-z0-9][A-Za-z0-9_.-]*$/
--event-bus <value> body yes 1-64 chars, /^[A-Za-z0-9][A-Za-z0-9_.-]*$/ · The bus whose events it keeps
--description <value> body max 512 chars · nullable
--event-pattern <key=<json>> body repeatable · key= · nullable · Keep only the events matching this pattern (default: every event of the bus)
--retention-days <number> body integer, 1-3650 · Days an archived event is kept (1–3650, default 90); lowering it removes older events at the next daily pass
  • May check events:DescribeEventBus or iam:GetAuditLogs instead, decided by server-side state the caller cannot see. A caller needs all of them to be sure of not getting a 403.
  • Keeps every event arriving on eventBus that matches eventPattern (none: all), whether a rule matched it or not, for retentionDays (default 90). Billed per GB-month held (storage.events.gb_month, €0.10). An archive on the default bus keeps the organization’s API activity and also needs iam:GetAuditLogs. At most 10 per bus, 50 per organization; 409 when the name is taken.

dcloud events archives get

Read an archive

GET /events/api/archives/{archive} — IAM events:DescribeArchive — read

dcloud events archives get <archive>

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<archive> --archive string 1-48 chars, /^[A-Za-z0-9][A-Za-z0-9_.-]*$/

dcloud events archives update

Change an archive’s pattern, description or retention

PATCH /events/api/archives/{archive} — IAM events:UpdateArchive — write

dcloud events archives update <archive> [flags]

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<archive> --archive string 1-48 chars, /^[A-Za-z0-9][A-Za-z0-9_.-]*$/
Flag In Required Notes
--description <value> body max 512 chars · nullable
--event-pattern <key=<json>> body repeatable · key= · nullable · EventBridge event pattern, e.g. {"source":["ews.ec2"],"detail":{"eventName":["RunInstances"]}}. Matchers: exact values, prefix, suffix, equals-ignore-case, anything-but, exists, numeric, wildcard ("*"); "$or": [{…}, {…}] at any level
--retention-days <number> body integer, 1-3650 · Days an archived event is kept (1–3650, default 90); lowering it removes older events at the next daily pass
  • May check iam:GetAuditLogs instead, decided by server-side state the caller cannot see. A caller needs all of them to be sure of not getting a 403.
  • A shorter retention removes the older events at the next daily pass.

dcloud events archives delete

Delete an archive and every event it holds

DELETE /events/api/archives/{archive} — IAM events:DeleteArchive — write

dcloud events archives delete <archive>

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<archive> --archive string 1-48 chars, /^[A-Za-z0-9][A-Za-z0-9_.-]*$/

dcloud events archives events

The newest events an archive holds

GET /events/api/archives/{archive}/events — IAM events:DescribeArchive — read

dcloud events archives events <archive> [flags]

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<archive> --archive string 1-48 chars, /^[A-Za-z0-9][A-Za-z0-9_.-]*$/
Flag In Required Notes
--limit <number> query integer, 1-100 · server default 25
  • May check iam:GetAuditLogs instead, decided by server-side state the caller cannot see. A caller needs all of them to be sure of not getting a 403.

dcloud events replays

Replays: an archive’s events sent to rules again, one at a time, in original order

Operation Method Path IAM action Effect
list GET /events/api/replays events:ListReplays read
start POST /events/api/replays events:StartReplay write
get GET /events/api/replays/{replay} events:DescribeReplay read
cancel POST /events/api/replays/{replay}/cancel events:CancelReplay write

dcloud events replays list

List replays (kept 7 days after they finish) with their progress

GET /events/api/replays — IAM events:ListReplays — read

dcloud events replays list [flags]
Flag In Required Notes
--archive <value> query 1-48 chars, /^[A-Za-z0-9][A-Za-z0-9_.-]*$/
--limit <number> query integer, 1-100 · server default 25

dcloud events replays start

Replay an archive’s events from a time window into rules of its bus

POST /events/api/replays — IAM events:StartReplay — write

dcloud events replays start --name <value> --archive <value> --event-start-time <json> --event-end-time <json> --rules <value> [flags]
Flag In Required Notes
--name <value> body yes 1-64 chars, /^[A-Za-z0-9][A-Za-z0-9_.-]*$/
--description <value> body max 512 chars · nullable
--archive <value> body yes 1-48 chars, /^[A-Za-z0-9][A-Za-z0-9_.-]*$/ · The archive to replay from
--event-start-time <json> body yes JSON · Replay events whose time is at or after this
--event-end-time <json> body yes JSON · …and at or before this (not in the future)
--rules <value> body yes repeatable · 1-64 chars, /^[A-Za-z0-9][A-Za-z0-9_.-]*$/ · Rules of the archive’s bus to replay into; their current pattern decides
  • May check iam:GetAuditLogs instead, decided by server-side state the caller cannot see. A caller needs all of them to be sure of not getting a 403.
  • Events whose time is within [eventStartTime, eventEndTime] are sent in the order the bus received them, one at a time: the next only when every delivery of the previous is final. Each is matched against the rules’ CURRENT pattern; the envelope gains "replay-name". Replay deliveries retry at most 3 times within 5 minutes, then go to the target’s dead-letter queue (or fail) and the replay moves on. events:StartReplay is checked on the replay, the archive and each rule. One active replay per archive, 5 per organization (409).

dcloud events replays get

Read a replay: state, eventsProcessed / eventsTotal, eventsReplayed

GET /events/api/replays/{replay} — IAM events:DescribeReplay — read

dcloud events replays get <replay>

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<replay> --replay string 1-64 chars, /^[A-Za-z0-9][A-Za-z0-9_.-]*$/

dcloud events replays cancel

Cancel a replay; the event in flight finishes, no further one is sent

POST /events/api/replays/{replay}/cancel — IAM events:CancelReplay — write

dcloud events replays cancel <replay>

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<replay> --replay string 1-64 chars, /^[A-Za-z0-9][A-Za-z0-9_.-]*$/

dcloud events patterns

Build and test event patterns

Operation Method Path IAM action Effect
test POST /events/api/test-pattern events:TestEventPattern read
catalog GET /events/api/catalog events:ListEventBuses read
samples GET /events/api/sample-events events:ListEventBuses read

dcloud events patterns test

Check whether an event matches a pattern

POST /events/api/test-pattern — IAM events:TestEventPattern — read

dcloud events patterns test --event-pattern <key=<json>> --event <key=<json>>
Flag In Required Notes
--event-pattern <key=<json>> body yes repeatable · key= · EventBridge event pattern, e.g. {"source":["ews.ec2"],"detail":{"eventName":["RunInstances"]}}. Matchers: exact values, prefix, suffix, equals-ignore-case, anything-but, exists, numeric, wildcard ("*"); "$or": [{…}, {…}] at any level
--event <key=<json>> body yes repeatable · key= · An event envelope to test

dcloud events patterns catalog

List the events the platform sends to the default bus, with example patterns

GET /events/api/catalog — IAM events:ListEventBuses — read

dcloud events patterns catalog

dcloud events patterns samples

Recent API-call events of the organization as the bus would deliver them

GET /events/api/sample-events — IAM events:ListEventBuses — read

dcloud events patterns samples [flags]
Flag In Required Notes
--limit <number> query integer, 1-100 · server default 25
  • May check iam:GetAuditLogs instead, decided by server-side state the caller cannot see. A caller needs all of them to be sure of not getting a 403.

dcloud functions

Functions. Base path /functions/api.

dcloud functions functions

Serverless functions: Node.js and Python handlers behind an HTTPS URL that scale to zero, isolated under gVisor

The resource is named after its service, so every command in this section reads dcloud functions functions <operation>. That is the literal three-word shape the dispatcher takes; there is no shorter spelling today.

Operation Method Path IAM action Effect
list GET /functions/api/functions functions:ListFunctions read
create POST /functions/api/functions functions:CreateFunction write
get GET /functions/api/functions/{name} functions:GetFunction read
update PATCH /functions/api/functions/{name} functions:UpdateFunctionConfiguration write
deploy PUT /functions/api/functions/{name}/code functions:UpdateFunctionCode write
code GET /functions/api/functions/{name}/code functions:GetFunctionCode read, sensitive
delete DELETE /functions/api/functions/{name} functions:DeleteFunction write
invoke POST /functions/api/functions/{name}/invoke functions:InvokeFunction write

dcloud functions functions list

List functions with their URLs and the instances running now

GET /functions/api/functions — IAM functions:ListFunctions — read

dcloud functions functions list

dcloud functions functions create

Create a function from source files

POST /functions/api/functions — IAM functions:CreateFunction — write

dcloud functions functions create --name <value> --runtime <nodejs22|python3.12|image> [flags]
Flag In Required Notes
--name <value> body yes 1-40 chars, /^a-z?$/
--runtime <nodejs22|python3.12|image> body yes
--entrypoint <value> body max 200 chars · The file the bootstrap loads (default index.mjs for Node.js, main.py for Python)
--files <key=value> body repeatable · key=value · Source files: path → UTF-8 content, e.g. {"index.mjs": "export default () => "hi""}. Dependencies: include package-lock.json (with package.json) or requirements.txt and they are installed at deploy (npm ci --omit=dev / pip install, from the public registries) — the new code goes live once that build is ready. Or vendor them yourself (node_modules/, or Python packages: /code is on sys.path).
--image <value> body 1-512 chars, /^([a-z0-9.-]+/)?[a-z0-9][a-z0-9./-]*(:[A-Za-z0-9][A-Za-z0-9._-]{0,127}|@sha256:[a-f0-9]{64})?$/ · runtime image: an image of your registry (repo:tag or repo@sha256:…), pinned to its digest when set. Its server must listen on $PORT (8080)
--tags <key=value> body repeatable · key=value · Tags for the new resource, e.g. {"env": "prod", "project": "shop"}. Keys your organization marks required must be present, or the create is refused with the missing keys (GET /tags/api/keys lists them).
--description <value> body max 256 chars
--memory-mb <number> body integer, 128-2048 · Memory per instance, 128–2048 MB (default 256); CPU is 1 vCPU per GB, at least 0.25
--timeout-seconds <number> body integer, 1-900 · Per request, default 30
--concurrency <number> body integer, 1-100 · Requests one instance handles at once (default 10 for Node.js, 1 for Python)
--max-instances <number> body integer, 1-50 · Instances at most (default 10); further requests wait for a slot
--idle-timeout-seconds <number> body integer, 30-3600 · An instance stops after this long without a request (default 300): scale to zero
--auth <iam|public> body iam (default): the URL needs Authorization: EWS-ACCESS-KEY with functions:InvokeFunction. public: anyone may call it (needs functions:MakeFunctionPublic)
--network <open|none> body open (default): the internet, minus private ranges, metadata and SMTP. none: no egress
--env <key=value> body repeatable · key=value · Plain environment variables (not secrets: they are readable with GetFunction)
--secrets <value> body repeatable · Secrets as environment variables. Read when an instance starts (needs secrets:GetSecretValue to bind; binding grants the secret to compute consumers); never shown by GetFunction. The whole list replaces the previous one
--role-name <value> body 1-64 chars · nullable · The IAM role the function acts as (needs iam:PassRole on it); its instances get a 60-minute session as EWS_ACCESS_KEY, which the Deutsche Cloud SDKs and CLI read. null removes it
--public-rate-limit <number> body integer, 1-1000 · Requests per second a public URL accepts (default 50)
--init-snapshot body Start instances from an image taken right after your module loaded (default false): the first cold start of each version takes it, later ones skip the import. The image holds what your module computed at import, its env and secrets, on the function host only. Not a new version
  • May check functions:MakeFunctionPublic instead, decided by server-side state the caller cannot see. A caller needs all of them to be sure of not getting a 403.
  • Node.js 22 (index.mjs): export default async function (request) { return new Response("hi") } — a Fetch API Request in, a Response (or a string, or an object for JSON) out. Python 3.12 (main.py): def handler(request): return {"ok": True} — request has method, path, query, headers, body, text and json(); return a dict (JSON), str/bytes, None (204) or (status, headers, body). The function gets an HTTPS URL; an instance starts on the first call and stops after idleTimeoutSeconds without one (scale to zero). auth defaults to iam (the URL needs a Deutsche Cloud access key with functions:InvokeFunction); public needs functions:MakeFunctionPublic. 409 when the name is taken. Dependencies: with package-lock.json (and package.json) or requirements.txt in the files, a function host installs them first (npm ci --omit=dev, or pip install, from registry.npmjs.org / PyPI only, in a gVisor instance of the same runtime) into node_modules/ or .python_packages/. A new function waits in state building until then (failed if the build fails).

dcloud functions functions get

Read a function: URL, limits, running instances and the last 24 hours of usage

GET /functions/api/functions/{name} — IAM functions:GetFunction — read

dcloud functions functions get <name>

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<name> --name string 1-40 chars, /^a-z?$/

dcloud functions functions update

Change memory, timeout, concurrency, scaling, auth, network or environment

PATCH /functions/api/functions/{name} — IAM functions:UpdateFunctionConfiguration — write

dcloud functions functions update <name> [flags]

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<name> --name string 1-40 chars, /^a-z?$/
Flag In Required Notes
--description <value> body max 256 chars
--memory-mb <number> body integer, 128-2048 · Memory per instance, 128–2048 MB (default 256); CPU is 1 vCPU per GB, at least 0.25
--timeout-seconds <number> body integer, 1-900 · Per request, default 30
--concurrency <number> body integer, 1-100 · Requests one instance handles at once (default 10 for Node.js, 1 for Python)
--max-instances <number> body integer, 1-50 · Instances at most (default 10); further requests wait for a slot
--idle-timeout-seconds <number> body integer, 30-3600 · An instance stops after this long without a request (default 300): scale to zero
--auth <iam|public> body iam (default): the URL needs Authorization: EWS-ACCESS-KEY with functions:InvokeFunction. public: anyone may call it (needs functions:MakeFunctionPublic)
--network <open|none> body open (default): the internet, minus private ranges, metadata and SMTP. none: no egress
--env <key=value> body repeatable · key=value · Plain environment variables (not secrets: they are readable with GetFunction)
--secrets <value> body repeatable · Secrets as environment variables. Read when an instance starts (needs secrets:GetSecretValue to bind; binding grants the secret to compute consumers); never shown by GetFunction. The whole list replaces the previous one
--role-name <value> body 1-64 chars · nullable · The IAM role the function acts as (needs iam:PassRole on it); its instances get a 60-minute session as EWS_ACCESS_KEY, which the Deutsche Cloud SDKs and CLI read. null removes it
--public-rate-limit <number> body integer, 1-1000 · Requests per second a public URL accepts (default 50)
--init-snapshot body Start instances from an image taken right after your module loaded (default false): the first cold start of each version takes it, later ones skip the import. The image holds what your module computed at import, its env and secrets, on the function host only. Not a new version
  • May check functions:MakeFunctionPublic instead, decided by server-side state the caller cannot see. A caller needs all of them to be sure of not getting a 403.
  • Running instances finish their requests and are replaced by the new configuration.

dcloud functions functions deploy

Deploy new source files

PUT /functions/api/functions/{name}/code — IAM functions:UpdateFunctionCode — write

dcloud functions functions deploy <name> [flags]

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<name> --name string 1-40 chars, /^a-z?$/
Flag In Required Notes
--files <key=value> body repeatable · key=value · Source files: path → UTF-8 content, e.g. {"index.mjs": "export default () => "hi""}. Dependencies: include package-lock.json (with package.json) or requirements.txt and they are installed at deploy (npm ci --omit=dev / pip install, from the public registries) — the new code goes live once that build is ready. Or vendor them yourself (node_modules/, or Python packages: /code is on sys.path).
--entrypoint <value> body max 200 chars
--image <value> body 1-512 chars, /^([a-z0-9.-]+/)?[a-z0-9][a-z0-9./-]*(:[A-Za-z0-9][A-Za-z0-9._-]{0,127}|@sha256:[a-f0-9]{64})?$/ · runtime image: an image of your registry (repo:tag or repo@sha256:…), pinned to its digest when set. Its server must listen on $PORT (8080)
  • Node.js 22 (index.mjs): export default async function (request) { return new Response("hi") } — a Fetch API Request in, a Response (or a string, or an object for JSON) out. Python 3.12 (main.py): def handler(request): return {"ok": True} — request has method, path, query, headers, body, text and json(); return a dict (JSON), str/bytes, None (204) or (status, headers, body). The function gets an HTTPS URL; an instance starts on the first call and stops after idleTimeoutSeconds without one (scale to zero). The next request runs the new code. Dependencies: with package-lock.json (and package.json) or requirements.txt in the files, a function host installs them first (npm ci --omit=dev, or pip install, from registry.npmjs.org / PyPI only, in a gVisor instance of the same runtime) into node_modules/ or .python_packages/. Then the answer is 202 and the current code keeps serving until the build is ready; a failed build never goes live (its log is in get → build.log). The same lockfile reuses its build: 200 at once.

dcloud functions functions code

Read the deployed source files (audited)

GET /functions/api/functions/{name}/code — IAM functions:GetFunctionCode — read, sensitive

dcloud functions functions code <name>

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<name> --name string 1-40 chars, /^a-z?$/

dcloud functions functions delete

Delete a function; its instances stop

DELETE /functions/api/functions/{name} — IAM functions:DeleteFunction — write

dcloud functions functions delete <name>

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<name> --name string 1-40 chars, /^a-z?$/

dcloud functions functions invoke

Call a function and return its answer (status, headers, body, cold start)

POST /functions/api/functions/{name}/invoke — IAM functions:InvokeFunction — write

dcloud functions functions invoke <name> [flags]

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<name> --name string 1-40 chars, /^a-z?$/
Flag In Required Notes
--method <GET|POST|PUT|PATCH|DELETE> body server default "POST"
--path <value> body max 2048 chars, /^// · server default "/" · Path and query string, e.g. /hello?name=ews
--headers <key=value> body repeatable · key=value
--body <value> body max 1048576 chars · Request body; for JSON, a JSON string
  • Works for iam and public functions alike. The body is returned as text, cut at 256 KB. Logs: monitoring logs with resourceType=function and resourceId=.

dcloud functions event-source-mappings

Queue triggers: a function consumes a queue in batches, read and deleted as its execution role

Operation Method Path IAM action Effect
list GET /functions/api/functions/{name}/event-source-mappings functions:ListEventSourceMappings read
create POST /functions/api/functions/{name}/event-source-mappings functions:CreateEventSourceMapping write
update PATCH /functions/api/functions/{name}/event-source-mappings/{id} functions:UpdateEventSourceMapping write
delete DELETE /functions/api/functions/{name}/event-source-mappings/{id} functions:DeleteEventSourceMapping write

dcloud functions event-source-mappings list

List the queues a function consumes, with their state and counters

GET /functions/api/functions/{name}/event-source-mappings — IAM functions:ListEventSourceMappings — read

dcloud functions event-source-mappings list <name>

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<name> --name string 1-40 chars, /^a-z?$/

dcloud functions event-source-mappings create

Let a function consume a queue

POST /functions/api/functions/{name}/event-source-mappings — IAM functions:CreateEventSourceMapping — write

dcloud functions event-source-mappings create <name> --queue-name <value> [flags]

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<name> --name string 1-40 chars, /^a-z?$/
Flag In Required Notes
--queue-name <value> body yes 1-80 chars · A queue of the Queue service in the same region
--batch-size <number> body integer, 1-10 · Messages per invocation, 1–10 (default 10)
--max-concurrency <number> body integer, 1-10 · Batches in flight at once, 1–10 (default 2); never more than maxInstances × concurrency
--enabled body Start consuming at once (default true)
  • The function needs an execution role allowed queue:ReceiveMessage and queue:DeleteMessage on the queue. It is called with POST / and {"records":[{messageId, body, attributes, receiveCount, sentAt, queueName}]}. A 2xx deletes the batch, except the ids it answers in {"failedMessageIds":[...]}; anything else leaves the batch to reappear after the visibility timeout (at least once; the queue’s redrive policy moves it to its dead-letter queue). Every batch writes a TRIGGER line to the function’s logs.

dcloud functions event-source-mappings update

Change a queue trigger, or pause and resume it (enabled)

PATCH /functions/api/functions/{name}/event-source-mappings/{id} — IAM functions:UpdateEventSourceMapping — write

dcloud functions event-source-mappings update <name> <id> [flags]

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<name> --name string 1-40 chars, /^a-z?$/
<id> --id string
Flag In Required Notes
--batch-size <number> body integer, 1-10 · Messages per invocation, 1–10 (default 10)
--max-concurrency <number> body integer, 1-10 · Batches in flight at once, 1–10 (default 2); never more than maxInstances × concurrency
--enabled body false pauses the trigger; true resumes it

dcloud functions event-source-mappings delete

Stop a function consuming a queue

DELETE /functions/api/functions/{name}/event-source-mappings/{id} — IAM functions:DeleteEventSourceMapping — write

dcloud functions event-source-mappings delete <name> <id>

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<name> --name string 1-40 chars, /^a-z?$/
<id> --id string

dcloud sandbox

Sandboxes. Base path /sandbox/api.

dcloud sandbox sandboxes

Sandboxes: long-lived isolated sessions (gVisor) to run commands and move files in, for agents and code interpreters

Operation Method Path IAM action Effect
list GET /sandbox/api/sandboxes sandbox:DescribeSandboxes read
create POST /sandbox/api/sandboxes sandbox:CreateSandbox write
get GET /sandbox/api/sandboxes/{id} sandbox:DescribeSandboxes read
update PATCH /sandbox/api/sandboxes/{id} sandbox:UpdateSandbox write
delete DELETE /sandbox/api/sandboxes/{id} sandbox:TerminateSandbox write
exec POST /sandbox/api/sandboxes/{id}/exec sandbox:ExecCommand write
fork POST /sandbox/api/sandboxes/{id}/fork sandbox:ForkSandbox write
connect POST /sandbox/api/sandboxes/{id}/connect sandbox:ConnectSandbox write
logs GET /sandbox/api/sandboxes/{id}/logs sandbox:GetSandboxLogs read, sensitive

dcloud sandbox sandboxes list

List sandboxes, and the organization’s sandbox hosts

GET /sandbox/api/sandboxes — IAM sandbox:DescribeSandboxes — read

dcloud sandbox sandboxes list [flags]
Flag In Required Notes
--state <active|all> query active (default): pending and running; all: also the last day of ended ones

dcloud sandbox sandboxes create

Start a sandbox from a stock runtime or an image of your registry

POST /sandbox/api/sandboxes — IAM sandbox:CreateSandbox — write

dcloud sandbox sandboxes create [flags]
Flag In Required Notes
--runtime <python3.12|nodejs22> body python3.12 (default) or nodejs22: the stock Debian-slim images (or give image)
--image <value> body 1-300 chars, /^[a-z0-9][a-z0-9._-/:@]*$/ · An image of this organization’s registry (repo:tag or repo@sha256:…), pinned to its digest at create. Its Env applies to every command; its ENTRYPOINT/CMD do not run; commands run as uid 65534; it needs /bin/sh
--ports <value> body repeatable · Ports to expose at once on https://-.sbx.apps. (at most 5)
--memory-mb <number> body integer, 256-4096 · Memory in MB (256–4096, default 512)
--vcpu <number> body 0.5-4 · vCPU (0.5–4); default memory/1 GB, at least 0.5
--disk-mb <number> body integer, 512-10240 · Workspace size in MB (512–10240, default 2048); writes beyond it fail
--timeout-seconds <number> body integer, 60-86400 · Lifetime in seconds (60–86400, default 3600); extend it with update
--idle-timeout-seconds <number> body integer, 0-86400 · Stop after this many seconds without an exec or file call (default 900; 0 = off)
--network <json> body JSON
--metadata <key=value> body repeatable · key=value
--wait-seconds <number> body integer, 0-120 · Wait up to this long for the sandbox to run (default 30). The first sandbox of an organization waits for its sandbox host (about a minute)
  • May check sandbox:UseOpenEgress or ecr:PullImage or sandbox:ExposePort or sandbox:ExposePublicPort instead, decided by server-side state the caller cannot see. A caller needs all of them to be sure of not getting a 403.
  • Answers 201 with state running, or 202 with state pending (the organization’s first sandbox waits about a minute for its own sandbox host, and an image is pulled once per host; get it again until it runs). image (repo:tag or repo@sha256:…, your own registry, needs ecr:PullImage) is pinned to its digest; its Env applies, its ENTRYPOINT/CMD do not run, commands run as uid 65534. A create matching a warm pool (same image or runtime, memoryMb, vcpu, diskMb, network mode) claims a started one: startMode pool. Network defaults to none; open needs sandbox:UseOpenEgress. Files live in /workspace (an ext4 volume of diskMb) and survive a restart of the host, not its replacement. It ends after timeoutSeconds, or idleTimeoutSeconds without an exec, file call, open terminal or port request.

dcloud sandbox sandboxes get

Read a sandbox: state and why, limits, network, host, deadlines, usage

GET /sandbox/api/sandboxes/{id} — IAM sandbox:DescribeSandboxes — read

dcloud sandbox sandboxes get <id>

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<id> --id string /^sbx-[0-9a-f]{12}$/

dcloud sandbox sandboxes update

Extend a sandbox’s lifetime, change its idle timeout or metadata

PATCH /sandbox/api/sandboxes/{id} — IAM sandbox:UpdateSandbox — write

dcloud sandbox sandboxes update <id> [flags]

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<id> --id string /^sbx-[0-9a-f]{12}$/
Flag In Required Notes
--timeout-seconds <number> body integer, 60-86400 · New lifetime, counted from now (60–86400)
--idle-timeout-seconds <number> body integer, 0-86400
--metadata <key=value> body repeatable · key=value

dcloud sandbox sandboxes delete

Stop a sandbox; its processes and workspace are discarded

DELETE /sandbox/api/sandboxes/{id} — IAM sandbox:TerminateSandbox — write

dcloud sandbox sandboxes delete <id>

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<id> --id string /^sbx-[0-9a-f]{12}$/

dcloud sandbox sandboxes exec

Run a command in a sandbox and return its output and exit code

POST /sandbox/api/sandboxes/{id}/exec — IAM sandbox:ExecCommand — write

dcloud sandbox sandboxes exec <id> [flags]

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<id> --id string /^sbx-[0-9a-f]{12}$/
Flag In Required Notes
--cmd <value> body repeatable · max 65536 chars · The program and its arguments, e.g. ["python3", "-c", "print(1)"]
--command <value> body 1-65536 chars · A shell command line, run as sh -c (instead of cmd)
--stdin <value> body max 1048576 chars
--env <key=value> body repeatable · key=value
--cwd <value> body max 4096 chars · Working directory (default /workspace)
--timeout-ms <number> body integer, 100-1800000 · Stop the command after this long (default 60000, at most 30 minutes)
  • cmd is argv (["python3","-c","print(1)"]); command is a shell line (sh -c). Runs as an unprivileged user in /workspace. Output is cut to 256 KB per stream through the API (head and tail kept, truncated: true). Each call is audited; the command line also goes to the sandbox log.

dcloud sandbox sandboxes fork

Copy a running sandbox, memory and workspace, into a new sandbox

POST /sandbox/api/sandboxes/{id}/fork — IAM sandbox:ForkSandbox — write

dcloud sandbox sandboxes fork <id>

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<id> --id string /^sbx-[0-9a-f]{12}$/
  • Needs sandbox:CreateSandbox too. The copy keeps running processes and /tmp, inherits the network policy and size, runs on the same host and gets a fresh lifetime. It counts against the sandbox quota.

dcloud sandbox sandboxes connect

Mint a short-lived token for the sandbox host’s data plane (lower latency, files up to 100 MB, the terminal)

POST /sandbox/api/sandboxes/{id}/connect — IAM sandbox:ConnectSandbox — write

dcloud sandbox sandboxes connect <id> [flags]

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<id> --id string /^sbx-[0-9a-f]{12}$/
Flag In Required Notes
--scopes <exec|files:read|files:write|terminal> body repeatable · What the token may do (default exec, files:read, files:write); each needs the matching action: ExecCommand, ReadFiles, WriteFiles, StartTerminal
--ttl-seconds <number> body integer, 60-3600 · Token lifetime (60–3600, default 900); never beyond the sandbox
  • May check sandbox:ExecCommand or sandbox:ReadFiles or sandbox:WriteFiles or sandbox:StartTerminal instead, decided by server-side state the caller cannot see. A caller needs all of them to be sure of not getting a 403.
  • Returns {url, token}: POST {url}/exec, GET/PUT {url}/files?path=, GET {url}/files/list, with Authorization: Bearer {token}. With scope terminal: a WebSocket at wss://…/pty (subprotocols ews.terminal and ews.token.{token}) is an interactive shell; dcloud sandbox shell <id> does this for you. Each scope needs the matching action. The mint is audited; calls with the token are logged to the sandbox log (a terminal: its open and close, not keystrokes).

dcloud sandbox sandboxes logs

Read a sandbox’s log: commands, file transfers, starts, restarts, denied lookups

GET /sandbox/api/sandboxes/{id}/logs — IAM sandbox:GetSandboxLogs — read, sensitive

dcloud sandbox sandboxes logs <id> [flags]

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<id> --id string /^sbx-[0-9a-f]{12}$/
Flag In Required Notes
--limit <number> query integer, 1-1000
--contains <value> query max 200 chars

dcloud sandbox files

Files in a sandbox’s /workspace, through the API (10 MB per file)

Operation Method Path IAM action Effect
read GET /sandbox/api/sandboxes/{id}/files sandbox:ReadFiles read, sensitive
write PUT /sandbox/api/sandboxes/{id}/files sandbox:WriteFiles write
list GET /sandbox/api/sandboxes/{id}/files/list sandbox:ReadFiles read, sensitive

dcloud sandbox files read

Download a file from a sandbox (text as content, binary as contentBase64)

GET /sandbox/api/sandboxes/{id}/files — IAM sandbox:ReadFiles — read, sensitive

dcloud sandbox files read <id> --path <value>

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<id> --id string /^sbx-[0-9a-f]{12}$/
Flag In Required Notes
--path <value> query yes 1-4096 chars · A path in the workspace: /workspace/data.csv or data.csv

dcloud sandbox files write

Upload a file into a sandbox, making its directories

PUT /sandbox/api/sandboxes/{id}/files — IAM sandbox:WriteFiles — write

dcloud sandbox files write <id> --path <value> [flags]

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<id> --id string /^sbx-[0-9a-f]{12}$/
Flag In Required Notes
--path <value> body yes 1-4096 chars · A path in the workspace: /workspace/data.csv or data.csv
--content <value> body The file as UTF-8 text
--content-base64 <value> body The file as base64 (binary files)

dcloud sandbox files list

List a directory of a sandbox’s workspace

GET /sandbox/api/sandboxes/{id}/files/list — IAM sandbox:ReadFiles — read, sensitive

dcloud sandbox files list <id> [flags]

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<id> --id string /^sbx-[0-9a-f]{12}$/
Flag In Required Notes
--path <value> query 1-4096 chars · A directory (default /workspace)

dcloud sandbox ports

Ports of a sandbox on their own HTTPS URL, https://-.sbx.apps.: private (token) or public

Operation Method Path IAM action Effect
expose PUT /sandbox/api/sandboxes/{id}/ports/{port} sandbox:ExposePort write
close DELETE /sandbox/api/sandboxes/{id}/ports/{port} sandbox:ExposePort write
open POST /sandbox/api/sandboxes/{id}/ports/{port}/open sandbox:ConnectSandbox write

dcloud sandbox ports expose

Expose a port of a sandbox on its own URL (private unless auth is public)

PUT /sandbox/api/sandboxes/{id}/ports/{port} — IAM sandbox:ExposePort — write

dcloud sandbox ports expose <id> <port> [flags]

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<id> --id string /^sbx-[0-9a-f]{12}$/
<port> --port number integer, 1024-65535
Flag In Required Notes
--auth <private|public> body private (default): a port token is needed. public: anyone with the URL (needs sandbox:ExposePublicPort)
  • May check sandbox:ExposePublicPort instead, decided by server-side state the caller cannot see. A caller needs all of them to be sure of not getting a 403.
  • The URL resolves within about 20 seconds. Something in the sandbox must listen on 0.0.0.0:; until then the URL answers 502. A sandbox with network none still takes requests on its exposed ports. At most 5 per sandbox.

dcloud sandbox ports close

Stop exposing a port

DELETE /sandbox/api/sandboxes/{id}/ports/{port} — IAM sandbox:ExposePort — write

dcloud sandbox ports close <id> <port>

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<id> --id string /^sbx-[0-9a-f]{12}$/
<port> --port number integer, 1024-65535

dcloud sandbox ports open

Get a link to a private port (a short-lived token bound to this port)

POST /sandbox/api/sandboxes/{id}/ports/{port}/open — IAM sandbox:ConnectSandbox — write

dcloud sandbox ports open <id> <port> [flags]

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<id> --id string /^sbx-[0-9a-f]{12}$/
<port> --port number integer, 1024-65535
Flag In Required Notes
--ttl-seconds <number> body integer, 60-3600 · How long the link (and the cookie it leaves) opens the port: 60–3600 s, default 900
  • Opening the link in a browser sets a cookie for that host name and drops the token from the address. A program sends Authorization: Bearer {token}. The token opens this one port of this one sandbox.

dcloud sandbox pools

Warm pools: sandboxes of one image and size kept started, so a matching create claims one at once

Operation Method Path IAM action Effect
list GET /sandbox/api/pools sandbox:DescribePools read
create POST /sandbox/api/pools sandbox:CreatePool write
get GET /sandbox/api/pools/{poolId} sandbox:DescribePools read
update PATCH /sandbox/api/pools/{poolId} sandbox:UpdatePool write
delete DELETE /sandbox/api/pools/{poolId} sandbox:DeletePool write

dcloud sandbox pools list

List warm pools: image, size class, ready instances, claims

GET /sandbox/api/pools — IAM sandbox:DescribePools — read

dcloud sandbox pools list

dcloud sandbox pools create

Keep sandboxes of one image and size started

POST /sandbox/api/pools — IAM sandbox:CreatePool — write

dcloud sandbox pools create --name <value> [flags]
Flag In Required Notes
--name <value> body yes 1-63 chars, /^a-z0-9?$/
--runtime <python3.12|nodejs22> body A stock runtime (or give image)
--image <value> body 1-300 chars, /^[a-z0-9][a-z0-9._-/:@]*$/ · An image of this organization’s registry (repo:tag or repo@sha256:…), pinned to its digest at create. Its Env applies to every command; its ENTRYPOINT/CMD do not run; commands run as uid 65534; it needs /bin/sh
--memory-mb <number> body integer, 256-4096 · Memory in MB of each sandbox (default 512); a create must ask for the same to claim one
--vcpu <number> body 0.5-4
--disk-mb <number> body integer, 512-10240
--network-mode <none|open> body none (default) or open (needs sandbox:UseOpenEgress); allowlist sandboxes start cold
--size <number> body integer, 0-10 · How many to keep started (0–10); with autoscale, the starting size (default its min)
--autoscale <json> body JSON · Size the pool by the creates that match it: between min and max, the most matching creates within any 10 s of the last 15 min (or the steady rate × refill time × 2, if more). Up at once, down by at most half per minute. Each warm instance is billed; size is then read-only
  • May check ecr:PullImage or sandbox:UseOpenEgress instead, decided by server-side state the caller cannot see. A caller needs all of them to be sure of not getting a 403.
  • Warm instances reserve memory on the organization’s sandbox host (a host boots for it if there is none) and are billed like running sandboxes. A create with the same image (or runtime), memoryMb, vcpu, diskMb and network mode claims one; allowlist sandboxes always start cold. At most 3 pools, 10 instances each, in the preview.

dcloud sandbox pools get

Read a warm pool

GET /sandbox/api/pools/{poolId} — IAM sandbox:DescribePools — read

dcloud sandbox pools get <poolId>

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<poolId> --pool-id string /^pool-[0-9a-f]{12}$/

dcloud sandbox pools update

Resize a warm pool, turn its autoscaling on or off, or move it to a new image (its warm instances are replaced)

PATCH /sandbox/api/pools/{poolId} — IAM sandbox:UpdatePool — write

dcloud sandbox pools update <poolId> [flags]

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<poolId> --pool-id string /^pool-[0-9a-f]{12}$/
Flag In Required Notes
--size <number> body integer, 0-10 · How many to keep started (0–10); each is billed like a running sandbox while warm
--image <value> body 1-300 chars, /^[a-z0-9][a-z0-9._-/:@]*$/ · A new image (re-resolved to its digest): the warm instances are replaced
--autoscale <json> body JSON · nullable · Turn autoscaling on ({min, max}) or off (null: the current size stays, now yours)
  • May check ecr:PullImage instead, decided by server-side state the caller cannot see. A caller needs all of them to be sure of not getting a 403.

dcloud sandbox pools delete

Delete a warm pool (sandboxes that claimed from it keep running)

DELETE /sandbox/api/pools/{poolId} — IAM sandbox:DeletePool — write

dcloud sandbox pools delete <poolId>

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<poolId> --pool-id string /^pool-[0-9a-f]{12}$/

dcloud cloudshell

Cloud shell. Base path /cloudshell/api.

dcloud cloudshell environment

Your cloud shell: a terminal signed in as you (ews, kubectl, helm, terraform, git, psql) with a home directory that is kept

Operation Method Path IAM action Effect
get GET /cloudshell/api/environment cloudshell:DescribeEnvironment read
start-session POST /cloudshell/api/session cloudshell:StartSession write
end-session POST /cloudshell/api/session/end cloudshell:StartSession write
delete DELETE /cloudshell/api/environment cloudshell:DeleteEnvironment write

dcloud cloudshell environment get

Your environment: running or not, the home directory, limits, the cost

GET /cloudshell/api/environment — IAM cloudshell:DescribeEnvironment — read

dcloud cloudshell environment get

dcloud cloudshell environment start-session

Open your shell (console sessions only): its terminal address and token

POST /cloudshell/api/session — IAM cloudshell:StartSession — write

dcloud cloudshell environment start-session [flags]
Flag In Required Notes
--terminal body false: only renew the credential in a shell that is already open
  • 202 while it starts (the organization’s first shell waits about 90 s for its sandbox host): call again until 201. Refused with an access key: the shell’s credential is minted from your console session and is deleted when you log out.

dcloud cloudshell environment end-session

End your shell now; the home directory is saved first

POST /cloudshell/api/session/end — IAM cloudshell:StartSession — write

dcloud cloudshell environment end-session
  • Ending your own shell needs no permission.

dcloud cloudshell environment delete

Delete your environment: the shell ends and the saved home is deleted

DELETE /cloudshell/api/environment — IAM cloudshell:DeleteEnvironment — write

dcloud cloudshell environment delete

dcloud cloudshell environments

Everyone’s cloud shell environments (administrators): never opened, only listed and deleted

Operation Method Path IAM action Effect
list GET /cloudshell/api/environments cloudshell:DescribeEnvironment read
delete DELETE /cloudshell/api/environments/{iamUserId} cloudshell:DeleteEnvironment write

dcloud cloudshell environments list

Every environment of the organization: whose, how big, when used

GET /cloudshell/api/environments — IAM cloudshell:DescribeEnvironment — read

dcloud cloudshell environments list

dcloud cloudshell environments delete

Delete someone’s environment (ends their shell, deletes their home)

DELETE /cloudshell/api/environments/{iamUserId} — IAM cloudshell:DeleteEnvironment — write

dcloud cloudshell environments delete <iamUserId>

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<iamUserId> --iam-user-id string uuid

dcloud s3

Object Storage. Base path /s3/api.

dcloud s3 buckets

S3-compatible buckets; objects are reached over the S3 protocol

Operation Method Path IAM action Effect
list GET /s3/api/buckets s3:ListBuckets read
create POST /s3/api/buckets s3:CreateBucket write
get GET /s3/api/buckets/{name} s3:GetBucket read
delete DELETE /s3/api/buckets/{name} s3:DeleteBucket write

dcloud s3 buckets list

List buckets, with the S3 endpoint to point clients at

GET /s3/api/buckets — IAM s3:ListBuckets — read

dcloud s3 buckets list
  • Answers { buckets, endpoint }. Buckets a database created for its backups carry managedBy: "rds".

dcloud s3 buckets create

Create a bucket

POST /s3/api/buckets — IAM s3:CreateBucket — write

dcloud s3 buckets create --name <value> [flags]
Flag In Required Notes
--name <value> body yes 3-63 chars, /^[a-z0-9][a-z0-9-]*[a-z0-9]$/ · Globally unique: 3–63 lowercase letters, digits and hyphens, no dots
--object-lock body Enable object lock, and with it versioning, for good. Only possible at creation
--zone <value> body max 16 chars · Zone the bytes live in, e.g. de1a (Falkenstein) or de1b (Nuremberg); the region default when omitted. Fixed for good
--kms-key-id <value> body KMS key that encrypts the objects (SSE-KMS); the platform key (SSE-S3) when omitted. Needs kms:Encrypt on it
--tags <key=value> body repeatable · key=value · Tags for the new resource, e.g. {"env": "prod", "project": "shop"}. Keys your organization marks required must be present, or the create is refused with the missing keys (GET /tags/api/keys lists them).
  • Bucket names are shared by everyone on the platform: 409 when the name is taken or the organization is at its bucket limit.

dcloud s3 buckets get

One bucket with its path-style and virtual-hosted URLs

GET /s3/api/buckets/{name} — IAM s3:GetBucket — read

dcloud s3 buckets get <name>

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<name> --name string 3-63 chars, /^[a-z0-9][a-z0-9-]*[a-z0-9]$/

dcloud s3 buckets delete

Delete an empty bucket

DELETE /s3/api/buckets/{name} — IAM s3:DeleteBucket — write

dcloud s3 buckets delete <name>

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<name> --name string 3-63 chars, /^[a-z0-9][a-z0-9-]*[a-z0-9]$/
  • Refused (409) while it holds objects or old object versions, and for a bucket a database manages (it goes with the database).

dcloud s3 bucket-objects

The console's object browser: list by folder, presigned download/upload, delete — as the caller, through the S3 gateway

Operation Method Path IAM action Effect
list GET /s3/api/buckets/{name}/objects s3:ListObjects read
download-url POST /s3/api/buckets/{name}/objects/download-url s3:GetObject read, sensitive
upload-url POST /s3/api/buckets/{name}/objects/upload-url s3:PutObject write
multipart-create POST /s3/api/buckets/{name}/objects/multipart s3:PutObject write
multipart-part-urls POST /s3/api/buckets/{name}/objects/multipart/part-urls s3:PutObject write
multipart-parts POST /s3/api/buckets/{name}/objects/multipart/parts s3:PutObject write
multipart-complete POST /s3/api/buckets/{name}/objects/multipart/complete s3:PutObject write
multipart-abort POST /s3/api/buckets/{name}/objects/multipart/abort s3:AbortMultipartUpload write
list-versions GET /s3/api/buckets/{name}/objects/versions s3:ListBucketVersions read
restore-version POST /s3/api/buckets/{name}/objects/restore-version s3:PutObject write
delete-versions POST /s3/api/buckets/{name}/objects/delete-versions s3:DeleteObjectVersion write
delete POST /s3/api/buckets/{name}/objects/delete s3:DeleteObject write
count GET /s3/api/buckets/{name}/objects/count s3:ListBucketVersions read
empty POST /s3/api/buckets/{name}/empty s3:DeleteObjectVersion write
empty-status GET /s3/api/buckets/{name}/empty s3:ListBucketVersions read
empty-cancel POST /s3/api/buckets/{name}/empty/cancel s3:DeleteObjectVersion write
delete-prefix POST /s3/api/buckets/{name}/objects/delete-prefix s3:DeleteObject write

dcloud s3 bucket-objects list

One page (200) of objects and folders under a prefix

GET /s3/api/buckets/{name}/objects — IAM s3:ListObjects — read

dcloud s3 bucket-objects list <name> [flags]

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<name> --name string 3-63 chars, /^[a-z0-9][a-z0-9-]*[a-z0-9]$/
Flag In Required Notes
--prefix <value> query max 1024 chars · The folder to list, e.g. photos/2026/; absent: the top level of the bucket
--continuation-token <value> query max 2048 chars · nextContinuationToken from the previous page; absent: the first page
  • Folders are common prefixes by "/". Pass nextContinuationToken back for the next page. Any S3 client does the same with ListObjectsV2.

dcloud s3 bucket-objects download-url

A presigned GET for one object, valid 15 minutes, saved as a download

POST /s3/api/buckets/{name}/objects/download-url — IAM s3:GetObject — read, sensitive

dcloud s3 bucket-objects download-url <name> --key <value> [flags]

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<name> --name string 3-63 chars, /^[a-z0-9][a-z0-9-]*[a-z0-9]$/
Flag In Required Notes
--key <value> body yes min 1 chars · Key of the object to download
--version-id <value> body 1-1024 chars, /^[A-Za-z0-9._-+=/]+$/ · An older version; absent: the current one

dcloud s3 bucket-objects upload-url

A presigned PUT for one key, valid 15 minutes

POST /s3/api/buckets/{name}/objects/upload-url — IAM s3:PutObject — write

dcloud s3 bucket-objects upload-url <name> --key <value> [flags]

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<name> --name string 3-63 chars, /^[a-z0-9][a-z0-9-]*[a-z0-9]$/
Flag In Required Notes
--key <value> body yes min 1 chars · Key the file is stored under, e.g. photos/2026/cat.jpg
--content-type <value> body max 255 chars · Content-Type the object is stored with; application/octet-stream when omitted
  • Send the file as the body of a PUT to url with the returned headers (Content-Type). The console origin may read the answer from the browser; other origins need the bucket's CORS rules.

dcloud s3 bucket-objects multipart-create

Start a multipart upload (files over 5 GiB must use one)

POST /s3/api/buckets/{name}/objects/multipart — IAM s3:PutObject — write

dcloud s3 bucket-objects multipart-create <name> --key <value> [flags]

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<name> --name string 3-63 chars, /^[a-z0-9][a-z0-9-]*[a-z0-9]$/
Flag In Required Notes
--key <value> body yes min 1 chars · Key the assembled object is stored under
--content-type <value> body max 255 chars · Content-Type the object is stored with; application/octet-stream when omitted
  • Answers { key, uploadId }. Then ask multipart-part-urls for presigned part URLs, PUT each part (5 MiB minimum except the last) and keep the ETag it answers, then multipart-complete. Until completed or aborted, the stored parts count as storage.

dcloud s3 bucket-objects multipart-part-urls

Presigned PUT URLs for up to 100 parts, valid 15 minutes

POST /s3/api/buckets/{name}/objects/multipart/part-urls — IAM s3:PutObject — write

dcloud s3 bucket-objects multipart-part-urls <name> --key <value> --upload-id <value> --part-numbers <value>

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<name> --name string 3-63 chars, /^[a-z0-9][a-z0-9-]*[a-z0-9]$/
Flag In Required Notes
--key <value> body yes min 1 chars · Key the upload was started for
--upload-id <value> body yes 1-1024 chars · From multipart create
--part-numbers <value> body yes repeatable · integer, 1-10000 · Up to 100 part numbers (1–10000)
  • Send each part as the body of a PUT to its url; the answer carries the part’s ETag, which the console origin may read from the browser.

dcloud s3 bucket-objects multipart-parts

The parts of an unfinished upload stored so far, to resume it

POST /s3/api/buckets/{name}/objects/multipart/parts — IAM s3:PutObject — write

dcloud s3 bucket-objects multipart-parts <name> --key <value> --upload-id <value>

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<name> --name string 3-63 chars, /^[a-z0-9][a-z0-9-]*[a-z0-9]$/
Flag In Required Notes
--key <value> body yes min 1 chars · Key the upload was started for
--upload-id <value> body yes 1-1024 chars · From multipart create
  • Answers { parts: [{ partNumber, etag, size }] }, every part (not paged).

dcloud s3 bucket-objects multipart-complete

Assemble the stored parts into the object

POST /s3/api/buckets/{name}/objects/multipart/complete — IAM s3:PutObject — write

dcloud s3 bucket-objects multipart-complete <name> --key <value> --upload-id <value> --parts <value>

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<name> --name string 3-63 chars, /^[a-z0-9][a-z0-9-]*[a-z0-9]$/
Flag In Required Notes
--key <value> body yes min 1 chars · Key the upload was started for
--upload-id <value> body yes 1-1024 chars · From multipart create
--parts <value> body yes repeatable · Every part, in ascending partNumber order, with the ETag its upload answered

dcloud s3 bucket-objects multipart-abort

Abort an unfinished upload; its stored parts are deleted

POST /s3/api/buckets/{name}/objects/multipart/abort — IAM s3:AbortMultipartUpload — write

dcloud s3 bucket-objects multipart-abort <name> --key <value> --upload-id <value>

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<name> --name string 3-63 chars, /^[a-z0-9][a-z0-9-]*[a-z0-9]$/
Flag In Required Notes
--key <value> body yes min 1 chars · Key the upload was started for
--upload-id <value> body yes 1-1024 chars · From multipart create
  • An upload that is gone already counts as aborted.

dcloud s3 bucket-objects list-versions

One page (200) of object versions and delete markers under a prefix

GET /s3/api/buckets/{name}/objects/versions — IAM s3:ListBucketVersions — read

dcloud s3 bucket-objects list-versions <name> [flags]

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<name> --name string 3-63 chars, /^[a-z0-9][a-z0-9-]*[a-z0-9]$/
Flag In Required Notes
--prefix <value> query max 1024 chars · The folder to list, e.g. photos/2026/; absent: the top level of the bucket
--key-marker <value> query max 1024 chars · nextKeyMarker from the previous page; absent: the first page
--version-id-marker <value> query max 1024 chars · nextVersionIdMarker from the previous page, sent together with keyMarker
  • Answers { prefix, prefixes, versions: [{ key, versionId, isLatest, deleteMarker, size, lastModified }], nextKeyMarker, nextVersionIdMarker }, newest first per key. Pass both markers back for the next page.

dcloud s3 bucket-objects restore-version

Make an older version the current one (copied over its key)

POST /s3/api/buckets/{name}/objects/restore-version — IAM s3:PutObject — write

dcloud s3 bucket-objects restore-version <name> --key <value> --version-id <value>

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<name> --name string 3-63 chars, /^[a-z0-9][a-z0-9-]*[a-z0-9]$/
Flag In Required Notes
--key <value> body yes min 1 chars · Key of the object
--version-id <value> body yes 1-1024 chars, /^[A-Za-z0-9._-+=/]+$/ · The older version to make the current one again
  • Also needs s3:GetObjectVersion. The older version stays; the copy is a new latest version. The same as CopyObject with x-amz-copy-source: bucket/key?versionId=….

dcloud s3 bucket-objects delete-versions

Delete up to 1000 versions for good; deleting a delete marker undeletes

POST /s3/api/buckets/{name}/objects/delete-versions — IAM s3:DeleteObjectVersion — write

dcloud s3 bucket-objects delete-versions <name> --versions <value>

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<name> --name string 3-63 chars, /^[a-z0-9][a-z0-9-]*[a-z0-9]$/
Flag In Required Notes
--versions <value> body yes repeatable · The versions to delete for good, as { key, versionId }; the versionId of a delete marker undeletes the key
  • Answers { deleted, errors }, each with key and versionId.

dcloud s3 bucket-objects delete

Delete up to 1000 objects

POST /s3/api/buckets/{name}/objects/delete — IAM s3:DeleteObject — write

dcloud s3 bucket-objects delete <name> --keys <value>

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<name> --name string 3-63 chars, /^[a-z0-9][a-z0-9-]*[a-z0-9]$/
Flag In Required Notes
--keys <value> body yes repeatable · min 1 chars · Keys of the objects to delete; in a versioned bucket each gets a delete marker and its versions stay
  • Answers { deleted, errors }. A key that does not exist counts as deleted, as in S3.

dcloud s3 bucket-objects count

How many objects, older versions and delete markers a folder or the bucket holds

GET /s3/api/buckets/{name}/objects/count — IAM s3:ListBucketVersions — read

dcloud s3 bucket-objects count <name> [flags]

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<name> --name string 3-63 chars, /^[a-z0-9][a-z0-9-]*[a-z0-9]$/
Flag In Required Notes
--prefix <value> query max 1024 chars · A folder ending in /; absent: the whole bucket
  • Answers { prefix, objects, objectBytes, olderVersions, deleteMarkers, totalBytes, complete }. Reads at most 10,000 entries; complete: false means the numbers are a floor.

dcloud s3 bucket-objects empty

Empty the bucket in the background: every object, version and delete marker, for good

POST /s3/api/buckets/{name}/empty — IAM s3:DeleteObjectVersion — write

dcloud s3 bucket-objects empty <name>

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<name> --name string 3-63 chars, /^[a-z0-9][a-z0-9-]*[a-z0-9]$/
  • Answers 202 with the job ({ id, status, total, deleted, failed, errors, remaining, perSecond, … }), or 200 with the one already running. total: what the bucket held when it started (counted first); when it finishes, deleted is total less remaining. Each version is still checked against your policies and the bucket policy; what they keep is counted in failed and stays. Follow it with empty-status; the bucket and its settings stay.

dcloud s3 bucket-objects empty-status

The bucket’s latest empty job and how far it got

GET /s3/api/buckets/{name}/empty — IAM s3:ListBucketVersions — read

dcloud s3 bucket-objects empty-status <name>

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<name> --name string 3-63 chars, /^[a-z0-9][a-z0-9-]*[a-z0-9]$/
  • null when the bucket was never emptied. status: queued, running, done, failed or cancelled; remaining: what the bucket still lists after it finished.

dcloud s3 bucket-objects empty-cancel

Stop emptying the bucket; what was deleted stays deleted

POST /s3/api/buckets/{name}/empty/cancel — IAM s3:DeleteObjectVersion — write

dcloud s3 bucket-objects empty-cancel <name>

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<name> --name string 3-63 chars, /^[a-z0-9][a-z0-9-]*[a-z0-9]$/

dcloud s3 bucket-objects delete-prefix

Delete everything under a folder; with prefix "" and allVersions, empty the bucket

POST /s3/api/buckets/{name}/objects/delete-prefix — IAM s3:DeleteObject — write

dcloud s3 bucket-objects delete-prefix <name> --prefix <value> --all-versions [flags]

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<name> --name string 3-63 chars, /^[a-z0-9][a-z0-9-]*[a-z0-9]$/
Flag In Required Notes
--prefix <value> body yes max 1024 chars · A folder ending in /; "" is the whole bucket
--all-versions body yes true: every version and delete marker, for good (Empty bucket). false: the current objects, as Delete does (a versioned bucket keeps them as old versions)
--cursor <json> body JSON · From the previous answer, when it said done: false
  • allVersions: true needs s3:DeleteObjectVersion and deletes every version and delete marker for good. Each call works ~20 seconds and answers { deleted, failed, errors, done, cursor }; while done is false, call again with cursor. A key your policies keep is reported in errors and stays.

dcloud s3 bucket-access

Who may reach a bucket without a key: Block Public Access, the bucket policy, and the static website

Operation Method Path IAM action Effect
get GET /s3/api/buckets/{name}/public-access s3:GetBucketPolicy read
get-block GET /s3/api/buckets/{name}/public-access-block s3:GetBucketPublicAccessBlock read
get-policy GET /s3/api/buckets/{name}/policy s3:GetBucketPolicy read
get-website GET /s3/api/buckets/{name}/website s3:GetBucketWebsite read
set-block PUT /s3/api/buckets/{name}/public-access-block s3:PutBucketPublicAccessBlock write
set-policy PUT /s3/api/buckets/{name}/policy s3:PutBucketPolicy write
delete-policy DELETE /s3/api/buckets/{name}/policy s3:DeleteBucketPolicy write
set-website PUT /s3/api/buckets/{name}/website s3:PutBucketWebsite write
delete-website DELETE /s3/api/buckets/{name}/website s3:DeleteBucketWebsite write
add-domain POST /s3/api/buckets/{name}/website/domains s3:PutBucketWebsite write
remove-domain DELETE /s3/api/buckets/{name}/website/domains/{domain} s3:DeleteBucketWebsite write

dcloud s3 bucket-access get

Block Public Access flags, the policy, whether the bucket is public, the website

GET /s3/api/buckets/{name}/public-access — IAM s3:GetBucketPolicy — read

dcloud s3 bucket-access get <name>

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<name> --name string 3-63 chars, /^[a-z0-9][a-z0-9-]*[a-z0-9]$/
  • Also needs s3:GetBucketPublicAccessBlock and s3:GetBucketWebsite; get-block, get-policy and get-website each need only their own read. public is true when a policy grants the public and Block Public Access does not stop it.

dcloud s3 bucket-access get-block

The four Block Public Access flags, and whether the bucket is public

GET /s3/api/buckets/{name}/public-access-block — IAM s3:GetBucketPublicAccessBlock — read

dcloud s3 bucket-access get-block <name>

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<name> --name string 3-63 chars, /^[a-z0-9][a-z0-9-]*[a-z0-9]$/

dcloud s3 bucket-access get-policy

The bucket policy (null when there is none)

GET /s3/api/buckets/{name}/policy — IAM s3:GetBucketPolicy — read

dcloud s3 bucket-access get-policy <name>

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<name> --name string 3-63 chars, /^[a-z0-9][a-z0-9-]*[a-z0-9]$/

dcloud s3 bucket-access get-website

The website configuration (null when off), its host and custom domains

GET /s3/api/buckets/{name}/website — IAM s3:GetBucketWebsite — read

dcloud s3 bucket-access get-website <name>

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<name> --name string 3-63 chars, /^[a-z0-9][a-z0-9-]*[a-z0-9]$/

dcloud s3 bucket-access set-block

Set the four Block Public Access flags (all true on a new bucket)

PUT /s3/api/buckets/{name}/public-access-block — IAM s3:PutBucketPublicAccessBlock — write

dcloud s3 bucket-access set-block <name> --block-public-acls --ignore-public-acls --block-public-policy --restrict-public-buckets

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<name> --name string 3-63 chars, /^[a-z0-9][a-z0-9-]*[a-z0-9]$/
Flag In Required Notes
--block-public-acls body yes Refuse public ACLs (Deutsche Cloud has no ACLs; stored for S3 tools)
--ignore-public-acls body yes Ignore public ACLs (Deutsche Cloud has no ACLs; stored for S3 tools)
--block-public-policy body yes Refuse a bucket policy that would make the bucket public
--restrict-public-buckets body yes Ignore the public statements of the bucket policy for anyone outside the organization
  • blockPublicPolicy refuses a policy that would make the bucket public; restrictPublicBuckets makes the public statements of an existing policy have no effect. Turn both off only for a bucket meant for everyone.

dcloud s3 bucket-access set-policy

Set the bucket policy (AWS grammar: the public, organizations, IAM users)

PUT /s3/api/buckets/{name}/policy — IAM s3:PutBucketPolicy — write

dcloud s3 bucket-access set-policy <name> --policy <value>

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<name> --name string 3-63 chars, /^[a-z0-9][a-z0-9-]*[a-z0-9]$/
Flag In Required Notes
--policy <value> body yes 1-20480 chars · The policy document as JSON text, as aws s3api put-bucket-policy takes it
  • Principal "*" (public), or {"EWS": [ | rn:ews:::iam:user/]}; another organization needs its own IAM to allow the action too. Resources as arn:aws:s3:::/… or EWS RNs; s3:ListBucket is accepted for s3:ListObjects. 403 when the policy would make the bucket public while blockPublicPolicy is on; 400 for a principal that does not exist.

dcloud s3 bucket-access delete-policy

Remove the bucket policy

DELETE /s3/api/buckets/{name}/policy — IAM s3:DeleteBucketPolicy — write

dcloud s3 bucket-access delete-policy <name>

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<name> --name string 3-63 chars, /^[a-z0-9][a-z0-9-]*[a-z0-9]$/

dcloud s3 bucket-access set-website

Serve the bucket as a static website on https://.s3-website.

PUT /s3/api/buckets/{name}/website — IAM s3:PutBucketWebsite — write

dcloud s3 bucket-access set-website <name> [flags]

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<name> --name string 3-63 chars, /^[a-z0-9][a-z0-9-]*[a-z0-9]$/
Flag In Required Notes
--index-document <value> body 1-255 chars · Index document suffix, e.g. index.html; required unless redirectAllRequestsTo
--redirect-all-requests-to <json> body JSON · { hostName, protocol? }: send every request, path and query kept, to another host
--routing-rules <value> body repeatable · AWS RoutingRules: [{ condition?: { keyPrefixEquals?, httpErrorCodeReturnedEquals? }, redirect: { hostName?, protocol?, replaceKeyPrefixWith? | replaceKeyWith?, httpRedirectCode? } }]
--error-document <value> body 1-1024 chars · nullable · Key served with 404 for a missing page, e.g. 404.html
  • Only objects the bucket policy makes public are served; anything else answers 403.

dcloud s3 bucket-access delete-website

Stop serving the bucket as a website

DELETE /s3/api/buckets/{name}/website — IAM s3:DeleteBucketWebsite — write

dcloud s3 bucket-access delete-website <name>

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<name> --name string 3-63 chars, /^[a-z0-9][a-z0-9-]*[a-z0-9]$/

dcloud s3 bucket-access add-domain

Answer the website on a domain of your own

POST /s3/api/buckets/{name}/website/domains — IAM s3:PutBucketWebsite — write

dcloud s3 bucket-access add-domain <name> --domain <json>

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<name> --name string 3-63 chars, /^[a-z0-9][a-z0-9-]*[a-z0-9]$/
Flag In Required Notes
--domain <json> body yes JSON · A domain of your own, e.g. www.example.com
  • Returns the CNAME to create. In a zone hosted in Deutsche Cloud DNS an ALIAS record is written instead (aliasRecordCreated: true). The certificate is issued on the first HTTPS visit.

dcloud s3 bucket-access remove-domain

Remove a custom domain from the website

DELETE /s3/api/buckets/{name}/website/domains/{domain} — IAM s3:DeleteBucketWebsite — write

dcloud s3 bucket-access remove-domain <name> <domain>

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<name> --name string 3-63 chars, /^[a-z0-9][a-z0-9-]*[a-z0-9]$/
<domain> --domain string

dcloud s3 bucket-encryption

Default encryption: every object is encrypted at rest under the bucket’s key, wrapped by the platform key or a KMS key of yours

Operation Method Path IAM action Effect
get GET /s3/api/buckets/{name}/encryption s3:GetEncryptionConfiguration read
set PUT /s3/api/buckets/{name}/encryption s3:PutEncryptionConfiguration write
delete DELETE /s3/api/buckets/{name}/encryption s3:PutEncryptionConfiguration write

dcloud s3 bucket-encryption get

Which key encrypts the bucket’s objects, and whether it is usable now

GET /s3/api/buckets/{name}/encryption — IAM s3:GetEncryptionConfiguration — read

dcloud s3 bucket-encryption get <name>

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<name> --name string 3-63 chars, /^[a-z0-9][a-z0-9-]*[a-z0-9]$/
  • Answers { algorithm: AES256 | aws:kms, kmsKeyId, active, usable, problem }, or { managed: true } for a bucket the platform writes.

dcloud s3 bucket-encryption set

Move the bucket to a KMS key, or back to the platform key

PUT /s3/api/buckets/{name}/encryption — IAM s3:PutEncryptionConfiguration — write

dcloud s3 bucket-encryption set <name> --kms-key-id <value>

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<name> --name string 3-63 chars, /^[a-z0-9][a-z0-9-]*[a-z0-9]$/
Flag In Required Notes
--kms-key-id <value> body yes nullable · A KMS key of the organization (SSE-KMS), or null for the platform key (SSE-S3)
  • Re-wraps the bucket’s one data key: every object, old and new, follows the new key at once. Disabling or deleting that KMS key makes the objects unreadable until it is enabled again (deleted: for good). Needs kms:Encrypt on the key. Also over S3: PutBucketEncryption.

dcloud s3 bucket-encryption delete

Return the bucket to the platform key (encryption itself stays on)

DELETE /s3/api/buckets/{name}/encryption — IAM s3:PutEncryptionConfiguration — write

dcloud s3 bucket-encryption delete <name>

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<name> --name string 3-63 chars, /^[a-z0-9][a-z0-9-]*[a-z0-9]$/

dcloud s3 bucket-remote-copy

A copy of every object of a bucket on a storage cluster in another location, read while the cluster is unavailable

Operation Method Path IAM action Effect
get GET /s3/api/buckets/{name}/remote-copy s3:GetBucketRemoteCopy read
set PUT /s3/api/buckets/{name}/remote-copy s3:PutBucketRemoteCopy write

dcloud s3 bucket-remote-copy get

Whether the bucket keeps a remote copy, where, and how many keys still wait

GET /s3/api/buckets/{name}/remote-copy — IAM s3:GetBucketRemoteCopy — read

dcloud s3 bucket-remote-copy get <name>

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<name> --name string 3-63 chars, /^[a-z0-9][a-z0-9-]*[a-z0-9]$/
  • Answers { enabled, available, zone, pendingKeys, failedKeys, note }. available is false for a bucket whose storage keeps no copy elsewhere (platform buckets, own hosts).

dcloud s3 bucket-remote-copy set

Turn the remote copy on (every existing object is copied too) or off

PUT /s3/api/buckets/{name}/remote-copy — IAM s3:PutBucketRemoteCopy — write

dcloud s3 bucket-remote-copy set <name> --enabled

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<name> --name string 3-63 chars, /^[a-z0-9][a-z0-9-]*[a-z0-9]$/
Flag In Required Notes
--enabled body yes true: keep a copy of every object in the storage cluster’s other location; false: stop keeping one
  • On by default for new buckets on a storage cluster. While the cluster is unavailable, objects are read from the copy; an object not copied yet, listings and writes answer 503 until it is back (never 404). Off: the copy is deleted after 7 days, and an outage of the cluster makes the bucket answer 503.

dcloud s3 bucket-replication

Cross-zone replication (S3 CRR): copy a bucket’s objects to another bucket of the organization, in either zone

Operation Method Path IAM action Effect
get GET /s3/api/buckets/{name}/replication s3:GetReplicationConfiguration read
set PUT /s3/api/buckets/{name}/replication s3:PutReplicationConfiguration write
delete DELETE /s3/api/buckets/{name}/replication s3:DeleteReplicationConfiguration write
retry POST /s3/api/buckets/{name}/replication/retry s3:PutReplicationConfiguration write

dcloud s3 bucket-replication get

The replication rules, and how many keys are pending or failed

GET /s3/api/buckets/{name}/replication — IAM s3:GetReplicationConfiguration — read

dcloud s3 bucket-replication get <name>

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<name> --name string 3-63 chars, /^[a-z0-9][a-z0-9-]*[a-z0-9]$/
  • Answers { zone, rules, pending, failed, oldestPendingAt, lastFullScanAt, recentFailures }.

dcloud s3 bucket-replication set

Replace the replication rules

PUT /s3/api/buckets/{name}/replication — IAM s3:PutReplicationConfiguration — write

dcloud s3 bucket-replication set <name> --rules <value> [flags]

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<name> --name string 3-63 chars, /^[a-z0-9][a-z0-9-]*[a-z0-9]$/
Flag In Required Notes
--role <value> body max 2048 chars · nullable · An IAM role ARN as AWS tools send it; kept for S3 GetBucketReplication, otherwise ignored
--rules <value> body yes repeatable · The rules, replacing the current ones; each names a destination bucket (name, arn:aws:s3:::name or its RN)
  • rules: [{ destination, prefix?, deleteMarkerReplication? (false), existingObjects? (true), enabled?, priority?, id? }]. Both buckets need versioning Enabled; the caller also needs s3:PutObject on the destination. Two-way replication is refused. Copies start within seconds of a write; every bucket is also compared in full hourly.

dcloud s3 bucket-replication delete

Stop replicating (replicas already made are kept)

DELETE /s3/api/buckets/{name}/replication — IAM s3:DeleteReplicationConfiguration — write

dcloud s3 bucket-replication delete <name>

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<name> --name string 3-63 chars, /^[a-z0-9][a-z0-9-]*[a-z0-9]$/

dcloud s3 bucket-replication retry

Give keys whose copy failed new attempts

POST /s3/api/buckets/{name}/replication/retry — IAM s3:PutReplicationConfiguration — write

dcloud s3 bucket-replication retry <name>

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<name> --name string 3-63 chars, /^[a-z0-9][a-z0-9-]*[a-z0-9]$/

dcloud s3 bucket-versioning

Keep every version of every object

Operation Method Path IAM action Effect
get GET /s3/api/buckets/{name}/versioning s3:GetBucketVersioning read
set PUT /s3/api/buckets/{name}/versioning s3:PutBucketVersioning write

dcloud s3 bucket-versioning get

Versioning status: Enabled, Suspended or Off

GET /s3/api/buckets/{name}/versioning — IAM s3:GetBucketVersioning — read

dcloud s3 bucket-versioning get <name>

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<name> --name string 3-63 chars, /^[a-z0-9][a-z0-9-]*[a-z0-9]$/

dcloud s3 bucket-versioning set

Enable or suspend versioning (it can never be removed)

PUT /s3/api/buckets/{name}/versioning — IAM s3:PutBucketVersioning — write

dcloud s3 bucket-versioning set <name> --enabled

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<name> --name string 3-63 chars, /^[a-z0-9][a-z0-9-]*[a-z0-9]$/
Flag In Required Notes
--enabled body yes true: Enabled; false: Suspended

dcloud s3 bucket-cors

Which web pages may call the bucket from a browser (CORS)

Operation Method Path IAM action Effect
get GET /s3/api/buckets/{name}/cors s3:GetBucketCORS read
set PUT /s3/api/buckets/{name}/cors s3:PutBucketCORS write
delete DELETE /s3/api/buckets/{name}/cors s3:PutBucketCORS write

dcloud s3 bucket-cors get

The bucket’s CORS rules; null when it has none

GET /s3/api/buckets/{name}/cors — IAM s3:GetBucketCORS — read

dcloud s3 bucket-cors get <name>

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<name> --name string 3-63 chars, /^[a-z0-9][a-z0-9-]*[a-z0-9]$/

dcloud s3 bucket-cors set

Replace the bucket’s CORS rules

PUT /s3/api/buckets/{name}/cors — IAM s3:PutBucketCORS — write

dcloud s3 bucket-cors set <name> --rules <value>

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<name> --name string 3-63 chars, /^[a-z0-9][a-z0-9-]*[a-z0-9]$/
Flag In Required Notes
--rules <value> body yes repeatable · The rules, replacing the current ones: { allowedOrigins, allowedMethods, allowedHeaders?, exposeHeaders?, maxAgeSeconds?, id? }; the first rule that matches a request applies

dcloud s3 bucket-cors delete

Remove every CORS rule: browsers on other sites can no longer call the bucket

DELETE /s3/api/buckets/{name}/cors — IAM s3:PutBucketCORS — write

dcloud s3 bucket-cors delete <name>

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<name> --name string 3-63 chars, /^[a-z0-9][a-z0-9-]*[a-z0-9]$/

dcloud s3 bucket-lifecycle

Expire objects, old versions and unfinished uploads by age

Operation Method Path IAM action Effect
get GET /s3/api/buckets/{name}/lifecycle s3:GetLifecycleConfiguration read
set PUT /s3/api/buckets/{name}/lifecycle s3:PutLifecycleConfiguration write
delete DELETE /s3/api/buckets/{name}/lifecycle s3:PutLifecycleConfiguration write

dcloud s3 bucket-lifecycle get

The lifecycle rules

GET /s3/api/buckets/{name}/lifecycle — IAM s3:GetLifecycleConfiguration — read

dcloud s3 bucket-lifecycle get <name>

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<name> --name string 3-63 chars, /^[a-z0-9][a-z0-9-]*[a-z0-9]$/

dcloud s3 bucket-lifecycle set

Replace the lifecycle rules

PUT /s3/api/buckets/{name}/lifecycle — IAM s3:PutLifecycleConfiguration — write

dcloud s3 bucket-lifecycle set <name> --rules <value>

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<name> --name string 3-63 chars, /^[a-z0-9][a-z0-9-]*[a-z0-9]$/
Flag In Required Notes
--rules <value> body yes repeatable · The rules, replacing the current ones; each has its own id and at least one action (expirationDays, noncurrentVersionExpirationDays, abortIncompleteMultipartUploadDays or expiredObjectDeleteMarker)
  • rules: [{ id, prefix?, enabled?, expirationDays?, noncurrentVersionExpirationDays?, abortIncompleteMultipartUploadDays?, expiredObjectDeleteMarker? }]. Applied by object storage once a day.

dcloud s3 bucket-lifecycle delete

Remove every lifecycle rule

DELETE /s3/api/buckets/{name}/lifecycle — IAM s3:PutLifecycleConfiguration — write

dcloud s3 bucket-lifecycle delete <name>

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<name> --name string 3-63 chars, /^[a-z0-9][a-z0-9-]*[a-z0-9]$/

dcloud s3 access-keys

S3 access keys; each acts with the permissions of the IAM user who created it

Operation Method Path IAM action Effect
list GET /s3/api/access-keys s3:ListAccessKeys read
create POST /s3/api/access-keys s3:CreateAccessKey write
delete DELETE /s3/api/access-keys/{id} s3:DeleteAccessKey write

dcloud s3 access-keys list

List S3 access keys (ids and status, never secrets)

GET /s3/api/access-keys — IAM s3:ListAccessKeys — read

dcloud s3 access-keys list

dcloud s3 access-keys create

Create an S3 access key

POST /s3/api/access-keys — IAM s3:CreateAccessKey — write

dcloud s3 access-keys create [flags]
Flag In Required Notes
--description <value> body max 200 chars · What the key is for
  • The secretAccessKey is in this response and nowhere else; store it now. The key acts as the calling IAM user.

dcloud s3 access-keys delete

Delete an S3 access key

DELETE /s3/api/access-keys/{id} — IAM s3:DeleteAccessKey — write

dcloud s3 access-keys delete <id>

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<id> --id string uuid

dcloud s3 temporary-credentials

Short-lived S3 credentials with a session token; they act with the caller’s permissions and expire on their own

Operation Method Path IAM action Effect
create POST /s3/api/temporary-credentials s3:CreateTemporaryCredentials write

dcloud s3 temporary-credentials create

Create temporary S3 credentials (15 minutes to 12 hours, default 1 hour)

POST /s3/api/temporary-credentials — IAM s3:CreateTemporaryCredentials — write

dcloud s3 temporary-credentials create [flags]
Flag In Required Notes
--duration-seconds <number> body integer, 900-43200 · Lifetime in seconds, 900–43200 (default 3600)
--description <value> body max 200 chars · What the credentials are for
  • Returns accessKeyId, secretAccessKey, sessionToken and expiresAt once. Every S3 request must carry the token as a signed x-amz-security-token (AWS_SESSION_TOKEN in the AWS CLI and SDKs). They are never listed and cannot be revoked; they expire.

dcloud git

Git. Base path /git/api.

dcloud git repositories

Repositories served by the platform itself

Operation Method Path IAM action Effect
list GET /git/api/repositories git:ListRepositories read
create POST /git/api/repositories git:CreateRepository write
import POST /git/api/repositories/import git:CreateRepository write
fork POST /git/api/repositories/{repoId}/fork git:CreateRepository write
sync-fork POST /git/api/repositories/{repoId}/sync-fork git:PushRepository write
get-import GET /git/api/repositories/{repoId}/import git:GetRepository read
retry-import POST /git/api/repositories/{repoId}/import/retry git:UpdateRepository write
sync-mirror POST /git/api/repositories/{repoId}/mirror/sync git:UpdateRepository write
get-mirror-status GET /git/api/repositories/{repoId}/mirror git:GetRepository read
update-mirror PATCH /git/api/repositories/{repoId}/mirror git:UpdateRepository write
run-shadow-ci POST /git/api/repositories/{repoId}/mirror/shadow-run ci:StartWorkflow write
list-shadow-comparisons GET /git/api/repositories/{repoId}/shadow-comparisons ci:ListRuns read
get-shadow-comparison GET /git/api/repositories/{repoId}/shadow-comparisons/{sha} ci:ListRuns read
stop-mirror DELETE /git/api/repositories/{repoId}/mirror git:StopMirroring write
set-push-mirror PUT /git/api/repositories/{repoId}/push-mirror git:ConfigurePushMirror write
sync-push-mirror POST /git/api/repositories/{repoId}/push-mirror/sync git:ConfigurePushMirror write
remove-push-mirror DELETE /git/api/repositories/{repoId}/push-mirror git:ConfigurePushMirror write
get GET /git/api/repositories/{repoId} git:GetRepository read
update PATCH /git/api/repositories/{repoId} git:UpdateRepository write
delete DELETE /git/api/repositories/{repoId} git:DeleteRepository write

dcloud git repositories list

List repositories

GET /git/api/repositories — IAM git:ListRepositories — read

dcloud git repositories list

dcloud git repositories create

Create a repository

POST /git/api/repositories — IAM git:CreateRepository — write

dcloud git repositories create --name <value> [flags]
Flag In Required Notes
--name <value> body yes 1-100 chars, /^[A-Za-z0-9][A-Za-z0-9._-]*$/ · Unique within the organization; part of the clone URL
--description <value> body max 500 chars · One line about the repository; the template's description when absent
--visibility <private|internal|public> body Who can see it; private when absent. public also needs git:PublishRepository
--default-branch <value> body 1-100 chars · The branch clones check out and pull requests target by default; main when absent
--tags <key=value> body repeatable · key=value · Tags for the new resource, e.g. {"env": "prod", "project": "shop"}. Keys your organization marks required must be present, or the create is refused with the missing keys (GET /tags/api/keys lists them).
--template <json> body JSON · Start from a template: one commit with its files, no history (CI runs on it)

dcloud git repositories import

Import a repository from GitHub, GitLab or a git URL, optionally as a mirror

POST /git/api/repositories/import — IAM git:CreateRepository — write

dcloud git repositories import --name <value> --source <json> [flags]
Flag In Required Notes
--name <value> body yes 1-100 chars, /^[A-Za-z0-9][A-Za-z0-9._-]*$/ · Unique within the organization; part of the clone URL
--description <value> body max 500 chars · One line about the repository, shown in lists and the About column
--visibility <private|public> body Who can see it; private when absent. public also needs git:PublishRepository
--source <json> body yes JSON · Where to import from: its URL and, optionally, the provider
--token <value> body 1-500 chars · GitHub/GitLab token for a private source or a higher API limit; kept (sealed) only for a mirror
--include <json> body JSON · What comes over besides the git history: pull requests and the wiki (both by default)
--mirror <json> body JSON · Keep following the source; pushes are refused while it mirrors
--tags <key=value> body repeatable · key=value · Tags for the new resource, e.g. {"env": "prod", "project": "shop"}. Keys your organization marks required must be present, or the create is refused with the missing keys (GET /tags/api/keys lists them).
  • Answers 202 with the new repository; importState.status goes queued → running → succeeded/failed, with counts of branches, tags and pull requests. History, branches, tags, pull requests (as pull requests here, original author and link in the body) and the wiki (as {name}.wiki) come over; issues and releases are not carried over. The fetch runs on the server, so there is no 2 GiB push limit.

dcloud git repositories fork

Fork a repository of the organization

POST /git/api/repositories/{repoId}/fork — IAM git:CreateRepository — write

dcloud git repositories fork <repoId> --name <value> [flags]

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<repoId> --repo-id string uuid
Flag In Required Notes
--name <value> body yes 1-100 chars, /^[A-Za-z0-9][A-Za-z0-9._-]*$/ · The new repository, in the same organization
--description <value> body max 500 chars · One line about the fork; the parent's description when absent
--tags <key=value> body repeatable · key=value · Tags for the new resource, e.g. {"env": "prod", "project": "shop"}. Keys your organization marks required must be present, or the create is refused with the missing keys (GET /tags/api/keys lists them).
  • Also checks git:PullRepository. Failing it degrades the response rather than rejecting the call.
  • Answers 202 with the new repository (private, forkedFromRepoId set); every branch and tag is copied by a job, whose progress is importState. Needs git:PullRepository on the parent.

dcloud git repositories sync-fork

Fast-forward a fork's branch to its parent's

POST /git/api/repositories/{repoId}/sync-fork — IAM git:PushRepository — write

dcloud git repositories sync-fork <repoId> [flags]

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<repoId> --repo-id string uuid
Flag In Required Notes
--branch <value> body 1-255 chars · The branch to bring up to the parent's branch of the same name; the default branch when absent
  • Only a fast-forward: a branch with commits of its own is refused (409), nothing is overwritten. Goes through branch protection, CI and webhooks like a push.

dcloud git repositories get-import

How far an import has come: phase, branches, tags and pull requests so far, started and finished, or why it failed

GET /git/api/repositories/{repoId}/import — IAM git:GetRepository — read

dcloud git repositories get-import <repoId>

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<repoId> --repo-id string uuid

dcloud git repositories retry-import

Start a failed import again from the same source

POST /git/api/repositories/{repoId}/import/retry — IAM git:UpdateRepository — write

dcloud git repositories retry-import <repoId> [flags]

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<repoId> --repo-id string uuid
Flag In Required Notes
--token <value> body 1-1000 chars · A token for a private source; a mirror reuses the one it keeps
  • Answers 202. A mirror reuses the token it keeps; a private source needs token.

dcloud git repositories sync-mirror

Fetch a mirror from its source now

POST /git/api/repositories/{repoId}/mirror/sync — IAM git:UpdateRepository — write

dcloud git repositories sync-mirror <repoId>

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<repoId> --repo-id string uuid

dcloud git repositories get-mirror-status

A mirror's last day (syncs, failures, lag), recent syncs and failures

GET /git/api/repositories/{repoId}/mirror — IAM git:GetRepository — read

dcloud git repositories get-mirror-status <repoId>

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<repoId> --repo-id string uuid

dcloud git repositories update-mirror

Change a mirror's interval, the minute poll, or shadow CI

PATCH /git/api/repositories/{repoId}/mirror — IAM git:UpdateRepository — write

dcloud git repositories update-mirror <repoId> [flags]

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<repoId> --repo-id string uuid
Flag In Required Notes
--interval-minutes <number> body integer, 5-1440 · Minutes between full fetches
--continuous body Check the source every minute (git ls-remote) and fetch when a ref moved
--shadow-ci <json> body JSON · Run the source workflows here on mirrored pushes to compare: no secrets, no deploy or publish jobs

dcloud git repositories run-shadow-ci

Run a shadowed mirror's workflows on a branch's current head now (default: the default branch)

POST /git/api/repositories/{repoId}/mirror/shadow-run — IAM ci:StartWorkflow — write

dcloud git repositories run-shadow-ci <repoId> [flags]

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<repoId> --repo-id string uuid
Flag In Required Notes
--branch <value> body 1-255 chars · Default: the default branch

dcloud git repositories list-shadow-comparisons

A shadowed mirror's newest commits: the source's CI and ours side by side, in counts

GET /git/api/repositories/{repoId}/shadow-comparisons — IAM ci:ListRuns — read

dcloud git repositories list-shadow-comparisons <repoId>

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<repoId> --repo-id string uuid

dcloud git repositories get-shadow-comparison

One commit: every workflow and job, the source's result and ours, and the verdict

GET /git/api/repositories/{repoId}/shadow-comparisons/{sha} — IAM ci:ListRuns — read

dcloud git repositories get-shadow-comparison <repoId> <sha>

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<repoId> --repo-id string uuid
<sha> --sha string /^[0-9a-f]{40}$/

dcloud git repositories stop-mirror

Stop mirroring: syncing ends and pushes become possible; history, branches, tags and pull requests stay

DELETE /git/api/repositories/{repoId}/mirror — IAM git:StopMirroring — write

dcloud git repositories stop-mirror <repoId>

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<repoId> --repo-id string uuid

dcloud git repositories set-push-mirror

Copy every push to a remote outside Deutsche Cloud (branches and tags)

PUT /git/api/repositories/{repoId}/push-mirror — IAM git:ConfigurePushMirror — write

dcloud git repositories set-push-mirror <repoId> --url <value> --token <value>

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<repoId> --repo-id string uuid
Flag In Required Notes
--url <value> body yes 1-500 chars · https URL of the remote repository, without credentials (https://github.com/acme/app.git)
--token <value> body yes 1-500 chars · A token allowed to push there (GitHub: fine-grained, Contents: write); stored sealed, never shown
  • Fast-forward only and nothing is deleted on the remote: a branch that moved there on its own is listed in pushMirror.rejectedRefs with lastStatus: failed instead of being overwritten. Pushes once at once, then after every push, merge or console edit. The token is never returned.

dcloud git repositories sync-push-mirror

Push to the push mirror now

POST /git/api/repositories/{repoId}/push-mirror/sync — IAM git:ConfigurePushMirror — write

dcloud git repositories sync-push-mirror <repoId>

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<repoId> --repo-id string uuid

dcloud git repositories remove-push-mirror

Stop copying pushes to the remote; it keeps what it has

DELETE /git/api/repositories/{repoId}/push-mirror — IAM git:ConfigurePushMirror — write

dcloud git repositories remove-push-mirror <repoId>

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<repoId> --repo-id string uuid

dcloud git repositories get

Describe one repository

GET /git/api/repositories/{repoId} — IAM git:GetRepository — read

dcloud git repositories get <repoId>

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<repoId> --repo-id string uuid

dcloud git repositories update

Change description, visibility, default branch or archive state

PATCH /git/api/repositories/{repoId} — IAM git:UpdateRepository — write

dcloud git repositories update <repoId> [flags]

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<repoId> --repo-id string uuid
Flag In Required Notes
--description <value> body max 500 chars · One line about the repository, shown in lists and the About column
--homepage <value> body url, max 300 chars · nullable · The About link (http or https); null removes it
--topics <value> body repeatable · /^[a-z0-9][a-z0-9-]{0,49}$/ · Topics: lowercase letters, digits and hyphens, at most 20
--visibility <private|internal|public> body Who can see it; making it public also needs git:PublishRepository
--default-branch <value> body 1-100 chars · The branch clones check out and pull requests target by default
--is-archived body true archives it (read-only: pushes, merges and edits refused); false unarchives
--allow-merge-commit body Pull requests may merge with a merge commit
--allow-squash-merge body Pull requests may be squash-merged
--allow-rebase-merge body Pull requests may be rebase-merged
--delete-branch-on-merge body Delete the source branch when a pull request is merged
--default-workflow-permissions <restricted|permissive> body What a workflow job's GITHUB_TOKEN may do when its file sets no permissions:: restricted (contents and packages read; new repositories) or permissive (read and write)

dcloud git repositories delete

Delete a repository

DELETE /git/api/repositories/{repoId} — IAM git:DeleteRepository — write

dcloud git repositories delete <repoId>

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<repoId> --repo-id string uuid

dcloud git branches

Refs, and the console-side equivalent of pushing to them

Operation Method Path IAM action Effect
list GET /git/api/repositories/{repoId}/branches git:GetRepository read
create POST /git/api/repositories/{repoId}/branches git:PushRepository write
delete DELETE /git/api/repositories/{repoId}/branches/{name} git:PushRepository write
update-from POST /git/api/repositories/{repoId}/update-branch git:PushRepository write

dcloud git branches list

List branches

GET /git/api/repositories/{repoId}/branches — IAM git:GetRepository — read

dcloud git branches list <repoId>

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<repoId> --repo-id string uuid

dcloud git branches create

Create a branch from a ref

POST /git/api/repositories/{repoId}/branches — IAM git:PushRepository — write

dcloud git branches create <repoId> --name <value> --from <value>

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<repoId> --repo-id string uuid
Flag In Required Notes
--name <value> body yes 1-255 chars · The new branch
--from <value> body yes 1-255 chars · The branch, tag or commit id it starts at
  • Writing through the console is the same act as pushing, so every write route needs git:PushRepository.

dcloud git branches delete

Delete a branch

DELETE /git/api/repositories/{repoId}/branches/{name} — IAM git:PushRepository — write

dcloud git branches delete <repoId> <name>

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<repoId> --repo-id string uuid
<name> --name string 1-255 chars
  • The route matches this segment as :name{.+} so branch names containing slashes survive; the value is URL-encoded on the wire.

dcloud git branches update-from

Bring a branch up to date with its target

POST /git/api/repositories/{repoId}/update-branch — IAM git:PushRepository — write

dcloud git branches update-from <repoId> --branch <value> --target <value>

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<repoId> --repo-id string uuid
Flag In Required Notes
--branch <value> body yes 1-255 chars · The branch to bring up to date; it gets a merge commit
--target <value> body yes 1-255 chars · The branch merged into it, usually the pull request target

dcloud git tags

Tag refs

Operation Method Path IAM action Effect
list GET /git/api/repositories/{repoId}/tags git:GetRepository read
delete DELETE /git/api/repositories/{repoId}/tags/{name} git:PushRepository write

dcloud git tags list

List tags

GET /git/api/repositories/{repoId}/tags — IAM git:GetRepository — read

dcloud git tags list <repoId>

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<repoId> --repo-id string uuid

dcloud git tags delete

Delete a tag

DELETE /git/api/repositories/{repoId}/tags/{name} — IAM git:PushRepository — write

dcloud git tags delete <repoId> <name>

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<repoId> --repo-id string uuid
<name> --name string 1-255 chars
  • The console side of git push --delete origin <tag>, so it needs what a push needs. The route matches this segment as :name{.+} so tag names containing slashes survive; the value is URL-encoded on the wire. The commit the tag named is not deleted.

dcloud git commits

History, individual commits, and console-made commits

Operation Method Path IAM action Effect
list GET /git/api/repositories/{repoId}/commits git:GetRepository read
get GET /git/api/repositories/{repoId}/commits/{sha} git:PullRepository read, sensitive
create POST /git/api/repositories/{repoId}/commits git:PushRepository write
compare GET /git/api/repositories/{repoId}/compare git:PullRepository read, sensitive

dcloud git commits list

List commits on a ref

GET /git/api/repositories/{repoId}/commits — IAM git:GetRepository — read

dcloud git commits list <repoId> [flags]

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<repoId> --repo-id string uuid
Flag In Required Notes
--ref <value> query 1-255 chars · Branch, tag or commit id whose history to list; the default branch when absent
--path <value> query max 1000 chars · Only commits that changed this file or directory
--limit <number> query integer, 1-200 · How many commits to return, newest first; 50 when absent
--skip <number> query integer, min 0 · How many of the newest commits to skip, for paging; 0 when absent
  • Metadata only, which is why this needs GetRepository rather than PullRepository.

dcloud git commits get

Show one commit with its patch

GET /git/api/repositories/{repoId}/commits/{sha} — IAM git:PullRepository — read, sensitive

dcloud git commits get <repoId> <sha>

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<repoId> --repo-id string uuid
<sha> --sha string 1-255 chars
  • Sensitive read — a patch is source code.

dcloud git commits create

Commit file edits to a branch

POST /git/api/repositories/{repoId}/commits — IAM git:PushRepository — write

dcloud git commits create <repoId> --branch <value> --message <value> --changes <value> [flags]

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<repoId> --repo-id string uuid
Flag In Required Notes
--branch <value> body yes 1-255 chars · The branch to commit to; it must exist, except the default branch of an empty repository
--message <value> body yes 1-2000 chars · The commit message
--expected-oid <value> body /^[0-9a-f]{40}$/ · Refuse (409) unless the branch is still at this commit, so an edit cannot overwrite a push
--changes <value> body yes repeatable · The file changes, applied in order: upsert writes content (the whole file, UTF-8) to path, delete removes path

dcloud git commits compare

Diff two refs

GET /git/api/repositories/{repoId}/compare — IAM git:PullRepository — read, sensitive

dcloud git commits compare <repoId> --base <value> --head <value>

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<repoId> --repo-id string uuid
Flag In Required Notes
--base <value> query yes 1-255 chars · The ref the change is measured against, e.g. the target branch
--head <value> query yes 1-255 chars · The ref with the changes; the diff is what it adds since its merge base

dcloud git files

Reading the working tree at a ref

Operation Method Path IAM action Effect
tree GET /git/api/repositories/{repoId}/tree git:GetRepository read
blob GET /git/api/repositories/{repoId}/blob git:PullRepository read, sensitive
insights GET /git/api/repositories/{repoId}/insights git:GetRepository read
blame GET /git/api/repositories/{repoId}/blame git:PullRepository read, sensitive
highlighted GET /git/api/repositories/{repoId}/highlighted git:PullRepository read, sensitive
raw GET /git/api/repositories/{repoId}/raw git:PullRepository read, sensitive
archive GET /git/api/repositories/{repoId}/archive git:PullRepository read, sensitive

dcloud git files tree

List entries under a path

GET /git/api/repositories/{repoId}/tree — IAM git:GetRepository — read

dcloud git files tree <repoId> [flags]

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<repoId> --repo-id string uuid
Flag In Required Notes
--ref <value> query 1-255 chars · Branch, tag or commit id; the default branch when absent
--path <value> query max 1000 chars · The directory to list, from the repository root; the root when absent
  • File names are metadata; file contents are not — see blob.

dcloud git files blob

Read one file as raw text

GET /git/api/repositories/{repoId}/blob — IAM git:PullRepository — read, sensitive

dcloud git files blob <repoId> --path <value> [flags]

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<repoId> --repo-id string uuid
Flag In Required Notes
--ref <value> query 1-255 chars · Branch, tag or commit id; the default branch when absent
--path <value> query yes 1-1000 chars · The file's path from the repository root, e.g. src/index.ts

dcloud git files insights

Commits per week, contributors and pull request activity

GET /git/api/repositories/{repoId}/insights — IAM git:GetRepository — read

dcloud git files insights <repoId>

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<repoId> --repo-id string uuid
  • On the default branch over the last 52 weeks: weeks (weekStart Monday UTC, commits), contributors (name, email, commits) and commitsInYear; pullRequests counts opened, merged and closed in the last 30 days and open now.

dcloud git files blame

Which commit last changed each line of a file

GET /git/api/repositories/{repoId}/blame — IAM git:PullRepository — read, sensitive

dcloud git files blame <repoId> --path <value> [flags]

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<repoId> --repo-id string uuid
Flag In Required Notes
--ref <value> query 1-255 chars · Branch, tag or commit id; the default branch when absent
--path <value> query yes 1-1000 chars · The file's path from the repository root, e.g. src/index.ts
  • Hunks of consecutive lines from one commit: the commit (oid, summary, author, authorTime in seconds), the first line number and the lines.

dcloud git files highlighted

One file as lines with syntax highlighting

GET /git/api/repositories/{repoId}/highlighted — IAM git:PullRepository — read, sensitive

dcloud git files highlighted <repoId> --path <value> [flags]

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<repoId> --repo-id string uuid
Flag In Required Notes
--ref <value> query 1-255 chars · Branch, tag or commit id; the default branch when absent
--path <value> query yes 1-1000 chars · The file's path from the repository root, e.g. src/index.ts
  • lines is the text split into lines; html one highlighted HTML fragment per line (both themes as CSS variables), or null when the file is over 512 KiB or has no known language.

dcloud git files raw

Serve one file verbatim

GET /git/api/repositories/{repoId}/raw — IAM git:PullRepository — read, sensitive

dcloud git files raw <repoId> --path <value> [flags]

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<repoId> --repo-id string uuid
Flag In Required Notes
--ref <value> query 1-255 chars · Branch, tag or commit id; the default branch when absent
--path <value> query yes 1-1000 chars · The file's path from the repository root, e.g. src/index.ts
--download <0|1> query 1 answers it as an attachment to save; otherwise it is served inline
  • Returns raw bytes with their own content type, written straight to stdout.

dcloud git files archive

Download the tree at a ref as an archive

GET /git/api/repositories/{repoId}/archive — IAM git:PullRepository — read, sensitive

dcloud git files archive <repoId> --ref <value> [flags]

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<repoId> --repo-id string uuid
Flag In Required Notes
--ref <value> query yes 1-255 chars · The branch, tag or commit id whose files to pack
--format <zip|tar.gz> query The archive format; zip when absent
  • Returns raw bytes with their own content type, written straight to stdout.

dcloud git pulls

Pull requests, backed by real merges

Operation Method Path IAM action Effect
list GET /git/api/repositories/{repoId}/pulls git:ListPullRequests read
create POST /git/api/repositories/{repoId}/pulls git:CreatePullRequest write
get GET /git/api/repositories/{repoId}/pulls/{prNumber} git:GetPullRequest read
update PATCH /git/api/repositories/{repoId}/pulls/{prNumber} git:UpdatePullRequest write
merge POST /git/api/repositories/{repoId}/pulls/{prNumber}/merge git:MergePullRequest write
enable-auto-merge PUT /git/api/repositories/{repoId}/pulls/{prNumber}/auto-merge git:MergePullRequest write
disable-auto-merge DELETE /git/api/repositories/{repoId}/pulls/{prNumber}/auto-merge git:MergePullRequest write
close POST /git/api/repositories/{repoId}/pulls/{prNumber}/close git:ClosePullRequest write
reopen POST /git/api/repositories/{repoId}/pulls/{prNumber}/reopen git:ClosePullRequest write
ready POST /git/api/repositories/{repoId}/pulls/{prNumber}/ready git:UpdatePullRequest write
convert-to-draft POST /git/api/repositories/{repoId}/pulls/{prNumber}/draft git:UpdatePullRequest write
list-reviews GET /git/api/repositories/{repoId}/pulls/{prNumber}/reviews git:GetPullRequest read
review POST /git/api/repositories/{repoId}/pulls/{prNumber}/reviews git:ReviewPullRequest write
list-comments GET /git/api/repositories/{repoId}/pulls/{prNumber}/comments git:GetPullRequest read
list-viewed-files GET /git/api/repositories/{repoId}/pulls/{prNumber}/viewed git:GetPullRequest read
mark-file-viewed PUT /git/api/repositories/{repoId}/pulls/{prNumber}/viewed git:MarkFilesViewed write
comment POST /git/api/repositories/{repoId}/pulls/{prNumber}/comments git:ReviewPullRequest write
resolve-comment POST /git/api/repositories/{repoId}/pulls/{prNumber}/comments/{commentId}/resolve git:ReviewPullRequest write
apply-suggestion POST /git/api/repositories/{repoId}/pulls/{prNumber}/comments/{commentId}/apply-suggestion git:PushRepository write
list-reviewers GET /git/api/repositories/{repoId}/pulls/{prNumber}/reviewers git:GetPullRequest read
add-reviewer POST /git/api/repositories/{repoId}/pulls/{prNumber}/reviewers git:ReviewPullRequest write
remove-reviewer DELETE /git/api/repositories/{repoId}/pulls/{prNumber}/reviewers/{reviewerId} git:ReviewPullRequest write

dcloud git pulls list

List pull requests

GET /git/api/repositories/{repoId}/pulls — IAM git:ListPullRequests — read

dcloud git pulls list <repoId> [flags]

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<repoId> --repo-id string uuid
Flag In Required Notes
--state <open|closed|merged|draft> query Only pull requests in this state; every state when absent
--author <value> query 1-200 chars · Opened by this IAM username, or for an imported pull request this login on the source; @me for the caller
--assignee <value> query 1-200 chars · Assigned to this IAM username; @me for the caller
--reviewer <value> query 1-200 chars · Review requested from, or given by, this IAM username; @me for the caller
--label <value> query 1-200 chars · Carries this label; @me for the caller
--mentions <json> query JSON · Only pull requests whose description or comments mention the caller
--sort <newest|oldest|updated|comments> query Default: by number, newest first; comments puts the most commented first

dcloud git pulls create

Open a pull request

POST /git/api/repositories/{repoId}/pulls — IAM git:CreatePullRequest — write

dcloud git pulls create <repoId> --title <value> --source-branch <value> --target-branch <value> [flags]

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<repoId> --repo-id string uuid
Flag In Required Notes
--title <value> body yes 1-200 chars · The title
--body <value> body max 20000 chars · The description (Markdown)
--source-branch <value> body yes 1-255 chars · The branch with the changes
--target-branch <value> body yes 1-255 chars · The branch to merge them into
--is-draft body Open it as a draft, which cannot be merged until marked ready; false when absent

dcloud git pulls get

Show a pull request with mergeability, checks and approvals

GET /git/api/repositories/{repoId}/pulls/{prNumber} — IAM git:GetPullRequest — read

dcloud git pulls get <repoId> <prNumber>

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<repoId> --repo-id string uuid
<prNumber> --pr-number number integer, min 1
  • Also checks git:PullRepository. Failing it degrades the response rather than rejecting the call.
  • The diff is included only for a caller who also holds git:PullRepository; canReadSource in the response says which happened.

dcloud git pulls update

Edit a pull request's title or description

PATCH /git/api/repositories/{repoId}/pulls/{prNumber} — IAM git:UpdatePullRequest — write

dcloud git pulls update <repoId> <prNumber> [flags]

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<repoId> --repo-id string uuid
<prNumber> --pr-number number integer, min 1
Flag In Required Notes
--title <value> body 1-200 chars · The new title
--body <value> body max 20000 chars · nullable · The new description (Markdown); null clears it
  • Only the fields sent change; body: null clears the description. Refused for a merged pull request and in an archived repository. Sends a pull_request webhook with action: edited.

dcloud git pulls merge

Merge, squash or rebase a pull request

POST /git/api/repositories/{repoId}/pulls/{prNumber}/merge — IAM git:MergePullRequest — write

dcloud git pulls merge <repoId> <prNumber> [flags]

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<repoId> --repo-id string uuid
<prNumber> --pr-number number integer, min 1
Flag In Required Notes
--message <value> body max 500 chars · The commit message; when absent Merge pull request #n from <branch> and the title, or for a squash Title (#n) and the description. A rebase keeps each commit message
--method <merge|squash|rebase> body server default "merge" · merge records a merge commit, squash lands the branch as one commit, rebase replays each commit onto the target; the repository must allow it
--expected-head-sha <value> body /^[0-9a-f]{40}$/ · Merge only if the source branch is still at this commit; otherwise 409

dcloud git pulls enable-auto-merge

Merge automatically once approvals and required checks pass

PUT /git/api/repositories/{repoId}/pulls/{prNumber}/auto-merge — IAM git:MergePullRequest — write

dcloud git pulls enable-auto-merge <repoId> <prNumber> --method <merge|squash|rebase>

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<repoId> --repo-id string uuid
<prNumber> --pr-number number integer, min 1
Flag In Required Notes
--method <merge|squash|rebase> body yes merge records a merge commit, squash lands the branch as one commit, rebase replays each commit onto the target; the repository must allow it
  • Merges as the caller, with this method; merges at once if it already can (result: merged). Refused for a draft and on a branch that requires the merge queue. autoMergeBlockedReason on the pull request says what it waits for. Turned off if the caller later loses git:MergePullRequest.

dcloud git pulls disable-auto-merge

Turn auto-merge off

DELETE /git/api/repositories/{repoId}/pulls/{prNumber}/auto-merge — IAM git:MergePullRequest — write

dcloud git pulls disable-auto-merge <repoId> <prNumber>

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<repoId> --repo-id string uuid
<prNumber> --pr-number number integer, min 1

dcloud git pulls close

Close a pull request without merging

POST /git/api/repositories/{repoId}/pulls/{prNumber}/close — IAM git:ClosePullRequest — write

dcloud git pulls close <repoId> <prNumber>

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<repoId> --repo-id string uuid
<prNumber> --pr-number number integer, min 1

dcloud git pulls reopen

Reopen a closed pull request

POST /git/api/repositories/{repoId}/pulls/{prNumber}/reopen — IAM git:ClosePullRequest — write

dcloud git pulls reopen <repoId> <prNumber>

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<repoId> --repo-id string uuid
<prNumber> --pr-number number integer, min 1
  • Guarded by git:ClosePullRequest, not an action of its own — it is the same open/closed transition, and a policy that could close but not reopen would be a trap. A merged pull request cannot be reopened.

dcloud git pulls ready

Mark a draft ready for review (fires ready_for_review: webhooks and the workflows that list it)

POST /git/api/repositories/{repoId}/pulls/{prNumber}/ready — IAM git:UpdatePullRequest — write

dcloud git pulls ready <repoId> <prNumber>

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<repoId> --repo-id string uuid
<prNumber> --pr-number number integer, min 1

dcloud git pulls convert-to-draft

Turn an open pull request back into a draft (fires converted_to_draft: webhooks and the workflows that list it)

POST /git/api/repositories/{repoId}/pulls/{prNumber}/draft — IAM git:UpdatePullRequest — write

dcloud git pulls convert-to-draft <repoId> <prNumber>

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<repoId> --repo-id string uuid
<prNumber> --pr-number number integer, min 1

dcloud git pulls list-reviews

List reviews on a pull request

GET /git/api/repositories/{repoId}/pulls/{prNumber}/reviews — IAM git:GetPullRequest — read

dcloud git pulls list-reviews <repoId> <prNumber>

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<repoId> --repo-id string uuid
<prNumber> --pr-number number integer, min 1

dcloud git pulls review

Approve, request changes, or comment

POST /git/api/repositories/{repoId}/pulls/{prNumber}/reviews — IAM git:ReviewPullRequest — write

dcloud git pulls review <repoId> <prNumber> --state <approved|changes_requested|commented> [flags]

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<repoId> --repo-id string uuid
<prNumber> --pr-number number integer, min 1
Flag In Required Notes
--state <approved|changes_requested|commented> body yes Your verdict; an approval counts toward required approvals
--body <value> body max 20000 chars · The review text (Markdown)

dcloud git pulls list-comments

List comments, including inline ones

GET /git/api/repositories/{repoId}/pulls/{prNumber}/comments — IAM git:GetPullRequest — read

dcloud git pulls list-comments <repoId> <prNumber>

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<repoId> --repo-id string uuid
<prNumber> --pr-number number integer, min 1

dcloud git pulls list-viewed-files

The files you marked viewed that have not changed since

GET /git/api/repositories/{repoId}/pulls/{prNumber}/viewed — IAM git:GetPullRequest — read

dcloud git pulls list-viewed-files <repoId> <prNumber>

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<repoId> --repo-id string uuid
<prNumber> --pr-number number integer, min 1
  • Per caller. A mark counts while the head still has the blob it was marked at, so a push that changes a file clears its mark and leaves the others.

dcloud git pulls mark-file-viewed

Mark one file viewed, or clear the mark, for yourself

PUT /git/api/repositories/{repoId}/pulls/{prNumber}/viewed — IAM git:MarkFilesViewed — write

dcloud git pulls mark-file-viewed <repoId> <prNumber> --path <value> --viewed

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<repoId> --repo-id string uuid
<prNumber> --pr-number number integer, min 1
Flag In Required Notes
--path <value> body yes 1-1000 chars · A changed file's path at the head
--viewed body yes true marks it viewed, false clears the mark

dcloud git pulls comment

Comment on a pull request or on a line of it

POST /git/api/repositories/{repoId}/pulls/{prNumber}/comments — IAM git:ReviewPullRequest — write

dcloud git pulls comment <repoId> <prNumber> --body <value> [flags]

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<repoId> --repo-id string uuid
<prNumber> --pr-number number integer, min 1
Flag In Required Notes
--body <value> body yes 1-20000 chars · The comment (Markdown)
--reply-to-id <value> body uuid · The comment this one answers, in its thread
--file-path <value> body 1-1000 chars · For a comment on a line: the changed file; give line and side with it
--line <number> body integer, min 1 · For a comment on a line: the line number in the file on side
--side <old|new> body For a comment on a line: new is the head version, old the version before

dcloud git pulls resolve-comment

Mark a comment thread resolved or reopen it

POST /git/api/repositories/{repoId}/pulls/{prNumber}/comments/{commentId}/resolve — IAM git:ReviewPullRequest — write

dcloud git pulls resolve-comment <repoId> <prNumber> <commentId> --resolved

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<repoId> --repo-id string uuid
<prNumber> --pr-number number integer, min 1
<commentId> --comment-id string uuid
Flag In Required Notes
--resolved body yes true resolves the thread, false reopens it
  • Only thread roots are resolvable; a reply returns 404.

dcloud git pulls apply-suggestion

Commit a review comment's suggested change to the pull request's branch

POST /git/api/repositories/{repoId}/pulls/{prNumber}/comments/{commentId}/apply-suggestion — IAM git:PushRepository — write

dcloud git pulls apply-suggestion <repoId> <prNumber> <commentId>

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<repoId> --repo-id string uuid
<prNumber> --pr-number number integer, min 1
<commentId> --comment-id string uuid
  • The comment must be on a line of the new side and carry a ```suggestion block; it replaces that line (empty deletes it). Refused once the branch has moved since the comment (409), and subject to branch protection like a push. Resolves the thread.

dcloud git pulls list-reviewers

List requested reviewers

GET /git/api/repositories/{repoId}/pulls/{prNumber}/reviewers — IAM git:GetPullRequest — read

dcloud git pulls list-reviewers <repoId> <prNumber>

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<repoId> --repo-id string uuid
<prNumber> --pr-number number integer, min 1

dcloud git pulls add-reviewer

Request a review from someone

POST /git/api/repositories/{repoId}/pulls/{prNumber}/reviewers — IAM git:ReviewPullRequest — write

dcloud git pulls add-reviewer <repoId> <prNumber> --reviewer-iam-user-id <value>

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<repoId> --repo-id string uuid
<prNumber> --pr-number number integer, min 1
Flag In Required Notes
--reviewer-iam-user-id <value> body yes uuid · The IAM user of the organization asked to review

dcloud git pulls remove-reviewer

Withdraw a review request

DELETE /git/api/repositories/{repoId}/pulls/{prNumber}/reviewers/{reviewerId} — IAM git:ReviewPullRequest — write

dcloud git pulls remove-reviewer <repoId> <prNumber> <reviewerId>

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<repoId> --repo-id string uuid
<prNumber> --pr-number number integer, min 1
<reviewerId> --reviewer-id string uuid

dcloud git merge-queue

A protected branch's merge queue (GitHub's merge queue)

Operation Method Path IAM action Effect
get GET /git/api/repositories/{repoId}/merge-queue git:GetMergeQueue read
add POST /git/api/repositories/{repoId}/pulls/{prNumber}/merge-queue git:AddToMergeQueue write
remove DELETE /git/api/repositories/{repoId}/pulls/{prNumber}/merge-queue git:RemoveFromMergeQueue write

dcloud git merge-queue get

Show a branch queue: settings, entries in order, recent results and events

GET /git/api/repositories/{repoId}/merge-queue — IAM git:GetMergeQueue — read

dcloud git merge-queue get <repoId> --branch <value>

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<repoId> --repo-id string uuid
Flag In Required Notes
--branch <value> query yes 1-255 chars · The target branch whose queue to show

dcloud git merge-queue add

Add a pull request to its target branch merge queue ("merge when ready")

POST /git/api/repositories/{repoId}/pulls/{prNumber}/merge-queue — IAM git:AddToMergeQueue — write

dcloud git merge-queue add <repoId> <prNumber>

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<repoId> --repo-id string uuid
<prNumber> --pr-number number integer, min 1
  • Only for a target branch whose protection rule requires a merge queue. If approvals or checks are not yet satisfied the entry waits (state waiting) and joins the end of the line once they are. The queue builds ews-readonly-queue/<base>/pr-<n>-<sha> with every pull request ahead of it, runs merge_group CI on it, and fast-forwards the base when the checks pass.

dcloud git merge-queue remove

Remove a pull request from the merge queue

DELETE /git/api/repositories/{repoId}/pulls/{prNumber}/merge-queue — IAM git:RemoveFromMergeQueue — write

dcloud git merge-queue remove <repoId> <prNumber>

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<repoId> --repo-id string uuid
<prNumber> --pr-number number integer, min 1
  • Builds behind it are thrown away and rebuilt without it.

dcloud git releases

Named, published tags; publishing one starts on: release workflows

Operation Method Path IAM action Effect
list GET /git/api/repositories/{repoId}/releases git:ListReleases read
get GET /git/api/repositories/{repoId}/releases/{releaseId} git:ListReleases read
create POST /git/api/repositories/{repoId}/releases git:CreateRelease write
update PATCH /git/api/repositories/{repoId}/releases/{releaseId} git:UpdateRelease write
delete DELETE /git/api/repositories/{repoId}/releases/{releaseId} git:DeleteRelease write

dcloud git releases list

List a repository’s releases, newest first

GET /git/api/repositories/{repoId}/releases — IAM git:ListReleases — read

dcloud git releases list <repoId>

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<repoId> --repo-id string uuid

dcloud git releases get

One release

GET /git/api/repositories/{repoId}/releases/{releaseId} — IAM git:ListReleases — read

dcloud git releases get <repoId> <releaseId>

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<repoId> --repo-id string uuid
<releaseId> --release-id string uuid

dcloud git releases create

Create a release (and its tag, when new)

POST /git/api/repositories/{repoId}/releases — IAM git:CreateRelease — write

dcloud git releases create <repoId> --tag-name <value> [flags]

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<repoId> --repo-id string uuid
Flag In Required Notes
--tag-name <value> body yes 1-255 chars · The tag; created at target when it does not exist
--target <value> body 1-255 chars · Branch or commit for a new tag; the default branch when absent
--name <value> body max 255 chars · Title; the tag name when absent
--body <value> body max 125000 chars · Release notes (Markdown)
--draft body A draft fires only created; publish it later
--prerelease body Mark it a pre-release (fires prereleased instead of released); false when absent
  • A new tag is created at target (default branch when absent) and needs git:PushRepository too. A non-draft release fires release with created, published and released (or prereleased); a draft only created. Answers the release and runIds of the workflows it started.

dcloud git releases update

Edit a release, or publish a draft (draft: false)

PATCH /git/api/repositories/{repoId}/releases/{releaseId} — IAM git:UpdateRelease — write

dcloud git releases update <repoId> <releaseId> [flags]

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<repoId> --repo-id string uuid
<releaseId> --release-id string uuid
Flag In Required Notes
--name <value> body max 255 chars · New title; an empty one resets it to the tag name
--body <value> body max 125000 chars · New release notes (Markdown), replacing the old
--draft <json> body JSON · false publishes a draft (fires published + released/prereleased)
--prerelease body Mark it a pre-release, or not

dcloud git releases delete

Delete a release; its tag stays

DELETE /git/api/repositories/{repoId}/releases/{releaseId} — IAM git:DeleteRelease — write

dcloud git releases delete <repoId> <releaseId>

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<repoId> --repo-id string uuid
<releaseId> --release-id string uuid
  • Its assets are deleted with it, files included.

dcloud git release-assets

Files attached to a release — binaries, archives, checksums

Operation Method Path IAM action Effect
list GET /git/api/repositories/{repoId}/releases/{releaseId}/assets git:ListReleases read
download GET /git/api/repositories/{repoId}/releases/{releaseId}/assets/{assetId}/download git:ListReleases read
delete DELETE /git/api/repositories/{repoId}/releases/{releaseId}/assets/{assetId} git:UpdateRelease write

dcloud git release-assets list

List a release's assets

GET /git/api/repositories/{repoId}/releases/{releaseId}/assets — IAM git:ListReleases — read

dcloud git release-assets list <repoId> <releaseId>

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<repoId> --repo-id string uuid
<releaseId> --release-id string uuid

dcloud git release-assets download

Download an asset

GET /git/api/repositories/{repoId}/releases/{releaseId}/assets/{assetId}/download — IAM git:ListReleases — read

dcloud git release-assets download <repoId> <releaseId> <assetId>

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<repoId> --repo-id string uuid
<releaseId> --release-id string uuid
<assetId> --asset-id string uuid
  • Returns raw bytes with their own content type, written straight to stdout.
  • Always application/octet-stream as an attachment; access is re-checked on every download. Counts toward downloadCount.

dcloud git release-assets delete

Remove an asset and its file

DELETE /git/api/repositories/{repoId}/releases/{releaseId}/assets/{assetId} — IAM git:UpdateRelease — write

dcloud git release-assets delete <repoId> <releaseId> <assetId>

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<repoId> --repo-id string uuid
<releaseId> --release-id string uuid
<assetId> --asset-id string uuid

dcloud git security

Security & quality: the security policy, secret scanning, dependency and code scanning alerts

Operation Method Path IAM action Effect
get GET /git/api/repositories/{repoId}/security git:ListSecurityAlerts read
update-settings PATCH /git/api/repositories/{repoId}/security/settings git:UpdateRepository write
overview GET /git/api/security/overview git:ListSecurityAlerts read
list-secret-alerts GET /git/api/repositories/{repoId}/security/secret-alerts git:ListSecurityAlerts read
resolve-secret-alert PATCH /git/api/repositories/{repoId}/security/secret-alerts/{alertId} git:UpdateSecurityAlert write
list-dependency-alerts GET /git/api/repositories/{repoId}/security/dependency-alerts git:ListSecurityAlerts read
set-dependency-alert PATCH /git/api/repositories/{repoId}/security/dependency-alerts/{alertId} git:UpdateSecurityAlert write
get-dependency-alert GET /git/api/repositories/{repoId}/security/dependency-alerts/{alertId} git:ListSecurityAlerts read
fix-dependencies POST /git/api/repositories/{repoId}/security/dependency-alerts/fix git:CreatePullRequest write
get-dependency-fix GET /git/api/repositories/{repoId}/security/dependency-alerts/fix git:ListSecurityAlerts read
scan-dependencies POST /git/api/repositories/{repoId}/security/dependency-alerts/scan git:UpdateSecurityAlert write
list-code-scanning-alerts GET /git/api/repositories/{repoId}/security/code-scanning-alerts git:ListSecurityAlerts read
set-code-scanning-alert PATCH /git/api/repositories/{repoId}/security/code-scanning-alerts/{alertId} git:UpdateSecurityAlert write
upload-sarif POST /git/api/repositories/{repoId}/code-scanning/sarifs git:UploadCodeScanningResults write
code-scanning-at-commit GET /git/api/repositories/{repoId}/commits/{sha}/code-scanning git:ListSecurityAlerts read

dcloud git security get

The repository’s security overview: settings, policy, open alert counts

GET /git/api/repositories/{repoId}/security — IAM git:ListSecurityAlerts — read

dcloud git security get <repoId>

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<repoId> --repo-id string uuid
  • Also checks git:PullRepository. Failing it degrades the response rather than rejecting the call.
  • policy is the first of .github/SECURITY.md, SECURITY.md, docs/SECURITY.md on the default branch (null without git:PullRepository). dependencyScan is the last lockfile scan.

dcloud git security update-settings

Turn secret push protection or dependency alerts on or off, set the file size limit

PATCH /git/api/repositories/{repoId}/security/settings — IAM git:UpdateRepository — write

dcloud git security update-settings <repoId> [flags]

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<repoId> --repo-id string uuid
Flag In Required Notes
--secret-push-protection body Refuse pushes that add a known credential format (on by default)
--dependency-alerts body Check lockfiles on the default branch against the vulnerability database
--max-file-size-mb <number> body integer, 1-2048 · nullable · Largest file a push may add, in MB; null for the platform default of 100

dcloud git security overview

Open alerts and protection settings for every repository you may see

GET /git/api/security/overview — IAM git:ListSecurityAlerts — read

dcloud git security overview

dcloud git security list-secret-alerts

Secrets push protection found: blocked, bypassed and resolved, plus scan gaps

GET /git/api/repositories/{repoId}/security/secret-alerts — IAM git:ListSecurityAlerts — read

dcloud git security list-secret-alerts <repoId>

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<repoId> --repo-id string uuid
  • Never the secret itself: a redacted preview and a fingerprint. gaps lists pushes the scan could not finish (fail-open past its time or size budget).

dcloud git security resolve-secret-alert

Say what was done about a bypassed secret (revoked, false positive, …)

PATCH /git/api/repositories/{repoId}/security/secret-alerts/{alertId} — IAM git:UpdateSecurityAlert — write

dcloud git security resolve-secret-alert <repoId> <alertId> --resolution <revoked|false_positive|used_in_tests|wont_fix> [flags]

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<repoId> --repo-id string uuid
<alertId> --alert-id string uuid
Flag In Required Notes
--resolution <revoked|false_positive|used_in_tests|wont_fix> body yes What was done about the secret that was pushed
--comment <value> body max 2000 chars · A note on the resolution, in your own words

dcloud git security list-dependency-alerts

Vulnerable dependencies in the default branch’s lockfiles

GET /git/api/repositories/{repoId}/security/dependency-alerts — IAM git:ListSecurityAlerts — read

dcloud git security list-dependency-alerts <repoId>

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<repoId> --repo-id string uuid

dcloud git security set-dependency-alert

Dismiss a dependency alert with a reason, or reopen it

PATCH /git/api/repositories/{repoId}/security/dependency-alerts/{alertId} — IAM git:UpdateSecurityAlert — write

dcloud git security set-dependency-alert <repoId> <alertId> --state <open|dismissed> [flags]

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<repoId> --repo-id string uuid
<alertId> --alert-id string uuid
Flag In Required Notes
--state <open|dismissed> body yes dismissed closes the alert, open reopens it
--reason <value> body max 2000 chars · Why it is dismissed: false positive, not exploitable, accepted risk, fix later, or your own words
--comment <value> body max 2000 chars · Your own words beside the reason

dcloud git security get-dependency-alert

One dependency alert: the advisory in full, CVSS, links, why the package is installed, and every place it is

GET /git/api/repositories/{repoId}/security/dependency-alerts/{alertId} — IAM git:ListSecurityAlerts — read

dcloud git security get-dependency-alert <repoId> <alertId>

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<repoId> --repo-id string uuid
<alertId> --alert-id string uuid

dcloud git security fix-dependencies

Fix the security issues of this repository: open a pull request that bumps the vulnerable dependencies of its package-lock.json and pnpm-lock.yaml

POST /git/api/repositories/{repoId}/security/dependency-alerts/fix — IAM git:CreatePullRequest — write

dcloud git security fix-dependencies <repoId> [flags]

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<repoId> --repo-id string uuid
Flag In Required Notes
--packages <value> body repeatable · 3-300 chars · Package groups to fix, as ecosystem:package (e.g. pnpm:vite); leave out to fix every package a fixed version exists for
  • Answers 202; the platform creates a branch, bumps the versions, updates the lockfile with the package manager (no install scripts, public registry) and opens a pull request listing the advisories, so CI runs. It never merges. Needs git:PushRepository too. get-dependency-fix shows the outcome; 409 names an open fix pull request for the same package.

dcloud git security get-dependency-fix

The last fix pull request asked for, and the open ones

GET /git/api/repositories/{repoId}/security/dependency-alerts/fix — IAM git:ListSecurityAlerts — read

dcloud git security get-dependency-fix <repoId>

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<repoId> --repo-id string uuid

dcloud git security scan-dependencies

Scan the default branch’s lockfiles now

POST /git/api/repositories/{repoId}/security/dependency-alerts/scan — IAM git:UpdateSecurityAlert — write

dcloud git security scan-dependencies <repoId>

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<repoId> --repo-id string uuid
  • Answers 202; the scan runs in the background and get shows its result.

dcloud git security list-code-scanning-alerts

Code scanning alerts on the default branch

GET /git/api/repositories/{repoId}/security/code-scanning-alerts — IAM git:ListSecurityAlerts — read

dcloud git security list-code-scanning-alerts <repoId>

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<repoId> --repo-id string uuid

dcloud git security set-code-scanning-alert

Dismiss a code scanning alert with a reason, or reopen it

PATCH /git/api/repositories/{repoId}/security/code-scanning-alerts/{alertId} — IAM git:UpdateSecurityAlert — write

dcloud git security set-code-scanning-alert <repoId> <alertId> --state <open|dismissed> [flags]

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<repoId> --repo-id string uuid
<alertId> --alert-id string uuid
Flag In Required Notes
--state <open|dismissed> body yes dismissed closes the alert, open reopens it
--reason <value> body max 2000 chars · Why it is dismissed

dcloud git security upload-sarif

Upload a SARIF 2.1.0 file of code scanning results for a commit

POST /git/api/repositories/{repoId}/code-scanning/sarifs — IAM git:UploadCodeScanningResults — write

dcloud git security upload-sarif <repoId> --commit-sha <value> --ref <value> --sarif <value>

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<repoId> --repo-id string uuid
Flag In Required Notes
--commit-sha <value> body yes /^[0-9a-f]{40}$/ · The commit the analysis ran on
--ref <value> body yes 1-255 chars · The ref analysed: refs/heads/, or refs/pull//head for a pull request
--sarif <value> body yes 2-12582912 chars · The SARIF 2.1.0 document, as JSON text (at most 12 MB)
  • Any SARIF-writing tool (Semgrep, CodeQL, Trivy, gosec). An analysis of the default branch updates the repository’s alerts and marks those it no longer reports fixed; an analysis of a pull request’s head shows on the pull request.

dcloud git security code-scanning-at-commit

Code scanning results reported for one commit, per tool

GET /git/api/repositories/{repoId}/commits/{sha}/code-scanning — IAM git:ListSecurityAlerts — read

dcloud git security code-scanning-at-commit <repoId> <sha>

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<repoId> --repo-id string uuid
<sha> --sha string /^[0-9a-f]{40}$/

dcloud git issues

Issues: bugs, tasks and CI alerts, with labels, assignees and comments

Operation Method Path IAM action Effect
list GET /git/api/repositories/{repoId}/issues git:ListIssues read
create POST /git/api/repositories/{repoId}/issues git:CreateIssue write
get GET /git/api/repositories/{repoId}/issues/{number} git:ListIssues read
update PATCH /git/api/repositories/{repoId}/issues/{number} git:UpdateIssue write
comment POST /git/api/repositories/{repoId}/issues/{number}/comments git:CommentOnIssue write

dcloud git issues list

List a repository’s issues, newest first

GET /git/api/repositories/{repoId}/issues — IAM git:ListIssues — read

dcloud git issues list <repoId>

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<repoId> --repo-id string uuid
  • Each with its labels, assignee IAM user ids and comment count. Issues and pull requests share one numbering per repository.

dcloud git issues create

Open an issue

POST /git/api/repositories/{repoId}/issues — IAM git:CreateIssue — write

dcloud git issues create <repoId> --title <value> [flags]

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<repoId> --repo-id string uuid
Flag In Required Notes
--title <value> body yes 1-256 chars · The title
--body <value> body max 65536 chars · The description (Markdown)
--labels <value> body repeatable · 1-50 chars · Label names; each must exist in the repository
--assignee-iam-user-ids <value> body repeatable · uuid · IAM users of the organization to assign

dcloud git issues get

One issue with its comments

GET /git/api/repositories/{repoId}/issues/{number} — IAM git:ListIssues — read

dcloud git issues get <repoId> <number>

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<repoId> --repo-id string uuid
<number> --number number integer, min 1

dcloud git issues update

Edit, close or reopen an issue; replace its labels or assignees

PATCH /git/api/repositories/{repoId}/issues/{number} — IAM git:UpdateIssue — write

dcloud git issues update <repoId> <number> [flags]

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<repoId> --repo-id string uuid
<number> --number number integer, min 1
Flag In Required Notes
--title <value> body 1-256 chars · The new title
--body <value> body max 65536 chars · nullable · The new description (Markdown); null clears it
--state <open|closed> body closed closes the issue, open reopens it
--state-reason <completed|not_planned> body Why it is closed; completed when absent
--labels <value> body repeatable · 1-50 chars · Replaces the labels; each name must exist in the repository
--assignee-iam-user-ids <value> body repeatable · uuid · Replaces the assignees: IAM users of the organization

dcloud git issues comment

Comment on an issue

POST /git/api/repositories/{repoId}/issues/{number}/comments — IAM git:CommentOnIssue — write

dcloud git issues comment <repoId> <number> --body <value>

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<repoId> --repo-id string uuid
<number> --number number integer, min 1
Flag In Required Notes
--body <value> body yes 1-65536 chars · The comment (Markdown)

dcloud git labels

A repository’s labels, shared by its issues and pull requests

Operation Method Path IAM action Effect
list GET /git/api/repositories/{repoId}/labels git:ListIssues read
create POST /git/api/repositories/{repoId}/labels git:ManageLabels write
update PATCH /git/api/repositories/{repoId}/labels/{labelId} git:ManageLabels write
delete DELETE /git/api/repositories/{repoId}/labels/{labelId} git:ManageLabels write
set-pull-request-labels PUT /git/api/repositories/{repoId}/pulls/{prNumber}/labels git:UpdateIssue write
set-pull-request-assignees PUT /git/api/repositories/{repoId}/pulls/{prNumber}/assignees git:UpdateIssue write

dcloud git labels list

List labels

GET /git/api/repositories/{repoId}/labels — IAM git:ListIssues — read

dcloud git labels list <repoId>

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<repoId> --repo-id string uuid

dcloud git labels create

Create a label

POST /git/api/repositories/{repoId}/labels — IAM git:ManageLabels — write

dcloud git labels create <repoId> --name <value> [flags]

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<repoId> --repo-id string uuid
Flag In Required Notes
--name <value> body yes 1-50 chars · The label name, unique in the repository
--color <value> body Six hex digits, e.g. d73a4a; grey (6b7280) when absent
--description <value> body max 200 chars · What the label is for

dcloud git labels update

Rename, recolour or describe a label

PATCH /git/api/repositories/{repoId}/labels/{labelId} — IAM git:ManageLabels — write

dcloud git labels update <repoId> <labelId> [flags]

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<repoId> --repo-id string uuid
<labelId> --label-id string uuid
Flag In Required Notes
--name <value> body 1-50 chars · The new name
--color <value> body The new colour: six hex digits, e.g. d73a4a
--description <value> body max 200 chars · nullable · The new description; null removes it

dcloud git labels delete

Delete a label (it comes off every issue and pull request)

DELETE /git/api/repositories/{repoId}/labels/{labelId} — IAM git:ManageLabels — write

dcloud git labels delete <repoId> <labelId>

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<repoId> --repo-id string uuid
<labelId> --label-id string uuid

dcloud git labels set-pull-request-labels

Replace a pull request’s labels

PUT /git/api/repositories/{repoId}/pulls/{prNumber}/labels — IAM git:UpdateIssue — write

dcloud git labels set-pull-request-labels <repoId> <prNumber> --labels <value>

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<repoId> --repo-id string uuid
<prNumber> --pr-number number integer, min 1
Flag In Required Notes
--labels <value> body yes repeatable · 1-50 chars · Label names replacing the current set (empty removes all); each must exist in the repository
  • Workflows see them as github.event.pull_request.labels (contains(github.event.pull_request.labels.*.name, …)).

dcloud git labels set-pull-request-assignees

Replace a pull request’s assignees

PUT /git/api/repositories/{repoId}/pulls/{prNumber}/assignees — IAM git:UpdateIssue — write

dcloud git labels set-pull-request-assignees <repoId> <prNumber> --assignee-iam-user-ids <value>

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<repoId> --repo-id string uuid
<prNumber> --pr-number number integer, min 1
Flag In Required Notes
--assignee-iam-user-ids <value> body yes repeatable · uuid · Replaces the assignees
  • Members of the organization, as on an issue; each change is a timeline entry.

dcloud git tag-protection

Tag patterns only holders of git:PushProtectedTag may create, move or delete

Operation Method Path IAM action Effect
list GET /git/api/repositories/{repoId}/tag-protection git:GetRepository read
create POST /git/api/repositories/{repoId}/tag-protection git:ManageBranchProtection write
delete DELETE /git/api/repositories/{repoId}/tag-protection/{ruleId} git:ManageBranchProtection write

dcloud git tag-protection list

List protected tag patterns

GET /git/api/repositories/{repoId}/tag-protection — IAM git:GetRepository — read

dcloud git tag-protection list <repoId>

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<repoId> --repo-id string uuid

dcloud git tag-protection create

Protect a tag pattern

POST /git/api/repositories/{repoId}/tag-protection — IAM git:ManageBranchProtection — write

dcloud git tag-protection create <repoId> --pattern <value>

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<repoId> --repo-id string uuid
Flag In Required Notes
--pattern <value> body yes 1-200 chars, /^[A-Za-z0-9._/+-]+$/ · Tag name or glob, e.g. v or release-*; matching tags need git:PushProtectedTag

dcloud git tag-protection delete

Remove a tag protection rule

DELETE /git/api/repositories/{repoId}/tag-protection/{ruleId} — IAM git:ManageBranchProtection — write

dcloud git tag-protection delete <repoId> <ruleId>

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<repoId> --repo-id string uuid
<ruleId> --rule-id string uuid

dcloud git commit-statuses

Pass/fail an external tool reports on a commit; a required check can name one

Operation Method Path IAM action Effect
list GET /git/api/repositories/{repoId}/commits/{sha}/statuses git:ListCommitStatuses read
create POST /git/api/repositories/{repoId}/commits/{sha}/statuses git:CreateCommitStatus write

dcloud git commit-statuses list

Statuses reported on a commit

GET /git/api/repositories/{repoId}/commits/{sha}/statuses — IAM git:ListCommitStatuses — read

dcloud git commit-statuses list <repoId> <sha>

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<repoId> --repo-id string uuid
<sha> --sha string /^[0-9a-f]{40}$/

dcloud git commit-statuses create

Report a status on a commit (one per context; a later one replaces it)

POST /git/api/repositories/{repoId}/commits/{sha}/statuses — IAM git:CreateCommitStatus — write

dcloud git commit-statuses create <repoId> <sha> --state <pending|success|failure|error> [flags]

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<repoId> --repo-id string uuid
<sha> --sha string /^[0-9a-f]{40}$/
Flag In Required Notes
--state <pending|success|failure|error> body yes The result: pending waits, success passes, failure and error block a required check
--context <value> body 1-255 chars · server default "default" · Names the check; a required check of this name gates merges
--description <value> body max 1000 chars · A short summary shown beside the status
--target-url <value> body max 2000 chars · An https:// link to the details
  • GitHub’s POST /repos/{owner}/{repo}/statuses/{sha}. A branch protection rule whose required checks name this context waits for it: pending waits, success passes, failure and error block.

dcloud git branch-protection

Rules that constrain what may land on a branch

Operation Method Path IAM action Effect
list GET /git/api/repositories/{repoId}/branch-protection git:GetRepository read
create POST /git/api/repositories/{repoId}/branch-protection git:ManageBranchProtection write
update PATCH /git/api/repositories/{repoId}/branch-protection/{ruleId} git:ManageBranchProtection write
delete DELETE /git/api/repositories/{repoId}/branch-protection/{ruleId} git:ManageBranchProtection write

dcloud git branch-protection list

List branch protection rules

GET /git/api/repositories/{repoId}/branch-protection — IAM git:GetRepository — read

dcloud git branch-protection list <repoId>

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<repoId> --repo-id string uuid

dcloud git branch-protection create

Add a branch protection rule

POST /git/api/repositories/{repoId}/branch-protection — IAM git:ManageBranchProtection — write

dcloud git branch-protection create <repoId> --branch-pattern <value> [flags]

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<repoId> --repo-id string uuid
Flag In Required Notes
--branch-pattern <value> body yes 1-200 chars · The branch name or glob the rule covers, e.g. main or release/*
--require-pull-request body Changes land only through a pull request; direct pushes are refused (true on a new rule)
--required-approvals <number> body integer, 0-10 · Approvals a pull request needs before it can merge (0 on a new rule)
--dismiss-stale-approvals body A push to the pull request dismisses the approvals given before it (false on a new rule)
--require-code-owner-review body Every changed file CODEOWNERS assigns needs an approval from one of its owners
--require-status-checks body Required checks must pass before a pull request can merge (false on a new rule)
--required-checks <value> body repeatable · 1-200 chars · Workflow or status names that must pass; empty means every workflow a pull request to the branch triggers
--block-force-push body Refuse pushes that rewrite the branch history (true on a new rule)
--block-deletion body Refuse deleting the branch (true on a new rule)
--require-merge-queue body The branch moves only through its merge queue; direct pushes and the merge button are refused (false on a new rule)
--merge-queue-method <merge|squash|rebase> body How the queue merges each pull request (merge on a new rule)
--merge-queue-build-concurrency <number> body integer, 1-100 · How many queued pull requests may be building at once (5 on a new rule)
--merge-queue-min-group-size <number> body integer, 1-100 · Fewest pull requests the queue waits for before it builds, up to the wait time (1 on a new rule)
--merge-queue-max-group-size <number> body integer, 1-100 · Most pull requests landed by one fast-forward (5 on a new rule)
--merge-queue-wait-minutes <number> body integer, 0-360 · Minutes to wait for the minimum group size before building anyway (5 on a new rule)
--merge-queue-check-timeout-minutes <number> body integer, 1-360 · Minutes a queue build may wait for its checks before it fails (60 on a new rule)
--merge-queue-only-non-failing body Land only pull requests whose own build passed; off, a failed build still lands if a later build containing it passes (true on a new rule)

dcloud git branch-protection update

Change a branch protection rule

PATCH /git/api/repositories/{repoId}/branch-protection/{ruleId} — IAM git:ManageBranchProtection — write

dcloud git branch-protection update <repoId> <ruleId> [flags]

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<repoId> --repo-id string uuid
<ruleId> --rule-id string uuid
Flag In Required Notes
--branch-pattern <value> body 1-200 chars · The branch name or glob the rule covers, e.g. main or release/*
--require-pull-request body Changes land only through a pull request; direct pushes are refused (true on a new rule)
--required-approvals <number> body integer, 0-10 · Approvals a pull request needs before it can merge (0 on a new rule)
--dismiss-stale-approvals body A push to the pull request dismisses the approvals given before it (false on a new rule)
--require-code-owner-review body Every changed file CODEOWNERS assigns needs an approval from one of its owners
--require-status-checks body Required checks must pass before a pull request can merge (false on a new rule)
--required-checks <value> body repeatable · 1-200 chars · Workflow or status names that must pass; empty means every workflow a pull request to the branch triggers
--block-force-push body Refuse pushes that rewrite the branch history (true on a new rule)
--block-deletion body Refuse deleting the branch (true on a new rule)
--require-merge-queue body The branch moves only through its merge queue; direct pushes and the merge button are refused (false on a new rule)
--merge-queue-method <merge|squash|rebase> body How the queue merges each pull request (merge on a new rule)
--merge-queue-build-concurrency <number> body integer, 1-100 · How many queued pull requests may be building at once (5 on a new rule)
--merge-queue-min-group-size <number> body integer, 1-100 · Fewest pull requests the queue waits for before it builds, up to the wait time (1 on a new rule)
--merge-queue-max-group-size <number> body integer, 1-100 · Most pull requests landed by one fast-forward (5 on a new rule)
--merge-queue-wait-minutes <number> body integer, 0-360 · Minutes to wait for the minimum group size before building anyway (5 on a new rule)
--merge-queue-check-timeout-minutes <number> body integer, 1-360 · Minutes a queue build may wait for its checks before it fails (60 on a new rule)
--merge-queue-only-non-failing body Land only pull requests whose own build passed; off, a failed build still lands if a later build containing it passes (true on a new rule)
  • Only the fields sent are written. Editing in place matters because the alternative — create the replacement, delete the old one — leaves the branch unprotected in between.

dcloud git branch-protection delete

Remove a branch protection rule

DELETE /git/api/repositories/{repoId}/branch-protection/{ruleId} — IAM git:ManageBranchProtection — write

dcloud git branch-protection delete <repoId> <ruleId>

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<repoId> --repo-id string uuid
<ruleId> --rule-id string uuid

dcloud git deploy-keys

Per-repository SSH keys for machines

Operation Method Path IAM action Effect
list GET /git/api/repositories/{repoId}/deploy-keys git:ListDeployKeys read
create POST /git/api/repositories/{repoId}/deploy-keys git:CreateDeployKey write
delete DELETE /git/api/repositories/{repoId}/deploy-keys/{keyId} git:DeleteDeployKey write

dcloud git deploy-keys list

List deploy keys

GET /git/api/repositories/{repoId}/deploy-keys — IAM git:ListDeployKeys — read

dcloud git deploy-keys list <repoId>

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<repoId> --repo-id string uuid

dcloud git deploy-keys create

Add a deploy key

POST /git/api/repositories/{repoId}/deploy-keys — IAM git:CreateDeployKey — write

dcloud git deploy-keys create <repoId> --name <value> --public-key <value> [flags]

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<repoId> --repo-id string uuid
Flag In Required Notes
--name <value> body yes 1-64 chars · A name to recognise the key by, e.g. the machine
--public-key <value> body yes 1-4000 chars · The OpenSSH public key line, e.g. ssh-ed25519 AAAA… comment
--read-only body true lets the key clone and fetch only; false also lets it push. true when absent

dcloud git deploy-keys delete

Remove a deploy key

DELETE /git/api/repositories/{repoId}/deploy-keys/{keyId} — IAM git:DeleteDeployKey — write

dcloud git deploy-keys delete <repoId> <keyId>

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<repoId> --repo-id string uuid
<keyId> --key-id string uuid

dcloud git webhooks

Outbound notifications on repository events

Operation Method Path IAM action Effect
list GET /git/api/repositories/{repoId}/webhooks git:ListWebhooks read, sensitive
create POST /git/api/repositories/{repoId}/webhooks git:CreateWebhook write
update PATCH /git/api/repositories/{repoId}/webhooks/{hookId} git:UpdateWebhook write
delete DELETE /git/api/repositories/{repoId}/webhooks/{hookId} git:DeleteWebhook write

dcloud git webhooks list

List webhooks

GET /git/api/repositories/{repoId}/webhooks — IAM git:ListWebhooks — read, sensitive

dcloud git webhooks list <repoId>

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<repoId> --repo-id string uuid

dcloud git webhooks create

Add a webhook

POST /git/api/repositories/{repoId}/webhooks — IAM git:CreateWebhook — write

dcloud git webhooks create <repoId> --url <value> --events <push|tag|pull_request|pull_request_review|issues|issue_comment|release|merge_queue> [flags]

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<repoId> --repo-id string uuid
Flag In Required Notes
--url <value> body yes url · The public URL each delivery is POSTed to
--events <push|tag|pull_request|pull_request_review|issues|issue_comment|release|merge_queue> body yes repeatable · The events that trigger a delivery
--secret <value> body max 200 chars · Signs each delivery with an HMAC-SHA256 of its body (sha256=… header); unsigned when absent
--is-active body false pauses deliveries without deleting the hook; true when created without it

dcloud git webhooks update

Change a webhook

PATCH /git/api/repositories/{repoId}/webhooks/{hookId} — IAM git:UpdateWebhook — write

dcloud git webhooks update <repoId> <hookId> [flags]

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<repoId> --repo-id string uuid
<hookId> --hook-id string uuid
Flag In Required Notes
--url <value> body url · The public URL each delivery is POSTed to
--events <push|tag|pull_request|pull_request_review|issues|issue_comment|release|merge_queue> body repeatable · The events that trigger a delivery
--secret <value> body max 200 chars · nullable · A new signing secret; absent keeps the stored one, null stops signing
--is-active body false pauses deliveries without deleting the hook; true when created without it
  • Only the fields sent are written. The secret is write-only — omit it to keep the stored one, send null to stop signing deliveries.

dcloud git webhooks delete

Remove a webhook

DELETE /git/api/repositories/{repoId}/webhooks/{hookId} — IAM git:DeleteWebhook — write

dcloud git webhooks delete <repoId> <hookId>

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<repoId> --repo-id string uuid
<hookId> --hook-id string uuid

dcloud git webhook-deliveries

A webhook's recent deliveries (30 days), and sending one again

Operation Method Path IAM action Effect
list GET /git/api/repositories/{repoId}/webhooks/{hookId}/deliveries git:ListWebhooks read, sensitive
get GET /git/api/repositories/{repoId}/webhooks/{hookId}/deliveries/{deliveryId} git:ListWebhooks read, sensitive
redeliver POST /git/api/repositories/{repoId}/webhooks/{hookId}/deliveries/{deliveryId}/redeliver git:UpdateWebhook write

dcloud git webhook-deliveries list

List recent deliveries

GET /git/api/repositories/{repoId}/webhooks/{hookId}/deliveries — IAM git:ListWebhooks — read, sensitive

dcloud git webhook-deliveries list <repoId> <hookId>

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<repoId> --repo-id string uuid
<hookId> --hook-id string uuid
  • Newest first, without bodies: status (pending, retrying, delivered, failed), attempts, response code and duration.

dcloud git webhook-deliveries get

Show one delivery

GET /git/api/repositories/{repoId}/webhooks/{hookId}/deliveries/{deliveryId} — IAM git:ListWebhooks — read, sensitive

dcloud git webhook-deliveries get <repoId> <hookId> <deliveryId>

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<repoId> --repo-id string uuid
<hookId> --hook-id string uuid
<deliveryId> --delivery-id string uuid
  • The request body sent and the first 4 KiB of the answer.

dcloud git webhook-deliveries redeliver

Send a delivery again

POST /git/api/repositories/{repoId}/webhooks/{hookId}/deliveries/{deliveryId}/redeliver — IAM git:UpdateWebhook — write

dcloud git webhook-deliveries redeliver <repoId> <hookId> <deliveryId>

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<repoId> --repo-id string uuid
<hookId> --hook-id string uuid
<deliveryId> --delivery-id string uuid
  • Queues a new delivery with its own id and the same body, signed with the current secret. Refused while the hook is inactive.

dcloud git access-tokens

HTTP credentials for cloning and pushing

Operation Method Path IAM action Effect
list GET /git/api/access-tokens git:ListAccessTokens read
create POST /git/api/access-tokens git:CreateAccessToken write
delete DELETE /git/api/access-tokens/{id} git:DeleteAccessToken write

dcloud git access-tokens list

List your git access tokens

GET /git/api/access-tokens — IAM git:ListAccessTokens — read

dcloud git access-tokens list

dcloud git access-tokens create

Create a git access token and return it once

POST /git/api/access-tokens — IAM git:CreateAccessToken — write

dcloud git access-tokens create --name <value> [flags]
Flag In Required Notes
--name <value> body yes 1-64 chars · A name to recognise the token by
--expires-in-days <number> body integer, 1-365 · Days until the token expires; it never expires when absent
--access <read|write> body read: clone, fetch and API reads only; write (default): also push and writes
--repository-ids <value> body repeatable · Only these repositories; omit for every repository you can reach

dcloud git access-tokens delete

Revoke a git access token

DELETE /git/api/access-tokens/{id} — IAM git:DeleteAccessToken — write

dcloud git access-tokens delete <id>

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<id> --id string uuid

dcloud git ssh-keys

Your SSH public keys for git over SSH

Operation Method Path IAM action Effect
list GET /git/api/ssh-keys git:ListAccessTokens read
create POST /git/api/ssh-keys git:RegisterSshKey write
delete DELETE /git/api/ssh-keys/{id} git:DeleteSshKey write

dcloud git ssh-keys list

List your registered SSH keys

GET /git/api/ssh-keys — IAM git:ListAccessTokens — read

dcloud git ssh-keys list
  • Guarded by git:ListAccessTokens rather than a key-specific read action — the git descriptor has no ListSshKeys.

dcloud git ssh-keys create

Register an SSH public key

POST /git/api/ssh-keys — IAM git:RegisterSshKey — write

dcloud git ssh-keys create --name <value> --public-key <value>
Flag In Required Notes
--name <value> body yes 1-64 chars · A name to recognise the key by, e.g. the laptop
--public-key <value> body yes 1-4000 chars · The OpenSSH public key line, e.g. ssh-ed25519 AAAA… comment

dcloud git ssh-keys delete

Remove a registered SSH key

DELETE /git/api/ssh-keys/{id} — IAM git:DeleteSshKey — write

dcloud git ssh-keys delete <id>

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<id> --id string uuid

dcloud git attachments

Images and video attached to pull request comments

Operation Method Path IAM action Effect
get GET /git/api/attachments/{id} git:GetRepository read

dcloud git attachments get

Fetch an attachment

GET /git/api/attachments/{id} — IAM git:GetRepository — read

dcloud git attachments get <id>

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<id> --id string uuid
  • Returns raw bytes with their own content type, written straight to stdout.
  • Access is re-checked against the repository the attachment belongs to, so losing repo access loses the attachment.

dcloud git github

Connect GitHub: installations of the platform's GitHub App, repositories mirrored and pushed back through them

Operation Method Path IAM action Effect
list-installations GET /git/api/github/installations git:ListGithubInstallations read
disconnect-installation DELETE /git/api/github/installations/{id} git:ConnectGithub write
mirror POST /git/api/github/installations/{id}/mirror git:ConnectGithub write
set-shadow-ci PUT /git/api/github/repositories/{repoId}/shadow-ci git:UpdateRepository write
set-push-back PUT /git/api/github/repositories/{repoId}/push-back git:ConfigurePushMirror write

dcloud git github list-installations

List connected GitHub accounts and the repositories each covers

GET /git/api/github/installations — IAM git:ListGithubInstallations — read

dcloud git github list-installations

dcloud git github disconnect-installation

Disconnect a GitHub account; its mirrors stop syncing

DELETE /git/api/github/installations/{id} — IAM git:ConnectGithub — write

dcloud git github disconnect-installation <id>

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<id> --id string uuid

dcloud git github mirror

Mirror a GitHub repository the installation covers (no token kept)

POST /git/api/github/installations/{id}/mirror — IAM git:ConnectGithub — write

dcloud git github mirror <id> --repository <value> [flags]

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<id> --id string uuid
Flag In Required Notes
--repository <value> body yes owner/name on GitHub
--name <value> body Name here; GitHub’s name when omitted
--shadow-ci body Run its workflows here on every push to the default branch (capped)
  • Answers 202. Needs git:CreateRepository as well as git:ConnectGithub.

dcloud git github set-shadow-ci

Turn shadow CI on or off for a mirror (3,000 runner minutes a month per repository, 10,000 per organization, 2 runs at once)

PUT /git/api/github/repositories/{repoId}/shadow-ci — IAM git:UpdateRepository — write

dcloud git github set-shadow-ci <repoId> --enabled

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<repoId> --repo-id string uuid
Flag In Required Notes
--enabled body yes true runs its workflows here on every mirrored push

dcloud git github set-push-back

Push a repository back to GitHub after every push, through the App

PUT /git/api/github/repositories/{repoId}/push-back — IAM git:ConfigurePushMirror — write

dcloud git github set-push-back <repoId> --installation <value> --repository <value>

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<repoId> --repo-id string uuid
Flag In Required Notes
--installation <value> body yes uuid · The installation (its id here)
--repository <value> body yes owner/name on GitHub to push to
  • Replaces any push mirror the repository had. Needs git:ConnectGithub as well.

Not in the CLI: git routes the surface does not describe

These routes exist and are reachable over HTTP. They are deliberately absent from the description, so there is no command for them. The reason is recorded next to the service so a gap has to be stated out loud and stops being stateable the moment the route goes.

Route Why it has no command
GET /git/api/github-app/install A browser redirect to GitHub's install page, not an API call
GET /git/api/github-app/installed GitHub's redirect back after an install (OAuth code), not an API call
POST /git/api/github-app/webhook GitHub's webhook deliveries, signed with the App's secret; not a caller
POST /git/api/repositories/{repoId}/attachments multipart/form-data upload — this surface models JSON bodies only, so the file field has no schema to declare
POST /git/api/repositories/{repoId}/releases/{releaseId}/assets multipart/form-data upload (field file, optional ?name=; git:UpdateRelease, up to 2 GiB) — this surface models JSON bodies only
POST /git/api/markdown/preview Authenticated but not IAM-gated — renders the caller own text and touches no repository, so there is no resource to authorize against

dcloud kms

KMS. Base path /kms/api.

dcloud kms ssh-key-pairs

ED25519 key pairs for instance login — private keys are never stored

Operation Method Path IAM action Effect
list GET /kms/api/ssh-key-pairs kms:ListSshKeyPairs read
get GET /kms/api/ssh-key-pairs/{id} kms:GetSshKeyPair read
import POST /kms/api/ssh-key-pairs/import kms:ImportSshKeyPair write
import-from-source POST /kms/api/ssh-key-pairs/from-source kms:ImportSshKeyPair write
sync POST /kms/api/ssh-key-pairs/{id}/sync kms:ImportSshKeyPair write
generate POST /kms/api/ssh-key-pairs/generate kms:GenerateSshKeyPair write
delete DELETE /kms/api/ssh-key-pairs/{id} kms:DeleteSshKeyPair write

dcloud kms ssh-key-pairs list

List SSH key pairs

GET /kms/api/ssh-key-pairs — IAM kms:ListSshKeyPairs — read

dcloud kms ssh-key-pairs list

dcloud kms ssh-key-pairs get

Describe one SSH key pair

GET /kms/api/ssh-key-pairs/{id} — IAM kms:GetSshKeyPair — read

dcloud kms ssh-key-pairs get <id>

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<id> --id string uuid

dcloud kms ssh-key-pairs import

Import an existing SSH public key

POST /kms/api/ssh-key-pairs/import — IAM kms:ImportSshKeyPair — write

dcloud kms ssh-key-pairs import --name <value> --public-key <value> [flags]
Flag In Required Notes
--name <value> body yes 1-64 chars
--public-key <value> body yes min 1 chars
--upload-to-hetzner body server default true
--tags <key=value> body repeatable · key=value · Tags for the new resource, e.g. {"env": "prod", "project": "shop"}. Keys your organization marks required must be present, or the create is refused with the missing keys (GET /tags/api/keys lists them).

dcloud kms ssh-key-pairs import-from-source

Add a key pair whose public key comes from a password manager and follows it

POST /kms/api/ssh-key-pairs/from-source — IAM kms:ImportSshKeyPair — write

dcloud kms ssh-key-pairs import-from-source --name <value> --reference <value> [flags]
Flag In Required Notes
--name <value> body yes 1-64 chars
--reference <value> body yes 1-512 chars
--source <value> body 2-63 chars
--upload-to-hetzner body server default true
--tags <key=value> body repeatable · key=value · Tags for the new resource, e.g. {"env": "prod", "project": "shop"}. Keys your organization marks required must be present, or the create is refused with the missing keys (GET /tags/api/keys lists them).
  • May check secrets:UseSecretSource instead, decided by server-side state the caller cannot see. A caller needs all of them to be sure of not getting a 403.
  • reference: op://vault/item/public key (a 1Password SSH Key item) or vault://mount/path#public_key. Only a public key is accepted; a reference to a private key is refused. The source sync keeps it in step: a changed key replaces the stored one and is uploaded anew; instances keep the key they booted with.

dcloud kms ssh-key-pairs sync

Re-read a synced key pair’s public key through its source now

POST /kms/api/ssh-key-pairs/{id}/sync — IAM kms:ImportSshKeyPair — write

dcloud kms ssh-key-pairs sync <id>

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<id> --id string uuid
  • May check secrets:SyncSecret instead, decided by server-side state the caller cannot see. A caller needs all of them to be sure of not getting a 403.

dcloud kms ssh-key-pairs generate

Generate a key pair and return the private key once

POST /kms/api/ssh-key-pairs/generate — IAM kms:GenerateSshKeyPair — write

dcloud kms ssh-key-pairs generate --name <value> [flags]
Flag In Required Notes
--name <value> body yes 1-64 chars
--comment <value> body max 128 chars
--upload-to-hetzner body server default true
--tags <key=value> body repeatable · key=value · Tags for the new resource, e.g. {"env": "prod", "project": "shop"}. Keys your organization marks required must be present, or the create is refused with the missing keys (GET /tags/api/keys lists them).
  • The private key is in the response and is never stored or retrievable again.

dcloud kms ssh-key-pairs delete

Delete an SSH key pair

DELETE /kms/api/ssh-key-pairs/{id} — IAM kms:DeleteSshKeyPair — write

dcloud kms ssh-key-pairs delete <id>

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<id> --id string uuid

dcloud kms keys

Customer master keys

Operation Method Path IAM action Effect
list GET /kms/api/keys kms:ListKeys read
get GET /kms/api/keys/{id} kms:GetKey read
create POST /kms/api/keys kms:CreateKey write
set-status PATCH /kms/api/keys/{id} kms:UpdateKey write
make-default POST /kms/api/keys/{id}/make-default kms:UpdateKey write
schedule-deletion POST /kms/api/keys/{id}/schedule-deletion kms:ScheduleKeyDeletion write
import-parameters POST /kms/api/keys/{id}/import-parameters kms:GetParametersForImport read
import POST /kms/api/keys/{id}/import kms:ImportKeyMaterial write
delete-material DELETE /kms/api/keys/{id}/material kms:DeleteImportedKeyMaterial write
usage GET /kms/api/keys/{id}/usage kms:GetKey read
cancel-deletion POST /kms/api/keys/{id}/cancel-deletion kms:CancelKeyDeletion write
delete DELETE /kms/api/keys/{id} kms:ScheduleKeyDeletion write
encrypt POST /kms/api/keys/{id}/encrypt kms:Encrypt write
decrypt POST /kms/api/keys/{id}/decrypt kms:Decrypt write

dcloud kms keys list

List keys

GET /kms/api/keys — IAM kms:ListKeys — read

dcloud kms keys list

dcloud kms keys get

Describe one key

GET /kms/api/keys/{id} — IAM kms:GetKey — read

dcloud kms keys get <id>

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<id> --id string uuid

dcloud kms keys create

Create a key

POST /kms/api/keys — IAM kms:CreateKey — write

dcloud kms keys create [flags]
Flag In Required Notes
--name <value> body /^[a-z0-9][a-z0-9._-]{0,62}$/
--description <value> body max 256 chars
--usage <json> body JSON · server default "encrypt_decrypt"
--origin <ews|external> body server default "ews"
--tags <key=value> body repeatable · key=value · Tags for the new resource, e.g. {"env": "prod", "project": "shop"}. Keys your organization marks required must be present, or the create is refused with the missing keys (GET /tags/api/keys lists them).

dcloud kms keys set-status

Enable, disable or rename a key, or change its description

PATCH /kms/api/keys/{id} — IAM kms:UpdateKey — write

dcloud kms keys set-status <id> [flags]

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<id> --id string uuid
Flag In Required Notes
--status <enabled|disabled> body
--name <value> body /^[a-z0-9][a-z0-9._-]{0,62}$/
--description <value> body max 256 chars · nullable

dcloud kms keys make-default

Make a key the default: new secrets and managed databases are encrypted under it

POST /kms/api/keys/{id}/make-default — IAM kms:UpdateKey — write

dcloud kms keys make-default <id>

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<id> --id string uuid
  • Only an enabled encrypt/decrypt key (409 otherwise). With no default chosen, the oldest enabled key is the default; default in the key list says which one it is now.

dcloud kms keys schedule-deletion

Schedule a key for deletion after a waiting period

POST /kms/api/keys/{id}/schedule-deletion — IAM kms:ScheduleKeyDeletion — write

dcloud kms keys schedule-deletion <id> [flags]

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<id> --id string uuid
Flag In Required Notes
--pending-window-in-days <number> body integer, 7-30 · server default 30
  • 409 default_key for the default key: make another key the default first.

dcloud kms keys import-parameters

Get a wrapping public key and a single-use import token for an imported key

POST /kms/api/keys/{id}/import-parameters — IAM kms:GetParametersForImport — read

dcloud kms keys import-parameters <id> [flags]

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<id> --id string uuid
Flag In Required Notes
--wrapping-algorithm <RSAES_OAEP_SHA_256|RSA_AES_KEY_WRAP_SHA_256> body server default "RSAES_OAEP_SHA_256"
  • Only for a key created with origin "external". Returns an RSA-3072 public key (SubjectPublicKeyInfo DER, base64) and an import token, both valid 24 hours. Wrap a 32-byte AES-256 key with RSAES_OAEP_SHA_256 (RSA-OAEP, SHA-256, MGF1 SHA-256) or RSA_AES_KEY_WRAP_SHA_256 (RSA-OAEP of a fresh AES-256 key, then AES-KWP RFC 5649 of the material, concatenated).

dcloud kms keys import

Import your wrapped key material; a pending_import key becomes enabled

POST /kms/api/keys/{id}/import — IAM kms:ImportKeyMaterial — write

dcloud kms keys import <id> --import-token <value> --encrypted-key-material <value> [flags]

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<id> --id string uuid
Flag In Required Notes
--import-token <value> body yes 10-200 chars
--encrypted-key-material <value> body yes 1-4096 chars
--expires-at <value> body datetime
  • Re-importing is accepted only for the same material (checked by key check value), so data encrypted under the key opens again. Optional expiresAt: the platform deletes the material then, as DeleteImportedKeyMaterial would.

dcloud kms keys delete-material

Delete imported key material — everything under the key is unreadable until re-imported

DELETE /kms/api/keys/{id}/material — IAM kms:DeleteImportedKeyMaterial — write

dcloud kms keys delete-material <id>

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<id> --id string uuid
  • The key becomes pending_import. Secrets, volumes, databases and caches under it stop opening.

dcloud kms keys usage

Count what the key protects: secrets, volumes by kind, databases, caches

GET /kms/api/keys/{id}/usage — IAM kms:GetKey — read

dcloud kms keys usage <id>

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<id> --id string uuid
  • notCovered lists what customer keys do not encrypt yet (object storage among them).

dcloud kms keys cancel-deletion

Cancel a pending key deletion

POST /kms/api/keys/{id}/cancel-deletion — IAM kms:CancelKeyDeletion — write

dcloud kms keys cancel-deletion <id>

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<id> --id string uuid
  • The key returns to the status it had when the deletion was scheduled (enabled or disabled). 409 when no deletion is scheduled.

dcloud kms keys delete

Delete a key whose waiting period has elapsed

DELETE /kms/api/keys/{id} — IAM kms:ScheduleKeyDeletion — write

dcloud kms keys delete <id>

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<id> --id string uuid
  • Guarded by kms:ScheduleKeyDeletion rather than a delete-specific action — a key must be scheduled first, so this only finishes what that started. 409 before deletionScheduledAt: the waiting period cannot be cut short, only cancelled.

dcloud kms keys encrypt

Encrypt UTF-8 plaintext with a key

POST /kms/api/keys/{id}/encrypt — IAM kms:Encrypt — write

dcloud kms keys encrypt <id> --plaintext <value>

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<id> --id string uuid
Flag In Required Notes
--plaintext <value> body yes min 1 chars

dcloud kms keys decrypt

Decrypt a ciphertext blob with a key

POST /kms/api/keys/{id}/decrypt — IAM kms:Decrypt — write

dcloud kms keys decrypt <id> --ciphertext <value> --iv <value> --tag <value>

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<id> --id string uuid
Flag In Required Notes
--ciphertext <value> body yes min 1 chars
--iv <value> body yes min 1 chars
--tag <value> body yes min 1 chars

dcloud secrets

Secrets. Base path /secrets/api.

dcloud secrets secrets

Values encrypted at rest under a CMK

The resource is named after its service, so every command in this section reads dcloud secrets secrets <operation>. That is the literal three-word shape the dispatcher takes; there is no shorter spelling today.

Operation Method Path IAM action Effect
list GET /secrets/api/secrets secrets:ListSecrets read
get GET /secrets/api/secrets/{id} secrets:GetSecret read
flow GET /secrets/api/secrets/{id}/flow secrets:GetSecret read
app-flow GET /secrets/api/apps/{appId}/flow deploy:DescribeApp read
get-value GET /secrets/api/secrets/{id}/value secrets:GetSecretValue read, sensitive
create POST /secrets/api/secrets secrets:CreateSecret write
sync POST /secrets/api/secrets/{id}/sync secrets:SyncSecret write
rotate POST /secrets/api/secrets/{id}/rotate secrets:RotateSecret write
list-versions GET /secrets/api/secrets/{id}/versions secrets:ListSecretVersions read
rollback POST /secrets/api/secrets/{id}/rollback secrets:RollbackSecret write
list-grants GET /secrets/api/secrets/{id}/grants secrets:ListSecretGrants read
grant POST /secrets/api/secrets/{id}/grants secrets:GrantSecret write
revoke-grant DELETE /secrets/api/secrets/{id}/grants secrets:RevokeSecretGrant write
access-log GET /secrets/api/secrets/{id}/access secrets:GetSecretAccessLog read
update PATCH /secrets/api/secrets/{id} secrets:UpdateSecret write
delete DELETE /secrets/api/secrets/{id} secrets:DeleteSecret write
bulk-move POST /secrets/api/secrets/bulk/move secrets:UpdateSecret write
bulk-grant POST /secrets/api/secrets/bulk/grant secrets:GrantSecret write
bulk-revoke POST /secrets/api/secrets/bulk/revoke secrets:RevokeSecretGrant write
bulk-delete POST /secrets/api/secrets/bulk/delete secrets:DeleteSecret write

dcloud secrets secrets list

List secrets without their values

GET /secrets/api/secrets — IAM secrets:ListSecrets — read

dcloud secrets secrets list

dcloud secrets secrets get

Describe one secret without its value

GET /secrets/api/secrets/{id} — IAM secrets:GetSecret — read

dcloud secrets secrets get <id>

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<id> --id string uuid

dcloud secrets secrets flow

Show where a secret comes from and every consumer it goes to, with last reads

GET /secrets/api/secrets/{id}/flow — IAM secrets:GetSecret — read

dcloud secrets secrets flow <id>

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<id> --id string uuid
  • Origin is the store or a source reference with its sync status. Each consumer (app env var, database/cache binding, registry login, workflow grant, source credential, database master password) carries the version it last read and stale when that is older than the active version. Last reads need secrets:GetSecretAccessLog; without it reads is "hidden".

dcloud secrets secrets app-flow

List every secret an app uses, where each comes from and the version it last read

GET /secrets/api/apps/{appId}/flow — IAM deploy:DescribeApp — read

dcloud secrets secrets app-flow <appId>

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<appId> --app-id string uuid
  • Secrets the caller may not describe (secrets:GetSecret) are left out.

dcloud secrets secrets get-value

Reveal the decrypted value of a secret

GET /secrets/api/secrets/{id}/value — IAM secrets:GetSecretValue — read, sensitive

dcloud secrets secrets get-value <id>

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<id> --id string uuid
  • Sensitive read — denials are recorded in the audit log.

dcloud secrets secrets create

Create a secret encrypted under a CMK — from a value, or synced from a source reference

POST /secrets/api/secrets — IAM secrets:CreateSecret — write

dcloud secrets secrets create --name <value> --key-id <value> [flags]
Flag In Required Notes
--name <value> body yes 1-128 chars, /^[A-Z][A-Z0-9_]*$/ · The name apps and workflows look it up by: UPPER_SNAKE_CASE starting with a letter, 1 to 128 characters. Unique per environment (and once as the Default): a taken name is 409.
--description <value> body max 256 chars · Free-text description, up to 256 characters
--environment-id <value> body uuid · nullable · The environment it overrides the Default value in (an environment id). Omitted or null: the Default value every environment falls back to. An unknown id is 404.
--key-id <value> body yes The KMS key (CMK) to encrypt it under. Required in the API; the console pre-selects the organization’s default key. Unknown: 404; not enabled: 409; not an encrypt_decrypt key: 400.
--value <value> body min 1 chars · The plaintext value, at least 1 character; stored as version 1. Give exactly one of value and reference (both or neither is 400).
--reference <json> body JSON · Make it a synced secret: { ref, source?, sourceId? }. ref is op://vault/item/field or vault://mount/path#key, up to 512 characters; it must resolve now (else 422, or 502 when the source itself fails). Without source or sourceId the source whose credential reaches the vault is used; several such sources is 409 naming them. A reference another secret already syncs is 409. Needs secrets:UseSecretSource on the source.
--scope <organization|project|resource> body A label for what the secret belongs to: organization, project or resource. Omitted: organization. It grants nothing.
--scope-ref <value> body max 500 chars · nullable · What scope names: a project slug or a resource RN, up to 500 characters. Omitted or null: none.
--rotation-interval-days <number> body integer, 1-3650 · nullable · Days between rotations, 1 to 3650: sets a due date (rotatesAt); it does not generate values. Omitted or null: no rotation policy.
--group <value> body max 122 chars · nullable · Where to file it, e.g. dialog/auth: up to three segments of lower-case letters, digits and hyphens (up to 40 each), at most 122 characters. Null: Ungrouped. Omitted: Ungrouped, or for a synced secret its vault and item path. A name that already exists in another environment keeps that name’s group whatever is sent.
--tags <key=value> body repeatable · key=value · Tags for the new resource, e.g. {"env": "prod", "project": "shop"}. Keys your organization marks required must be present, or the create is refused with the missing keys (GET /tags/api/keys lists them).
  • May check secrets:UseSecretSource instead, decided by server-side state the caller cannot see. A caller needs all of them to be sure of not getting a 403.
  • Give value, or reference: { ref: "op://vault/item/field", source? } for a synced secret. Without source (a source name) the source whose token reaches the vault is used; several such sources is a refusal naming them. Needs secrets:UseSecretSource on the source; the reference must resolve now.

dcloud secrets secrets sync

Refresh a synced secret from its source now

POST /secrets/api/secrets/{id}/sync — IAM secrets:SyncSecret — write

dcloud secrets secrets sync <id>

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<id> --id string uuid

dcloud secrets secrets rotate

Store a new value as the current version

POST /secrets/api/secrets/{id}/rotate — IAM secrets:RotateSecret — write

dcloud secrets secrets rotate <id> --value <value>

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<id> --id string uuid
Flag In Required Notes
--value <value> body yes min 1 chars · The new plaintext value, at least 1 character. It becomes the next version; the current one is retired, not deleted.

dcloud secrets secrets list-versions

List stored versions of a secret

GET /secrets/api/secrets/{id}/versions — IAM secrets:ListSecretVersions — read

dcloud secrets secrets list-versions <id>

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<id> --id string uuid

dcloud secrets secrets rollback

Promote a retired version back to current

POST /secrets/api/secrets/{id}/rollback — IAM secrets:RollbackSecret — write

dcloud secrets secrets rollback <id> --version <number>

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<id> --id string uuid
Flag In Required Notes
--version <number> body yes integer, min 1 · The version number to make active again (see list-versions). The active one is retired. A version the secret does not have is 404.

dcloud secrets secrets list-grants

List which consumers may read a secret

GET /secrets/api/secrets/{id}/grants — IAM secrets:ListSecretGrants — read

dcloud secrets secrets list-grants <id>

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<id> --id string uuid

dcloud secrets secrets grant

Grant a consumer access to a secret

POST /secrets/api/secrets/{id}/grants — IAM secrets:GrantSecret — write

dcloud secrets secrets grant <id> --consumer <actions|deploy|cli|code|compute|registry> [flags]

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<id> --id string uuid
Flag In Required Notes
--consumer <actions|deploy|cli|code|compute|registry> body yes Which consumer may read the value, e.g. actions (CI runs), deploy (deployed apps) or registry (pull-through cache credentials)
--repository-id <value> body nullable · Limit an actions grant to one repository; omitted or null means every repository
--ttl-days <number> body integer, 1-3650 · nullable · Days until the grant expires; omitted or null means it does not expire

dcloud secrets secrets revoke-grant

Revoke a consumer grant

DELETE /secrets/api/secrets/{id}/grants — IAM secrets:RevokeSecretGrant — write

dcloud secrets secrets revoke-grant <id> --consumer <actions|deploy|cli|code|compute|registry> [flags]

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<id> --id string uuid
Flag In Required Notes
--consumer <actions|deploy|cli|code|compute|registry> body yes Which consumer may read the value, e.g. actions (CI runs), deploy (deployed apps) or registry (pull-through cache credentials)
--repository-id <value> body nullable · Limit an actions grant to one repository; omitted or null means every repository
  • A DELETE that carries a JSON body — the consumer is named in the body, not the path. An omitted repositoryId revokes the every-repository grant, not every scoped one.

dcloud secrets secrets access-log

Show who has actually read a secret value

GET /secrets/api/secrets/{id}/access — IAM secrets:GetSecretAccessLog — read

dcloud secrets secrets access-log <id>

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<id> --id string uuid

dcloud secrets secrets update

Change a secret’s description, group or rotation interval (never its value)

PATCH /secrets/api/secrets/{id} — IAM secrets:UpdateSecret — write

dcloud secrets secrets update <id> [flags]

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<id> --id string uuid
Flag In Required Notes
--description <value> body max 256 chars · nullable · Free-text description, up to 256 characters. Null clears it; omitted: unchanged.
--group <value> body max 122 chars · nullable · Where the name is filed, e.g. dialog/auth: up to three lower-case segments of letters, digits and hyphens, at most 122 characters. Null: Ungrouped; omitted: unchanged. Moves the secret of this name in every environment and needs secrets:UpdateSecret on each, else 403 and nothing moves.
--rotation-interval-days <number> body integer, 1-3650 · nullable · Days between rotations, 1 to 3650: sets the due date (rotatesAt) to that many days from now; nothing rotates by itself. Null removes the policy; omitted: unchanged.
  • A group belongs to the name: changing it moves every environment’s secret of this name, and needs secrets:UpdateSecret on each.

dcloud secrets secrets delete

Delete a secret

DELETE /secrets/api/secrets/{id} — IAM secrets:DeleteSecret — write

dcloud secrets secrets delete <id>

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<id> --id string uuid

dcloud secrets secrets bulk-move

Move secrets to a group (null: Ungrouped), answered per secret

POST /secrets/api/secrets/bulk/move — IAM secrets:UpdateSecret — write

dcloud secrets secrets bulk-move --ids <value> --group <value>
Flag In Required Notes
--ids <value> body yes repeatable · Secret ids, 1 to 500. Each is answered on its own: an unknown id or a refused permission fails that item only.
--group <value> body yes max 122 chars · nullable · The group to file the names under, e.g. dialog/auth (up to three lower-case segments, at most 122 characters), or null for Ungrouped. Required.
  • Each secret’s every environment row moves; a name with one refused row does not move. Not atomic: results says which moved.

dcloud secrets secrets bulk-grant

Grant one consumer access to many secrets, answered per secret

POST /secrets/api/secrets/bulk/grant — IAM secrets:GrantSecret — write

dcloud secrets secrets bulk-grant --consumer <actions|deploy|cli|code|compute|registry> --ids <value> [flags]
Flag In Required Notes
--consumer <actions|deploy|cli|code|compute|registry> body yes Which consumer may read the value, e.g. actions (CI runs), deploy (deployed apps) or registry (pull-through cache credentials)
--repository-id <value> body nullable · Limit an actions grant to one repository; omitted or null means every repository
--ttl-days <number> body integer, 1-3650 · nullable · Days until the grant expires; omitted or null means it does not expire
--ids <value> body yes repeatable · Secret ids, 1 to 500. Each is answered on its own: an unknown id or a refused permission fails that item only.

dcloud secrets secrets bulk-revoke

Revoke one consumer’s grant on many secrets, answered per secret

POST /secrets/api/secrets/bulk/revoke — IAM secrets:RevokeSecretGrant — write

dcloud secrets secrets bulk-revoke --consumer <actions|deploy|cli|code|compute|registry> --ids <value> [flags]
Flag In Required Notes
--consumer <actions|deploy|cli|code|compute|registry> body yes Which consumer may read the value, e.g. actions (CI runs), deploy (deployed apps) or registry (pull-through cache credentials)
--repository-id <value> body nullable · Limit an actions grant to one repository; omitted or null means every repository
--ids <value> body yes repeatable · Secret ids, 1 to 500. Each is answered on its own: an unknown id or a refused permission fails that item only.

dcloud secrets secrets bulk-delete

Delete many secrets and every version of them, answered per secret

POST /secrets/api/secrets/bulk/delete — IAM secrets:DeleteSecret — write

dcloud secrets secrets bulk-delete --ids <value>
Flag In Required Notes
--ids <value> body yes repeatable · Secret ids, 1 to 500. Each is answered on its own: an unknown id or a refused permission fails that item only.
  • A source’s credential is refused (disconnect the source instead).

dcloud secrets groups

Where secrets are filed: paths like dialog/auth, up to three segments

Operation Method Path IAM action Effect
list GET /secrets/api/groups secrets:ListSecrets read

dcloud secrets groups list

The group tree with how many secrets each group holds

GET /secrets/api/groups — IAM secrets:ListSecrets — read

dcloud secrets groups list
  • Counts include every group below. A group exists while a secret is filed in it; move secrets with secrets update --group or secrets bulk-move.

dcloud secrets sources

External secret managers (1Password) whose references become synced secrets

Operation Method Path IAM action Effect
providers GET /secrets/api/source-providers secrets:ListSecretSources read
list GET /secrets/api/sources secrets:ListSecretSources read
create POST /secrets/api/sources secrets:CreateSecretSource write
update PATCH /secrets/api/sources/{id} secrets:UpdateSecretSource write
test POST /secrets/api/sources/{id}/test secrets:UseSecretSource write
sync POST /secrets/api/sources/{id}/sync secrets:SyncSecret write
check POST /secrets/api/sources/{id}/check secrets:UseSecretSource write
delete DELETE /secrets/api/sources/{id} secrets:DeleteSecretSource write

dcloud secrets sources providers

List the providers a source can be, and their reference syntax

GET /secrets/api/source-providers — IAM secrets:ListSecretSources — read

dcloud secrets sources providers

dcloud secrets sources list

List connected sources with sync status (never the credential)

GET /secrets/api/sources — IAM secrets:ListSecretSources — read

dcloud secrets sources list

dcloud secrets sources create

Connect a source — the credential is verified, then stored as a secret

POST /secrets/api/sources — IAM secrets:CreateSecretSource — write

dcloud secrets sources create --name <value> --provider <onepassword|vault> --credential <value> [flags]
Flag In Required Notes
--name <value> body yes 2-63 chars, /^[a-z0-9][a-z0-9-]*$/ · The source’s name, 2 to 63 lower-case letters, digits and hyphens, unique in the organization (409 if taken). Its credential is stored as the secret SOURCE__TOKEN, which must not exist yet (409).
--description <value> body max 256 chars · Free-text description, up to 256 characters
--provider <onepassword|vault> body yes onepassword (a 1Password service account) or vault (HashiCorp Vault or OpenBao)
--credential <value> body yes 8-8192 chars · The provider credential, 8 to 8192 characters: a 1Password service-account token (ops_…), a Vault token, or an AppRole secret ID. Verified with the provider before anything is stored (rejected: 422), then encrypted as a secret.
--config <key=value> body repeatable · key=value · Provider settings, at most 16 keys, each value up to 512 characters. Vault/OpenBao: address (https, required), namespace, authMethod (token or approle), roleId and approleMount (AppRole). 1Password: none. Omitted: {}. Settings the provider does not accept are 400.
--key-id <value> body uuid · The KMS key the credential is encrypted under. Omitted: the organization’s default key, else its first enabled encrypt/decrypt key (none: 409). A key that is unknown, disabled or not encrypt/decrypt is 409.
--refresh-interval-minutes <number> body integer, 5-1440 · Minutes between scheduled syncs, 5 to 1440. Omitted: 60.
  • May check secrets:CreateSecret instead, decided by server-side state the caller cannot see. A caller needs all of them to be sure of not getting a 403.

dcloud secrets sources update

Rename the source, replace the credential or change the refresh interval

PATCH /secrets/api/sources/{id} — IAM secrets:UpdateSecretSource — write

dcloud secrets sources update <id> [flags]

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<id> --id string uuid
Flag In Required Notes
--name <value> body 2-63 chars, /^[a-z0-9][a-z0-9-]*$/ · New name, 2 to 63 lower-case letters, digits and hyphens; its credential secret is renamed to SOURCE__TOKEN with it. A taken name (or credential secret name) is 409. Synced secrets follow the source by id.
--description <value> body max 256 chars · nullable · Free-text description, up to 256 characters. Null clears it; omitted: unchanged.
--credential <value> body 8-8192 chars · A replacement credential, 8 to 8192 characters. Verified first (rejected: 422), then written as a new version of the credential secret. Omitted: unchanged.
--config <key=value> body repeatable · key=value · Replaces the provider settings whole (the same keys as on create). Verified with the new or the stored credential first: 400 for invalid settings, 422 when the provider refuses them. Omitted: unchanged.
--refresh-interval-minutes <number> body integer, 5-1440 · Minutes between scheduled syncs, 5 to 1440. Omitted: unchanged.

dcloud secrets sources test

Check the stored credential still works

POST /secrets/api/sources/{id}/test — IAM secrets:UseSecretSource — write

dcloud secrets sources test <id>

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<id> --id string uuid

dcloud secrets sources sync

Refresh every secret synced from this source now

POST /secrets/api/sources/{id}/sync — IAM secrets:SyncSecret — write

dcloud secrets sources sync <id>

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<id> --id string uuid

dcloud secrets sources check

Check which references resolve — ok/error per reference, never a value

POST /secrets/api/sources/{id}/check — IAM secrets:UseSecretSource — write

dcloud secrets sources check <id> --references <value>

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<id> --id string uuid
Flag In Required Notes
--references <value> body yes repeatable · 1-512 chars · References to try through this source, 1 to 1000, each up to 512 characters; trimmed and de-duplicated. Each is answered ok or with its error; no value is returned.

dcloud secrets sources delete

Disconnect a source (refused while secrets still sync from it)

DELETE /secrets/api/sources/{id} — IAM secrets:DeleteSecretSource — write

dcloud secrets sources delete <id>

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<id> --id string uuid

dcloud secrets environments

Environments (dev, staging, prod …): the same secret name once per environment

Operation Method Path IAM action Effect
list GET /secrets/api/environments secrets:ListSecretEnvironments read
create POST /secrets/api/environments secrets:CreateSecretEnvironment write
update PATCH /secrets/api/environments/{id} secrets:UpdateSecretEnvironment write
delete DELETE /secrets/api/environments/{id} secrets:DeleteSecretEnvironment write
diff GET /secrets/api/environments/diff secrets:ListSecrets read
promote POST /secrets/api/secrets/{id}/promote secrets:PromoteSecret write
promote-many POST /secrets/api/environments/promote secrets:PromoteSecret write
matrix GET /secrets/api/environments/matrix secrets:ListSecrets read
set-app-environment PUT /secrets/api/apps/{appId}/environment deploy:UpdateApp write

dcloud secrets environments list

List environments in promotion order, with their secret and app counts

GET /secrets/api/environments — IAM secrets:ListSecretEnvironments — read

dcloud secrets environments list
  • dev, staging and prod are created on first use.

dcloud secrets environments create

Add an environment

POST /secrets/api/environments — IAM secrets:CreateSecretEnvironment — write

dcloud secrets environments create --slug <value> --name <value> [flags]
Flag In Required Notes
--slug <value> body yes /^[a-z0-9][a-z0-9-]{0,62}$/ · Short id of the environment, e.g. qa: lower-case letters, digits and hyphens, starting with a letter or digit, at most 63 characters. Unique in the organization (an existing slug is refused with 409) and cannot be changed later. Workflow jobs name an environment by it.
--name <value> body yes 1-64 chars · Display name, e.g. QA. 1 to 64 characters.
--position <number> body integer, 0-10000 · Place in the promotion order, 0 to 10000; a higher number is later (Development 10, Staging 20, Production 30 to start with). Omitted: the last environment’s position plus 10.
--color <gray|blue|teal|green|amber|red|violet> body nullable · The dot shown beside the environment: gray, blue, teal, green, amber, red or violet. Null: automatic (from the slug).

dcloud secrets environments update

Rename an environment, move it in the promotion order or change its colour

PATCH /secrets/api/environments/{id} — IAM secrets:UpdateSecretEnvironment — write

dcloud secrets environments update <id> [flags]

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<id> --id string uuid
Flag In Required Notes
--name <value> body 1-64 chars · New display name, 1 to 64 characters. Omitted: unchanged. The slug cannot change.
--position <number> body integer, 0-10000 · New place in the promotion order, 0 to 10000; higher is later. Omitted: unchanged.
--color <gray|blue|teal|green|amber|red|violet> body nullable · The dot shown beside the environment: gray, blue, teal, green, amber, red or violet. Null: automatic (from the slug).

dcloud secrets environments delete

Delete an environment (refused while it holds secrets or apps)

DELETE /secrets/api/environments/{id} — IAM secrets:DeleteSecretEnvironment — write

dcloud secrets environments delete <id>

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<id> --id string uuid

dcloud secrets environments diff

Compare two environments by name: present where, and equal or not

GET /secrets/api/environments/diff — IAM secrets:ListSecrets — read

dcloud secrets environments diff --from <json> --to <json>
Flag In Required Notes
--from <json> query yes JSON · One side of the comparison: an environment id, or default for the Default values (shared, its old name, is accepted). An unknown environment id is 404.
--to <json> query yes JSON · The other side: an environment id, or default (shared is accepted). An unknown environment id is 404.
  • May check secrets:CompareSecretValues instead, decided by server-side state the caller cannot see. A caller needs all of them to be sure of not getting a 403.
  • from and to are environment ids or default (the value every environment falls back to). Equality is computed server-side and needs secrets:CompareSecretValues on both secrets (audited); otherwise the row is unknown with the reason. Values are never returned.

dcloud secrets environments promote

Copy a secret into another environment (or its source reference, if synced)

POST /secrets/api/secrets/{id}/promote — IAM secrets:PromoteSecret — write

dcloud secrets environments promote <id> --to-environment-id <value> [flags]

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<id> --id string uuid
Flag In Required Notes
--to-environment-id <value> body yes nullable · The environment to promote into (an environment id), or null for Default, the value every environment falls back to. The secret’s own environment is refused with 400; an unknown id with 404.
--reference <value> body 1-512 chars · Synced secrets only: the source reference the target should sync from, e.g. op://Production/db/password, up to 512 characters. Omitted for a synced secret: 409 with suggestedReference (the reference with the vault swapped for the target environment) to confirm and send back. Ignored for a stored secret.
  • May check secrets:CreateSecret or secrets:RotateSecret or secrets:UseSecretSource instead, decided by server-side state the caller cannot see. A caller needs all of them to be sure of not getting a 403.
  • A stored secret: its active value becomes a new version of the same-named secret in the target (created under the same key if missing). A synced secret: give reference; without it the answer is 409 with suggestedReference (the vault swapped for the target environment). Grants are not copied.

dcloud secrets environments promote-many

Promote many secrets into one environment; dryRun returns the plan first

POST /secrets/api/environments/promote — IAM secrets:PromoteSecret — write

dcloud secrets environments promote-many --to-environment-id <value> --items <value> [flags]
Flag In Required Notes
--to-environment-id <value> body yes nullable · The environment every item is promoted into, or null for Default. An item already in it is blocked; an unknown id blocks every item with 404.
--items <value> body yes repeatable · The secrets to promote, 1 to 500, each { secretId, reference? }. Promoted one at a time in this order; each is authorized and answered on its own.
--dry-run body true: answer with each item’s plan and write nothing (only value comparisons are made, each audited). Omitted or false: promote.
  • May check secrets:CreateSecret or secrets:RotateSecret or secrets:UseSecretSource or secrets:CompareSecretValues instead, decided by server-side state the caller cannot see. A caller needs all of them to be sure of not getting a 403.
  • Each item gets a plan: create, update, unchanged, not-compared (no secrets:CompareSecretValues), needs-reference (synced: confirm suggestedReference and send it as the item’s reference) or blocked (error). Run the dry run, then the same items without dryRun. Per item, not atomic.

dcloud secrets environments matrix

Every secret name × Default and each environment: what each environment resolves it to

GET /secrets/api/environments/matrix — IAM secrets:ListSecrets — read

dcloud secrets environments matrix [flags]
Flag In Required Notes
--compare <0|1> query 1: add a valueClass letter to each cell (the same letter, the same value), compared on the server; needs secrets:CompareSecretValues on each secret, each compare audited, refused ones counted in notCompared. Omitted or 0: no comparison.
--group <value> query max 122 chars · Only names filed in this group or a group below it, e.g. dialog or dialog/auth; up to 122 characters. Omitted: every group, Ungrouped included.
  • May check secrets:CompareSecretValues instead, decided by server-side state the caller cannot see. A caller needs all of them to be sure of not getting a 403.
  • resolves[envId].resolution is own, default (no own secret: the Default value) or missing; promotableFrom names an earlier environment that has it. compare=1 adds a valueClass letter per cell (same letter, same value), audited per secret. Values are never returned.

dcloud secrets environments set-app-environment

Set which environment an app’s secret names resolve in (null: shared only)

PUT /secrets/api/apps/{appId}/environment — IAM deploy:UpdateApp — write

dcloud secrets environments set-app-environment <appId> --environment-id <value>

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<appId> --app-id string uuid
Flag In Required Notes
--environment-id <value> body yes nullable · The environment the app’s secret names resolve in (its own secret, else the Default one), or null for Default values only. An unknown environment id is 404.

dcloud ecr

Container registry. Base path /ecr/api.

dcloud ecr repositories

Container image repositories

Operation Method Path IAM action Effect
list GET /ecr/api/repositories ecr:DescribeRepositories read
create POST /ecr/api/repositories ecr:CreateRepository write
get GET /ecr/api/repositories/{id} ecr:DescribeRepositories read
update PATCH /ecr/api/repositories/{id} ecr:UpdateRepository write
delete DELETE /ecr/api/repositories/{id} ecr:DeleteRepository write

dcloud ecr repositories list

List repositories

GET /ecr/api/repositories — IAM ecr:DescribeRepositories — read

dcloud ecr repositories list

dcloud ecr repositories create

Create a repository

POST /ecr/api/repositories — IAM ecr:CreateRepository — write

dcloud ecr repositories create --name <value> [flags]
Flag In Required Notes
--name <value> body yes 2-255 chars, /^[a-z0-9]+(?:(?:.||__|-+)[a-z0-9]+)*(?:/[a-z0-9]+(?:(?:.||__|-+)[a-z0-9]+))$/ · Repository name, unique in the organization: 2–255 characters of lowercase path components joined by / (team/api), each letters and digits joined by . _ __ or -. blobs, manifests, tags, referrers and uploads may not be a component. A taken name is refused with 409
--description <value> body max 256 chars · Free text shown with the repository, up to 256 characters; none when omitted
--visibility <private|public> body private: every pull needs a credential with ecr:PullImage. public: anyone can pull this repository’s images without credentials (read-only, and only the layers its own images reference). private when omitted
--tag-mutability <mutable|immutable> body immutable: a push that would move an existing tag to a different image is refused (re-pushing the same image is fine; deleting the tag is still allowed). mutable when omitted
--tag-mutability-exclusions <value> body repeatable · 1-128 chars, /^[A-Za-z0-9_.-]+$/ · Up to 10 tag patterns (letters, digits, _ . - and * as a glob, 1–128 characters) that stay mutable in an immutable repository, e.g. ["latest", "main-"]; none when omitted
--storage-quota-bytes <number> body integer, 1048576-1125899906842624 · nullable · Cap in bytes on every layer this repository holds, shared ones included: 1 MiB (1048576) to 1 PiB. null: no repository cap (the organization quota still applies). A push over it is refused; lowering it deletes nothing. No cap when omitted
--tags <key=value> body repeatable · key=value · Tags for the new resource, e.g. {"env": "prod", "project": "shop"}. Keys your organization marks required must be present, or the create is refused with the missing keys (GET /tags/api/keys lists them).
  • Public repositories serve anonymous pulls for their own images only; private is the default and is what a push creates.

dcloud ecr repositories get

Describe one repository

GET /ecr/api/repositories/{id} — IAM ecr:DescribeRepositories — read

dcloud ecr repositories get <id>

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<id> --id string uuid

dcloud ecr repositories update

Change visibility, tag immutability or description

PATCH /ecr/api/repositories/{id} — IAM ecr:UpdateRepository — write

dcloud ecr repositories update <id> [flags]

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<id> --id string uuid
Flag In Required Notes
--visibility <private|public> body private: every pull needs a credential with ecr:PullImage. public: anyone can pull this repository’s images without credentials (read-only, and only the layers its own images reference). Unchanged when omitted; public is reversible at any time
--tag-mutability <mutable|immutable> body immutable: a push that would move an existing tag to a different image is refused (re-pushing the same image is fine; deleting the tag is still allowed). Unchanged when omitted
--tag-mutability-exclusions <value> body repeatable · 1-128 chars, /^[A-Za-z0-9_.-]+$/ · Up to 10 tag patterns (letters, digits, _ . - and * as a glob, 1–128 characters) that stay mutable in an immutable repository, e.g. ["latest", "main-"]. Replaces the list; unchanged when omitted
--description <value> body max 256 chars · nullable · Free text, up to 256 characters; null clears it; unchanged when omitted
--storage-quota-bytes <number> body integer, 1048576-1125899906842624 · nullable · Cap in bytes on every layer this repository holds, shared ones included: 1 MiB (1048576) to 1 PiB. null: no repository cap (the organization quota still applies). A push over it is refused; lowering it deletes nothing. Unchanged when omitted
  • Only the fields given change. Public is reversible on purpose. tagMutability "immutable" refuses a push that would move an existing tag to a different image (re-pushing the same image is fine); tagMutabilityExclusions are * globs, e.g. ["latest"], that stay mutable.

dcloud ecr repositories delete

Delete a repository

DELETE /ecr/api/repositories/{id} — IAM ecr:DeleteRepository — write

dcloud ecr repositories delete <id>

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<id> --id string uuid

dcloud ecr lifecycle-policy

Rules that expire images automatically (AWS ECR lifecycle policy JSON)

Operation Method Path IAM action Effect
get GET /ecr/api/repositories/{id}/lifecycle-policy ecr:GetLifecyclePolicy read
put PUT /ecr/api/repositories/{id}/lifecycle-policy ecr:PutLifecyclePolicy write
delete DELETE /ecr/api/repositories/{id}/lifecycle-policy ecr:DeleteLifecyclePolicy write
preview POST /ecr/api/repositories/{id}/lifecycle-policy/preview ecr:GetLifecyclePolicy read
set-mode PUT /ecr/api/repositories/{id}/lifecycle-mode ecr:PutLifecyclePolicy write

dcloud ecr lifecycle-policy get

Read a repository's lifecycle policy

GET /ecr/api/repositories/{id}/lifecycle-policy — IAM ecr:GetLifecyclePolicy — read

dcloud ecr lifecycle-policy get <id>

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<id> --id string uuid

dcloud ecr lifecycle-policy put

Set the lifecycle policy

PUT /ecr/api/repositories/{id}/lifecycle-policy — IAM ecr:PutLifecyclePolicy — write

dcloud ecr lifecycle-policy put <id> --policy <json>

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<id> --id string uuid
Flag In Required Notes
--policy <json> body yes JSON · The policy: AWS ECR lifecycle JSON ({"rules": [{rulePriority, selection, action}]}, at most 50 rules; expired images stay restorable for 7 days) or ews-lifecycle/v1 ({"version": "ews-lifecycle/v1", rules, keep, softDeleteDays 0–30, default 7}). Stored as given, and the repository switches to its own policy
  • {"policy": {"rules": [...]}} in the AWS ECR format; a policy written for ECR pastes in unchanged. Applied hourly. The response lists what it would expire right now (wouldExpire) — the next run expires exactly that. Expired images stay restorable for softDeleteDays (7 for an AWS ECR policy) before they are purged.

dcloud ecr lifecycle-policy delete

Remove the lifecycle policy

DELETE /ecr/api/repositories/{id}/lifecycle-policy — IAM ecr:DeleteLifecyclePolicy — write

dcloud ecr lifecycle-policy delete <id>

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<id> --id string uuid

dcloud ecr lifecycle-policy preview

Which images a policy would expire now

POST /ecr/api/repositories/{id}/lifecycle-policy/preview — IAM ecr:GetLifecyclePolicy — read

dcloud ecr lifecycle-policy preview <id> [flags]

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<id> --id string uuid
Flag In Required Notes
--policy <json> body JSON · A policy to try before saving it (AWS ECR JSON or ews-lifecycle/v1), previewed as if saved and active. Omitted: the policy that applies to the repository now
  • The stored policy, or {"policy": …} to try one before saving it. Changes nothing. Answers per rule what it would expire (count, bytes) and per image the decision and why (a protection such as in-use, a keep clause, or the rule).

dcloud ecr lifecycle-policy set-mode

Inherit the organization default, or let nothing expire

PUT /ecr/api/repositories/{id}/lifecycle-mode — IAM ecr:PutLifecyclePolicy — write

dcloud ecr lifecycle-policy set-mode <id> --mode <inherit|none>

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<id> --id string uuid
Flag In Required Notes
--mode <inherit|none> body yes inherit: the organization’s registry default applies; none: nothing in this repository expires. A stored own policy is kept, unused, for a later PUT lifecycle-policy
  • "inherit": the registry default applies; "none": nothing expires (an explicit choice).

dcloud ecr expired-images

Images a lifecycle rule expired, restorable until purged

Operation Method Path IAM action Effect
list GET /ecr/api/repositories/{id}/expired-images ecr:GetLifecyclePolicy read
restore POST /ecr/api/repositories/{id}/expired-images/restore ecr:RestoreExpiredItem write

dcloud ecr expired-images list

List expired images with why, when they are purged, and whether something pulled them since

GET /ecr/api/repositories/{id}/expired-images — IAM ecr:GetLifecyclePolicy — read

dcloud ecr expired-images list <id>

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<id> --id string uuid

dcloud ecr expired-images restore

Bring an expired image back, with the tags nothing has taken since

POST /ecr/api/repositories/{id}/expired-images/restore — IAM ecr:RestoreExpiredItem — write

dcloud ecr expired-images restore <id> --digest <value>

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<id> --id string uuid
Flag In Required Notes
--digest <value> body yes /^sha256:[a-f0-9]{64}$/ · Digest of the expired image, sha256:<64 hex>, as the expired-image list gives it

dcloud ecr lifecycle-defaults

The organization’s default lifecycle policy for every repository that inherits it

Operation Method Path IAM action Effect
get GET /ecr/api/lifecycle-defaults ecr:GetLifecyclePolicy read
put PUT /ecr/api/lifecycle-defaults ecr:PutLifecyclePolicy write
preview POST /ecr/api/lifecycle-defaults/preview ecr:GetLifecyclePolicy read

dcloud ecr lifecycle-defaults get

Read the default that applies, and the platform default

GET /ecr/api/lifecycle-defaults — IAM ecr:GetLifecyclePolicy — read

dcloud ecr lifecycle-defaults get

dcloud ecr lifecycle-defaults put

Set the default and whether it is active, preview-only or off

PUT /ecr/api/lifecycle-defaults — IAM ecr:PutLifecyclePolicy — write

dcloud ecr lifecycle-defaults put --policy <json> --mode <active|preview|off>
Flag In Required Notes
--policy <json> body yes JSON · The default, in ews-lifecycle/v1 only (the AWS ECR format is accepted per repository, not here): {"version": "ews-lifecycle/v1", rules (at most 50), keep, softDeleteDays 1–30}. softDeleteDays 0 is refused with 400: a default always keeps expired images restorable for at least a day
--mode <active|preview|off> body yes active: the hourly run expires what the default selects in every inheriting repository; preview: it only reports; off: the default does nothing
  • Organizations created before the defaults existed see them preview-only until they enable them here. The answer says what would expire across the inheriting repositories.

dcloud ecr lifecycle-defaults preview

What the default would expire across every inheriting repository, as if active

POST /ecr/api/lifecycle-defaults/preview — IAM ecr:GetLifecyclePolicy — read

dcloud ecr lifecycle-defaults preview [flags]
Flag In Required Notes
--policy <json> body JSON · A draft default in ews-lifecycle/v1 to dry-run instead of the saved one. Omitted (or no body at all): the saved default, else the platform default
  • A dry run, nothing changes. Without a body it runs the saved default; with {"policy": …} it runs that draft instead. images lists every image (the first 5,000; totalImages counts all) with action, reason and by, what decided it.

dcloud ecr images

Image manifests and tags within a repository

Operation Method Path IAM action Effect
list GET /ecr/api/repositories/{id}/images ecr:ListImages read
delete-tag DELETE /ecr/api/repositories/{id}/tags/{tag} ecr:DeleteImage write
delete-untagged DELETE /ecr/api/repositories/{id}/manifests/{manifestId} ecr:DeleteImage write
scan POST /ecr/api/repositories/{repoId}/images/{manifestId}/scan ecr:ScanImage write
latest-scan GET /ecr/api/repositories/{repoId}/images/{manifestId}/scan ecr:GetScanResults read
list-scans GET /ecr/api/repositories/{repoId}/images/{manifestId}/scans ecr:GetScanResults read

dcloud ecr images list

List images in a repository

GET /ecr/api/repositories/{id}/images — IAM ecr:ListImages — read

dcloud ecr images list <id> [flags]

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<id> --id string uuid
Flag In Required Notes
--limit <number> query integer, 1-500 · server default 100 · Images (manifests) per page, 1–500; 100 when omitted. An image’s tags never span two pages
--offset <number> query integer, 0-1000000 · server default 0 · Images to skip, newest first, 0–1,000,000; 0 when omitted
  • Paged by manifest, newest first: limit (default 100, max 500) and offset. The response carries hasMore; one row per tag, plus one row with tag: null for an untagged manifest.

dcloud ecr images delete-tag

Delete a tag from a repository

DELETE /ecr/api/repositories/{id}/tags/{tag} — IAM ecr:DeleteImage — write

dcloud ecr images delete-tag <id> <tag>

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<id> --id string uuid
<tag> --tag string 1-128 chars

dcloud ecr images delete-untagged

Delete an image that no tag points at

DELETE /ecr/api/repositories/{id}/manifests/{manifestId} — IAM ecr:DeleteImage — write

dcloud ecr images delete-untagged <id> <manifestId>

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<id> --id string uuid
<manifestId> --manifest-id string uuid
  • Refuses with 409 while any tag still points at the manifest, naming them — delete the tag instead, and the image goes with the last one. The digest is returned so a script can log what it removed.

dcloud ecr images scan

Trigger a vulnerability scan on an image

POST /ecr/api/repositories/{repoId}/images/{manifestId}/scan — IAM ecr:ScanImage — write

dcloud ecr images scan <repoId> <manifestId>

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<repoId> --repo-id string uuid
<manifestId> --manifest-id string uuid

dcloud ecr images latest-scan

Show the most recent scan for an image

GET /ecr/api/repositories/{repoId}/images/{manifestId}/scan — IAM ecr:GetScanResults — read

dcloud ecr images latest-scan <repoId> <manifestId>

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<repoId> --repo-id string uuid
<manifestId> --manifest-id string uuid

dcloud ecr images list-scans

List the scans recorded for an image

GET /ecr/api/repositories/{repoId}/images/{manifestId}/scans — IAM ecr:GetScanResults — read

dcloud ecr images list-scans <repoId> <manifestId> [flags]

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<repoId> --repo-id string uuid
<manifestId> --manifest-id string uuid
Flag In Required Notes
--limit <number> query integer, 1-200 · server default 50 · Scans per page, 1–200; 50 when omitted
--offset <number> query integer, 0-1000000 · server default 0 · Scans to skip, newest first, 0–1,000,000; 0 when omitted
  • Newest first, without findings: limit (default 50, max 200) and offset; the response carries hasMore. Fetch one scan for its findings.

dcloud ecr storage

What the registry stores, and the quotas that cap it

Operation Method Path IAM action Effect
get GET /ecr/api/storage ecr:GetRegistryStorage read
put-quota PUT /ecr/api/storage-quota ecr:PutRegistryStorageQuota write
delete-quota DELETE /ecr/api/storage-quota ecr:PutRegistryStorageQuota write

dcloud ecr storage get

Show storage used per repository against the quotas

GET /ecr/api/storage — IAM ecr:GetRegistryStorage — read

dcloud ecr storage get
  • usedBytes counts each stored layer once (deduplicated across repositories) and is exactly breakdown.inRepositoriesBytes + pendingPurgeBytes (held only by expired, restorable images; the first is purged at nextPurgeAt) + unreferencedBytes (no image holds them; cleanup deletes them 24 h later when cleanup.mode is delete, and keeps them when it is report). quotaUsedBytes = inRepositoriesBytes is what the quota counts. A repository's usedBytes counts every layer it holds; sharedBytes is the part other repositories hold too. effectiveQuotaBytes is the lower of the organization's quota and the platform's.

dcloud ecr storage put-quota

Set the organization's storage quota

PUT /ecr/api/storage-quota — IAM ecr:PutRegistryStorageQuota — write

dcloud ecr storage put-quota --quota-bytes <number>
Flag In Required Notes
--quota-bytes <number> body yes integer, 1048576-1125899906842624 · nullable · Cap in bytes on the layers in the organization’s repositories, each counted once: 1 MiB (1048576) to 1 PiB. null removes it. Required. A push over it is refused; lowering it deletes nothing. The platform quota applies too, whichever is lower
  • A push (or pull-through fill) that would store more is refused with DENIED and the numbers; a layer already stored always passes. A repository has its own storageQuotaBytes (PATCH /ecr/api/repositories/{id}). Lowering a quota deletes nothing.

dcloud ecr storage delete-quota

Remove the organization's storage quota

DELETE /ecr/api/storage-quota — IAM ecr:PutRegistryStorageQuota — write

dcloud ecr storage delete-quota

dcloud ecr registry-aliases

Send image references a workflow writes for another registry (ghcr.io/acme) to this one when CI jobs run

Operation Method Path IAM action Effect
get GET /ecr/api/registry-aliases ecr:DescribeRegistryAliases read
put PUT /ecr/api/registry-aliases ecr:PutRegistryAliases write

dcloud ecr registry-aliases get

List the registry aliases

GET /ecr/api/registry-aliases — IAM ecr:DescribeRegistryAliases — read

dcloud ecr registry-aliases get

dcloud ecr registry-aliases put

Set the registry aliases (replaces the list)

PUT /ecr/api/registry-aliases — IAM ecr:PutRegistryAliases — write

dcloud ecr registry-aliases put --aliases <value>
Flag In Required Notes
--aliases <value> body yes repeatable · The whole list, at most 20: [{ "from": "ghcr.io/acme", "to": "acme" }]. from is host/owner; to is a namespace in this registry. Each from once; [] removes every alias
  • An alias { from: "ghcr.io/acme", to: "acme" } makes ghcr.io/acme/… in a workflow file this registry's acme/… and docker login ghcr.io this registry, in the job a runner receives. A job logs in with its GITHUB_TOKEN (packages: read pulls, write pushes and creates repositories inside the namespace). References in repository scripts, composite actions and Dockerfiles are not rewritten.

dcloud ecr pull-through-cache

Mirror Docker Hub, GHCR and other public registries into this one

Operation Method Path IAM action Effect
list GET /ecr/api/pull-through-cache-rules ecr:DescribePullThroughCacheRules read
create POST /ecr/api/pull-through-cache-rules ecr:CreatePullThroughCacheRule write
update PATCH /ecr/api/pull-through-cache-rules/{id} ecr:UpdatePullThroughCacheRule write
delete DELETE /ecr/api/pull-through-cache-rules/{id} ecr:DeletePullThroughCacheRule write

dcloud ecr pull-through-cache list

List the pull-through cache rules

GET /ecr/api/pull-through-cache-rules — IAM ecr:DescribePullThroughCacheRules — read

dcloud ecr pull-through-cache list

dcloud ecr pull-through-cache create

Mirror an upstream registry under a prefix

POST /ecr/api/pull-through-cache-rules — IAM ecr:CreatePullThroughCacheRule — write

dcloud ecr pull-through-cache create --prefix <value> --upstream-registry <docker.io|ghcr.io|quay.io|registry.k8s.io|public.ecr.aws|mcr.microsoft.com> [flags]
Flag In Required Notes
--prefix <value> body yes 2-64 chars, /^[a-z0-9]+(?:[.-][a-z0-9]+)*(?:/[a-z0-9]+(?:[.-][a-z0-9]+))$/ · The path images are pulled under, e.g. dockerhub: / mirrors upstream. 2–64 characters of lowercase path components (letters, digits, . _ - inside, / between). A prefix another rule has is refused with 409
--upstream-registry <docker.io|ghcr.io|quay.io|registry.k8s.io|public.ecr.aws|mcr.microsoft.com> body yes The registry mirrored: docker.io, ghcr.io, quay.io, registry.k8s.io, public.ecr.aws or mcr.microsoft.com
--username <value> body 1-255 chars · Upstream user name, 1–255 characters; given together with passwordSecretId or not at all. Omitted: anonymous pulls
--password-secret-id <value> body Id of a Secret of this organization holding the upstream password or token, granted to the registry consumer; given together with username. An id that names no secret is refused with 400
  • Then docker pull <org>.ecr.<root>/<prefix>/<name>:<tag> fetches from the upstream on first pull and serves it from this registry after that (Docker Hub official images: <prefix>/node = library/node). Tags are re-checked upstream after 6 hours; when upstream fails, the cached copy is served. Bringing new images in needs ecr:BatchImportUpstreamImage. upstreamRegistry: docker.io, ghcr.io, quay.io, registry.k8s.io, public.ecr.aws, mcr.microsoft.com. A login (username + passwordSecretId, a Deutsche Cloud Secret granted to the registry consumer) raises Docker Hub's anonymous pull limit and reaches private upstream images.

dcloud ecr pull-through-cache update

Set or clear a rule's upstream login

PATCH /ecr/api/pull-through-cache-rules/{id} — IAM ecr:UpdatePullThroughCacheRule — write

dcloud ecr pull-through-cache update <id> --username <value> --password-secret-id <value>

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<id> --id string uuid
Flag In Required Notes
--username <value> body yes 1-255 chars · nullable · Upstream user name, 1–255 characters, or null to drop the login. Required, and null exactly when passwordSecretId is
--password-secret-id <value> body yes nullable · Id of a Secret of this organization holding the password or token (granted to the registry consumer), or null to drop the login. Required, and null exactly when username is

dcloud ecr pull-through-cache delete

Delete a rule (cached repositories stay, and stop refreshing)

DELETE /ecr/api/pull-through-cache-rules/{id} — IAM ecr:DeletePullThroughCacheRule — write

dcloud ecr pull-through-cache delete <id>

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<id> --id string uuid

dcloud ecr signing

Trusted signing keys and the "only signed images deploy" policy

Operation Method Path IAM action Effect
get-policy GET /ecr/api/signing-policy ecr:GetSigningPolicy read
put-policy PUT /ecr/api/signing-policy ecr:PutSigningPolicy write
delete-policy DELETE /ecr/api/signing-policy ecr:PutSigningPolicy write
add-key POST /ecr/api/signing-keys ecr:CreateSigningKey write
delete-key DELETE /ecr/api/signing-keys/{id} ecr:DeleteSigningKey write
verify GET /ecr/api/repositories/{repoId}/images/{manifestId}/signatures ecr:DescribeImageSignatures read

dcloud ecr signing get-policy

Show the signing policy and the trusted keys

GET /ecr/api/signing-policy — IAM ecr:GetSigningPolicy — read

dcloud ecr signing get-policy

dcloud ecr signing put-policy

Turn "only signed images deploy" on or off

PUT /ecr/api/signing-policy — IAM ecr:PutSigningPolicy — write

dcloud ecr signing put-policy --require-signed-images
Flag In Required Notes
--require-signed-images body yes true: a new deployment is refused unless a trusted key signed its image (images built from source pass by provenance; images from another registry are refused). false: signatures are shown, nothing is refused. Running apps are not affected either way
  • {"requireSignedImages": true} makes the deploy service refuse an image from the registry that no trusted key signed, and every image from another registry. Images Deutsche Cloud builds from source pass by provenance. New deployments only — running apps keep running.

dcloud ecr signing delete-policy

Turn the signing policy off (trusted keys stay)

DELETE /ecr/api/signing-policy — IAM ecr:PutSigningPolicy — write

dcloud ecr signing delete-policy

dcloud ecr signing add-key

Trust a cosign public key or a notation certificate

POST /ecr/api/signing-keys — IAM ecr:CreateSigningKey — write

dcloud ecr signing add-key --name <value> --kind <cosign|notation> --pem <value> [flags]
Flag In Required Notes
--name <value> body yes 1-64 chars, /^[A-Za-z0-9][A-Za-z0-9 ._-]*$/ · A name for the key, unique in the organization: 1–64 letters, digits, space, . _ - (starting with a letter or digit)
--kind <cosign|notation> body yes cosign: a cosign public key; notation: a Notary Project (notation) certificate
--pem <value> body yes 1-65536 chars · PEM text, up to 64 KiB. cosign: the public key (cosign.pub; ECDSA, RSA of at least 2048 bits or Ed25519). notation: one or more certificates (a root, an intermediate or the signing certificate) a signature’s chain must reach. Material that does not parse as that kind is refused with 400
--repository-pattern <value> body 1-255 chars, /^[a-z0-9._/-]+$/ · Which repositories the key may vouch for: a repository name with * globs (team/), 1–255 characters; * (every repository) when omitted
  • kind "cosign": the PEM public key (cosign.pub; ECDSA, RSA ≥ 2048 or Ed25519). kind "notation": PEM certificate(s) — a root, an intermediate or the signing certificate — that a signature's chain must reach. repositoryPattern (* globs, default "*") limits which repositories the key may vouch for.

dcloud ecr signing delete-key

Stop trusting a signing key

DELETE /ecr/api/signing-keys/{id} — IAM ecr:DeleteSigningKey — write

dcloud ecr signing delete-key <id>

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<id> --id string uuid

dcloud ecr signing verify

Verify an image's signatures against the trusted keys

GET /ecr/api/repositories/{repoId}/images/{manifestId}/signatures — IAM ecr:DescribeImageSignatures — read

dcloud ecr signing verify <repoId> <manifestId>

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<repoId> --repo-id string uuid
<manifestId> --manifest-id string uuid
  • status: signed (a trusted key verifies a signature), untrusted (signatures, none trusted), unsigned. Each signature: format (cosign-bundle, cosign-simplesigning, notation-jws), status (verified, untrusted, invalid, unsupported — keyless cosign and COSE notation), the key that verified it and why not. deployable says whether the policy would let it deploy.

dcloud ecr scan-results

Findings from a completed scan

Operation Method Path IAM action Effect
get GET /ecr/api/scan-results/{scanId} ecr:GetScanResults read

dcloud ecr scan-results get

Fetch the findings of one scan

GET /ecr/api/scan-results/{scanId} — IAM ecr:GetScanResults — read

dcloud ecr scan-results get <scanId>

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<scanId> --scan-id string uuid

dcloud ecr auth

Registry credentials

Operation Method Path IAM action Effect
login-token POST /ecr/api/login-token ecr:GetAuthorizationToken write
list-login-tokens GET /ecr/api/login-tokens ecr:GetAuthorizationToken write
revoke-login-token DELETE /ecr/api/login-tokens/{id} ecr:GetAuthorizationToken write

dcloud ecr auth login-token

Mint a short-lived docker login token

POST /ecr/api/login-token — IAM ecr:GetAuthorizationToken — write

dcloud ecr auth login-token
  • Mints a 12-hour bearer credential for the whole org registry, so the IAM descriptor classifies GetAuthorizationToken as a write: the operation reports mutates: true and every issuance is audited. The answer carries the token id, which revokes it.

dcloud ecr auth list-login-tokens

List your own live login tokens (never their values)

GET /ecr/api/login-tokens — IAM ecr:GetAuthorizationToken — write

dcloud ecr auth list-login-tokens

dcloud ecr auth revoke-login-token

Revoke one of your own login tokens; the registry refuses it at once

DELETE /ecr/api/login-tokens/{id} — IAM ecr:GetAuthorizationToken — write

dcloud ecr auth revoke-login-token <id>

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<id> --id string uuid

dcloud npm

npm registry. Base path /npm/api.

dcloud npm packages

Packages published to the organization registry

Operation Method Path IAM action Effect
list GET /npm/api/packages npm:ListPackages read
get GET /npm/api/packages/{id} npm:DescribePackages read
update PATCH /npm/api/packages/{id} npm:PublishPackage write
delete DELETE /npm/api/packages/{id} npm:DeletePackage write
delete-version DELETE /npm/api/packages/{id}/versions/{version} npm:DeletePackage write
set-dist-tag PUT /npm/api/packages/{id}/dist-tags/{tag} npm:ManageDistTags write
delete-dist-tag DELETE /npm/api/packages/{id}/dist-tags/{tag} npm:ManageDistTags write

dcloud npm packages list

List packages with their version count and latest tag

GET /npm/api/packages — IAM npm:ListPackages — read

dcloud npm packages list

dcloud npm packages get

Describe a package with its versions and dist-tags

GET /npm/api/packages/{id} — IAM npm:DescribePackages — read

dcloud npm packages get <id>

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<id> --id string uuid

dcloud npm packages update

Set a package description or visibility

PATCH /npm/api/packages/{id} — IAM npm:PublishPackage — write

dcloud npm packages update <id> [flags]

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<id> --id string uuid
Flag In Required Notes
--description <value> body max 512 chars · nullable
--visibility <private|public> body

dcloud npm packages delete

Delete a package and every version of it

DELETE /npm/api/packages/{id} — IAM npm:DeletePackage — write

dcloud npm packages delete <id>

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<id> --id string uuid

dcloud npm packages delete-version

Delete one published version

DELETE /npm/api/packages/{id}/versions/{version} — IAM npm:DeletePackage — write

dcloud npm packages delete-version <id> <version>

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<id> --id string uuid
<version> --version string 1-256 chars, /^[0-9]+.[0-9]+.[0-9]+(?:[-+][0-9A-Za-z.-]+)*$/

dcloud npm packages set-dist-tag

Point a dist-tag at a version

PUT /npm/api/packages/{id}/dist-tags/{tag} — IAM npm:ManageDistTags — write

dcloud npm packages set-dist-tag <id> <tag> --version <value>

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<id> --id string uuid
<tag> --tag string 1-128 chars, /^[a-zA-Z][a-zA-Z0-9._-]*$/
Flag In Required Notes
--version <value> body yes 1-256 chars, /^[0-9]+.[0-9]+.[0-9]+(?:[-+][0-9A-Za-z.-]+)*$/

dcloud npm packages delete-dist-tag

Remove a dist-tag

DELETE /npm/api/packages/{id}/dist-tags/{tag} — IAM npm:ManageDistTags — write

dcloud npm packages delete-dist-tag <id> <tag>

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<id> --id string uuid
<tag> --tag string 1-128 chars, /^[a-zA-Z][a-zA-Z0-9._-]*$/

dcloud npm tokens

Credentials for the npm client

Operation Method Path IAM action Effect
create POST /npm/api/token npm:GetAuthorizationToken write
list GET /npm/api/tokens npm:GetAuthorizationToken write
revoke DELETE /npm/api/tokens/{id} npm:GetAuthorizationToken write

dcloud npm tokens create

Mint a 12-hour registry token for the npm client

POST /npm/api/token — IAM npm:GetAuthorizationToken — write

dcloud npm tokens create

dcloud npm tokens list

List your own live npm tokens (never their values)

GET /npm/api/tokens — IAM npm:GetAuthorizationToken — write

dcloud npm tokens list

dcloud npm tokens revoke

Revoke one of your own npm tokens; the registry refuses it at once

DELETE /npm/api/tokens/{id} — IAM npm:GetAuthorizationToken — write

dcloud npm tokens revoke <id>

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<id> --id string uuid

dcloud npm lifecycle-defaults

The organization’s lifecycle default for package versions

Operation Method Path IAM action Effect
get GET /npm/api/lifecycle-defaults npm:GetLifecyclePolicy read
put PUT /npm/api/lifecycle-defaults npm:PutLifecyclePolicy write
preview POST /npm/api/lifecycle-defaults/preview npm:GetLifecyclePolicy read
package GET /npm/api/packages/{id}/lifecycle npm:GetLifecyclePolicy read
restore POST /npm/api/packages/{id}/expired-versions/restore npm:RestoreExpiredItem write

dcloud npm lifecycle-defaults get

Read the default that applies, and the platform default

GET /npm/api/lifecycle-defaults — IAM npm:GetLifecyclePolicy — read

dcloud npm lifecycle-defaults get

dcloud npm lifecycle-defaults put

Set the default and whether it is active, preview-only or off

PUT /npm/api/lifecycle-defaults — IAM npm:PutLifecyclePolicy — write

dcloud npm lifecycle-defaults put --policy <json> --mode <active|preview|off>
Flag In Required Notes
--policy <json> body yes JSON
--mode <active|preview|off> body yes
  • The platform default expires only prereleases nobody downloaded for 90 days; dist-tagged versions, the newest 10 and the latest release of every major are always kept.

dcloud npm lifecycle-defaults preview

What the default would expire across every package, as if active

POST /npm/api/lifecycle-defaults/preview — IAM npm:GetLifecyclePolicy — read

dcloud npm lifecycle-defaults preview

dcloud npm lifecycle-defaults package

Per version of one package: expire or keep, and why; the expired ones

GET /npm/api/packages/{id}/lifecycle — IAM npm:GetLifecyclePolicy — read

dcloud npm lifecycle-defaults package <id>

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<id> --id string uuid

dcloud npm lifecycle-defaults restore

Bring an expired version back

POST /npm/api/packages/{id}/expired-versions/restore — IAM npm:RestoreExpiredItem — write

dcloud npm lifecycle-defaults restore <id> --version <value>

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<id> --id string uuid
Flag In Required Notes
--version <value> body yes 1-256 chars, /^[0-9]+.[0-9]+.[0-9]+(?:[-+][0-9A-Za-z.-]+)*$/

dcloud billing

Billing. Base path /billing/api.

dcloud billing summary

Current-period spend rollup

Operation Method Path IAM action Effect
get GET /billing/api/summary billing:GetBillingSummary read

dcloud billing summary get

Show the current billing summary

GET /billing/api/summary — IAM billing:GetBillingSummary — read

dcloud billing summary get

dcloud billing costs

Cost explorer: where the euros come from

Operation Method Path IAM action Effect
query POST /billing/api/cost-explorer/query billing:GetCostAndUsage read
lines POST /billing/api/cost-explorer/lines billing:GetCostAndUsage read
compare POST /billing/api/cost-explorer/compare billing:GetCostAndUsage read
export POST /billing/api/cost-explorer/export billing:GetCostAndUsage read
accounting-export GET /billing/api/cost-explorer/accounting-export billing:GetCostAndUsage read
credits GET /billing/api/credits billing:GetCostAndUsage read
resource GET /billing/api/resource-cost billing:GetCostAndUsage read

dcloud billing costs query

Cost over time, grouped and filtered by any dimension

POST /billing/api/cost-explorer/query — IAM billing:GetCostAndUsage — read

dcloud billing costs query --start <value> --end <value> [flags]
Flag In Required Notes
--start <value> body yes /^\d{4}-\d{2}-\d{2}$/
--end <value> body yes /^\d{4}-\d{2}-\d{2}$/
--granularity <hour|day|month> body server default "day"
--group-by <json> body JSON · server default {"dimension":"service"}
--filters <value> body repeatable · server default []
--max-groups <number> body integer, 1-50 · server default 8
  • Dimensions: service, usageType, resource, resourceType, region, zone, project, tag (with tagKey), creator. Returns the stacked series, group totals vs the previous period of equal length, top movers by group and by resource, anomaly hints with the rule spelled out, a month-end forecast, discounts and credits, every billed resource with idle/detached/untagged hints, and the budgets. Amounts are EUR strings at 8 decimal places, exact. A read behind a POST: nothing is written.

dcloud billing costs lines

The usage lines behind a bar, a group or a resource

POST /billing/api/cost-explorer/lines — IAM billing:GetCostAndUsage — read

dcloud billing costs lines --start <value> --end <value> [flags]
Flag In Required Notes
--start <value> body yes /^\d{4}-\d{2}-\d{2}$/
--end <value> body yes /^\d{4}-\d{2}-\d{2}$/
--filters <value> body repeatable · server default []
--bucket <value> body datetime
--granularity <hour|day|month> body server default "day"
--limit <number> body integer, 1-2000 · server default 200
  • One line per (resource, usage type, unit price): quantity, unit, rate, amount, first and last metered. Pass bucket (the ISO start of a bar) with its granularity to see one bar.

dcloud billing costs compare

The same usage priced at other clouds’ public list prices

POST /billing/api/cost-explorer/compare — IAM billing:GetCostAndUsage — read

dcloud billing costs compare --start <value> --end <value> [flags]
Flag In Required Notes
--start <value> body yes /^\d{4}-\d{2}-\d{2}$/
--end <value> body yes /^\d{4}-\d{2}-\d{2}$/
--granularity <hour|day|month> body server default "day"
--group-by <json> body JSON · server default {"dimension":"service"}
--filters <value> body repeatable · server default []
--max-groups <number> body integer, 1-50 · server default 8
  • A read behind a POST. For the query’s window and filters: instance hours (matched to each provider’s cheapest machine of the same CPU class and architecture with at least the vCPUs and memory, named in matches), managed PostgreSQL node hours (matched to the provider’s cheapest managed PostgreSQL server with at least the vCPUs and memory: RDS, Azure Flexible Server, STACKIT Flex; counted at our price and named in partial where none is read), block and object storage GB-months, priced at each reference provider’s list price (providers: name, region, matched machines), read weekly from their public price lists with pricesFrom and sources; a provider without a verified price list says so in missing. The provider whose servers we resell is priced at its list price (what we bill divided by our markup, ×1 today) and its matches say so; it sells no managed PostgreSQL, so a database node is its bare server there. Usage that is metered and not charged yet is left out (notChargedEur); everything else (requests, tokens, traffic, other managed services’ nodes, …) is notComparedEur. No free tiers, commitments or discounts are applied anywhere.

dcloud billing costs export

CSV of every (period, resource, usage type) row

POST /billing/api/cost-explorer/export — IAM billing:GetCostAndUsage — read

dcloud billing costs export --start <value> --end <value> [flags]
Flag In Required Notes
--format <machine|excel-de> query
--start <value> body yes /^\d{4}-\d{2}-\d{2}$/
--end <value> body yes /^\d{4}-\d{2}-\d{2}$/
--granularity <hour|day|month> body server default "day"
--group-by <json> body JSON · server default {"dimension":"service"}
--filters <value> body repeatable · server default []
--max-groups <number> body integer, 1-50 · server default 8
  • Returns raw bytes with their own content type, written straight to stdout.
  • Columns: period_start, service, service_name, usage_type, usage_type_name, resource_type, resource_id, resource_name, region, zone, projects, created_by, tags, quantity, unit, amount_eur (8 places, unrounded — sums reproduce the explorer exactly), runs_on. format=excel-de writes the same columns for a German Excel: semicolons, decimal commas, names in words, dates as DD.MM.YYYY, euros to the cent, UTF-8 with a BOM, CRLF.

dcloud billing costs accounting-export

A month or a range of days as a DATEV Buchungsstapel (EXTF) for the tax advisor

GET /billing/api/cost-explorer/accounting-export — IAM billing:GetCostAndUsage — read

dcloud billing costs accounting-export [flags]
Flag In Required Notes
--month <value> query /^\d{4}-(0[1-9]|1[0-2])$/ · The billing month, YYYY-MM; or give start and end
--start <value> query /^\d{4}-(0[1-9]|1[0-2])-(0[1-9]|[12]\d|3[01])$/ · First day of the range, YYYY-MM-DD (UTC), with end; instead of month
--end <value> query /^\d{4}-(0[1-9]|1[0-2])-(0[1-9]|[12]\d|3[01])$/ · Last day of the range, YYYY-MM-DD (UTC), inclusive
--kost1-tag-key <value> query max 64 chars, /^[a-z][a-z0-9_.-]*$/ · Override the cost-centre tag for this export
--konto <value> query max 20 chars, /^[0-9A-Za-z]*$/ · Override the expense account
--gegenkonto <value> query max 20 chars, /^[0-9A-Za-z]*$/ · Override the creditor account
  • Returns raw bytes with their own content type, written straight to stdout.
  • DATEV-Format Buchungsstapel: the EXTF header record (version 700, category 21, format 13; Berater- and Mandantennummer, fiscal year start and account length from the cost-report settings, empty until set; Datum vom/bis = the range; not fixed), then the 125 standard columns. Windows-1252, semicolons, decimal comma, CRLF. Give month (YYYY-MM) or start and end (YYYY-MM-DD, inclusive, UTC); a range across two fiscal years is refused (400). One row per month × cost centre × project × service, net of discounts and before VAT; each credit an H row; KOST1 is the cost-centre tag (default cost-center), KOST2 the project, a resource in two projects split evenly. Belegdatum and Leistungsdatum are the last day of service in that month inside the range, never a future day; a month not over yet says "vorläufig" in the Buchungstext. Cents are allocated by largest remainder so the rows sum exactly to the net. Konto and Gegenkonto come from the report settings unless given here.

dcloud billing costs credits

Credits and discounts granted to the organization, with what is left

GET /billing/api/credits — IAM billing:GetCostAndUsage — read

dcloud billing costs credits

dcloud billing costs resource

What one resource costs: this month, last month, per hour now, monthly cap

GET /billing/api/resource-cost — IAM billing:GetCostAndUsage — read

dcloud billing costs resource --kind <instance|database|cache|vpn|volume|distribution|webAcl> --id <value>
Flag In Required Notes
--kind <instance|database|cache|vpn|volume|distribution|webAcl> query yes instance, database, cache, vpn, volume, distribution (CDN) or webAcl (WAF)
--id <value> query yes 1-128 chars · The resource id, as its own service names it
  • From the usage records the invoice is summed from. currentHour is null when the resource was not metered in the last two hours (stopped, deleted, or storage). caps has one row per machine (a 3-node database has three): charged this month against its monthly cap; once reached, its hours cost €0 until the month ends.

dcloud billing estimates

What an operation costs before it runs

Operation Method Path IAM action Effect
create POST /billing/api/estimate billing:EstimateCost read

dcloud billing estimates create

Price an operation before running it (per hour, per month, monthly cap)

POST /billing/api/estimate — IAM billing:EstimateCost — read

dcloud billing estimates create --operation <value> [flags]
Flag In Required Notes
--operation <value> body yes 3-96 chars, /^[a-z0-9-]+(.[a-z0-9-]+)+$/ · API operation id, e.g. ec2.instances.run, rds.instances.create
--body <key=<json>> body repeatable · key= · server default {} · The request body the operation would be sent
  • A read behind a POST: nothing is created. operation is the API operation id (ec2.instances.run, rds.instances.create, cache.clusters.create, vpn.endpoints.create, ec2.volumes.create, autoscaling.groups.create, lb.load-balancers.create, …) and body the request body it would get. Returns lines (per hour, per full month with the monthly cap applied, the cap), totals, summary ("5,99 €/month max · 0,0096 €/h (excl. VAT)", German number format as in the console; the numeric fields are plain decimals), pay-per-use unit prices, and lines marked billed: false for things that are not metered yet. Allowed with billing:EstimateCost or with the operation’s own action. ews <command> --dry-run prints this for the command it would run.

dcloud billing invoices

Issued invoices

Operation Method Path IAM action Effect
list GET /billing/api/invoices billing:GetInvoices read
pdf GET /billing/api/invoices/{id}/pdf billing:GetInvoices read

dcloud billing invoices list

List invoices

GET /billing/api/invoices — IAM billing:GetInvoices — read

dcloud billing invoices list [flags]
Flag In Required Notes
--limit <number> query integer, 1-100 · At most this many, newest first (default 12)

dcloud billing invoices pdf

An issued invoice as a PDF (A4)

GET /billing/api/invoices/{id}/pdf — IAM billing:GetInvoices — read

dcloud billing invoices pdf <id>

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<id> --id string uuid
  • Returns raw bytes with their own content type, written straight to stdout.
  • Rendered from the invoice as issued: the parties, VAT ID and rate snapshotted at issue time, the lines, the totals and how to pay. A draft has no number and no PDF (404).

dcloud billing account

Who invoices are made out to

Operation Method Path IAM action Effect
get GET /billing/api/account billing:GetBillingAccount read
update PATCH /billing/api/account billing:UpdateBillingAccount write

dcloud billing account get

The billing account: company name, invoice address, VAT ID, invoice e-mail

GET /billing/api/account — IAM billing:GetBillingAccount — read

dcloud billing account get

dcloud billing account update

Change the company name, invoice address, VAT ID or invoice e-mail

PATCH /billing/api/account — IAM billing:UpdateBillingAccount — write

dcloud billing account update --company-name <value> --address-line1 <value> --postal-code <value> --city <value> --country <value> [flags]
Flag In Required Notes
--company-name <value> body yes 2-200 chars
--vat-number <value> body max 20 chars
--address-line1 <value> body yes 2-200 chars
--address-line2 <value> body max 200 chars
--postal-code <value> body yes 1-20 chars
--city <value> body yes 1-100 chars
--country <value> body yes /^[A-Za-z]{2}$/
--billing-email <json> body JSON
  • Applies to invoices issued from now on; issued invoices keep what they said. A changed VAT ID is checked for its member state’s format and against VIES: one VIES does not know is refused (400, field vatNumber); when VIES cannot be reached the ID is saved with vatNumberStatus unavailable, every later save checks it again until VIES confirms it, and until then invoices treat it as no VAT ID (no reverse charge for an EU customer outside Germany; a German customer pays German VAT either way). country is one of the listed ISO codes; postalCode must fit that country (DE: five digits). Send every field. billingEmail is recorded for invoice e-mails, which are not sent yet.

dcloud billing budgets

Spend limits and alert thresholds

Operation Method Path IAM action Effect
list GET /billing/api/budgets billing:GetBudgets read
create POST /billing/api/budgets billing:CreateBudget write
status GET /billing/api/budgets/status billing:GetBudgets read
scope-preview POST /billing/api/budgets/scope-preview billing:GetBudgets read
get GET /billing/api/budgets/{id} billing:GetBudgets read
update PATCH /billing/api/budgets/{id} billing:UpdateBudget write
delete DELETE /billing/api/budgets/{id} billing:DeleteBudget write
action-preview GET /billing/api/budgets/{id}/action-preview billing:GetBudgets read

dcloud billing budgets list

List budgets

GET /billing/api/budgets — IAM billing:GetBudgets — read

dcloud billing budgets list

dcloud billing budgets create

Create a budget

POST /billing/api/budgets — IAM billing:CreateBudget — write

dcloud billing budgets create --name <value> --amount-cents <number> --period <monthly|quarterly|annual> [flags]
Flag In Required Notes
--name <value> body yes 1-255 chars
--amount-cents <number> body yes integer, min 1
--period <monthly|quarterly|annual> body yes
--scope <json> body JSON
--service-filter <value> body repeatable
--alert-thresholds <value> body repeatable · integer, 1-1000
--notification-emails <value> body repeatable · email
--action <json> body JSON · nullable · Let the budget propose stopping non-production resources: {thresholdPercent (default 100), selector (tag clauses, default environment in dev/development/test/staging/preview)}. A person approves each proposal.
--forecast-thresholds <value> body repeatable · integer, 1-1000 · nullable · Monthly budgets: also alert (mail and the ews.billing "Budget Threshold Crossed" event, kind forecast) when the month-end forecast reaches these percentages, e.g. [100]

dcloud billing budgets status

List budgets with current spend, scope size and fired alerts

GET /billing/api/budgets/status — IAM billing:GetBudgets — read

dcloud billing budgets status
  • Reports whether a budget’s scope currently selects no billable resource — a budget guarding an empty set looks identical to one that is guarding something.

dcloud billing budgets scope-preview

Count the resources a scope would cover, before saving it

POST /billing/api/budgets/scope-preview — IAM billing:GetBudgets — read

dcloud billing budgets scope-preview --scope <json>
Flag In Required Notes
--scope <json> body yes JSON
  • A read behind a POST: the scope is a nested structure, and encoding it into a query string would mean a second parser for the same shape. Nothing is written. Also requires tags:ListTags — it reads tag membership.

dcloud billing budgets get

Describe one budget

GET /billing/api/budgets/{id} — IAM billing:GetBudgets — read

dcloud billing budgets get <id>

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<id> --id string uuid

dcloud billing budgets update

Update a budget

PATCH /billing/api/budgets/{id} — IAM billing:UpdateBudget — write

dcloud billing budgets update <id> [flags]

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<id> --id string uuid
Flag In Required Notes
--name <value> body 1-255 chars
--amount-cents <number> body integer, min 1
--period <monthly|quarterly|annual> body
--scope <json> body JSON
--service-filter <value> body repeatable · nullable
--alert-thresholds <value> body repeatable · integer, 1-1000 · nullable
--notification-emails <value> body repeatable · email · nullable
--action <json> body JSON · nullable · The budget’s action; null removes it (the budget then only notifies)
--forecast-thresholds <value> body repeatable · integer, 1-1000 · nullable · Monthly budgets: also alert (mail and the ews.billing "Budget Threshold Crossed" event, kind forecast) when the month-end forecast reaches these percentages, e.g. [100]

dcloud billing budgets delete

Delete a budget

DELETE /billing/api/budgets/{id} — IAM billing:DeleteBudget — write

dcloud billing budgets delete <id>

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<id> --id string uuid

dcloud billing budgets action-preview

What the budget’s action would propose to stop right now

GET /billing/api/budgets/{id}/action-preview — IAM billing:GetBudgets — read

dcloud billing budgets action-preview <id>

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<id> --id string uuid
  • Running instances and databases, and autoscaling groups, inside the budget’s scope whose tags match the action’s selector, never those tagged budget-action=keep. Kubernetes nodes are left to their node groups; autoscaling members are covered by scaling their group to 0. Each with the hourly charge that stops.

dcloud billing cost-report

The monthly cost report mail: who gets it, preview, send

Operation Method Path IAM action Effect
get GET /billing/api/cost-report billing:GetCostReportSettings read
update PUT /billing/api/cost-report billing:UpdateCostReportSettings write
preview GET /billing/api/cost-report/preview billing:GetCostAndUsage read
send POST /billing/api/cost-report/send billing:SendCostReport write

dcloud billing cost-report get

Show the monthly cost report settings and the reports sent

GET /billing/api/cost-report — IAM billing:GetCostReportSettings — read

dcloud billing cost-report get
  • Sent on the 2nd at 08:00 German time for the month before, once per month. effectiveRecipients resolves the default (the owner plus the billing account’s invoice e-mail; a budget’s notification addresses get only that budget’s alerts).

dcloud billing cost-report update

Turn the monthly cost report on or off, or choose who gets it

PUT /billing/api/cost-report — IAM billing:UpdateCostReportSettings — write

dcloud billing cost-report update [flags]
Flag In Required Notes
--enabled body Send the monthly cost report (default on)
--recipients <value> body repeatable · nullable · Who gets it; null = the default: the owner plus the billing account’s invoice e-mail
--accounting <json> body JSON · The accounting (DATEV-style) export: cost-centre tag and accounts

dcloud billing cost-report preview

A month’s report as data, without sending it

GET /billing/api/cost-report/preview — IAM billing:GetCostAndUsage — read

dcloud billing cost-report preview [flags]
Flag In Required Notes
--period <value> query /^\d{4}-(0[1-9]|1[0-2])$/ · The billing month, YYYY-MM (default: last month)

dcloud billing cost-report send

Send a month’s report now, with its CSVs (once per month unless again)

POST /billing/api/cost-report/send — IAM billing:SendCostReport — write

dcloud billing cost-report send [flags]
Flag In Required Notes
--period <value> body /^\d{4}-(0[1-9]|1[0-2])$/ · The billing month, YYYY-MM (default: last month)
--again body Send even if this month already went out (at most every 10 minutes); default: only if it has not
  • outcome: sent, already_sent, disabled, no_recipients or failed. With again: true it goes out once more, at most every 10 minutes (429 otherwise). Attached: cost-lines-YYYY-MM.csv and accounting-YYYY-MM.csv.

dcloud billing cost-views

Saved cost explorer views, optionally mailed monthly

Operation Method Path IAM action Effect
list GET /billing/api/cost-views billing:GetCostAndUsage read
get GET /billing/api/cost-views/{id} billing:GetCostAndUsage read
create POST /billing/api/cost-views billing:CreateCostView write
update PATCH /billing/api/cost-views/{id} billing:UpdateCostView write
delete DELETE /billing/api/cost-views/{id} billing:DeleteCostView write
report GET /billing/api/cost-views/{id}/report billing:GetCostAndUsage read

dcloud billing cost-views list

List the saved views you can see (shared ones and your own)

GET /billing/api/cost-views — IAM billing:GetCostAndUsage — read

dcloud billing cost-views list

dcloud billing cost-views get

Describe one saved view, with the range it resolves to today

GET /billing/api/cost-views/{id} — IAM billing:GetCostAndUsage — read

dcloud billing cost-views get <id>

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<id> --id string uuid

dcloud billing cost-views create

Save a cost explorer view

POST /billing/api/cost-views — IAM billing:CreateCostView — write

dcloud billing cost-views create --name <value> --state <json> [flags]
Flag In Required Notes
--name <value> body yes 1-100 chars · Unique in the organization
--description <value> body max 500 chars
--state <json> body yes JSON · The explorer question: range (relative preset or fixed dates), granularity, groupBy, filters — the same shapes as cost-explorer/query
--shared body Visible to everyone with billing:GetCostAndUsage (default) or only to its creator
--report <json> body JSON · Mail this view monthly, on the 2nd, for the month before
  • state.range is relative ({type: relative, preset: last-month | month-to-date | last-30-days | …}) so the view keeps its meaning, or fixed ({type: fixed, start, end}). report: {enabled, recipients} mails the view on the 2nd for the month before, with its CSV. Names are unique per organization (409).

dcloud billing cost-views update

Change a saved view, its sharing or its monthly mail

PATCH /billing/api/cost-views/{id} — IAM billing:UpdateCostView — write

dcloud billing cost-views update <id> [flags]

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<id> --id string uuid
Flag In Required Notes
--name <value> body 1-100 chars · Unique in the organization
--description <value> body max 500 chars
--state <json> body JSON · The explorer question: range (relative preset or fixed dates), granularity, groupBy, filters — the same shapes as cost-explorer/query
--shared body
--report <json> body JSON

dcloud billing cost-views delete

Delete a saved view

DELETE /billing/api/cost-views/{id} — IAM billing:DeleteCostView — write

dcloud billing cost-views delete <id>

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<id> --id string uuid

dcloud billing cost-views report

A view’s monthly report for a month, as data, without sending it

GET /billing/api/cost-views/{id}/report — IAM billing:GetCostAndUsage — read

dcloud billing cost-views report <id> [flags]

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<id> --id string uuid
Flag In Required Notes
--period <value> query /^\d{4}-(0[1-9]|1[0-2])$/ · The billing month, YYYY-MM (default: last month)

dcloud billing savings

Waste: idle, oversized, stopped, unattached and unused resources, with the saving

Operation Method Path IAM action Effect
list GET /billing/api/cost-findings billing:GetCostAndUsage read
dismiss POST /billing/api/cost-findings/dismiss billing:DismissCostFinding write
restore POST /billing/api/cost-findings/restore billing:DismissCostFinding write

dcloud billing savings list

What could be saved a month, resource by resource, with the action

GET /billing/api/cost-findings — IAM billing:GetCostAndUsage — read

dcloud billing savings list
  • Kinds: idle-machine, oversized-machine, oversized-database, stopped-server, unattached-volume, unused-elastic-ip. Each finding: evidence (one sentence with the numbers), monthlySaving (EUR, 8 places, after discounts; 0 for elastic IPs, not billed yet), confidence (medium when memory is not measured), and the action as an API operation id with method, path and body. rules spells out every rule. Dismissed findings are listed separately with who kept them and why.

dcloud billing savings dismiss

Keep a finding, with a reason, for good or until a date

POST /billing/api/cost-findings/dismiss — IAM billing:DismissCostFinding — write

dcloud billing savings dismiss --key <value> --reason <value> [flags]
Flag In Required Notes
--key <value> body yes 3-300 chars, /^[a-z-]+:[^\s]+$/ · The finding’s key, e.g. idle-machine:ec2_instance/i-abc
--reason <value> body yes 3-500 chars · Why it stays — shown to everyone
--until <value> body datetime · Bring it back after this instant; omitted = keep for good

dcloud billing savings restore

Bring a dismissed finding back

POST /billing/api/cost-findings/restore — IAM billing:DismissCostFinding — write

dcloud billing savings restore --key <value>
Flag In Required Notes
--key <value> body yes 3-300 chars, /^[a-z-]+:[^\s]+$/ · The finding’s key, e.g. idle-machine:ec2_instance/i-abc

dcloud billing budget-proposals

What crossed budgets propose to stop, waiting for a person

Operation Method Path IAM action Effect
list GET /billing/api/budgets/action-proposals billing:GetBudgets read
approve POST /billing/api/budgets/action-proposals/{id}/approve billing:ApproveBudgetAction write
dismiss POST /billing/api/budgets/action-proposals/{id}/dismiss billing:ApproveBudgetAction write

dcloud billing budget-proposals list

List budget action proposals, newest first

GET /billing/api/budgets/action-proposals — IAM billing:GetBudgets — read

dcloud billing budget-proposals list [flags]
Flag In Required Notes
--budget-id <value> query uuid · Only this budget’s proposals
  • status: pending (waiting for approval), executing, done (each item carries result), dismissed, expired (the period ended undecided).

dcloud billing budget-proposals approve

Approve a proposal: stop or scale down every resource it names

POST /billing/api/budgets/action-proposals/{id}/approve — IAM billing:ApproveBudgetAction — write

dcloud billing budget-proposals approve <id>

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<id> --id string uuid
  • Each stop runs through its own route with your credential, so it also needs ec2:StopInstances, rds:StopDBInstance or autoscaling:UpdateAutoScalingGroup on that resource and is audited as yours. A resource someone already stopped is skipped. Only a pending proposal can be approved, once (409 otherwise). Start the resources again, or set the group’s sizes back to previous, to undo.

dcloud billing budget-proposals dismiss

Dismiss a proposal: nothing is stopped this period

POST /billing/api/budgets/action-proposals/{id}/dismiss — IAM billing:ApproveBudgetAction — write

dcloud billing budget-proposals dismiss <id>

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<id> --id string uuid

dcloud billing payment-methods

How invoices get paid

Operation Method Path IAM action Effect
list GET /billing/api/payment-methods billing:GetPaymentMethods read
create POST /billing/api/payment-methods billing:ManagePaymentMethods write
set-default PATCH /billing/api/payment-methods/{id}/default billing:ManagePaymentMethods write
delete DELETE /billing/api/payment-methods/{id} billing:ManagePaymentMethods write

dcloud billing payment-methods list

List payment methods

GET /billing/api/payment-methods — IAM billing:GetPaymentMethods — read

dcloud billing payment-methods list

dcloud billing payment-methods create

Add a payment method

POST /billing/api/payment-methods — IAM billing:ManagePaymentMethods — write

dcloud billing payment-methods create --type <bank_transfer>
Flag In Required Notes
--type <bank_transfer> body yes

dcloud billing payment-methods set-default

Make a payment method the default

PATCH /billing/api/payment-methods/{id}/default — IAM billing:ManagePaymentMethods — write

dcloud billing payment-methods set-default <id>

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<id> --id string uuid

dcloud billing payment-methods delete

Remove a payment method

DELETE /billing/api/payment-methods/{id} — IAM billing:ManagePaymentMethods — write

dcloud billing payment-methods delete <id>

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<id> --id string uuid

dcloud iam

Identity. Base path /iam/api.

dcloud iam users

IAM principals — humans and service accounts

Operation Method Path IAM action Effect
list GET /iam/api/users iam:ListUsers read
who-can GET /iam/api/users/who-can iam:ListUsers read
create POST /iam/api/users iam:CreateUser write
get GET /iam/api/users/{id} iam:GetUser read
delete DELETE /iam/api/users/{id} iam:DeleteUser write
assign-role POST /iam/api/users/{id}/roles iam:AssignUserRole write
remove-role DELETE /iam/api/users/{id}/roles/{roleId} iam:RemoveUserRole write
attach-policy POST /iam/api/users/{id}/policies iam:AttachUserPolicy write
detach-policy DELETE /iam/api/users/{id}/policies/{policyId} iam:DetachUserPolicy write
get-login-profile GET /iam/api/users/{id}/login-profile iam:GetLoginProfile read
create-login-profile POST /iam/api/users/{id}/login-profile iam:CreateLoginProfile write
update-login-profile PATCH /iam/api/users/{id}/login-profile iam:UpdateLoginProfile write
cli-access GET /iam/api/users/{id}/cli iam:ListUserSessions read
block-device-key POST /iam/api/users/{id}/cli/device-keys/{keyId}/block iam:BlockUserDeviceKey write
unblock-device-key DELETE /iam/api/users/{id}/cli/device-keys/{keyId}/block iam:UnblockUserDeviceKey write
end-cli-session DELETE /iam/api/users/{id}/cli/sessions/{sessionId} iam:RevokeUserSessions write
delete-login-profile DELETE /iam/api/users/{id}/login-profile iam:DeleteLoginProfile write
deactivate-mfa DELETE /iam/api/users/{id}/mfa iam:DeactivateMfaDevice write

dcloud iam users list

List IAM users

GET /iam/api/users — IAM iam:ListUsers — read

dcloud iam users list --limit <json>
Flag In Required Notes
--limit <json> query yes JSON · At most this many users, newest first; default 1000

dcloud iam users who-can

List the principals allowed to perform an action on a resource today

GET /iam/api/users/who-can — IAM iam:ListUsers — read

dcloud iam users who-can --action <value> --resource <value>
Flag In Required Notes
--action <value> query yes One action, e.g. git:PushRepository
--resource <value> query yes The RN of a resource of this organization, or * for every resource
  • The same evaluation the routes perform, over every active principal of the organization.

dcloud iam users create

Create an IAM user or service account

POST /iam/api/users — IAM iam:CreateUser — write

dcloud iam users create --username <value> [flags]
Flag In Required Notes
--username <value> body yes 1-64 chars, /^[a-z0-9_-]+$/ · The user name, unique in the organization; an IAM user with a console password signs in with it
--display-name <value> body max 128 chars · A readable name shown in the console
--type <user|service_account> body server default "user" · service_account for a program, which uses access keys and never a console password; default user

dcloud iam users get

Describe one IAM user

GET /iam/api/users/{id} — IAM iam:GetUser — read

dcloud iam users get <id>

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<id> --id string uuid

dcloud iam users delete

Delete an IAM user

DELETE /iam/api/users/{id} — IAM iam:DeleteUser — write

dcloud iam users delete <id>

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<id> --id string uuid

dcloud iam users assign-role

Assign a role to a user

POST /iam/api/users/{id}/roles — IAM iam:AssignUserRole — write

dcloud iam users assign-role <id> --role-id <value>

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<id> --id string uuid
Flag In Required Notes
--role-id <value> body yes uuid · The ID of the role to assign, a role of this organization

dcloud iam users remove-role

Remove a role from a user

DELETE /iam/api/users/{id}/roles/{roleId} — IAM iam:RemoveUserRole — write

dcloud iam users remove-role <id> <roleId>

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<id> --id string uuid
<roleId> --role-id string uuid

dcloud iam users attach-policy

Attach a policy directly to a user

POST /iam/api/users/{id}/policies — IAM iam:AttachUserPolicy — write

dcloud iam users attach-policy <id> --policy-id <value>

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<id> --id string uuid
Flag In Required Notes
--policy-id <value> body yes uuid · The ID of the policy to attach, a policy of this organization

dcloud iam users detach-policy

Detach a policy from a user

DELETE /iam/api/users/{id}/policies/{policyId} — IAM iam:DetachUserPolicy — write

dcloud iam users detach-policy <id> <policyId>

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<id> --id string uuid
<policyId> --policy-id string uuid

dcloud iam users get-login-profile

Show an IAM user's console access

GET /iam/api/users/{id}/login-profile — IAM iam:GetLoginProfile — read

dcloud iam users get-login-profile <id>

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<id> --id string uuid
  • Enabled or not, whether a new password is due, locked until, last sign-in, second factors, and the org sign-in URL. 404 when the user has no console password.

dcloud iam users create-login-profile

Give an IAM user a console password

POST /iam/api/users/{id}/login-profile — IAM iam:CreateLoginProfile — write

dcloud iam users create-login-profile <id> [flags]

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<id> --id string uuid
Flag In Required Notes
--password <value> body 1-256 chars · The password to set, checked against the organization's password policy; leave out with generatePassword
--generate-password body true: a password that meets the policy is made for you and returned once, in generatedPassword
--password-reset-required body server default true · The user must choose a new password at the first sign-in; default true
  • The user signs in at /login/ with the user name and this password. Pass password (checked against the password policy) or generatePassword: true; a generated one is returned once in generatedPassword. Users of type user only.

dcloud iam users update-login-profile

Reset, unlock, or turn on/off an IAM user's console password

PATCH /iam/api/users/{id}/login-profile — IAM iam:UpdateLoginProfile — write

dcloud iam users update-login-profile <id> [flags]

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<id> --id string uuid
Flag In Required Notes
--password <value> body 1-256 chars · A new password, checked against the organization's password policy; ends the user's sessions
--generate-password body true: a new password is made for you and returned once, in generatedPassword; ends the user's sessions
--password-reset-required body The user must choose a new password at the next sign-in; with a new password, default true
--enabled body false turns console sign-in off and ends the user's sessions at once (the password is kept); true turns it on again
--unlock body true lifts a lockout after too many wrong passwords
  • A new password ends the user’s sessions and, unless passwordResetRequired: false, must be changed at the next sign-in. enabled: false ends their sessions at once.

dcloud iam users cli-access

A member's CLI devices (Touch ID keys) and their CLI sessions in this organization

GET /iam/api/users/{id}/cli — IAM iam:ListUserSessions — read

dcloud iam users cli-access <id>

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<id> --id string uuid
  • Each device says whether this organization blocked it.

dcloud iam users block-device-key

Block a member's CLI device in this organization

POST /iam/api/users/{id}/cli/device-keys/{keyId}/block — IAM iam:BlockUserDeviceKey — write

dcloud iam users block-device-key <id> <keyId>

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<id> --id string uuid
<keyId> --key-id string uuid
  • It signs in here no more and its CLI sessions here end now. The device keeps working in other organizations; only its owner removes it.

dcloud iam users unblock-device-key

Lift this organization's block on a member's CLI device

DELETE /iam/api/users/{id}/cli/device-keys/{keyId}/block — IAM iam:UnblockUserDeviceKey — write

dcloud iam users unblock-device-key <id> <keyId>

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<id> --id string uuid
<keyId> --key-id string uuid

dcloud iam users end-cli-session

End one of a member's CLI sessions in this organization

DELETE /iam/api/users/{id}/cli/sessions/{sessionId} — IAM iam:RevokeUserSessions — write

dcloud iam users end-cli-session <id> <sessionId>

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<id> --id string uuid
<sessionId> --session-id string uuid

dcloud iam users delete-login-profile

Remove an IAM user's console password

DELETE /iam/api/users/{id}/login-profile — IAM iam:DeleteLoginProfile — write

dcloud iam users delete-login-profile <id>

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<id> --id string uuid
  • Ends their console sessions. Their second factors are kept.

dcloud iam users deactivate-mfa

Remove an IAM user's second factors

DELETE /iam/api/users/{id}/mfa — IAM iam:DeactivateMfaDevice — write

dcloud iam users deactivate-mfa <id>

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<id> --id string uuid
  • Authenticator app, recovery codes and passkeys of the console sign-in; ends its sessions. For a lost phone: an IAM user has no mailbox to recover with.

dcloud iam password-policy

The organization's rules for IAM-user console passwords

Operation Method Path IAM action Effect
get GET /iam/api/password-policy iam:GetPasswordPolicy read
update PUT /iam/api/password-policy iam:UpdatePasswordPolicy write
delete DELETE /iam/api/password-policy iam:DeletePasswordPolicy write

dcloud iam password-policy get

Show the password policy and the org sign-in URL

GET /iam/api/password-policy — IAM iam:GetPasswordPolicy — read

dcloud iam password-policy get

dcloud iam password-policy update

Set the password policy (the whole policy)

PUT /iam/api/password-policy — IAM iam:UpdatePasswordPolicy — write

dcloud iam password-policy update --min-length <number> --require-uppercase --require-lowercase --require-numbers --require-symbols --max-age-days <number> --lockout-threshold <number> --lockout-minutes <number> --max-session-hours <number> --console-passwords-allowed
Flag In Required Notes
--min-length <number> body yes integer, 8-128 · The fewest characters a password may have (12 by default)
--require-uppercase body yes A password needs an uppercase letter A–Z (true by default)
--require-lowercase body yes A password needs a lowercase letter a–z (true by default)
--require-numbers body yes A password needs a digit 0–9 (true by default)
--require-symbols body yes A password needs a character that is not a letter or digit (false by default)
--max-age-days <number> body yes integer, 1-365 · nullable · Days after which a password must be changed; null: never (null by default)
--lockout-threshold <number> body yes integer, 3-20 · Wrong passwords in a row from one address before sign-in from it is locked (5 by default)
--lockout-minutes <number> body yes integer, 1-1440 · Minutes a lockout lasts (15 by default)
--max-session-hours <number> body yes integer, 1-168 · Hours a console session of an IAM user lasts before signing in again (12 by default)
--console-passwords-allowed body yes false turns console password sign-in off for every IAM user of the organization (true by default)
  • Applies to IAM-user console passwords only. consolePasswordsAllowed: false turns IAM-user password sign-in off; an enforced SSO connection does too.

dcloud iam password-policy delete

Return the password policy to the defaults

DELETE /iam/api/password-policy — IAM iam:DeletePasswordPolicy — write

dcloud iam password-policy delete

dcloud iam cli-auth-policy

The organization's CLI sign-in policy: Touch ID or a passkey for people, and personal access key age

Operation Method Path IAM action Effect
get GET /iam/api/cli-auth-policy iam:GetCliAuthPolicy read
dry-run POST /iam/api/cli-auth-policy/dry-run iam:GetCliAuthPolicy read
update PUT /iam/api/cli-auth-policy iam:UpdateCliAuthPolicy write

dcloud iam cli-auth-policy get

Show the CLI sign-in policy

GET /iam/api/cli-auth-policy — IAM iam:GetCliAuthPolicy — read

dcloud iam cli-auth-policy get

dcloud iam cli-auth-policy dry-run

Show who and what a proposed policy would affect, changing nothing

POST /iam/api/cli-auth-policy/dry-run — IAM iam:GetCliAuthPolicy — read

dcloud iam cli-auth-policy dry-run --require-passkey-cli --personal-key-max-age-days <number>
Flag In Required Notes
--require-passkey-cli body yes People's CLI sessions must be opened with Touch ID or a passkey, sensitive commands ask for a fresh confirmation after five minutes, and older CLIs can no longer sign in with a 90-day access key. Service accounts and role sessions are never affected
--personal-key-max-age-days <number> body yes integer, 0-3650 · nullable · People's own access keys: null = no restriction, 0 = refused, N = refused once older than N days (at most 3650). Keys of service accounts and role sessions, and keys with a scope policy, are never refused
  • Lists people with neither a passkey nor a Touch ID device key, personal access keys that would be refused, unverified CLI sessions that would stop, and machine keys (never affected).

dcloud iam cli-auth-policy update

Set the CLI sign-in policy

PUT /iam/api/cli-auth-policy — IAM iam:UpdateCliAuthPolicy — write

dcloud iam cli-auth-policy update --require-passkey-cli --personal-key-max-age-days <number>
Flag In Required Notes
--require-passkey-cli body yes People's CLI sessions must be opened with Touch ID or a passkey, sensitive commands ask for a fresh confirmation after five minutes, and older CLIs can no longer sign in with a 90-day access key. Service accounts and role sessions are never affected
--personal-key-max-age-days <number> body yes integer, 0-3650 · nullable · People's own access keys: null = no restriction, 0 = refused, N = refused once older than N days (at most 3650). Keys of service accounts and role sessions, and keys with a scope policy, are never refused
  • A person only, with a fresh Touch ID or passkey confirmation (the CLI asks for it). personalKeyMaxAgeDays: null = no restriction, 0 = people’s access keys refused, N = refused once older than N days. Service accounts and role sessions (OIDC) are never affected. Run dry-run first.

dcloud iam groups

Collections of users that share policies

Operation Method Path IAM action Effect
list GET /iam/api/groups iam:ListGroups read
create POST /iam/api/groups iam:CreateGroup write
get GET /iam/api/groups/{id} iam:GetGroup read
update PATCH /iam/api/groups/{id} iam:UpdateGroup write
delete DELETE /iam/api/groups/{id} iam:DeleteGroup write
add-member POST /iam/api/groups/{id}/members iam:AddUserToGroup write
remove-member DELETE /iam/api/groups/{id}/members/{userId} iam:RemoveUserFromGroup write
attach-policy POST /iam/api/groups/{id}/policies iam:AttachGroupPolicy write
detach-policy DELETE /iam/api/groups/{id}/policies/{policyId} iam:DetachGroupPolicy write

dcloud iam groups list

List groups

GET /iam/api/groups — IAM iam:ListGroups — read

dcloud iam groups list

dcloud iam groups create

Create a group

POST /iam/api/groups — IAM iam:CreateGroup — write

dcloud iam groups create --name <value> [flags]
Flag In Required Notes
--name <value> body yes 1-128 chars · The group’s name
--description <value> body max 512 chars · What the group is for

dcloud iam groups get

Describe one group

GET /iam/api/groups/{id} — IAM iam:GetGroup — read

dcloud iam groups get <id>

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<id> --id string uuid

dcloud iam groups update

Rename or re-describe a group

PATCH /iam/api/groups/{id} — IAM iam:UpdateGroup — write

dcloud iam groups update <id> [flags]

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<id> --id string uuid
Flag In Required Notes
--name <value> body 1-128 chars · A new name
--description <value> body max 512 chars · A new description

dcloud iam groups delete

Delete a group

DELETE /iam/api/groups/{id} — IAM iam:DeleteGroup — write

dcloud iam groups delete <id>

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<id> --id string uuid

dcloud iam groups add-member

Add a user to a group

POST /iam/api/groups/{id}/members — IAM iam:AddUserToGroup — write

dcloud iam groups add-member <id> --iam-user-id <value>

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<id> --id string uuid
Flag In Required Notes
--iam-user-id <value> body yes uuid · The ID of the IAM user to add, a user of this organization

dcloud iam groups remove-member

Remove a user from a group

DELETE /iam/api/groups/{id}/members/{userId} — IAM iam:RemoveUserFromGroup — write

dcloud iam groups remove-member <id> <userId>

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<id> --id string uuid
<userId> --user-id string uuid

dcloud iam groups attach-policy

Attach a policy to a group

POST /iam/api/groups/{id}/policies — IAM iam:AttachGroupPolicy — write

dcloud iam groups attach-policy <id> --policy-id <value>

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<id> --id string uuid
Flag In Required Notes
--policy-id <value> body yes uuid · The ID of the policy to attach, a policy of this organization

dcloud iam groups detach-policy

Detach a policy from a group

DELETE /iam/api/groups/{id}/policies/{policyId} — IAM iam:DetachGroupPolicy — write

dcloud iam groups detach-policy <id> <policyId>

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<id> --id string uuid
<policyId> --policy-id string uuid

dcloud iam roles

Named policy bundles assignable to users

Operation Method Path IAM action Effect
list GET /iam/api/roles iam:ListRoles read
create POST /iam/api/roles iam:CreateRole write
get GET /iam/api/roles/{id} iam:GetRole read
delete DELETE /iam/api/roles/{id} iam:DeleteRole write
attach-policy POST /iam/api/roles/{id}/policies iam:AttachRolePolicy write
detach-policy DELETE /iam/api/roles/{id}/policies/{policyId} iam:DetachRolePolicy write
set-trust-policy PUT /iam/api/roles/{id}/trust-policy iam:UpdateAssumeRolePolicy write
trust-ci POST /iam/api/roles/{id}/trust-ci iam:UpdateAssumeRolePolicy write
list-sessions GET /iam/api/roles/{id}/sessions iam:GetRole read
revoke-sessions POST /iam/api/roles/{id}/sessions/revoke iam:RevokeRoleSessions write

dcloud iam roles list

List roles

GET /iam/api/roles — IAM iam:ListRoles — read

dcloud iam roles list

dcloud iam roles create

Create a role

POST /iam/api/roles — IAM iam:CreateRole — write

dcloud iam roles create --name <value> [flags]
Flag In Required Notes
--name <value> body yes 1-128 chars · The role’s name
--description <value> body max 512 chars · What the role is for

dcloud iam roles get

Describe one role

GET /iam/api/roles/{id} — IAM iam:GetRole — read

dcloud iam roles get <id>

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<id> --id string uuid

dcloud iam roles delete

Delete a role

DELETE /iam/api/roles/{id} — IAM iam:DeleteRole — write

dcloud iam roles delete <id>

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<id> --id string uuid

dcloud iam roles attach-policy

Attach a policy to a role

POST /iam/api/roles/{id}/policies — IAM iam:AttachRolePolicy — write

dcloud iam roles attach-policy <id> --policy-id <value>

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<id> --id string uuid
Flag In Required Notes
--policy-id <value> body yes uuid · The ID of the policy to attach, a policy of this organization

dcloud iam roles detach-policy

Detach a policy from a role

DELETE /iam/api/roles/{id}/policies/{policyId} — IAM iam:DetachRolePolicy — write

dcloud iam roles detach-policy <id> <policyId>

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<id> --id string uuid
<policyId> --policy-id string uuid

dcloud iam roles set-trust-policy

Set which federated workloads (e.g. GitHub Actions jobs) may assume a role

PUT /iam/api/roles/{id}/trust-policy — IAM iam:UpdateAssumeRolePolicy — write

dcloud iam roles set-trust-policy <id> --trust-policy <json>

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<id> --id string uuid
Flag In Required Notes
--trust-policy <json> body yes JSON · The trust policy, as a JSON object or JSON text: which identity providers, and which token claims, may assume the role; null removes it, so nobody can

dcloud iam roles trust-ci

Let this platform's CI assume the role wherever it trusts GitHub Actions, for the repositories imported or mirrored here

POST /iam/api/roles/{id}/trust-ci — IAM iam:UpdateAssumeRolePolicy — write

dcloud iam roles trust-ci <id>

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<id> --id string uuid
  • Each Allow statement whose principal is the GitHub Actions identity provider gets a twin for this CI (its provider is added when missing, which needs iam:CreateOpenIdConnectProvider): the same conditions, with repo:/ mapped to the repository here. GitHub keeps working. Statements that pin only by numeric ids are skipped and listed.

dcloud iam roles list-sessions

List the federated sessions issued for a role

GET /iam/api/roles/{id}/sessions — IAM iam:GetRole — read

dcloud iam roles list-sessions <id> --limit <json>

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<id> --id string uuid
Flag In Required Notes
--limit <json> query yes JSON · At most this many sessions, newest first; default 50

dcloud iam roles revoke-sessions

Invalidate every temporary credential issued for a role

POST /iam/api/roles/{id}/sessions/revoke — IAM iam:RevokeRoleSessions — write

dcloud iam roles revoke-sessions <id>

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<id> --id string uuid

dcloud iam oidc-providers

External OIDC issuers (GitHub Actions, …) whose tokens roles can trust

Operation Method Path IAM action Effect
list GET /iam/api/oidc-providers iam:ListOpenIdConnectProviders read
create POST /iam/api/oidc-providers iam:CreateOpenIdConnectProvider write
get GET /iam/api/oidc-providers/{id} iam:GetOpenIdConnectProvider read
update PATCH /iam/api/oidc-providers/{id} iam:UpdateOpenIdConnectProvider write
delete DELETE /iam/api/oidc-providers/{id} iam:DeleteOpenIdConnectProvider write

dcloud iam oidc-providers list

List identity providers

GET /iam/api/oidc-providers — IAM iam:ListOpenIdConnectProviders — read

dcloud iam oidc-providers list

dcloud iam oidc-providers create

Register an identity provider

POST /iam/api/oidc-providers — IAM iam:CreateOpenIdConnectProvider — write

dcloud iam oidc-providers create --url <value> [flags]
Flag In Required Notes
--url <value> body yes 1-512 chars · The issuer: a public https:// URL equal to the iss claim of the tokens it signs, e.g. https://token.actions.githubusercontent.com
--audiences <value> body repeatable · 1-256 chars · The aud values a token may carry; omitted: the console’s own address, the audience the guides tell a job to request

dcloud iam oidc-providers get

Describe one identity provider

GET /iam/api/oidc-providers/{id} — IAM iam:GetOpenIdConnectProvider — read

dcloud iam oidc-providers get <id>

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<id> --id string uuid

dcloud iam oidc-providers update

Change the accepted audiences

PATCH /iam/api/oidc-providers/{id} — IAM iam:UpdateOpenIdConnectProvider — write

dcloud iam oidc-providers update <id> --audiences <value>

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<id> --id string uuid
Flag In Required Notes
--audiences <value> body yes repeatable · 1-256 chars · The aud values a token may carry; replaces the whole list

dcloud iam oidc-providers delete

Remove an identity provider

DELETE /iam/api/oidc-providers/{id} — IAM iam:DeleteOpenIdConnectProvider — write

dcloud iam oidc-providers delete <id>

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<id> --id string uuid

dcloud iam sso-connections

The company identity provider people sign in to the console through (OIDC or SAML)

Operation Method Path IAM action Effect
list GET /iam/api/sso-connections iam:ListSsoConnections read
create POST /iam/api/sso-connections iam:CreateSsoConnection write
get GET /iam/api/sso-connections/{id} iam:GetSsoConnection read
update PATCH /iam/api/sso-connections/{id} iam:UpdateSsoConnection write
delete DELETE /iam/api/sso-connections/{id} iam:DeleteSsoConnection write
add-domain POST /iam/api/sso-connections/{id}/domains iam:UpdateSsoConnection write
verify-domain POST /iam/api/sso-connections/{id}/domains/{domainId}/verify iam:VerifySsoDomain write
remove-domain DELETE /iam/api/sso-connections/{id}/domains/{domainId} iam:UpdateSsoConnection write
group-mappings GET /iam/api/sso-connections/{id}/group-mappings iam:GetSsoConnection read
set-group-mappings PUT /iam/api/sso-connections/{id}/group-mappings iam:UpdateSsoConnection write
scim-tokens GET /iam/api/sso-connections/{id}/scim-tokens iam:ListScimTokens read
create-scim-token POST /iam/api/sso-connections/{id}/scim-tokens iam:CreateScimToken write
delete-scim-token DELETE /iam/api/sso-connections/{id}/scim-tokens/{tokenId} iam:DeleteScimToken write

dcloud iam sso-connections list

List single sign-on connections and their domains

GET /iam/api/sso-connections — IAM iam:ListSsoConnections — read

dcloud iam sso-connections list

dcloud iam sso-connections create

Connect an OIDC or SAML identity provider (created switched off)

POST /iam/api/sso-connections — IAM iam:CreateSsoConnection — write

dcloud iam sso-connections create --protocol <oidc|saml> [flags]
Flag In Required Notes
--protocol <oidc|saml> body yes Selects which of the other fields apply
--name <value> body 1-100 chars · A name for the connection, e.g. the identity provider’s
--default-role <admin|member|viewer|billing> body The organization role a person gets when single sign-on first adds them; default member
--oidc <json> body JSON · For protocol oidc: {issuer, clientId, clientSecret} of the app registered at the identity provider
--saml <json> body JSON · For protocol saml: {idpSsoUrl (https), idpEntityId, idpCertificate (PEM), allowSha1 (default false)} from the identity provider
  • The body is a union of 2 shapes (oidc, saml). The flags above are the union of every branch, so the server decides which combination is legal.
  • The OIDC client secret is stored encrypted and never returned. A connection signs nobody in until a domain is verified and it is enabled

dcloud iam sso-connections get

Describe one connection, with the values to enter at the identity provider

GET /iam/api/sso-connections/{id} — IAM iam:GetSsoConnection — read

dcloud iam sso-connections get <id>

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<id> --id string uuid

dcloud iam sso-connections update

Change settings, turn the connection on or off, or enforce it

PATCH /iam/api/sso-connections/{id} — IAM iam:UpdateSsoConnection — write

dcloud iam sso-connections update <id> [flags]

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<id> --id string uuid
Flag In Required Notes
--name <value> body 1-100 chars · A new name for the connection
--enabled body true lets people sign in through the connection (needs a verified domain); false stops it and its enforcement
--enforced body true refuses password sign-in for addresses on the verified domains, except the organization owner; needs enabled
--default-role <admin|member|viewer|billing> body The organization role a person gets when single sign-on first adds them
--groups-claim <value> body 1-256 chars · The OIDC claim or SAML attribute that lists the person’s groups at the identity provider (groups until changed)
--oidc <json> body JSON · New OIDC settings {issuer, clientId, clientSecret}; leave out clientSecret to keep the stored one. A new issuer or client ID unlinks the accounts linked through the old one
--saml <json> body JSON · New SAML settings {idpSsoUrl, idpEntityId, idpCertificate, allowSha1}. A new URL, entity ID or certificate unlinks the accounts linked through the old one
  • enabled requires at least one verified domain; enforced requires enabled. Enforcing refuses password sign-in for addresses on the verified domains, except the organization owner

dcloud iam sso-connections delete

Remove a connection; accounts it created stay members

DELETE /iam/api/sso-connections/{id} — IAM iam:DeleteSsoConnection — write

dcloud iam sso-connections delete <id>

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<id> --id string uuid

dcloud iam sso-connections add-domain

Claim an email domain; returns the TXT record that proves it

POST /iam/api/sso-connections/{id}/domains — IAM iam:UpdateSsoConnection — write

dcloud iam sso-connections add-domain <id> --domain <value>

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<id> --id string uuid
Flag In Required Notes
--domain <value> body yes 3-253 chars · An email domain the organization owns, e.g. acme.com

dcloud iam sso-connections verify-domain

Look up the TXT record and mark the domain verified when it matches

POST /iam/api/sso-connections/{id}/domains/{domainId}/verify — IAM iam:VerifySsoDomain — write

dcloud iam sso-connections verify-domain <id> <domainId>

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<id> --id string uuid
<domainId> --domain-id string uuid

dcloud iam sso-connections remove-domain

Remove a domain; a connection left without a verified one is switched off

DELETE /iam/api/sso-connections/{id}/domains/{domainId} — IAM iam:UpdateSsoConnection — write

dcloud iam sso-connections remove-domain <id> <domainId>

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<id> --id string uuid
<domainId> --domain-id string uuid

dcloud iam sso-connections group-mappings

The IdP group → IAM group mappings and the claim groups are read from

GET /iam/api/sso-connections/{id}/group-mappings — IAM iam:GetSsoConnection — read

dcloud iam sso-connections group-mappings <id>

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<id> --id string uuid

dcloud iam sso-connections set-group-mappings

Replace the IdP group → IAM group mappings

PUT /iam/api/sso-connections/{id}/group-mappings — IAM iam:UpdateSsoConnection — write

dcloud iam sso-connections set-group-mappings <id> --mappings <value>

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<id> --id string uuid
Flag In Required Notes
--mappings <value> body yes repeatable · Every mapping, as {idpGroup, iamGroupId}: idpGroup as the identity provider sends it (a name, a path, a DN or an object ID); an empty list removes them all
  • At every SSO sign-in, membership in each mapped IAM group is set to what the IdP says; memberships added by hand and SCIM-managed groups are never touched. A leading / on a group path is ignored.

dcloud iam sso-connections scim-tokens

List the SCIM provisioning tokens of a connection, and the SCIM base URL

GET /iam/api/sso-connections/{id}/scim-tokens — IAM iam:ListScimTokens — read

dcloud iam sso-connections scim-tokens <id>

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<id> --id string uuid

dcloud iam sso-connections create-scim-token

Create a SCIM token for the IdP; the token is returned once

POST /iam/api/sso-connections/{id}/scim-tokens — IAM iam:CreateScimToken — write

dcloud iam sso-connections create-scim-token <id> --name <value>

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<id> --id string uuid
Flag In Required Notes
--name <value> body yes 1-100 chars · A name for the token, e.g. the identity provider that uses it

dcloud iam sso-connections delete-scim-token

Revoke a SCIM token

DELETE /iam/api/sso-connections/{id}/scim-tokens/{tokenId} — IAM iam:DeleteScimToken — write

dcloud iam sso-connections delete-scim-token <id> <tokenId>

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<id> --id string uuid
<tokenId> --token-id string uuid

dcloud iam policies

Allow/Deny documents evaluated on every request

Operation Method Path IAM action Effect
list GET /iam/api/policies iam:ListPolicies read
create POST /iam/api/policies iam:CreatePolicy write
get GET /iam/api/policies/{id} iam:GetPolicy read
update PATCH /iam/api/policies/{id} iam:UpdatePolicy write
delete DELETE /iam/api/policies/{id} iam:DeletePolicy write
simulate POST /iam/api/simulate iam:SimulatePrincipalPolicy read

dcloud iam policies list

List policies

GET /iam/api/policies — IAM iam:ListPolicies — read

dcloud iam policies list

dcloud iam policies create

Create a customer-managed policy

POST /iam/api/policies — IAM iam:CreatePolicy — write

dcloud iam policies create --name <value> --document <value> [flags]
Flag In Required Notes
--name <value> body yes 1-128 chars · The policy’s name
--description <value> body max 512 chars · What the policy is for
--document <value> body yes min 1 chars · The policy document as JSON text: {"Version":"2024-01-01","Statement":[{"Effect":"Allow","Action":[…],"Resource":[…]}]}; checked before it is stored
  • document is a JSON string, validated by validatePolicyDocument before it is stored.

dcloud iam policies get

Describe one policy

GET /iam/api/policies/{id} — IAM iam:GetPolicy — read

dcloud iam policies get <id>

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<id> --id string uuid

dcloud iam policies update

Update a policy document

PATCH /iam/api/policies/{id} — IAM iam:UpdatePolicy — write

dcloud iam policies update <id> [flags]

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<id> --id string uuid
Flag In Required Notes
--name <value> body 1-128 chars · A new name
--description <value> body max 512 chars · A new description
--document <value> body min 1 chars · A replacement policy document as JSON text; checked before it is stored

dcloud iam policies delete

Delete a policy

DELETE /iam/api/policies/{id} — IAM iam:DeletePolicy — write

dcloud iam policies delete <id>

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<id> --id string uuid

dcloud iam policies simulate

Test whether a user, role or draft policy allows an action, and why

POST /iam/api/simulate — IAM iam:SimulatePrincipalPolicy — read

dcloud iam policies simulate --action <value> --resource <value> [flags]
Flag In Required Notes
--principal <json> body JSON · The user or role to test, as {type: user|role, id}; omitted: only policyDocuments are evaluated
--policy-documents <value> body repeatable · 2-65536 chars · Policy documents (JSON text) that are not saved: with a principal, evaluated as if attached to it; without one, on their own
--action <value> body yes 3-128 chars, /^[a-z0-9-]+:[A-Za-z0-9]+$/ · The one action to test, e.g. ec2:StartInstances (not a pattern)
--resource <value> body yes 1-1024 chars, /^(*|rn:(?:dcloud|ews):[^\s]*)$/ · The resource name (RN) the request would act on, or *
--context <json> body JSON · Condition keys of the imagined request: sourceIp, multiFactorAuthPresent, currentTime (default now), requestedRegion (default your region), availabilityZone; a key left out is unknown
  • May check iam:SimulateCustomPolicy instead, decided by server-side state the caller cannot see. A caller needs all of them to be sure of not getting a 403.
  • Give principal ({type: user|role, id}), policyDocuments (JSON strings, not saved), or both — drafts are then evaluated as if attached. A principal needs iam:SimulatePrincipalPolicy on it, drafts need iam:SimulateCustomPolicy. The answer names the deciding statement, its policy and how that policy reaches the principal (directly, group, role). context sets condition keys (sourceIp, multiFactorAuthPresent, currentTime, requestedRegion, availabilityZone, requestProject, resourceProject); a key left out is unknown, as it would be for a request that does not carry it. Bucket policies of S3 are not included.

dcloud iam grants

Capabilities granted on one resource — the Access panel’s half of policy

Operation Method Path IAM action Effect
list GET /iam/api/grants iam:ListPolicies read
create POST /iam/api/grants iam:AttachUserPolicy write
revoke DELETE /iam/api/grants/{policyId} iam:DetachUserPolicy write

dcloud iam grants list

List the grants that exist on one resource

GET /iam/api/grants — IAM iam:ListPolicies — read

dcloud iam grants list --resource <value>
Flag In Required Notes
--resource <value> query yes 1-500 chars · The RN of the resource whose grants to list, one named resource of this organization
  • Only policies this endpoint wrote — a hand-authored policy mentioning the same resource is not a grant.

dcloud iam grants create

Grant capabilities on one resource to a user, group or role

POST /iam/api/grants — IAM iam:AttachUserPolicy — write

dcloud iam grants create --principal <json> --resource <value> --capabilities <value>
Flag In Required Notes
--principal <json> body yes JSON · Who receives the capabilities: {kind: user|group|role, id}
--resource <value> body yes 1-500 chars · The RN of one named resource of this organization; a wildcard is refused
--capabilities <value> body yes repeatable · 1-64 chars · Capability IDs, e.g. repository.push or database.view; each must apply to the resource’s type, and you must hold every action it stands for
  • May check iam:AttachGroupPolicy or iam:AttachRolePolicy instead, decided by server-side state the caller cannot see. A caller needs all of them to be sure of not getting a 403.
  • Each capability id stands for a fixed set of IAM actions; the caller must already hold every action being granted, or the call is refused naming the one they lack. The resource must be one named thing in the caller’s own organization — a wildcard such as zone/* is refused, since org-wide reach belongs on the policy pages.

dcloud iam grants revoke

Take a grant back and delete the policy it created

DELETE /iam/api/grants/{policyId} — IAM iam:DetachUserPolicy — write

dcloud iam grants revoke <policyId>

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<policyId> --policy-id string uuid
  • May check iam:DetachGroupPolicy or iam:DetachRolePolicy or iam:DeletePolicy instead, decided by server-side state the caller cannot see. A caller needs all of them to be sure of not getting a 403.
  • Refuses any policy this endpoint did not create. The detach action checked is the one matching the principal holding it, and iam:DeletePolicy is checked as well.

dcloud iam access-keys

Long-lived credentials for the API, the CLI, Terraform and S3 clients, optionally capped by a scope policy

Operation Method Path IAM action Effect
list GET /iam/api/access-keys iam:ListAccessKeys read
create POST /iam/api/access-keys iam:CreateAccessKey write
set-expiry POST /iam/api/access-keys/set-expiry iam:UpdateAccessKey write
set-status PATCH /iam/api/access-keys/{id} iam:UpdateAccessKey write
delete DELETE /iam/api/access-keys/{id} iam:DeleteAccessKey write

dcloud iam access-keys list

List access keys, optionally for one IAM user

GET /iam/api/access-keys — IAM iam:ListAccessKeys — read

dcloud iam access-keys list [flags]
Flag In Required Notes
--iam-user-id <value> query uuid · Only the keys of this IAM user; omitted: every key of the organization

dcloud iam access-keys create

Create an access key and return its secret once

POST /iam/api/access-keys — IAM iam:CreateAccessKey — write

dcloud iam access-keys create [flags]
Flag In Required Notes
--iam-user-id <value> body uuid · The ID of the IAM user the key signs in as; omitted: yourself
--expires-in-days <number> body integer, 1-3650 · Days until the key expires; default the organization’s default (90), at most its maximum (365)
--description <value> body max 256 chars · What the key is for
--scope-policy <value> body max 10240 chars · A policy document (JSON text) that caps the key: a request needs the principal’s policies AND this document to allow it. E.g. S3 on one bucket: {"Version":"2024-01-01","Statement":[{"Effect":"Allow","Action":["s3:ListObjects","s3:GetObject"],"Resource":["rn:ews:::s3:bucket/","rn:ews:::s3:bucket//object/*"]}]}
--act-as-member body Must be true when iamUserId is another person’s own IAM user: everything done with the key is recorded as that person, and the audit entry names both
  • The secret is in the response and nowhere else. The key signs Deutsche Cloud API calls (Authorization: EWS-ACCESS-KEY id:secret) and S3 requests (SigV4: id as the access key id, secret as the secret access key). Every key expires: expiresAt is in the response. With scopePolicy the key can do only what both the principal and the scope allow.

dcloud iam access-keys set-expiry

Give every key of the organization that never expires an expiry

POST /iam/api/access-keys/set-expiry — IAM iam:UpdateAccessKey — write

dcloud iam access-keys set-expiry --expires-in-days <number>
Flag In Required Notes
--expires-in-days <number> body yes integer, 1-3650 · Days from now, at most the organization’s maximum
  • For keys made before keys expired. Keys Deutsche Cloud mints for app machines are left out; role session keys carry their own expiry.

dcloud iam access-keys set-status

Activate or deactivate an access key

PATCH /iam/api/access-keys/{id} — IAM iam:UpdateAccessKey — write

dcloud iam access-keys set-status <id> --status <active|inactive>

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<id> --id string uuid
Flag In Required Notes
--status <active|inactive> body yes inactive refuses every request signed with the key until it is set active again

dcloud iam access-keys delete

Delete an access key

DELETE /iam/api/access-keys/{id} — IAM iam:DeleteAccessKey — write

dcloud iam access-keys delete <id>

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<id> --id string uuid

dcloud iam agent-sessions

AI agents connected to the MCP endpoint: what each session may do

Operation Method Path IAM action Effect
list GET /iam/api/agent-sessions iam:ListAgentSessions read
set-scope POST /iam/api/agent-sessions/{id}/scope iam:UpdateAgentSession write
approve-call POST /iam/api/agent-sessions/approvals/{id} iam:UpdateAgentSession write
end POST /iam/api/agent-sessions/{id}/end iam:EndAgentSession write
revoke-connection POST /iam/api/agent-sessions/{id}/revoke-connection iam:EndAgentSession write
update-settings PUT /iam/api/agent-sessions/settings iam:UpdateAgentSettings write

dcloud iam agent-sessions list

List agent sessions, calls waiting for approval and the agent settings

GET /iam/api/agent-sessions — IAM iam:ListAgentSessions — read

dcloud iam agent-sessions list [flags]
Flag In Required Notes
--days <number> query integer, 1-90 · server default 7 · How many days of ended sessions to include
  • Without iam:ListAgentSessions a caller sees only the sessions of their own agents.

dcloud iam agent-sessions set-scope

Allow an agent session to write or destroy for a while, or drop it to read-only

POST /iam/api/agent-sessions/{id}/scope — IAM iam:UpdateAgentSession — write

dcloud iam agent-sessions set-scope <id> --scope <read|write|destructive> [flags]

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<id> --id string uuid
Flag In Required Notes
--scope <read|write|destructive> body yes What the session may do
--duration-minutes <number> body integer · 15, 60 or 480. Default: 60 for write, 15 for destructive
  • Raising a session needs a person signed in to the console; an access key or OAuth token is refused, so an agent cannot raise itself. Your own agents need no IAM action.

dcloud iam agent-sessions approve-call

Approve one destructive call an agent planned

POST /iam/api/agent-sessions/approvals/{id} — IAM iam:UpdateAgentSession — write

dcloud iam agent-sessions approve-call <id>

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<id> --id string uuid
  • Console sign-in only, like set-scope.

dcloud iam agent-sessions end

End an agent session; the agent starts over read-only

POST /iam/api/agent-sessions/{id}/end — IAM iam:EndAgentSession — write

dcloud iam agent-sessions end <id>

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<id> --id string uuid

dcloud iam agent-sessions revoke-connection

Revoke the connection behind a session: OAuth app disconnected, access key refused by MCP

POST /iam/api/agent-sessions/{id}/revoke-connection — IAM iam:EndAgentSession — write

dcloud iam agent-sessions revoke-connection <id>

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<id> --id string uuid

dcloud iam agent-sessions update-settings

Set the agent rate limits, or switch off changes by every agent

PUT /iam/api/agent-sessions/settings — IAM iam:UpdateAgentSettings — write

dcloud iam agent-sessions update-settings --calls-per-minute <number> --writes-per-minute <number> --destructive-per-ten-minutes <number> --writes-disabled
Flag In Required Notes
--calls-per-minute <number> body yes integer, 1-1000 · Tool calls one agent connection may make per minute (120 until changed)
--writes-per-minute <number> body yes integer, 1-500 · Calls that change something, per agent connection and minute (30 until changed)
--destructive-per-ten-minutes <number> body yes integer, 0-500 · Destructive calls per agent connection in ten minutes; 0 allows none (10 until changed)
--writes-disabled body yes Switch off changes by every AI agent in the organization
  • Console sign-in only.

dcloud iam members

Organization membership and org-level roles

Operation Method Path IAM action Effect
list GET /iam/api/members iam:ListMembers read
set-role PATCH /iam/api/members/{id} iam:UpdateMember write
remove DELETE /iam/api/members/{id} iam:RemoveMember write
sessions GET /iam/api/members/{id}/sessions iam:ListUserSessions read
revoke-sessions POST /iam/api/members/{id}/revoke-sessions iam:RevokeUserSessions write

dcloud iam members list

List organization members

GET /iam/api/members — IAM iam:ListMembers — read

dcloud iam members list

dcloud iam members set-role

Change a member org role

PATCH /iam/api/members/{id} — IAM iam:UpdateMember — write

dcloud iam members set-role <id> --role <admin|member|viewer|billing>

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<id> --id string uuid
Flag In Required Notes
--role <admin|member|viewer|billing> body yes The member’s new organization role; the owner’s cannot be changed

dcloud iam members remove

Remove a member from the organization

DELETE /iam/api/members/{id} — IAM iam:RemoveMember — write

dcloud iam members remove <id>

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<id> --id string uuid

dcloud iam members sessions

List a member's console sessions: device, address, sign-in method

GET /iam/api/members/{id}/sessions — IAM iam:ListUserSessions — read

dcloud iam members sessions <id>

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<id> --id string uuid

dcloud iam members revoke-sessions

Sign a member out of the console everywhere and disconnect their apps

POST /iam/api/members/{id}/revoke-sessions — IAM iam:RevokeUserSessions — write

dcloud iam members revoke-sessions <id>

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<id> --id string uuid
  • Their browsers are told an administrator signed them out. Access keys are separate credentials and stay; deactivate those under access-keys.

dcloud iam invitations

Pending invites to join the organization

Operation Method Path IAM action Effect
list GET /iam/api/invitations iam:ListInvitations read
create POST /iam/api/invitations iam:InviteUser write
link POST /iam/api/invitations/{id}/link iam:GetInvitationLink read, sensitive
resend POST /iam/api/invitations/{id}/resend iam:ResendInvitation write
cancel DELETE /iam/api/invitations/{id} iam:CancelInvitation write

dcloud iam invitations list

List invitations

GET /iam/api/invitations — IAM iam:ListInvitations — read

dcloud iam invitations list [flags]
Flag In Required Notes
--status <pending|accepted|expired|cancelled> query Only invitations with this status; omitted: every invitation

dcloud iam invitations create

Invite someone to the organization

POST /iam/api/invitations — IAM iam:InviteUser — write

dcloud iam invitations create --email <value> [flags]
Flag In Required Notes
--email <value> body yes email · The address to invite; the invitation is mailed there
--role <admin|member|viewer|billing|none> body server default "member" · The organization role, and its preset policy, the person gets on accepting; none attaches no policy; default member
--group-id <value> body uuid · A group of this organization the person joins on accepting
--role-id <value> body uuid · A role of this organization the person is given on accepting
  • role none attaches no preset policy; groupId / roleId add the person to a group of this organization or give them a role when they accept.

Get the link of a pending invitation, to pass on yourself

POST /iam/api/invitations/{id}/link — IAM iam:GetInvitationLink — read, sensitive

dcloud iam invitations link <id>

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<id> --id string uuid

dcloud iam invitations resend

Send a pending invitation again; the link gets 7 more days

POST /iam/api/invitations/{id}/resend — IAM iam:ResendInvitation — write

dcloud iam invitations resend <id>

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<id> --id string uuid

dcloud iam invitations cancel

Cancel a pending invitation

DELETE /iam/api/invitations/{id} — IAM iam:CancelInvitation — write

dcloud iam invitations cancel <id>

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<id> --id string uuid

dcloud iam audit-logs

Every write, denial, sensitive read and sign-in: who, from where, what, and how it was answered

Operation Method Path IAM action Effect
list GET /iam/api/audit-logs iam:GetAuditLogs read
get GET /iam/api/audit-logs/{id} iam:GetAuditLogs read
export GET /iam/api/audit-logs/export iam:GetAuditLogs read
verify GET /iam/api/audit-logs/verify iam:GetAuditLogs read
digests GET /iam/api/audit-logs/digests iam:GetAuditLogs read
get-settings GET /iam/api/audit-logs/settings iam:GetAuditLogs read
update-settings PUT /iam/api/audit-logs/settings iam:UpdateAuditLogSettings write

dcloud iam audit-logs list

Search audit log entries, newest first

GET /iam/api/audit-logs — IAM iam:GetAuditLogs — read

dcloud iam audit-logs list --limit <json> --offset <json> [flags]
Flag In Required Notes
--action <value> query max 2000 chars · Comma-separated action patterns, e.g. iam:*,auth:SignIn; omitted: every action
--outcome <success|error|failure> query success (Succeeded), error (allowed but Failed) or failure (Denied); omitted: every outcome
--principal <value> query max 300 chars · One principal, exactly: user/alice@acme.com, iam-user/ci, role/deployer/run-42
--access-key-id <value> query max 64 chars · Only entries made with this access key ID
--ip <value> query max 64 chars · Only entries from this source IP address
--resource-id <value> query max 200 chars · Only entries about this resource ID, exactly
--request-id <value> query max 128 chars · Only the entries of this request ID
--caller-type <session|access_key|oauth|cli_session|anonymous|scim|system> query Only entries by this kind of caller: console session, access key, connected app, CLI session, unauthenticated, SCIM provisioning, or the platform itself
--from <value> query max 40 chars · ISO-8601 time; entries at or after it (inclusive)
--to <value> query max 40 chars · ISO-8601 time; entries before it (exclusive)
--search <value> query max 200 chars · Text to find, ignoring case, in the action, resource, IP address, request parameters, principal, access key ID, request ID, or the person's name or email
--limit <json> query yes JSON · Entries per page; default 50
--offset <json> query yes JSON · Entries to skip, for the next page; default 0
--order <asc|desc> query server default "desc" · desc lists the newest entry first, asc the oldest; default desc
  • action takes comma-separated globs (iam:*,auth:SignIn); from is inclusive and to exclusive (ISO-8601); principal is exact (user/alice@acme.com, iam-user/ci, role/deployer/run-42). The response carries total.

dcloud iam audit-logs get

One audit log entry with its session context, request and response

GET /iam/api/audit-logs/{id} — IAM iam:GetAuditLogs — read

dcloud iam audit-logs get <id>

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<id> --id string uuid

dcloud iam audit-logs export

Download every matching entry, oldest first, as JSON lines or CSV

GET /iam/api/audit-logs/export — IAM iam:GetAuditLogs — read

dcloud iam audit-logs export [flags]
Flag In Required Notes
--action <value> query max 2000 chars · Comma-separated action patterns, e.g. iam:*,auth:SignIn; omitted: every action
--outcome <success|error|failure> query success (Succeeded), error (allowed but Failed) or failure (Denied); omitted: every outcome
--principal <value> query max 300 chars · One principal, exactly: user/alice@acme.com, iam-user/ci, role/deployer/run-42
--access-key-id <value> query max 64 chars · Only entries made with this access key ID
--ip <value> query max 64 chars · Only entries from this source IP address
--resource-id <value> query max 200 chars · Only entries about this resource ID, exactly
--request-id <value> query max 128 chars · Only the entries of this request ID
--caller-type <session|access_key|oauth|cli_session|anonymous|scim|system> query Only entries by this kind of caller: console session, access key, connected app, CLI session, unauthenticated, SCIM provisioning, or the platform itself
--from <value> query max 40 chars · ISO-8601 time; entries at or after it (inclusive)
--to <value> query max 40 chars · ISO-8601 time; entries before it (exclusive)
--search <value> query max 200 chars · Text to find, ignoring case, in the action, resource, IP address, request parameters, principal, access key ID, request ID, or the person's name or email
--format <jsonl|csv> query jsonl (one JSON object per line) or csv; default jsonl
  • Returns raw bytes with their own content type, written straight to stdout.
  • Same filters as list; at most 1,000,000 rows per download.

dcloud iam audit-logs verify

Recompute the hash chain and check the signed digests and the head

GET /iam/api/audit-logs/verify — IAM iam:GetAuditLogs — read

dcloud iam audit-logs verify [flags]
Flag In Required Notes
--max-rows <value> query /^\d+$/ · Entries to check before stopping, 1 to 2000000; default 200000
  • ok is false on a chain break (an edited, inserted or deleted row), a digest whose signature or hash does not match, or a head past the last row (a cut-off tail).

dcloud iam audit-logs digests

The hourly Ed25519-signed digests of the chain head, and the public keys

GET /iam/api/audit-logs/digests — IAM iam:GetAuditLogs — read

dcloud iam audit-logs digests

dcloud iam audit-logs get-settings

How long entries are kept

GET /iam/api/audit-logs/settings — IAM iam:GetAuditLogs — read

dcloud iam audit-logs get-settings

dcloud iam audit-logs update-settings

Set how long entries are kept, 90 to 3650 days

PUT /iam/api/audit-logs/settings — IAM iam:UpdateAuditLogSettings — write

dcloud iam audit-logs update-settings --days <number>
Flag In Required Notes
--days <number> body yes integer, 90-3650 · Days an audit log entry is kept (400 until changed)
  • A daily sweep deletes older entries, never past the newest signed digest. Export to S3 for longer archives.

dcloud iam audit-destinations

Where the audit log is exported (S3, webhook, syslog) and the alarms on it (email)

Operation Method Path IAM action Effect
list GET /iam/api/audit-destinations iam:ListAuditDestinations read
get GET /iam/api/audit-destinations/{id} iam:ListAuditDestinations read
create POST /iam/api/audit-destinations iam:CreateAuditDestination write
update PATCH /iam/api/audit-destinations/{id} iam:UpdateAuditDestination write
delete DELETE /iam/api/audit-destinations/{id} iam:DeleteAuditDestination write
test POST /iam/api/audit-destinations/{id}/test iam:TestAuditDestination write

dcloud iam audit-destinations list

List exports and alarms with their delivery state

GET /iam/api/audit-destinations — IAM iam:ListAuditDestinations — read

dcloud iam audit-destinations list

dcloud iam audit-destinations get

One export or alarm: cursor, last delivery, last error

GET /iam/api/audit-destinations/{id} — IAM iam:ListAuditDestinations — read

dcloud iam audit-destinations get <id>

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<id> --id string uuid

dcloud iam audit-destinations create

Export to S3, a webhook or syslog over TLS, or alarm by email on matching events

POST /iam/api/audit-destinations — IAM iam:CreateAuditDestination — write

dcloud iam audit-destinations create --kind <s3|webhook|syslog|email> --name <value> --config <key=<json>> [flags]
Flag In Required Notes
--kind <s3|webhook|syslog|email> body yes Where entries go: an S3 bucket, an https webhook, a syslog receiver over TLS, or email (an alarm)
--name <value> body yes 1-64 chars · A name, unique in the organization
--filter-actions <value> body repeatable · max 100 chars · Action patterns to send, e.g. iam:* or auth:SignIn; empty or omitted: every action
--filter-outcome <success|error|failure> body nullable · Send only entries with this outcome: success (Succeeded), error (Failed) or failure (Denied); null or omitted: every outcome
--config <key=<json>> body yes repeatable · key= · Settings for the kind. s3: {bucket, accessKeyId, region (default us-east-1), prefix, endpoint (default this platform’s object storage)}; webhook: {url} (https); syslog: {host, port (default 6514), caCertificate (PEM, for a private CA)}; email: {addresses}
--secret-access-key <value> body 16-256 chars · The secret key that goes with config.accessKeyId; required for s3, stored encrypted and never returned
  • Delivers events from now on (update with resumeFrom=start to replay what is stored). filterActions takes globs; empty means every action. A webhook signing secret is returned once.

dcloud iam audit-destinations update

Rename, pause, resume, change the filter, or replay from the start or skip to now

PATCH /iam/api/audit-destinations/{id} — IAM iam:UpdateAuditDestination — write

dcloud iam audit-destinations update <id> [flags]

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<id> --id string uuid
Flag In Required Notes
--name <value> body 1-64 chars, /^[A-Za-z0-9 ._-]+$/ · A new name, unique in the organization
--enabled body false pauses delivery; true resumes it where it stopped
--filter-actions <value> body repeatable · /^[a-z0-9*-]+:[A-Za-z0-9*]+$/ · Replaces the action patterns, e.g. iam:*; an empty list sends every action
--filter-outcome <success|error|failure> body nullable · Send only entries with this outcome: success (Succeeded), error (Failed) or failure (Denied); null sends every outcome
--resume-from <now|start> body now skips every entry not yet delivered; start replays every entry still stored; omitted: delivery carries on where it stands

dcloud iam audit-destinations delete

Remove an export or alarm

DELETE /iam/api/audit-destinations/{id} — IAM iam:DeleteAuditDestination — write

dcloud iam audit-destinations delete <id>

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<id> --id string uuid

dcloud iam audit-destinations test

Send one synthetic event now and report what the destination answered

POST /iam/api/audit-destinations/{id}/test — IAM iam:TestAuditDestination — write

dcloud iam audit-destinations test <id>

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<id> --id string uuid

Not in the CLI: iam routes the surface does not describe

These routes exist and are reachable over HTTP. They are deliberately absent from the description, so there is no command for them. The reason is recorded next to the service so a gap has to be stated out loud and stops being stateable the moment the route goes.

Route Why it has no command
POST /iam/api/sts/assume-role-with-web-identity DELIBERATELY UNAUTHENTICATED — the OIDC token in the body IS the credential. Verified against the role's org's identity provider (SSRF-guarded JWKS, RS256/ES256, iss/aud/exp/nbf/iat), then the role's trust policy decides; rate limited per IP and per role, audited per attempt with the token claims
POST /iam/api/invitations/accept Bootstrap route — authenticated by session plus an invite token, with no IAM user and therefore no action to check
GET /iam/api/actions Authenticated but not IAM-gated — serves ACTION_CATALOG to the policy builder
GET /iam/api/managed-policies Authenticated but not IAM-gated — serves MANAGED_POLICY_DOCUMENTS to the policy builder
GET /iam/api/whoami Authenticated but not IAM-gated — every caller may ask about itself and nothing else, and the answer is derived entirely from the credential already presented
POST /iam/api/device/code DELIBERATELY UNAUTHENTICATED — a CLI beginning a login holds no credential yet. Defended by a per-IP rate limit; the code it returns authorizes nothing until a signed-in human approves it
POST /iam/api/device/token DELIBERATELY UNAUTHENTICATED — the polling half of the device flow. The device code IS the credential here, stored only as a hash, rate limited per IP and per code, and collectable exactly once
GET /iam/api/device/pending/{userCode} Authenticated but not IAM-gated — shows a signed-in user what a code they typed would authorize. Rate limited per caller so a code cannot be cheaply guessed
POST /iam/api/device/approve Not IAM-gated, but a console session of a person only (403 for an access key, an agent or an OAuth grant) — this IS the consent step, and it grants only what the approver already holds. Gating it on an IAM action would mean a user could be unable to authorize their own terminal
POST /iam/api/device/passkey-options Not IAM-gated, a console session of a person only — the passkey prompt (user verification required) for approving one device-flow row the person is looking at
POST /iam/api/cli-sessions/challenge DELIBERATELY UNAUTHENTICATED — a CLI signing in with Touch ID has no credential yet. Hands out a single-use, two-minute nonce for an enrolled device key; rate limited per IP
POST /iam/api/cli-sessions DELIBERATELY UNAUTHENTICATED — the Touch ID sign-in itself: the signed challenge IS the credential (single use, verified against the enrolled public key). Rate limited per IP
POST /iam/api/cli-sessions/refresh DELIBERATELY UNAUTHENTICATED — authenticated by the refresh token plus the device binding-key signature; rotates the tokens, reuse ends the session
GET /iam/api/cli-sessions/current Not IAM-gated — a CLI session asks about itself (step-up state), nothing else
POST /iam/api/cli-sessions/current/challenge Not IAM-gated — step-up for the caller's own CLI session: a nonce bound to that session
POST /iam/api/cli-sessions/current/verify Not IAM-gated — step-up for the caller's own CLI session: the Touch ID signature over that nonce
POST /iam/api/cli-sessions/current/step-up Not IAM-gated — step-up for the caller's own CLI session in the browser (a device-flow row only that person can approve, with a passkey)
DELETE /iam/api/cli-sessions/current Not IAM-gated — logout: the caller ends its own CLI session
GET /iam/api/cli-sessions Not IAM-gated — a person lists their own CLI sessions, like the console's own session list
POST /iam/api/cli-sessions/revoke-all Not IAM-gated — a person ends their own CLI sessions (logout --all)
DELETE /iam/api/cli-sessions/{id} Not IAM-gated — a person ends one of their own CLI sessions
GET /iam/api/cli-sessions/device-keys Not IAM-gated — a person lists their own device keys
POST /iam/api/cli-sessions/device-keys Not IAM-gated — a person enrols another device key of their own, from a CLI session verified in the last five minutes
DELETE /iam/api/cli-sessions/device-keys/{id} Not IAM-gated — a person revokes one of their own device keys (lost device); its sessions end
POST /iam/api/cli-sessions/settings/passkey-options Not IAM-gated — the passkey prompt for changing the person's own CLI setting
GET /iam/api/cli-sessions/settings Not IAM-gated — a person reads their own CLI step-up setting
PUT /iam/api/cli-sessions/settings Not IAM-gated — a person changes their own CLI step-up setting; loosening it needs a fresh user verification
POST /iam/api/cli-auth-policy/passkey-options Not IAM-gated on its own — the passkey prompt the console sends with an iam:UpdateCliAuthPolicy change (fresh user verification)

dcloud dns

DNS. Base path /dns/api.

dcloud dns zones

Domains delegated to the platform nameservers

Operation Method Path IAM action Effect
list GET /dns/api/zones dns:ListZones read
get GET /dns/api/zones/{id} dns:GetZone read
create POST /dns/api/zones dns:CreateZone write
delete DELETE /dns/api/zones/{id} dns:DeleteZone write
check-delegation POST /dns/api/zones/{id}/check-delegation dns:CheckDelegation read
export GET /dns/api/zones/{id}/export dns:ListRecords read
import POST /dns/api/zones/{id}/import dns:ImportZone write

dcloud dns zones list

List hosted zones and the platform nameservers

GET /dns/api/zones — IAM dns:ListZones — read

dcloud dns zones list

dcloud dns zones get

Describe a hosted zone and its delegation state

GET /dns/api/zones/{id} — IAM dns:GetZone — read

dcloud dns zones get <id>

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<id> --id string uuid

dcloud dns zones create

Create a hosted zone for a domain you own

POST /dns/api/zones — IAM dns:CreateZone — write

dcloud dns zones create --name <value> [flags]
Flag In Required Notes
--name <value> body yes 1-253 chars · The domain, such as example.com: trimmed, lowercased, trailing dot dropped, at most 253 characters. Refused (400) when it is not a hostname or is, sits under or encloses the platform domain; refused (409) when another organization holds it or an overlapping name as a zone or app domain, or when it lies inside an existing hosted zone
--tags <key=value> body repeatable · key=value · Tags for the new resource, e.g. {"env": "prod", "project": "shop"}. Keys your organization marks required must be present, or the create is refused with the missing keys (GET /tags/api/keys lists them).
  • One owner per domain platform-wide, and the platform root domain cannot be hosted. Delegate by setting the returned nameservers as the NS records at the registrar.

dcloud dns zones delete

Delete a hosted zone and every record in it

DELETE /dns/api/zones/{id} — IAM dns:DeleteZone — write

dcloud dns zones delete <id>

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<id> --id string uuid

dcloud dns zones check-delegation

Ask public resolvers which nameservers the domain delegates to

POST /dns/api/zones/{id}/check-delegation — IAM dns:CheckDelegation — read

dcloud dns zones check-delegation <id>

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<id> --id string uuid
  • Records the result on the zone; a read that stores what it saw.

dcloud dns zones export

The zone as a master file

GET /dns/api/zones/{id}/export — IAM dns:ListRecords — read

dcloud dns zones export <id>

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<id> --id string uuid

dcloud dns zones import

Add records from a zone file, replacing sets with the same name and type

POST /dns/api/zones/{id}/import — IAM dns:ImportZone — write

dcloud dns zones import <id> --zone-file <value>

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<id> --id string uuid
Flag In Required Notes
--zone-file <value> body yes 1-1000000 chars · RFC 1035 master-file text, 1 to 1,000,000 characters. $ORIGIN and $TTL are honoured (TTL 300 until a $TTL line); other $ directives, SOA and apex NS lines are skipped and reported
  • SOA and apex NS lines are skipped. Any invalid line fails the whole import.

dcloud dns records

Record sets of a hosted zone

Operation Method Path IAM action Effect
list GET /dns/api/zones/{id}/records dns:ListRecords read
set POST /dns/api/zones/{id}/records dns:ChangeRecords write
update PUT /dns/api/zones/{id}/records/{recordId} dns:ChangeRecords write
delete DELETE /dns/api/zones/{id}/records/{recordId} dns:ChangeRecords write

dcloud dns records list

List the record sets of a zone

GET /dns/api/zones/{id}/records — IAM dns:ListRecords — read

dcloud dns records list <id>

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<id> --id string uuid

dcloud dns records set

Create or replace the record set at a name and type

POST /dns/api/zones/{id}/records — IAM dns:ChangeRecords — write

dcloud dns records set <id> --name <value> --type <A|AAAA|CNAME|MX|TXT|NS|SRV|CAA|ALIAS> [flags]

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<id> --id string uuid
Flag In Required Notes
--name <value> body yes max 253 chars · Where the set sits: "@" or empty for the apex, a relative label such as "www", or a fully qualified name inside the zone. Refused (400) outside the zone, for NS or CNAME at the apex, for a CNAME next to other records, and for another type at a name that has a CNAME
--type <A|AAAA|CNAME|MX|TXT|NS|SRV|CAA|ALIAS> body yes Record type. ALIAS is the platform type that answers with the address of an app, load balancer, bucket website or CDN distribution. Writing a set replaces the one at the same name and type
--ttl <number> body integer, 1-604800 · Seconds resolvers may cache the set, 1 to 604800. Absent: 300 in the API (the console form starts at 3600). A set with a health check or routed variant checks is served with at most 60
--values <value> body repeatable · 1-4096 chars · The record data in presentation format, one entry per value, at most 100 of at most 4096 characters each: A "203.0.113.7", MX "10 mail.example.com", SRV "10 5 5060 sip.example.com", CAA "0 issue letsencrypt.org", TXT the text. Duplicates are merged. A CNAME takes exactly one. Required (400 "At least one value is required") unless the type is ALIAS or routing supplies them, when a routed set takes the first variant's values
--app-id <value> body ALIAS: the app whose address is answered
--load-balancer-id <value> body ALIAS: a load balancer, answered with its IPv4 (A) and IPv6 (AAAA)
--bucket <value> body ALIAS: a bucket name; the name answers with the bucket's static website
--distribution-id <value> body ALIAS: a CDN distribution, answered with its healthy edge nodes (TTL at most 30 s); list the name among the distribution's aliases too, for its certificate
--health-check-id <value> body nullable · A, AAAA, CNAME: an uptime check; null removes it
--failover-values <value> body repeatable · Answered instead of values while the health check is down
--routing <json> body JSON · nullable · Weighted ({policy:"weighted", variants:[{id, weight 0-255, values, healthCheckId?}]}) or geolocation ({policy:"geo", variants:[{id, country|continent, values, healthCheckId?}]}) routing; null removes it. For geo, values are the default answer.
  • name is "@", a relative label such as "www", or a fully qualified name in the zone. ALIAS takes exactly one of appId, loadBalancerId, bucket or distributionId instead of values, and works at the apex. A, AAAA and CNAME may name an uptime check (healthCheckId) and failoverValues answered while it is down; their TTL is then served as at most 60 seconds.

dcloud dns records update

Change the values or TTL of a record set

PUT /dns/api/zones/{id}/records/{recordId} — IAM dns:ChangeRecords — write

dcloud dns records update <id> <recordId> [flags]

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<id> --id string uuid
<recordId> --record-id string uuid
Flag In Required Notes
--ttl <number> body integer, 1-604800 · Seconds resolvers may cache the set, 1 to 604800. Absent: the TTL is kept
--values <value> body repeatable · 1-4096 chars · Replaces the values (at most 100 of at most 4096 characters each; a CNAME takes one). Absent: the values are kept. The name and type of a set cannot change
--app-id <value> body ALIAS: the app whose address is answered
--load-balancer-id <value> body ALIAS: a load balancer, answered with its IPv4 (A) and IPv6 (AAAA)
--bucket <value> body ALIAS: a bucket name; the name answers with the bucket's static website
--distribution-id <value> body ALIAS: a CDN distribution, answered with its healthy edge nodes (TTL at most 30 s); list the name among the distribution's aliases too, for its certificate
--health-check-id <value> body nullable · A, AAAA, CNAME: an uptime check; null removes it
--failover-values <value> body repeatable · Answered instead of values while the health check is down
--routing <json> body JSON · nullable · Weighted ({policy:"weighted", variants:[{id, weight 0-255, values, healthCheckId?}]}) or geolocation ({policy:"geo", variants:[{id, country|continent, values, healthCheckId?}]}) routing; null removes it. For geo, values are the default answer.
  • Fields left out keep their stored value. An ALIAS target sent here replaces the old one; healthCheckId null removes the check, but stored failoverValues must be cleared in the same call (failoverValues: []) or the change is refused.

dcloud dns records delete

Delete a record set

DELETE /dns/api/zones/{id}/records/{recordId} — IAM dns:ChangeRecords — write

dcloud dns records delete <id> <recordId>

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<id> --id string uuid
<recordId> --record-id string uuid

dcloud dns query-log

A hosted zone's query log and its logging switch

Operation Method Path IAM action Effect
get GET /dns/api/zones/{id}/query-log dns:GetQueryLog read
set PUT /dns/api/zones/{id}/query-logging dns:UpdateQueryLogging write

dcloud dns query-log get

The queries the nameservers answered for the zone, newest first

GET /dns/api/zones/{id}/query-log — IAM dns:GetQueryLog — read

dcloud dns query-log get <id> [flags]

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<id> --id string uuid
Flag In Required Notes
--minutes <number> query integer, 1-10080 · How far back, in minutes: 1 to 10080 (the seven days the log keeps), default 60
--limit <number> query integer, 1-1000 · At most this many lines, newest first: 1 to 1000, default 200
--contains <value> query max 253 chars · Only lines containing this text (a name, a type, an rcode, a client network), at most 253 characters
  • One line per query: name, type, rcode, answer count, transport, client network (/24 or /56), DO and ECS flags. Kept seven days. Query counts per zone and rcode are the EWS/DNS Queries metric in monitoring, whether logging is on or not.

dcloud dns query-log set

Turn query logging on or off

PUT /dns/api/zones/{id}/query-logging — IAM dns:UpdateQueryLogging — write

dcloud dns query-log set <id> --enabled

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<id> --id string uuid
Flag In Required Notes
--enabled body yes Log every answered query of the zone
  • Takes effect within one nameserver pull; lines arrive about a minute later.

dcloud dns dnssec

DNSSEC signing of a hosted zone: keys, DS records, rollovers

Operation Method Path IAM action Effect
get GET /dns/api/zones/{id}/dnssec dns:GetDnssec read
check POST /dns/api/zones/{id}/dnssec/check dns:GetDnssec read
enable POST /dns/api/zones/{id}/dnssec/enable dns:EnableDnssec write
disable POST /dns/api/zones/{id}/dnssec/disable dns:DisableDnssec write
rotate POST /dns/api/zones/{id}/dnssec/rotate dns:RotateDnssecKey write
complete-rollover POST /dns/api/zones/{id}/dnssec/complete-rollover dns:CompleteDnssecKeyRollover write

dcloud dns dnssec get

A zone's DNSSEC status, keys, the DS to put at the registrar and the parent's DS

GET /dns/api/zones/{id}/dnssec — IAM dns:GetDnssec — read

dcloud dns dnssec get <id>

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<id> --id string uuid

dcloud dns dnssec check

Ask public resolvers which DS records the parent zone serves

POST /dns/api/zones/{id}/dnssec/check — IAM dns:GetDnssec — read

dcloud dns dnssec check <id>

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<id> --id string uuid
  • Records the result on the zone; a read that stores what it saw.

dcloud dns dnssec enable

Sign the zone (ECDSA P-256); returns the DS record for the registrar

POST /dns/api/zones/{id}/dnssec/enable — IAM dns:EnableDnssec — write

dcloud dns dnssec enable <id>

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<id> --id string uuid
  • The zone is signed within one nameserver pull. Validation starts once the DS is at the registrar.

dcloud dns dnssec disable

Stop signing once the parent no longer serves the DS, or at once

POST /dns/api/zones/{id}/dnssec/disable — IAM dns:DisableDnssec — write

dcloud dns dnssec disable <id> [flags]

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<id> --id string uuid
Flag In Required Notes
--immediately body Stop signing now instead of once the parent no longer serves the DS
  • Remove the DS at the registrar first. Without immediately the zone stays signed until public resolvers stop returning the DS, then about an hour more.

dcloud dns dnssec rotate

Start a rollover of the key-signing (ksk) or zone-signing (zsk) key

POST /dns/api/zones/{id}/dnssec/rotate — IAM dns:RotateDnssecKey — write

dcloud dns dnssec rotate <id> --key <ksk|zsk>

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<id> --id string uuid
Flag In Required Notes
--key <ksk|zsk> body yes ksk: key-signing key; zsk: zone-signing key
  • zsk: a new key is published and signs after two hours (ZSKs also roll every 90 days by themselves). ksk: a second key signs the DNSKEY set at once; replace the DS at the registrar, and the old key goes when public resolvers serve only the new DS.

dcloud dns dnssec complete-rollover

Finish a key-signing key rollover now, removing the old key

POST /dns/api/zones/{id}/dnssec/complete-rollover — IAM dns:CompleteDnssecKeyRollover — write

dcloud dns dnssec complete-rollover <id>

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<id> --id string uuid
  • Only once the registrar has the new DS: a parent still pointing at the old key makes the zone fail validation.

dcloud ci

CI. Base path /ci/api.

dcloud ci workflows

Workflow files: check one, or convert one from another CI system

Operation Method Path IAM action Effect
validate POST /ci/api/workflows/validate ci:ListRuns read
convert POST /ci/api/workflows/convert ci:ListRuns read

dcloud ci workflows validate

Check a workflow file against the parser without pushing it

POST /ci/api/workflows/validate — IAM ci:ListRuns — read

dcloud ci workflows validate --source <value> [flags]
Flag In Required Notes
--source <value> body yes 1-65536 chars
--path <value> body 1-500 chars · Where the file will live; under .github/workflows/ it is checked as GitHub Actions
  • The same parser a push runs. Answers { valid, issues }; each issue names the key and, where the source allowed it, the line.

dcloud ci workflows convert

Translate a GitHub Actions or GitLab CI file into a Deutsche Cloud workflow

POST /ci/api/workflows/convert — IAM ci:ListRuns — read

dcloud ci workflows convert --source <value> --from <github|gitlab|other> [flags]
Flag In Required Notes
--source <value> body yes 1-65536 chars
--from <github|gitlab|other> body yes
--filename <value> body 1-200 chars
  • Answers { yaml, valid, issues, notes }; notes lists what had no Deutsche Cloud equivalent and was left out. The result is validated by the real parser, with one repair round, and returned rather than committed. 503 when the installation has no AI provider configured. The prompt it uses is public at /docs/workflows/prompt.md.

dcloud ci runners

Self-hosted machines that claim runs their labels match

Operation Method Path IAM action Effect
list GET /ci/api/runners ci:DescribeRunners read
create-registration-token POST /ci/api/runners/registration-tokens ci:ManageRunners write
set-group PATCH /ci/api/runners/{id} ci:ManageRunners write
disable DELETE /ci/api/runners/{id} ci:ManageRunners write

dcloud ci runners list

List the self-hosted runners registered to this organization

GET /ci/api/runners — IAM ci:DescribeRunners — read

dcloud ci runners list
  • Credential hashes are never returned. status is online, offline or disabled; lastSeenAt is the last heartbeat or claim.

dcloud ci runners create-registration-token

Issue a one-time token a machine registers itself with

POST /ci/api/runners/registration-tokens — IAM ci:ManageRunners — write

dcloud ci runners create-registration-token [flags]
Flag In Required Notes
--repository-id <value> body uuid · Limit the token, and the runner it registers, to this repository (authorized on the repository); org-wide when absent
--group-id <value> body uuid · The runner group the machine joins; the Default group when absent
--labels <value> body repeatable · 1-50 chars · Fix the runner’s custom labels; what the machine declares is then ignored (platform labels such as self-hosted, linux, x64 are kept)
  • The token is returned once and stored hashed. It expires after 15 minutes and can be redeemed by exactly one machine. configCommand registers GitHub’s own runner (./config.sh --url https://git.{root}/{org}[/{repo}] --token …), which then runs GitHub-syntax jobs with runs-on: self-hosted (plus any labels it carries); installCommand installs the Deutsche Cloud agent on a Mac. A runner that will hold deploy credentials belongs in a group with protectedRefsOnly.

dcloud ci runners set-group

Move a runner into a runner group, or back to Default

PATCH /ci/api/runners/{id} — IAM ci:ManageRunners — write

dcloud ci runners set-group <id> --group-id <value>

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<id> --id string uuid
Flag In Required Notes
--group-id <value> body yes uuid · nullable · The group; null for Default

dcloud ci runners disable

Disable a runner and revoke its credential

DELETE /ci/api/runners/{id} — IAM ci:ManageRunners — write

dcloud ci runners disable <id>

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<id> --id string uuid
  • The row is kept so past runs still name the machine that ran them; the credential is overwritten, so the machine stops working immediately.

dcloud ci runner-groups

Which runs self-hosted runners may take: repositories, refs, protected branches only, pull requests

Operation Method Path IAM action Effect
list GET /ci/api/runner-groups ci:DescribeRunners read
create POST /ci/api/runner-groups ci:ManageRunners write
update PATCH /ci/api/runner-groups/{id} ci:ManageRunners write
delete DELETE /ci/api/runner-groups/{id} ci:ManageRunners write

dcloud ci runner-groups list

List the runner groups of this organization

GET /ci/api/runner-groups — IAM ci:DescribeRunners — read

dcloud ci runner-groups list
  • A runner without a group is in Default, which takes any run its labels match.

dcloud ci runner-groups create

Create a runner group

POST /ci/api/runner-groups — IAM ci:ManageRunners — write

dcloud ci runner-groups create --name <value> [flags]
Flag In Required Notes
--name <value> body yes 1-100 chars
--repository-ids <value> body repeatable · uuid · nullable · Repositories the group serves; null or absent: every repository
--refs <value> body repeatable · 1-200 chars · Ref globs it serves (main, release/*, refs/tags/v*); empty: any ref
--protected-refs-only body Only branches covered by a branch protection rule; for runners that hold deploy credentials
--allow-pull-requests body Whether pull-request runs reach it (default true)
  • A run reaches a runner of the group only when its repository, its ref and its event are all allowed. A merge queue build is judged by the branch it lands on.

dcloud ci runner-groups update

Change a runner group

PATCH /ci/api/runner-groups/{id} — IAM ci:ManageRunners — write

dcloud ci runner-groups update <id> [flags]

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<id> --id string uuid
Flag In Required Notes
--name <value> body 1-100 chars
--repository-ids <value> body repeatable · uuid · nullable
--refs <value> body repeatable · 1-200 chars
--protected-refs-only body
--allow-pull-requests body

dcloud ci runner-groups delete

Delete a runner group

DELETE /ci/api/runner-groups/{id} — IAM ci:ManageRunners — write

dcloud ci runner-groups delete <id>

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<id> --id string uuid
  • 409 while runners belong to it: they would otherwise fall back to Default.

dcloud ci runner-pools

Machines the platform starts for GitHub-syntax jobs whose labels a pool carries, one job per just-in-time runner

Operation Method Path IAM action Effect
list GET /ci/api/runner-pools ci:DescribeRunnerPools read
get GET /ci/api/runner-pools/{id} ci:DescribeRunnerPools read
create POST /ci/api/runner-pools ci:CreateRunnerPool write
update PATCH /ci/api/runner-pools/{id} ci:UpdateRunnerPool write
delete DELETE /ci/api/runner-pools/{id} ci:DeleteRunnerPool write

dcloud ci runner-pools list

List the runner pools of this organization

GET /ci/api/runner-pools — IAM ci:DescribeRunnerPools — read

dcloud ci runner-pools list

dcloud ci runner-pools get

A pool with its machines, waiting and running jobs, and the last scaling decision

GET /ci/api/runner-pools/{id} — IAM ci:DescribeRunnerPools — read

dcloud ci runner-pools get <id>

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<id> --id string uuid

dcloud ci runner-pools create

Create a runner pool

POST /ci/api/runner-pools — IAM ci:CreateRunnerPool — write

dcloud ci runner-pools create --name <value> --labels <value> --size <s-2|s-4|s-8|s-16|m-4|d-2|d-8|a-2|a-4|a-8|a-16> --max-size <number> [flags]
Flag In Required Notes
--name <value> body yes /^[a-z0-9][a-z0-9-]{0,39}$/ · Name of the pool; its group and template are named runner-pool-
--labels <value> body yes repeatable · /^[a-z0-9][a-z0-9._-]{0,49}$/ · Jobs whose runs-on labels are all among these go here, e.g. ubuntu-latest, ubuntu-24.04 (hosted jobs) or hetzner-16
--size <s-2|s-4|s-8|s-16|m-4|d-2|d-8|a-2|a-4|a-8|a-16> body yes Machine size: s-2 (2 vCPU / 4 GiB), s-4 (4 / 8), s-8 (8 / 16), s-16 (16 / 32), d-2, d-8 (dedicated), a-2, a-4, a-8, a-16 (ARM, for ubuntu-24.04-arm jobs); the smallest machine of your provider that fits
--min-size <number> body integer, 0-200 · Machines always on (the base)
--max-size <number> body yes integer, 1-200 · Most machines at once
--spare <number> body integer, 0-50 · Idle machines kept above demand
--clean-machine-per-job body Destroy every machine after its job instead of reusing it within its paid hour
--share-trusted-machines body Let trusted jobs (default branch, tags, dispatch, schedules) of every repository share machines; pull request jobs never do
--prebuilt-image body Start machines from the organization's pre-built runner image once it is built (first job about a minute sooner); default true; false: stock Ubuntu, installed at every boot
--runner-group-id <value> body uuid · A runner group whose repository and ref rules decide which runs reach the pool
  • Creates a launch template and an auto scaling group named runner-pool- in your organization (also needs autoscaling:CreateLaunchTemplate, autoscaling:CreateAutoScalingGroup and ec2:RunInstances). A job whose runs-on labels are all among the pool’s goes to it, with or without self-hosted in the file: give a pool ubuntu-latest and ubuntu-24.04 to move hosted jobs onto per-job machines. Idle machines stay until shortly before their paid hour ends.

dcloud ci runner-pools update

Change a pool’s labels, sizes, spare machines or machine reuse

PATCH /ci/api/runner-pools/{id} — IAM ci:UpdateRunnerPool — write

dcloud ci runner-pools update <id> [flags]

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<id> --id string uuid
Flag In Required Notes
--labels <value> body repeatable · /^[a-z0-9][a-z0-9._-]{0,49}$/ · Jobs whose runs-on labels are all among these go here, e.g. ubuntu-latest, ubuntu-24.04 (hosted jobs) or hetzner-16
--min-size <number> body integer, 0-200
--max-size <number> body integer, 1-200 · Most machines at once
--spare <number> body integer, 0-50
--clean-machine-per-job body
--share-trusted-machines body
--prebuilt-image body

dcloud ci runner-pools delete

Delete a pool: its machines drain (a running job finishes) and go

DELETE /ci/api/runner-pools/{id} — IAM ci:DeleteRunnerPool — write

dcloud ci runner-pools delete <id>

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<id> --id string uuid

dcloud ci runs

Workflow runs: one per push, pull request or re-run

Operation Method Path IAM action Effect
list GET /ci/api/repositories/{repoId}/runs ci:ListRuns read
get GET /ci/api/runs/{runId} ci:GetRun read
cancel POST /ci/api/runs/{runId}/cancel ci:CancelRun write
rerun POST /ci/api/runs/{runId}/rerun ci:RerunWorkflow write

dcloud ci runs list

List a repository’s most recent runs, newest first

GET /ci/api/repositories/{repoId}/runs — IAM ci:ListRuns — read

dcloud ci runs list <repoId>

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<repoId> --repo-id string uuid
  • At most the 50 newest runs; there is no paging or filter yet.

dcloud ci runs get

One run with its jobs and their steps, each with status and timing

GET /ci/api/runs/{runId} — IAM ci:GetRun — read

dcloud ci runs get <runId>

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<runId> --run-id string uuid
  • Answers { run, jobs, steps }. A failed step names its job; read that job’s log with dcloud ci jobs logs.

dcloud ci runs cancel

Cancel a run that is queued or in progress

POST /ci/api/runs/{runId}/cancel — IAM ci:CancelRun — write

dcloud ci runs cancel <runId>

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<runId> --run-id string uuid
  • Its machines are torn down within moments; a runner that has not started it never will. 409 when the run has already finished.

dcloud ci runs rerun

Start a new run of the same workflow at the same commit

POST /ci/api/runs/{runId}/rerun — IAM ci:RerunWorkflow — write

dcloud ci runs rerun <runId>

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<runId> --run-id string uuid
  • Planned from the workflow source the original run used, not the current file, so it reproduces what ran. Answers the new run.

dcloud ci dispatch

Start a workflow by hand (workflow_dispatch / on.manual)

Operation Method Path IAM action Effect
start POST /ci/api/repositories/{repoId}/workflows/dispatch ci:StartWorkflow write

dcloud ci dispatch start

Run one workflow file now, at a branch or tag, with inputs

POST /ci/api/repositories/{repoId}/workflows/dispatch — IAM ci:StartWorkflow — write

dcloud ci dispatch start <repoId> --path <value> [flags]

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<repoId> --repo-id string uuid
Flag In Required Notes
--path <value> body yes 1-500 chars · Workflow file, e.g. .github/workflows/ci.yml
--ref <value> body 1-250 chars · Branch or tag; the default branch when absent
--inputs <key=value> body repeatable · key=value · workflow_dispatch inputs, name → value
  • A .github/workflows/ file needs on: workflow_dispatch; an .ews/workflows/ file needs on.manual. The file is read at the tip of ref (default branch when absent); declared input defaults fill what is not passed. 201 with { runId, workflowName, path }; 409 when the file does not accept a manual start.

dcloud ci jobs

One job of a run: a machine running its steps

Operation Method Path IAM action Effect
logs GET /ci/api/jobs/{jobId}/logs ci:GetRunLogs read, sensitive

dcloud ci jobs logs

Read one page of a job’s log

GET /ci/api/jobs/{jobId}/logs — IAM ci:GetRunLogs — read, sensitive

dcloud ci jobs logs <jobId> [flags]

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<jobId> --job-id string uuid
Flag In Required Notes
--after <number> query integer, min 0 · Older clients: the sequence number to read after. Prefer cursor
--cursor <value> query nextCursor from the previous page
--limit <number> query integer, min 1 · Lines per page
  • Answers { lines, nextCursor, hasMore }. Pass nextCursor back as cursor for the next page; while the job runs, an empty page means no new lines yet.

dcloud ci variables

Configuration variables — the vars context of GitHub-syntax workflows

Operation Method Path IAM action Effect
list-org GET /ci/api/variables ci:ListVariables read
put-org PUT /ci/api/variables/{variable} ci:PutVariable write
delete-org DELETE /ci/api/variables/{variable} ci:DeleteVariable write
list GET /ci/api/repositories/{repoId}/variables ci:ListVariables read
put PUT /ci/api/repositories/{repoId}/variables/{variable} ci:PutVariable write
delete DELETE /ci/api/repositories/{repoId}/variables/{variable} ci:DeleteVariable write
list-environment GET /ci/api/repositories/{repoId}/environments/{name}/variables ci:ListVariables read
put-environment PUT /ci/api/repositories/{repoId}/environments/{name}/variables/{variable} ci:PutVariable write
delete-environment DELETE /ci/api/repositories/{repoId}/environments/{name}/variables/{variable} ci:DeleteVariable write

dcloud ci variables list-org

List the organization’s variables (every repository sees them)

GET /ci/api/variables — IAM ci:ListVariables — read

dcloud ci variables list-org

dcloud ci variables put-org

Create or change an organization variable

PUT /ci/api/variables/{variable} — IAM ci:PutVariable — write

dcloud ci variables put-org <variable> --value <value>

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<variable> --variable string /^[A-Za-z_][A-Za-z0-9_]*$/
Flag In Required Notes
--value <value> body yes max 49152 chars · Plain text, never secret; up to 48 KiB

dcloud ci variables delete-org

Delete an organization variable

DELETE /ci/api/variables/{variable} — IAM ci:DeleteVariable — write

dcloud ci variables delete-org <variable>

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<variable> --variable string /^[A-Za-z_][A-Za-z0-9_]*$/

dcloud ci variables list

List a repository’s variables

GET /ci/api/repositories/{repoId}/variables — IAM ci:ListVariables — read

dcloud ci variables list <repoId>

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<repoId> --repo-id string uuid
  • A repository variable wins over an organization one of the same name; an environment variable wins over both, in jobs of that environment.

dcloud ci variables put

Create or change a repository variable

PUT /ci/api/repositories/{repoId}/variables/{variable} — IAM ci:PutVariable — write

dcloud ci variables put <repoId> <variable> --value <value>

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<repoId> --repo-id string uuid
<variable> --variable string /^[A-Za-z_][A-Za-z0-9_]*$/
Flag In Required Notes
--value <value> body yes max 49152 chars · Plain text, never secret; up to 48 KiB

dcloud ci variables delete

Delete a repository variable

DELETE /ci/api/repositories/{repoId}/variables/{variable} — IAM ci:DeleteVariable — write

dcloud ci variables delete <repoId> <variable>

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<repoId> --repo-id string uuid
<variable> --variable string /^[A-Za-z_][A-Za-z0-9_]*$/

dcloud ci variables list-environment

List an environment’s variables

GET /ci/api/repositories/{repoId}/environments/{name}/variables — IAM ci:ListVariables — read

dcloud ci variables list-environment <repoId> <name>

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<repoId> --repo-id string uuid
<name> --name string 1-255 chars

dcloud ci variables put-environment

Create or change an environment variable

PUT /ci/api/repositories/{repoId}/environments/{name}/variables/{variable} — IAM ci:PutVariable — write

dcloud ci variables put-environment <repoId> <name> <variable> --value <value>

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<repoId> --repo-id string uuid
<name> --name string 1-255 chars
<variable> --variable string /^[A-Za-z_][A-Za-z0-9_]*$/
Flag In Required Notes
--value <value> body yes max 49152 chars · Plain text, never secret; up to 48 KiB

dcloud ci variables delete-environment

Delete an environment variable

DELETE /ci/api/repositories/{repoId}/environments/{name}/variables/{variable} — IAM ci:DeleteVariable — write

dcloud ci variables delete-environment <repoId> <name> <variable>

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<repoId> --repo-id string uuid
<name> --name string 1-255 chars
<variable> --variable string /^[A-Za-z_][A-Za-z0-9_]*$/

dcloud ci environments

Deployment environments: who may deploy where, from which branches, after whose approval

Operation Method Path IAM action Effect
list GET /ci/api/repositories/{repoId}/environments ci:ListEnvironments read
put PUT /ci/api/repositories/{repoId}/environments/{name} ci:PutEnvironment write
delete DELETE /ci/api/repositories/{repoId}/environments/{name} ci:DeleteEnvironment write
approvals GET /ci/api/repositories/{repoId}/approvals ci:ListEnvironments read
review POST /ci/api/approvals/{approvalId}/review ci:ReviewDeployments write

dcloud ci environments list

List a repository’s environments and their protection rules

GET /ci/api/repositories/{repoId}/environments — IAM ci:ListEnvironments — read

dcloud ci environments list <repoId>

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<repoId> --repo-id string uuid
  • A workflow that names an environment (environment: production) creates it without rules, as on GitHub (createdByWorkflow).

dcloud ci environments put

Create an environment or change its protection rules

PUT /ci/api/repositories/{repoId}/environments/{name} — IAM ci:PutEnvironment — write

dcloud ci environments put <repoId> <name> [flags]

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<repoId> --repo-id string uuid
<name> --name string 1-255 chars
Flag In Required Notes
--url <value> body url, max 2000 chars · nullable
--wait-timer-minutes <number> body integer, 0-43200
--reviewers <value> body repeatable · uuid
--prevent-self-review body
--deployment-branch-policy <all|protected|custom> body
--deployment-patterns <value> body repeatable
  • Fields left out keep their value. reviewers are IAM user ids of this organization (up to six); one of them must approve each job. deploymentBranchPolicy: all, protected (branches with a protection rule) or custom (deploymentPatterns). Environment secrets are the org secrets environment with the same slug.

dcloud ci environments delete

Delete an environment with its rules and variables

DELETE /ci/api/repositories/{repoId}/environments/{name} — IAM ci:DeleteEnvironment — write

dcloud ci environments delete <repoId> <name>

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<repoId> --repo-id string uuid
<name> --name string 1-255 chars

dcloud ci environments approvals

Jobs waiting at an environment for a reviewer (all=true: decided ones too)

GET /ci/api/repositories/{repoId}/approvals — IAM ci:ListEnvironments — read

dcloud ci environments approvals <repoId> [flags]

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<repoId> --repo-id string uuid
Flag In Required Notes
--all <true|false> query Also decided ones, newest first

dcloud ci environments review

Approve or reject a job waiting at an environment

POST /ci/api/approvals/{approvalId}/review — IAM ci:ReviewDeployments — write

dcloud ci environments review <approvalId> --decision <approve|reject> [flags]

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<approvalId> --approval-id string uuid
Flag In Required Notes
--decision <approve|reject> body yes
--comment <value> body max 2000 chars
  • Needs the IAM action AND a place on the environment’s reviewer list; with preventSelfReview, not the person who started the run. 409 when it was already decided.

dcloud ci artifacts

Files a run uploaded, kept until they expire

Operation Method Path IAM action Effect
list GET /ci/api/runs/{runId}/artifacts ci:ListArtifacts read
download GET /ci/api/artifacts/{artifactId}/download ci:DownloadArtifact read, sensitive

dcloud ci artifacts list

List a run’s artifacts with size and expiry

GET /ci/api/runs/{runId}/artifacts — IAM ci:ListArtifacts — read

dcloud ci artifacts list <runId>

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<runId> --run-id string uuid

dcloud ci artifacts download

Download an artifact

GET /ci/api/artifacts/{artifactId}/download — IAM ci:DownloadArtifact — read, sensitive

dcloud ci artifacts download <artifactId>

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<artifactId> --artifact-id string uuid
  • Returns raw bytes with their own content type, written straight to stdout.
  • Redirects (302) to a presigned storage URL valid for five minutes; over MCP the tool answers { url } instead of the bytes. 410 once the artifact has expired.

Not in the CLI: ci routes the surface does not describe

These routes exist and are reachable over HTTP. They are deliberately absent from the description, so there is no command for them. The reason is recorded next to the service so a gap has to be stated out loud and stops being stateable the moment the route goes.

Route Why it has no command
GET /ci/api/agent/install.sh The macOS runner installer, fetched by curl on the Mac; no caller, like /agent/bootstrap
GET /ci/api/runners/install-linux.sh The Linux installer for GitHub's runner, fetched by curl on the machine; no caller, holds nothing secret
POST /ci/api/runners/register Registration token, not a caller
POST /ci/api/runners/heartbeat Runner credential, not a caller
POST /ci/api/runners/claim Runner credential, not a caller
POST /ci/api/runners/jit Runner credential, not a caller
POST /ci/api/runner-pools/machine/jit A pool machine's instance identity token, not a caller
POST /ci/api/runner-pools/machine/retire A pool machine's instance identity token, not a caller
POST /ci/api/runner-pools/machine/baked A runner image builder's instance identity token, not a caller
GET /ci/api/agent/bootstrap Run token, not a caller
GET /ci/api/agent/plan Run token, not a caller
GET /ci/api/agent/state Run token, not a caller
POST /ci/api/agent/logs Run token, not a caller
POST /ci/api/agent/job-status Run token, not a caller
POST /ci/api/agent/step-status Run token, not a caller
POST /ci/api/agent/job-instance Run token, not a caller
POST /ci/api/agent/artifact-url Run token, not a caller
POST /ci/api/agent/artifact-complete Run token, not a caller
POST /ci/api/agent/cache-restore Run token, not a caller
POST /ci/api/agent/cache-url Run token, not a caller
POST /ci/api/agent/cache-complete Run token, not a caller
POST /ci/api/agent/complete Run token, not a caller
GET /ci/api/oidc/.well-known/openid-configuration OIDC discovery document, public by design
GET /ci/api/oidc/jwks OIDC signing keys, public by design
GET /ci/api/oidc/token A job's ACTIONS_ID_TOKEN_REQUEST_TOKEN, not a caller
GET /ci/api/oidc/gate A job's request token, polled by the environment gate step

dcloud deploy

Apps. Base path /deploy/api.

dcloud deploy apps

Deployable applications: what runs, how it is checked, where it is served

Operation Method Path IAM action Effect
list GET /deploy/api/apps deploy:DescribeApp read
get GET /deploy/api/apps/{id} deploy:DescribeApp read
create POST /deploy/api/apps deploy:CreateApp write
update PATCH /deploy/api/apps/{id} deploy:UpdateApp write
delete DELETE /deploy/api/apps/{id} deploy:DeleteApp write
routing GET /deploy/api/apps/{id}/routing deploy:DescribeApp read
resources GET /deploy/api/apps/{id}/resources deploy:DescribeApp read
resource-activity GET /deploy/api/apps/{id}/resources/activity deploy:DescribeApp read
live-diff GET /deploy/api/apps/{id}/resources/diff deploy:DescribeApp read

dcloud deploy apps list

List apps

GET /deploy/api/apps — IAM deploy:DescribeApp — read

dcloud deploy apps list

dcloud deploy apps get

Describe an app with its environment, deployments, domains and machines

GET /deploy/api/apps/{id} — IAM deploy:DescribeApp — read

dcloud deploy apps get <id>

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<id> --id string uuid
  • Also checks deploy:ManageEnv. Failing it degrades the response rather than rejecting the call.
  • Environment values are included only with deploy:ManageEnv, the compose file only with deploy:UpdateApp.

dcloud deploy apps create

Create an app

POST /deploy/api/apps — IAM deploy:CreateApp — write

dcloud deploy apps create --name <value> [flags]
Flag In Required Notes
--name <value> body yes 1-64 chars · Display name of the app
--slug <value> body 1-63 chars, /^a-z0-9?$/ · Short name used in the app’s default hostname; must be unique in the organization; derived from name when omitted
--hosting <machine|pooled> body machine (default): the app runs on its own machines; pooled: a Next.js app on shared hosts that scales to zero, deployed from bundles your CI uploads
--memory-mb <number> body integer, 256-2048 · Pooled hosting: memory reserved for the app’s server while it runs, in MB; default 768
--idle-seconds <number> body integer, 60-3600 · Pooled hosting: seconds without a request after which the app’s server is stopped; default 300
--database <none|postgres> body Pooled hosting only: postgres gives the app a Postgres database on its pool host (needs deploy:ManageHostDatabase); none (default) gives it none. An app on its own machines is refused with 400 and binds a managed Postgres instead
--git-repository-id <value> body Git repository the app builds from; required for every builder except image and compose. The app starts with that repository’s tags
--branch <value> body 1-255 chars · Branch the app deploys from; omitted, the repository’s default branch (main for pooled hosting)
--deploy-on-push body Deploy each commit pushed to the branch, as the person who pushed it; default true when gitRepositoryId is set (always false for pooled hosting)
--root-dir <value> body 1-255 chars, /^[A-Za-z0-9._/-]+$/ · Directory in the repository the app is built from; default the repository root (.)
--builder <railpack|dockerfile|forgejo_actions|image|compose> body How the app is built: railpack (default) detects the stack, dockerfile uses the repository’s Dockerfile, image runs imageRef, compose runs a compose file
--build-command <value> body max 1024 chars · Replaces the build command the builder would detect
--start-command <value> body max 1024 chars · Replaces the command the builder would start the app with
--image-ref <value> body 1-512 chars, /^a-z0-9?(:[0-9]+)?(/a-z0-9?)*(:[A-Za-z0-9._-]+|@sha256:[a-f0-9]{64})?$/ · Container image the app runs (host/repository:tag or @sha256 digest); required when builder is image. A short Docker Hub name is stored with docker.io/ in front
--ecr-repository-id <value> body Repository of this organization’s registry the image comes from, so the machines get a pull credential for it; for an inline compose file it is found from the file when omitted
--compose-source <inline|git> body Compose apps: inline takes the file text from composeFile, git reads composePath from the connected repository
--compose-file <value> body max 131072 chars · Compose apps with composeSource inline: the compose file text, checked when saved
--compose-path <value> body 1-255 chars, /^[A-Za-z0-9._/-]+$/ · Compose apps with composeSource git: path of the compose file in the repository
--compose-service <value> body 1-63 chars · Compose apps: the service published on the app’s domains; required
--compose-port <number> body integer, 1-65535 · Compose apps: the container port of composeService that receives traffic; required
--port <number> body integer, 1-65535 · Port the app listens on in its container; default 3000
--instance-type <value> body 1-32 chars · Machine size of each machine, an instance type, e.g. performance-2 (the provider’s own names are still accepted, deprecated); default the region’s default size
--replicas <number> body integer, 1-10 · Number of machines; default 1. More than one puts a load balancer in front
--release-command <value> body 1-4096 chars · nullable · Command run once per deployment with /bin/sh -c in the new image, before traffic moves to it (e.g. database migrations); null or omitted runs none
--release-service <value> body 1-63 chars · nullable · Compose apps: the service whose image and environment run the release command; omitted or null, the published service
--release-timeout-sec <number> body integer, 10-3600 · Seconds the release command may run before the deployment fails; a new app gets 600
--health-check <json> body JSON · nullable · The HTTP check a new container must pass before it gets traffic; null or omitted means GET / on the app port, any status below 500
--compose-health-checks <key=<json>> body repeatable · key= · nullable · Compose apps: health checks for services other than the published one, keyed by service name
--tags <key=value> body repeatable · key=value · Tags for the app, added to those inherited from the repository
  • builder "image" needs imageRef; "compose" needs composeSource, composeService and composePort.

dcloud deploy apps update

Change an app, including its release command and health checks

PATCH /deploy/api/apps/{id} — IAM deploy:UpdateApp — write

dcloud deploy apps update <id> [flags]

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<id> --id string uuid
Flag In Required Notes
--name <value> body 1-64 chars · New display name
--branch <value> body 1-255 chars · nullable · Branch the app deploys from; null returns to the repository’s default branch
--deploy-on-push body Whether each commit pushed to the branch is deployed
--root-dir <value> body 1-255 chars, /^[A-Za-z0-9._/-]+$/ · Directory in the repository the app is built from
--builder <railpack|dockerfile|forgejo_actions|image|compose> body How the app is built: railpack, dockerfile, image or compose (see Create an app)
--build-command <value> body max 1024 chars · nullable · Replaces the detected build command; null returns to the detected one
--start-command <value> body max 1024 chars · nullable · Replaces the detected start command; null returns to the detected one
--image-ref <value> body 1-512 chars, /^a-z0-9?(:[0-9]+)?(/a-z0-9?)*(:[A-Za-z0-9._-]+|@sha256:[a-f0-9]{64})?$/ · Container image the app runs, for builder image
--compose-source <inline|git> body Compose apps: inline (composeFile) or git (composePath in the repository)
--compose-file <value> body max 131072 chars · Compose apps: the new compose file text, checked when saved
--compose-path <value> body 1-255 chars, /^[A-Za-z0-9._/-]+$/ · Compose apps: path of the compose file in the repository
--compose-service <value> body 1-63 chars · Compose apps: the service published on the app’s domains
--compose-port <number> body integer, 1-65535 · Compose apps: the container port of composeService that receives traffic
--port <number> body integer, 1-65535 · Port the app listens on in its container
--instance-type <value> body 1-32 chars · Machine size of each machine, an instance type, e.g. performance-2 (the provider’s own names are still accepted, deprecated)
--replicas <number> body integer, 1-10 · Number of machines; more than one puts a load balancer in front
--locations <value> body repeatable · /^[a-z]{3}\d$/ · Locations the machines are spread over in order, all in one region (e.g. fsn1, nbg1); empty means the region’s own location
--release-command <value> body 1-4096 chars · nullable · Command run once per deployment with /bin/sh -c in the new image, before traffic moves to it (e.g. database migrations); null or omitted runs none
--release-service <value> body 1-63 chars · nullable · Compose apps: the service whose image and environment run the release command; omitted or null, the published service
--release-timeout-sec <number> body integer, 10-3600 · Seconds the release command may run before the deployment fails; a new app gets 600
--health-check <json> body JSON · nullable · The HTTP check a new container must pass before it gets traffic; null or omitted means GET / on the app port, any status below 500
--compose-health-checks <key=<json>> body repeatable · key= · nullable · Compose apps: health checks for services other than the published one, keyed by service name
  • Takes effect on the next deployment.

dcloud deploy apps delete

Delete an app

DELETE /deploy/api/apps/{id} — IAM deploy:DeleteApp — write

dcloud deploy apps delete <id>

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<id> --id string uuid

dcloud deploy apps routing

Show how each hostname of the app resolves right now

GET /deploy/api/apps/{id}/routing — IAM deploy:DescribeApp — read

dcloud deploy apps routing <id>

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<id> --id string uuid

dcloud deploy apps resources

Show the app as a tree: deployment, load balancer, machines, containers, names and bound data, each with health and sync

GET /deploy/api/apps/{id}/resources — IAM deploy:DescribeApp — read

dcloud deploy apps resources <id>

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<id> --id string uuid
  • Bound databases, caches and brokers appear only for a caller who may describe that service. Health is one of healthy, progressing, degraded, suspended, missing, unknown; sync is in_sync, out_of_sync or unknown.

dcloud deploy apps resource-activity

Read one node's last events and, for a container, its last log lines

GET /deploy/api/apps/{id}/resources/activity — IAM deploy:DescribeApp — read

dcloud deploy apps resource-activity <id> --node <value>

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<id> --id string uuid
Flag In Required Notes
--node <value> query yes 1-300 chars · Key of a node from the resources tree, e.g. machine:i-abc or container:i-abc:web
  • node is a key from the resources tree, e.g. machine:i-abc or container:i-abc:web. Log lines need monitoring:FilterLogEvents.

dcloud deploy apps live-diff

Compare what one machine runs with what it was asked to run

GET /deploy/api/apps/{id}/resources/diff — IAM deploy:DescribeApp — read

dcloud deploy apps live-diff <id> --instance <value>

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<id> --id string uuid
Flag In Required Notes
--instance <value> query yes /^i-[a-z0-9]{1,40}$/ · The machine to compare, by its id as the resources tree names it (i-…)
  • state is match, differs or unknown (the machine has not sent a summary yet). Containers, images, states, published ports, routes and the health check are compared; environment keys only for a caller with deploy:ManageEnv, by keyed hash. Values never leave the machine.

dcloud deploy hosting

Pooled hosting of a Next.js app: hand over a build, see where and how the app runs (scales to zero)

Operation Method Path IAM action Effect
get GET /deploy/api/apps/{id}/hosting deploy:DescribeApp read
create-bundle POST /deploy/api/apps/{id}/bundles deploy:DeployApp write
complete-bundle POST /deploy/api/apps/{id}/bundles/{deploymentId}/complete deploy:DeployApp write

dcloud deploy hosting get

Show how a pooled app is served: its URLs, deployments and previews, what is served from files and what needs its server, and whether the server runs

GET /deploy/api/apps/{id}/hosting — IAM deploy:DescribeApp — read

dcloud deploy hosting get <id>

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<id> --id string uuid

dcloud deploy hosting create-bundle

Start a deployment of a pooled app from a build: returns an upload URL for the bundle

POST /deploy/api/apps/{id}/bundles — IAM deploy:DeployApp — write

dcloud deploy hosting create-bundle <id> --commit-sha <value> --sha256 <value> --size-bytes <number> [flags]

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<id> --id string uuid
Flag In Required Notes
--commit-sha <value> body yes 4-64 chars, /^[0-9A-Za-z._-]+$/ · The commit the bundle was built from; also names its preview URL
--branch <value> body 1-255 chars · nullable · The branch the commit was pushed to: the app’s branch (default main) makes it production, any other a preview; omitted or null counts as production
--sha256 <value> body yes /^[0-9a-f]{64}$/ · SHA-256 of the tar.gz, in hex; checked again after download
--size-bytes <number> body yes integer, 1-1073741824 · Exact size of the tar.gz in bytes; completing fails if the upload differs
  • The bundle is a tar.gz of .next/standalone, .next/static, .next/server, .next/ews-outputs.json and public/ (the starter template workflow makes it). PUT it to uploadUrl within an hour, then call complete-bundle. A commit on the app branch (default main) becomes production; any other branch a preview at its own URL.

dcloud deploy hosting complete-bundle

Confirm a bundle upload: the deployment is served at its URLs

POST /deploy/api/apps/{id}/bundles/{deploymentId}/complete — IAM deploy:DeployApp — write

dcloud deploy hosting complete-bundle <id> <deploymentId>

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<id> --id string uuid
<deploymentId> --deployment-id string uuid
  • Fails while the upload is missing or its size differs from the one announced.

dcloud deploy host-database

A pooled app's Postgres on its pool host: single node, no failover, backed up daily and before a delete

Operation Method Path IAM action Effect
get GET /deploy/api/apps/{id}/host-database deploy:DescribeApp read
create POST /deploy/api/apps/{id}/host-database deploy:ManageHostDatabase write
set-limit PATCH /deploy/api/apps/{id}/host-database deploy:ManageHostDatabase write
backup POST /deploy/api/apps/{id}/host-database/backups deploy:ManageHostDatabase write
restore POST /deploy/api/apps/{id}/host-database/restore deploy:RestoreHostDatabase write
move POST /deploy/api/apps/{id}/host-database/move deploy:ManageHostDatabase write

dcloud deploy host-database get

Show a pooled app's pool-host database and its backups, newest first

GET /deploy/api/apps/{id}/host-database — IAM deploy:DescribeApp — read

dcloud deploy host-database get <id>

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<id> --id string uuid

dcloud deploy host-database create

Give a pooled app a Postgres database on its pool host; the app gets DATABASE_URL at its next start

POST /deploy/api/apps/{id}/host-database — IAM deploy:ManageHostDatabase — write

dcloud deploy host-database create <id>

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<id> --id string uuid
  • One Postgres per pool host, a database and role per app, on the host disk. No failover: a lost host is replaced and the database restored from its newest backup. Your own DATABASE_URL (or a managed Postgres binding) wins over this one.

dcloud deploy host-database set-limit

Set the database size limit (MiB); over it the database is read only

PATCH /deploy/api/apps/{id}/host-database — IAM deploy:ManageHostDatabase — write

dcloud deploy host-database set-limit <id> --limit-mb <number>

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<id> --id string uuid
Flag In Required Notes
--limit-mb <number> body yes integer, 64-20480 · The size limit in MiB, 64 (64 MiB) to 20480 (20 GiB); over it the database is read only
  • 1 GiB unless set, 64 MiB to 20 GiB. Over the limit the pool host makes the database read only (writes fail with "cannot execute … in a read-only transaction") and get says so in limitProblem; below 90 % of the limit it is writable again.

dcloud deploy host-database backup

Back the database up now (kept 30 days)

POST /deploy/api/apps/{id}/host-database/backups — IAM deploy:ManageHostDatabase — write

dcloud deploy host-database backup <id>

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<id> --id string uuid
  • The pool host takes it within seconds; it appears in get when done.

dcloud deploy host-database restore

Replace the database with one of its backups

POST /deploy/api/apps/{id}/host-database/restore — IAM deploy:RestoreHostDatabase — write

dcloud deploy host-database restore <id> --backup-id <value>

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<id> --id string uuid
Flag In Required Notes
--backup-id <value> body yes The backup to restore: one of the app’s backups listed by get
  • The current data is backed up first (reason before-restore, kept 7 days), so a restore can be undone.

dcloud deploy host-database move

Move the database to managed Postgres in one step: dump, create the role and database there, restore, bind

POST /deploy/api/apps/{id}/host-database/move — IAM deploy:ManageHostDatabase — write

dcloud deploy host-database move <id> [flags]

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<id> --id string uuid
Flag In Required Notes
--db-instance-id <value> body 3-64 chars · An existing managed Postgres database to move to; it may still be creating (the move waits). Give this or instanceClass
--instance-class <value> body 1-32 chars · Or create a managed Postgres named -db of this instance class (as rds instances create --instance-class), single node, in the app’s region
  • Also needs deploy:ManageDatabaseBinding and rds:ModifyDBInstance on the database (with instanceClass: on all databases, and rds:CreateDBInstance; checked before anything is created). The database must be a publicly accessible Postgres, since a pool host reaches managed Postgres only on its public endpoint; with instanceClass it is created so. It may still be creating: the move waits for it. The app is bound only after the restore succeeded. Writes made between the dump and the switch are not carried over, so move at a quiet time. The pool-host copy is dropped; its dump is kept 30 days.

dcloud deploy deployments

Rollouts of an app: trigger, read, wait for, cancel

Operation Method Path IAM action Effect
list GET /deploy/api/apps/{id}/deployments deploy:DescribeApp read
create POST /deploy/api/apps/{id}/deployments deploy:DeployApp write
get GET /deploy/api/deployments/{id} deploy:DescribeApp read
wait GET /deploy/api/deployments/{id}/wait deploy:DescribeApp read
events GET /deploy/api/deployments/{id}/events deploy:DescribeApp read
build-log GET /deploy/api/deployments/{id}/build-log deploy:GetBuildLogs read, sensitive
cancel POST /deploy/api/deployments/{id}/cancel deploy:DeployApp write

dcloud deploy deployments list

List the deployments of an app, newest first

GET /deploy/api/apps/{id}/deployments — IAM deploy:DescribeApp — read

dcloud deploy deployments list <id>

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<id> --id string uuid

dcloud deploy deployments create

Start a deployment of an app

POST /deploy/api/apps/{id}/deployments — IAM deploy:DeployApp — write

dcloud deploy deployments create <id> [flags]

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<id> --id string uuid
Flag In Required Notes
--trigger <manual|rollback> body server default "manual" · rollback marks the deployment as a rollback and, with fromDeploymentId, restores that deployment’s environment by default
--git-commit-sha <value> body 7-64 chars · Commit to build; omitted, the head of the app’s branch
--image-ref <value> body 1-512 chars, /^a-z0-9?(:[0-9]+)?(/a-z0-9?)*(:[A-Za-z0-9._-]+|@sha256:[a-f0-9]{64})?$/ · Image to run for this deployment only; the app’s own image is not changed
--from-deployment-id <value> body An earlier deployment of this app to run again: its image or pinned compose file, commit and release command
--reason <value> body 1-500 chars · Why, shown on the deployment timeline beside who started it
--restore-environment body With fromDeploymentId: also put back the environment that deployment started with; default true for a rollback, false otherwise
  • imageRef deploys that image this once without changing the app. An image in this organization’s registry is resolved to a digest first. fromDeploymentId runs what that deployment ran; with trigger rollback it also restores the environment that deployment started with (restoreEnvironment, default true for a rollback, needs deploy:ManageEnv as well).

dcloud deploy deployments get

Describe one deployment

GET /deploy/api/deployments/{id} — IAM deploy:DescribeApp — read

dcloud deploy deployments get <id>

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<id> --id string uuid

dcloud deploy deployments wait

Wait until a deployment is live, failed or superseded

GET /deploy/api/deployments/{id}/wait — IAM deploy:DescribeApp — read

dcloud deploy deployments wait <id> [flags]

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<id> --id string uuid
Flag In Required Notes
--timeout-sec <number> query integer, 1-55 · Seconds to wait at most before answering with terminal false; default 55
  • Long-poll: returns at a terminal status or after timeoutSec (max 55) with terminal=false. Call it again until terminal. A failed deployment carries its error events.

dcloud deploy deployments events

Read the activity feed of a deployment, including release output

GET /deploy/api/deployments/{id}/events — IAM deploy:DescribeApp — read

dcloud deploy deployments events <id> [flags]

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<id> --id string uuid
Flag In Required Notes
--since <value> query datetime · Only events created after this time (ISO 8601), to follow the feed

dcloud deploy deployments build-log

Read the log of a deployment's image build, line by line

GET /deploy/api/deployments/{id}/build-log — IAM deploy:GetBuildLogs — read, sensitive

dcloud deploy deployments build-log <id> [flags]

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<id> --id string uuid
Flag In Required Notes
--after <number> query integer, min 0 · The previous answer’s next: only lines after this byte offset; omitted, from the start
--limit <number> query integer, 1-5000 · Most lines to return; default 2000
  • Lines as the builder printed them (colours stripped, URL credentials masked), kept with the deployment. Pass the previous answer's next as after to tail it while it runs; done is true once the builder reported its exitCode or the build step is over.

dcloud deploy deployments cancel

Stop a deployment that has not finished

POST /deploy/api/deployments/{id}/cancel — IAM deploy:DeployApp — write

dcloud deploy deployments cancel <id>

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<id> --id string uuid
  • Only a queued, building, pushing or deploying deployment can be cancelled (409 otherwise). The pipeline stops at the end of its current step.

dcloud deploy env

Environment of an app: plain values, secrets, synced 1Password references

Operation Method Path IAM action Effect
get GET /deploy/api/apps/{id}/env deploy:ManageEnv write
replace PUT /deploy/api/apps/{id}/env deploy:ManageEnv write
import POST /deploy/api/apps/{id}/env/import deploy:ManageEnv write
export GET /deploy/api/apps/{id}/env/export deploy:ManageEnv write

dcloud deploy env get

Variables with sync status, database bindings, and whether a redeploy is pending

GET /deploy/api/apps/{id}/env — IAM deploy:ManageEnv — write

dcloud deploy env get <id>

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<id> --id string uuid

dcloud deploy env replace

Replace the whole environment of an app

PUT /deploy/api/apps/{id}/env — IAM deploy:ManageEnv — write

dcloud deploy env replace <id> --vars <value> [flags]

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<id> --id string uuid
Flag In Required Notes
--vars <value> body yes repeatable · The complete environment: each entry is a key with valueKind plain (and plainValue, one line) or secret (and kmsSecretId, the Secret to bind). Keys left out are removed
--redeploy body Also roll the live deployment onto the new environment; default false
  • May check secrets:GetSecretValue or deploy:DeployApp instead, decided by server-side state the caller cannot see. A caller needs all of them to be sure of not getting a 403.
  • Binding a secret needs secrets:GetSecretValue on it and grants it to the deploy consumer. Saving does not restart the app. Pass redeploy: true to roll the live deployment’s own source onto the new configuration (also needs deploy:DeployApp); otherwise the response and GET …/env report pending until someone redeploys.

dcloud deploy env import

Import a .env or .env.op file — dry run for the plan, then apply atomically

POST /deploy/api/apps/{id}/env/import — IAM deploy:ManageEnv — write

dcloud deploy env import <id> --content <value> [flags]

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<id> --id string uuid
Flag In Required Notes
--content <value> body yes max 524288 chars · The .env / .env.op file text
--mode <merge|replace> body merge (default) keeps variables the file does not mention; replace removes them
--classify <key=value> body repeatable · key=value · Per key, plain or secret, overriding the kind the import would pick
--source <value> body 2-63 chars · nullable · Secret source (by name) for NEW op:// references, needed only when several sources reach the vault
--source-id <value> body uuid · nullable · The same secret source as source, by id (the older spelling)
--key-id <value> body uuid · nullable · KMS key new secrets are encrypted under; default the organization’s default key
--preview body Return the plan without changing anything; default false
--redeploy body Also roll the live deployment onto the imported environment; default false, ignored with preview
  • May check secrets:CreateSecret or secrets:RotateSecret or secrets:UseSecretSource or secrets:GetSecretValue or deploy:DeployApp instead, decided by server-side state the caller cannot see. A caller needs all of them to be sure of not getting a 403.
  • dcloud deploy env import --content "$(cat .env.op)" --preview. op:// references become synced secrets; sensitive-looking values become secrets, the rest plain (override per key with classify); dcloud-secret://NAME (or ews-secret://NAME) binds an existing secret. mode=merge keeps keys the file omits, replace removes them. Nothing is applied if any key has an error. No value is ever echoed back. Saving does not restart the app. Pass redeploy: true to roll the live deployment’s own source onto the new configuration (also needs deploy:DeployApp); otherwise the response and GET …/env report pending until someone redeploys.

dcloud deploy env export

The environment as .env text — plain values, references, secret names; no secret values

GET /deploy/api/apps/{id}/env/export — IAM deploy:ManageEnv — write

dcloud deploy env export <id>

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<id> --id string uuid

dcloud deploy connections

How each database and cache binding connects — everything but the password

Operation Method Path IAM action Effect
get GET /deploy/api/apps/{id}/connections deploy:DescribeApp read

dcloud deploy connections get

Host (private or public, as the binding resolves it), port, database, role and the secret holding the password

GET /deploy/api/apps/{id}/connections — IAM deploy:DescribeApp — read

dcloud deploy connections get <id>

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<id> --id string uuid
  • Resolved exactly as the next rollout resolves it; a binding that would fail the rollout carries error instead of connection. No password is returned: read it with dcloud secrets secrets get-value <password.secretId> (needs secrets:GetSecretValue on that secret, audited). DATABASE_URL is postgresql://:@:/?sslmode=require.

dcloud deploy redeploy

Roll the saved configuration out

Operation Method Path IAM action Effect
apply POST /deploy/api/apps/{id}/redeploy deploy:DeployApp write

dcloud deploy redeploy apply

Redeploy the live deployment’s source with the current configuration (no rebuild)

POST /deploy/api/apps/{id}/redeploy — IAM deploy:DeployApp — write

dcloud deploy redeploy apply <id> [flags]

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<id> --id string uuid
Flag In Required Notes
--reason <value> body max 200 chars · Why, shown on the deployment; default "configuration applied by "

dcloud deploy database

Managed Postgres binding — DATABASE_URL and PG* generated from it

Operation Method Path IAM action Effect
bind PUT /deploy/api/apps/{id}/database deploy:ManageDatabaseBinding write
rotate POST /deploy/api/apps/{id}/database/rotate deploy:ManageDatabaseBinding write
unbind DELETE /deploy/api/apps/{id}/database deploy:ManageDatabaseBinding write

dcloud deploy database bind

Bind a managed Postgres database (a dedicated app role by default)

PUT /deploy/api/apps/{id}/database — IAM deploy:ManageDatabaseBinding — write

dcloud deploy database bind <id> --db-instance-id <value> [flags]

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<id> --id string uuid
Flag In Required Notes
--db-instance-id <value> body yes 3-64 chars · The managed Postgres database (instance) to bind
--db-branch-id <value> body /^ewbr-[0-9a-f]{12}$/ · A branch of the database (ewbr-…) to connect to instead: the branch's master user and port, no pooler
--database <value> body /^[a-z_][a-z0-9_]{0,62}$/ · Database inside the instance (app_role mode creates it if missing). Default: the app’s slug as a Postgres name; in master mode or for a branch, the instance’s own database
--mode <app_role|master> body app_role (default): a role of the app’s own, its password kept in Secrets; master: the instance’s master credential
--env-prefix <value> body max 32 chars, /^([A-Z][A-Z0-9_]*_)?$/ · Put in front of every generated variable name (e.g. CACHE_ gives CACHE_REDIS_URL), so one app can hold several bindings of a kind; default empty
--pooled body Connect through the PgBouncer pooler (default true) or straight to Postgres on 5432; ignored for a branch
--redeploy body Also roll the live deployment onto the new configuration; default false
  • May check rds:ModifyDBInstance or deploy:DeployApp instead, decided by server-side state the caller cannot see. A caller needs all of them to be sure of not getting a 403.
  • mode=app_role creates role app_ and its database (or grants on an existing one); its password is a secret the binding reads at every rollout. mode=master hands the app the master credential. Saving does not restart the app. Pass redeploy: true to roll the live deployment’s own source onto the new configuration (also needs deploy:DeployApp); otherwise the response and GET …/env report pending until someone redeploys.

dcloud deploy database rotate

New password for the app role; redeploys by default

POST /deploy/api/apps/{id}/database/rotate — IAM deploy:ManageDatabaseBinding — write

dcloud deploy database rotate <id> [flags]

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<id> --id string uuid
Flag In Required Notes
--env-prefix <value> body max 32 chars, /^([A-Z][A-Z0-9_]*_)?$/ · Which database binding, by its envPrefix; default empty (the unprefixed one)
--redeploy body Roll the live deployment onto the new password; default true, since new connections with the old password stop working at once
  • May check rds:ModifyDBInstance or deploy:DeployApp instead, decided by server-side state the caller cannot see. A caller needs all of them to be sure of not getting a 403.

dcloud deploy database unbind

Remove the binding (the role and its data are kept)

DELETE /deploy/api/apps/{id}/database — IAM deploy:ManageDatabaseBinding — write

dcloud deploy database unbind <id> [flags]

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<id> --id string uuid
Flag In Required Notes
--env-prefix <value> query max 32 chars, /^([A-Z][A-Z0-9_]*_)?$/ · Which binding to remove, by its envPrefix; default empty (the unprefixed one)

dcloud deploy cache

Managed Valkey binding — REDIS_URL and VALKEY_URL generated from it

Operation Method Path IAM action Effect
bind PUT /deploy/api/apps/{id}/cache deploy:ManageCacheBinding write
unbind DELETE /deploy/api/apps/{id}/cache deploy:ManageCacheBinding write

dcloud deploy cache bind

Bind a managed Valkey cache (its private address, in the app’s VPC)

PUT /deploy/api/apps/{id}/cache — IAM deploy:ManageCacheBinding — write

dcloud deploy cache bind <id> --cache-cluster-id <value> [flags]

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<id> --id string uuid
Flag In Required Notes
--cache-cluster-id <value> body yes /^ewc-[0-9a-f]{12}$/ · The managed Valkey cache to bind
--env-prefix <value> body max 32 chars, /^([A-Z][A-Z0-9_]*_)?$/ · Put in front of every generated variable name (e.g. CACHE_ gives CACHE_REDIS_URL), so one app can hold several bindings of a kind; default empty
--redeploy body Also roll the live deployment onto the new configuration; default false
  • May check cache:ModifyCacheCluster or deploy:DeployApp instead, decided by server-side state the caller cannot see. A caller needs all of them to be sure of not getting a 403.
  • Generates {prefix}REDIS_URL and {prefix}VALKEY_URL (redis://default:@:6379) at every rollout. Refused unless every machine of the app is in the cache’s VPC. Saving does not restart the app. Pass redeploy: true to roll the live deployment’s own source onto the new configuration (also needs deploy:DeployApp); otherwise the response and GET …/env report pending until someone redeploys.

dcloud deploy cache unbind

Remove the binding (the cache is unchanged)

DELETE /deploy/api/apps/{id}/cache — IAM deploy:ManageCacheBinding — write

dcloud deploy cache unbind <id> [flags]

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<id> --id string uuid
Flag In Required Notes
--env-prefix <value> query max 32 chars, /^([A-Z][A-Z0-9_]*_)?$/ · Which binding to remove, by its envPrefix; default empty (the unprefixed one)

dcloud deploy kafka

Managed Kafka binding — KAFKA_BOOTSTRAP_SERVERS and the SASL settings, as a named user

Operation Method Path IAM action Effect
bind PUT /deploy/api/apps/{id}/kafka deploy:ManageBrokerBinding write
unbind DELETE /deploy/api/apps/{id}/kafka deploy:ManageBrokerBinding write

dcloud deploy kafka bind

Bind a managed Kafka cluster as one of its users (private, in the app’s VPC)

PUT /deploy/api/apps/{id}/kafka — IAM deploy:ManageBrokerBinding — write

dcloud deploy kafka bind <id> --cluster-id <value> --user-name <value> [flags]

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<id> --id string uuid
Flag In Required Notes
--cluster-id <value> body yes /^kfk-[0-9a-f]{12}$/ · The managed Kafka cluster to bind
--user-name <value> body yes /^[a-z][a-z0-9_.-]{0,63}$/ · The cluster user the app signs in as (create one with the right grants first)
--env-prefix <value> body max 32 chars, /^([A-Z][A-Z0-9_]*_)?$/ · Put in front of every generated variable name (e.g. CACHE_ gives CACHE_REDIS_URL), so one app can hold several bindings of a kind; default empty
--redeploy body Also roll the live deployment onto the new configuration; default false
  • May check secrets:GetSecretValue or deploy:DeployApp instead, decided by server-side state the caller cannot see. A caller needs all of them to be sure of not getting a 403.
  • Generates {prefix}KAFKA_BOOTSTRAP_SERVERS (every node:9093), KAFKA_SECURITY_PROTOCOL (SASL_SSL), KAFKA_SASL_MECHANISM (SCRAM-SHA-512), KAFKA_SASL_USERNAME, KAFKA_SASL_PASSWORD (the user’s current password from Secrets) and KAFKA_SSL_CA_LOCATION (the platform CA in the container) at every rollout. Needs secrets:GetSecretValue on the user’s password. A bound user cannot be deleted. Saving does not restart the app. Pass redeploy: true to roll the live deployment’s own source onto the new configuration (also needs deploy:DeployApp); otherwise the response and GET …/env report pending until someone redeploys.

dcloud deploy kafka unbind

Remove the binding (the cluster and its user are unchanged)

DELETE /deploy/api/apps/{id}/kafka — IAM deploy:ManageBrokerBinding — write

dcloud deploy kafka unbind <id> [flags]

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<id> --id string uuid
Flag In Required Notes
--env-prefix <value> query max 32 chars, /^([A-Z][A-Z0-9_]*_)?$/ · Which binding to remove, by its envPrefix; default empty (the unprefixed one)

dcloud deploy rabbitmq

Managed RabbitMQ binding — AMQP_URL and AMQP_HOSTS, as a named user

Operation Method Path IAM action Effect
bind PUT /deploy/api/apps/{id}/rabbitmq deploy:ManageBrokerBinding write
unbind DELETE /deploy/api/apps/{id}/rabbitmq deploy:ManageBrokerBinding write

dcloud deploy rabbitmq bind

Bind a managed RabbitMQ broker as one of its users (private, in the app’s VPC)

PUT /deploy/api/apps/{id}/rabbitmq — IAM deploy:ManageBrokerBinding — write

dcloud deploy rabbitmq bind <id> --broker-id <value> --user-name <value> [flags]

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<id> --id string uuid
Flag In Required Notes
--broker-id <value> body yes /^rmq-[0-9a-f]{12}$/ · The managed RabbitMQ broker to bind
--user-name <value> body yes /^[a-z][a-z0-9_.-]{0,63}$/ · The broker user the app signs in as
--env-prefix <value> body max 32 chars, /^([A-Z][A-Z0-9_]*_)?$/ · Put in front of every generated variable name (e.g. CACHE_ gives CACHE_REDIS_URL), so one app can hold several bindings of a kind; default empty
--redeploy body Also roll the live deployment onto the new configuration; default false
  • May check secrets:GetSecretValue or deploy:DeployApp instead, decided by server-side state the caller cannot see. A caller needs all of them to be sure of not getting a 403.
  • Generates {prefix}AMQP_URL (amqps://user:password@:5671/%2F — the balancer with 3 nodes), AMQP_HOSTS (every node:5671, for clients that take a list), AMQP_USERNAME, AMQP_PASSWORD and AMQP_CA_FILE (the platform CA in the container) at every rollout. Needs secrets:GetSecretValue on the user’s password. A bound user cannot be deleted. Saving does not restart the app. Pass redeploy: true to roll the live deployment’s own source onto the new configuration (also needs deploy:DeployApp); otherwise the response and GET …/env report pending until someone redeploys.

dcloud deploy rabbitmq unbind

Remove the binding (the broker and its user are unchanged)

DELETE /deploy/api/apps/{id}/rabbitmq — IAM deploy:ManageBrokerBinding — write

dcloud deploy rabbitmq unbind <id> [flags]

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<id> --id string uuid
Flag In Required Notes
--env-prefix <value> query max 32 chars, /^([A-Z][A-Z0-9_]*_)?$/ · Which binding to remove, by its envPrefix; default empty (the unprefixed one)

dcloud deploy docdb

Document Database binding — MONGODB_URL, as the master user or one of its users

Operation Method Path IAM action Effect
bind PUT /deploy/api/apps/{id}/docdb deploy:ManageBrokerBinding write
unbind DELETE /deploy/api/apps/{id}/docdb deploy:ManageBrokerBinding write

dcloud deploy docdb bind

Bind a Document Database cluster (MongoDB-compatible) as one of its users

PUT /deploy/api/apps/{id}/docdb — IAM deploy:ManageBrokerBinding — write

dcloud deploy docdb bind <id> --cluster-id <value> --user-name <value> [flags]

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<id> --id string uuid
Flag In Required Notes
--cluster-id <value> body yes /^ewdoc-[0-9a-f]{12}$/ · The Document Database cluster to bind
--user-name <value> body yes The user the app signs in as: the cluster’s master user (masterUsername) or one of its users
--env-prefix <value> body max 32 chars, /^([A-Z][A-Z0-9_]*_)?$/ · Put in front of every generated variable name (e.g. CACHE_ gives CACHE_REDIS_URL), so one app can hold several bindings of a kind; default empty
--redeploy body Also roll the live deployment onto the new configuration; default false
  • May check secrets:GetSecretValue or deploy:DeployApp instead, decided by server-side state the caller cannot see. A caller needs all of them to be sure of not getting a 403.
  • Generates {prefix}MONGODB_URL (mongodb://user:password@:27017/?tls=true&authMechanism=SCRAM-SHA-256&authSource=admin&directConnection=true&tlsCAFile=) at every rollout, and on a 3-node cluster {prefix}MONGODB_READER_URL (the same on port 27018: the replicas, reads only, may lag). A private cluster needs the app’s machines in its VPC; a public one is reachable from anywhere. Needs secrets:GetSecretValue on that user’s password. Saving does not restart the app. Pass redeploy: true to roll the live deployment’s own source onto the new configuration (also needs deploy:DeployApp); otherwise the response and GET …/env report pending until someone redeploys.

dcloud deploy docdb unbind

Remove the binding (the cluster is unchanged)

DELETE /deploy/api/apps/{id}/docdb — IAM deploy:ManageBrokerBinding — write

dcloud deploy docdb unbind <id> [flags]

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<id> --id string uuid
Flag In Required Notes
--env-prefix <value> query max 32 chars, /^([A-Z][A-Z0-9_]*_)?$/ · Which binding to remove, by its envPrefix; default empty (the unprefixed one)

dcloud deploy errors

Error Tracking binding — SENTRY_DSN, NEXT_PUBLIC_SENTRY_DSN, SENTRY_ENVIRONMENT, SENTRY_RELEASE and a per-build upload token

Operation Method Path IAM action Effect
get GET /deploy/api/apps/{id}/errors deploy:DescribeApp read
connect PUT /deploy/api/apps/{id}/errors deploy:ManageErrorsBinding write
disconnect DELETE /deploy/api/apps/{id}/errors deploy:ManageErrorsBinding write

dcloud deploy errors get

The app’s Error Tracking binding: project, variable names, environment, DSN

GET /deploy/api/apps/{id}/errors — IAM deploy:DescribeApp — read

dcloud deploy errors get <id>

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<id> --id string uuid

dcloud deploy errors connect

Connect Error Tracking: DSN, environment and release at build and run time

PUT /deploy/api/apps/{id}/errors — IAM deploy:ManageErrorsBinding — write

dcloud deploy errors connect <id> --project-id <value> [flags]

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<id> --id string uuid
Flag In Required Notes
--project-id <value> body yes uuid · Error Tracking project id
--dsn-env <value> body /^([A-Za-z_][A-Za-z0-9_]{0,127})?$/ · Server DSN variable (default SENTRY_DSN)
--public-dsn-env <value> body /^([A-Za-z_][A-Za-z0-9_]{0,127})?$/ · Browser DSN variable (default NEXT_PUBLIC_SENTRY_DSN; VITE_SENTRY_DSN or PUBLIC_SENTRY_DSN for Vite and SvelteKit)
--environment-env <value> body /^([A-Za-z_][A-Za-z0-9_]{0,127})?$/ · Environment variable (default SENTRY_ENVIRONMENT)
--release-env <value> body /^([A-Za-z_][A-Za-z0-9_]{0,127})?$/ · Release variable (default SENTRY_RELEASE)
--environment <value> body 1-64 chars, /^[^\s/]+$/ · nullable · SENTRY_ENVIRONMENT; omitted: the app’s secrets environment, else production
--redeploy body Rebuild and redeploy now, so the build bakes the DSN into the browser bundle and uploads source maps
  • May check errors:UpdateProject or deploy:DeployApp instead, decided by server-side state the caller cannot see. A caller needs all of them to be sure of not getting a 403.
  • At every build and rollout the app gets SENTRY_DSN and NEXT_PUBLIC_SENTRY_DSN (the project’s managed key, filed in Secrets as a managed entry), SENTRY_ENVIRONMENT and SENTRY_RELEASE (the commit). A build also gets SENTRY_ORG, SENTRY_PROJECT, SENTRY_URL and, as a BuildKit secret, a SENTRY_AUTH_TOKEN minted for that build alone (source-map upload to this project only), revoked when the build ends. A variable the app defines itself wins. With redeploy: true the live commit is rebuilt, so the DSN reaches the browser bundle and source maps are uploaded.

dcloud deploy errors disconnect

Disconnect (the project, its key and its managed secret are unchanged)

DELETE /deploy/api/apps/{id}/errors — IAM deploy:ManageErrorsBinding — write

dcloud deploy errors disconnect <id>

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<id> --id string uuid

dcloud deploy jobs

Scheduled jobs (cron) of an app: a command run on a schedule in the app’s image

Operation Method Path IAM action Effect
list GET /deploy/api/apps/{id}/jobs deploy:DescribeJobs read
create POST /deploy/api/apps/{id}/jobs deploy:CreateJob write
update PATCH /deploy/api/apps/{id}/jobs/{jobId} deploy:UpdateJob write
delete DELETE /deploy/api/apps/{id}/jobs/{jobId} deploy:DeleteJob write
run POST /deploy/api/apps/{id}/jobs/{jobId}/runs deploy:RunJob write
runs GET /deploy/api/apps/{id}/jobs/{jobId}/runs deploy:DescribeJobs read

dcloud deploy jobs list

List an app’s jobs with their schedule in words, next run and last result

GET /deploy/api/apps/{id}/jobs — IAM deploy:DescribeJobs — read

dcloud deploy jobs list <id>

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<id> --id string uuid

dcloud deploy jobs create

Add a scheduled job to an app

POST /deploy/api/apps/{id}/jobs — IAM deploy:CreateJob — write

dcloud deploy jobs create <id> --name <value> --schedule <value> --command <value> [flags]

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<id> --id string uuid
Flag In Required Notes
--name <value> body yes 1-63 chars, /^a-z0-9?$/ · Name of the job, unique within the app
--schedule <value> body yes 1-200 chars · When it runs: a five-field cron expression in UTC, or @hourly, @daily, @weekly, @monthly, @yearly
--command <value> body yes 1-4096 chars · Command run with /bin/sh -c in the app’s image, with the app’s environment
--service <value> body 1-63 chars · nullable · Compose apps only: the service whose image and environment the job runs with; omitted or null, the published service
--enabled body Whether the job runs on its schedule; a new job is enabled unless this is false
--timeout-sec <number> body integer, 10-86400 · Seconds a run may take before it is stopped; a new job gets 3600
--concurrency <skip|allow> body What happens when a run is due while the previous one is still going: skip (a new job’s default) records it as skipped, allow starts it anyway
--timezone <json> body JSON · Time zone of the schedule; only UTC
  • schedule is a five-field cron expression in UTC (minute hour day-of-month month day-of-week, or @hourly/@daily/@weekly/@monthly/@yearly). The command runs with /bin/sh -c in the app’s image with its full environment, on one of the app’s machines, which keeps the schedule itself. concurrency "skip" (default) records a due run as skipped while the previous one is still going.

dcloud deploy jobs update

Change a job, or enable/disable it

PATCH /deploy/api/apps/{id}/jobs/{jobId} — IAM deploy:UpdateJob — write

dcloud deploy jobs update <id> <jobId> [flags]

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<id> --id string uuid
<jobId> --job-id string uuid
Flag In Required Notes
--name <value> body 1-63 chars, /^a-z0-9?$/ · Name of the job, unique within the app
--schedule <value> body 1-200 chars · When it runs: a five-field cron expression in UTC, or @hourly, @daily, @weekly, @monthly, @yearly
--command <value> body 1-4096 chars · Command run with /bin/sh -c in the app’s image, with the app’s environment
--service <value> body 1-63 chars · nullable · Compose apps only: the service whose image and environment the job runs with; omitted or null, the published service
--enabled body Whether the job runs on its schedule; a new job is enabled unless this is false
--timeout-sec <number> body integer, 10-86400 · Seconds a run may take before it is stopped; a new job gets 3600
--concurrency <skip|allow> body What happens when a run is due while the previous one is still going: skip (a new job’s default) records it as skipped, allow starts it anyway
--timezone <json> body JSON · Time zone of the schedule; only UTC
  • schedule is a five-field cron expression in UTC (minute hour day-of-month month day-of-week, or @hourly/@daily/@weekly/@monthly/@yearly). The command runs with /bin/sh -c in the app’s image with its full environment, on one of the app’s machines, which keeps the schedule itself. Fields left out keep their value.

dcloud deploy jobs delete

Remove a job and its run history

DELETE /deploy/api/apps/{id}/jobs/{jobId} — IAM deploy:DeleteJob — write

dcloud deploy jobs delete <id> <jobId>

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<id> --id string uuid
<jobId> --job-id string uuid

dcloud deploy jobs run

Run a job now, outside its schedule

POST /deploy/api/apps/{id}/jobs/{jobId}/runs — IAM deploy:RunJob — write

dcloud deploy jobs run <id> <jobId>

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<id> --id string uuid
<jobId> --job-id string uuid
  • Returns the run with status "requested"; the machine starts it within seconds. Read it back with runs.

dcloud deploy jobs runs

Read a job’s run history, newest first, with each run’s exit code and output

GET /deploy/api/apps/{id}/jobs/{jobId}/runs — IAM deploy:DescribeJobs — read

dcloud deploy jobs runs <id> <jobId> [flags]

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<id> --id string uuid
<jobId> --job-id string uuid
Flag In Required Notes
--limit <number> query integer, 1-200 · Most runs to return, newest first; default 50

dcloud deploy registry-credentials

Pull credentials for external registries (ghcr.io, Docker Hub, any v2 registry)

Operation Method Path IAM action Effect
list GET /deploy/api/apps/{id}/registry-credentials deploy:DescribeApp read
replace PUT /deploy/api/apps/{id}/registry-credentials deploy:UpdateApp write

dcloud deploy registry-credentials list

List the registry credentials of an app (never the password)

GET /deploy/api/apps/{id}/registry-credentials — IAM deploy:DescribeApp — read

dcloud deploy registry-credentials list <id>

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<id> --id string uuid

dcloud deploy registry-credentials replace

Replace the registry credentials of an app

PUT /deploy/api/apps/{id}/registry-credentials — IAM deploy:UpdateApp — write

dcloud deploy registry-credentials replace <id> --credentials <value>

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<id> --id string uuid
Flag In Required Notes
--credentials <value> body yes repeatable · The complete set, one per registry: registryHost, username and passwordSecretId (the Secret holding the password or token). Registries left out lose their credential; an empty list removes all
  • May check secrets:GetSecretValue instead, decided by server-side state the caller cannot see. A caller needs all of them to be sure of not getting a 403.
  • The password is the id of a Deutsche Cloud Secret. Binding needs secrets:GetSecretValue on it and grants it to the deploy consumer.

dcloud deploy domains

Custom domains of an app

Operation Method Path IAM action Effect
list GET /deploy/api/apps/{id}/domains deploy:DescribeApp read
add POST /deploy/api/apps/{id}/domains deploy:ManageDomain write
verify POST /deploy/api/apps/{id}/domains/{domainId}/verify deploy:ManageDomain write
remove DELETE /deploy/api/apps/{id}/domains/{domainId} deploy:ManageDomain write

dcloud deploy domains list

List the custom domains of an app

GET /deploy/api/apps/{id}/domains — IAM deploy:DescribeApp — read

dcloud deploy domains list <id>

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<id> --id string uuid

dcloud deploy domains add

Attach a custom domain to an app

POST /deploy/api/apps/{id}/domains — IAM deploy:ManageDomain — write

dcloud deploy domains add <id> --domain <value> [flags]

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<id> --id string uuid
Flag In Required Notes
--domain <value> body yes 1-253 chars, /^(*.)?[a-z0-9.-]+$/i · Hostname to serve the app on, or *.host for every subdomain of host
--is-primary body Mark this as the app’s primary domain; default false

dcloud deploy domains verify

Check that a custom domain points at the app, and record it

POST /deploy/api/apps/{id}/domains/{domainId}/verify — IAM deploy:ManageDomain — write

dcloud deploy domains verify <id> <domainId>

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<id> --id string uuid
<domainId> --domain-id string uuid

dcloud deploy domains remove

Detach a custom domain

DELETE /deploy/api/apps/{id}/domains/{domainId} — IAM deploy:ManageDomain — write

dcloud deploy domains remove <id> <domainId>

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<id> --id string uuid
<domainId> --domain-id string uuid

Not in the CLI: deploy routes the surface does not describe

These routes exist and are reachable over HTTP. They are deliberately absent from the description, so there is no command for them. The reason is recorded next to the service so a gap has to be stated out loud and stops being stateable the moment the route goes.

Route Why it has no command
GET /deploy/api/agent/binary Agent download, not a caller
GET /deploy/api/agent/desired-state App service account only (deploy:AgentSync)
POST /deploy/api/agent/status App service account only (deploy:AgentSync)
POST /deploy/api/agent/events App service account only (deploy:AgentSync)
POST /deploy/api/agent/logs App service account only (deploy:AgentSync)
POST /deploy/api/agent/metrics App service account only (deploy:AgentSync); the agent’s StatsD flush, stored as custom metrics
GET /deploy/api/agent/jobs App service account only (deploy:AgentSync); carries decrypted environment
POST /deploy/api/agent/job-runs App service account only (deploy:AgentSync)

dcloud monitoring

Monitoring. Base path /monitoring/api.

dcloud monitoring metrics

CPU, disk and network of every machine, and database volume usage

Operation Method Path IAM action Effect
resources GET /monitoring/api/resources monitoring:ListMetrics read
list GET /monitoring/api/metrics monitoring:ListMetrics read
get-data GET /monitoring/api/metrics/data monitoring:GetMetricData read

dcloud monitoring metrics resources

List the resources that record metrics, and the apps that ship logs

GET /monitoring/api/resources — IAM monitoring:ListMetrics — read

dcloud monitoring metrics resources

dcloud monitoring metrics list

List the metrics of one resource and when each was last recorded

GET /monitoring/api/metrics — IAM monitoring:ListMetrics — read

dcloud monitoring metrics list --resource-type <instance|db_node|vpn_connection|eks_cluster|app> --resource-id <value>
Flag In Required Notes
--resource-type <instance|db_node|vpn_connection|eks_cluster|app> query yes
--resource-id <value> query yes

dcloud monitoring metrics get-data

Datapoints of up to eight metrics of one resource, one per period

GET /monitoring/api/metrics/data — IAM monitoring:GetMetricData — read

dcloud monitoring metrics get-data --resource-type <instance|db_node|vpn_connection|eks_cluster|app> --resource-id <value> --metrics <value> --start <value> [flags]
Flag In Required Notes
--resource-type <instance|db_node|vpn_connection|eks_cluster|app> query yes
--resource-id <value> query yes
--metrics <value> query yes
--start <value> query yes
--end <value> query
--period <number> query integer
--statistic <avg|max|min> query
  • metrics is comma-separated. start and end are ISO 8601; end defaults to now. period is seconds, a whole number of minutes; at most 1440 points per series. Metrics are kept 14 days.

dcloud monitoring custom-metrics

Series an application publishes itself, charted and alarmed on like built-ins

Operation Method Path IAM action Effect
put POST /monitoring/api/custom-metrics monitoring:PutMetricData write
list GET /monitoring/api/custom-metrics monitoring:ListMetrics read
get-data GET /monitoring/api/custom-metrics/data monitoring:GetMetricData read

dcloud monitoring custom-metrics put

Publish datapoints to custom metrics (CloudWatch PutMetricData)

POST /monitoring/api/custom-metrics — IAM monitoring:PutMetricData — write

dcloud monitoring custom-metrics put --namespace <value> --metric-data <value>
Flag In Required Notes
--namespace <value> body yes Letters, digits and . _ / # : -, up to 255; EWS/ and AWS/ are reserved
--metric-data <value> body yes repeatable · 1–1000 datums
  • Datums are checked one by one: the valid ones are stored and each refused one is listed with its index and reason (400 only when none was stored). Values are aggregated per minute. At most 1000 active series per organization and 20000 datums a minute. Kept 15 days per minute, 15 months per hour. OTLP/HTTP (JSON) is accepted at /monitoring/api/otlp/v1/metrics.

dcloud monitoring custom-metrics list

List custom series: namespace, metric name, dimensions, last datapoint

GET /monitoring/api/custom-metrics — IAM monitoring:ListMetrics — read

dcloud monitoring custom-metrics list [flags]
Flag In Required Notes
--namespace <value> query Only this namespace
--name <value> query Case-insensitive substring of the metric name
--limit <number> query integer · 1–1000, default 200

dcloud monitoring custom-metrics get-data

Datapoints of one custom series, one per period

GET /monitoring/api/custom-metrics/data — IAM monitoring:GetMetricData — read

dcloud monitoring custom-metrics get-data --series-id <value> --start <value> [flags]
Flag In Required Notes
--series-id <value> query yes uuid · From custom-metrics list
--start <value> query yes ISO 8601
--end <value> query ISO 8601; now when left out
--period <number> query integer · Seconds, a whole number of minutes, default 60; at most 1440 points
--statistic <avg|max|min|sum|count> query avg (default), sum, min, max or count
  • Ranges older than 15 days, or periods of whole hours, are read from hourly rows and the period is rounded up to an hour.

dcloud monitoring alarms

Thresholds on a metric that notify by email or webhook

Operation Method Path IAM action Effect
list GET /monitoring/api/alarms monitoring:DescribeAlarms read
get GET /monitoring/api/alarms/{id} monitoring:DescribeAlarms read
create POST /monitoring/api/alarms monitoring:PutMetricAlarm write
update PUT /monitoring/api/alarms/{id} monitoring:PutMetricAlarm write
delete DELETE /monitoring/api/alarms/{id} monitoring:DeleteAlarms write
history GET /monitoring/api/alarms/{id}/history monitoring:DescribeAlarmHistory read

dcloud monitoring alarms list

List alarms, those in ALARM first

GET /monitoring/api/alarms — IAM monitoring:DescribeAlarms — read

dcloud monitoring alarms list [flags]
Flag In Required Notes
--resource-type <instance|db_node|vpn_connection|eks_cluster|app> query
--resource-id <value> query

dcloud monitoring alarms get

Describe one alarm and its current state

GET /monitoring/api/alarms/{id} — IAM monitoring:DescribeAlarms — read

dcloud monitoring alarms get <id>

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<id> --id string uuid

dcloud monitoring alarms create

Create an alarm on one metric of one resource

POST /monitoring/api/alarms — IAM monitoring:PutMetricAlarm — write

dcloud monitoring alarms create --name <value> --resource-type <instance|db_node|vpn_connection|eks_cluster|app|custom> --resource-id <value> --metric <value> --comparator <>|>=|<|<=> --threshold <number> --period-seconds <number> [flags]
Flag In Required Notes
--name <value> body yes
--resource-type <instance|db_node|vpn_connection|eks_cluster|app|custom> body yes custom: a series the organization publishes itself
--resource-id <value> body yes The instance, database node or site-to-site connection id; for custom, the series’ namespace
--metric <value> body yes One of cpu_percent, disk_read_iops, disk_write_iops, disk_read_bps, disk_write_bps, network_in_bps, network_out_bps, disk_used_percent, connections, replication_lag_bytes, query_slowdown, docdb_up, tunnel_up, tunnel_in_bps, tunnel_out_bps, bgp_prefixes, api_available, control_plane_ready, nodes_ready, nodes_not_ready, cdn_requests, cdn_cache_hits, cdn_cache_misses, cdn_hit_ratio, cdn_bytes_out, cdn_origin_bytes, waf_blocked, waf_counted, waf_challenged, waf_rate_limited, deploy_duration_seconds, deploys_succeeded, deploys_failed; for custom, the series’ metric name
--dimensions <key=value> body repeatable · key=value · nullable · custom only: the series’ dimensions
--statistic <avg|max|min|sum|count> body count is the number of samples (CloudWatch SampleCount)
--comparator <>|>=|<|<=> body yes
--threshold <number> body yes
--period-seconds <number> body yes integer
--evaluation-periods <number> body integer
--notify-emails <value> body repeatable
--webhook-url <value> body nullable
--enabled body
  • An alarm goes to ALARM when every one of its evaluation periods breaches, to OK when any does not, and to INSUFFICIENT_DATA when none has data. webhookUrl must be https on a public address. Notifications go out on entering and leaving ALARM.

dcloud monitoring alarms update

Change an alarm; changing what it measures resets it to INSUFFICIENT_DATA

PUT /monitoring/api/alarms/{id} — IAM monitoring:PutMetricAlarm — write

dcloud monitoring alarms update <id> [flags]

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<id> --id string uuid
Flag In Required Notes
--name <value> body
--resource-type <instance|db_node|vpn_connection|eks_cluster|app|custom> body custom: a series the organization publishes itself
--resource-id <value> body The instance, database node or site-to-site connection id; for custom, the series’ namespace
--metric <value> body One of cpu_percent, disk_read_iops, disk_write_iops, disk_read_bps, disk_write_bps, network_in_bps, network_out_bps, disk_used_percent, connections, replication_lag_bytes, query_slowdown, docdb_up, tunnel_up, tunnel_in_bps, tunnel_out_bps, bgp_prefixes, api_available, control_plane_ready, nodes_ready, nodes_not_ready, cdn_requests, cdn_cache_hits, cdn_cache_misses, cdn_hit_ratio, cdn_bytes_out, cdn_origin_bytes, waf_blocked, waf_counted, waf_challenged, waf_rate_limited, deploy_duration_seconds, deploys_succeeded, deploys_failed; for custom, the series’ metric name
--dimensions <key=value> body repeatable · key=value · nullable · Up to 10 name → value pairs; together with namespace and name they make the series
--statistic <avg|max|min|sum|count> body count is the number of samples (CloudWatch SampleCount)
--comparator <>|>=|<|<=> body
--threshold <number> body
--period-seconds <number> body integer
--evaluation-periods <number> body integer
--notify-emails <value> body repeatable
--webhook-url <value> body nullable
--enabled body

dcloud monitoring alarms delete

Delete an alarm and its history

DELETE /monitoring/api/alarms/{id} — IAM monitoring:DeleteAlarms — write

dcloud monitoring alarms delete <id>

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<id> --id string uuid

dcloud monitoring alarms history

The state changes of an alarm, newest first, and who was notified

GET /monitoring/api/alarms/{id}/history — IAM monitoring:DescribeAlarmHistory — read

dcloud monitoring alarms history <id> [flags]

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<id> --id string uuid
Flag In Required Notes
--limit <number> query integer

dcloud monitoring checks

Uptime checks: a URL requested on a schedule, with response times and outages

Operation Method Path IAM action Effect
list GET /monitoring/api/checks monitoring:DescribeChecks read
get GET /monitoring/api/checks/{id} monitoring:DescribeChecks read
create POST /monitoring/api/checks monitoring:CreateCheck write
update PATCH /monitoring/api/checks/{id} monitoring:UpdateCheck write
delete DELETE /monitoring/api/checks/{id} monitoring:DeleteChecks write
pause POST /monitoring/api/checks/{id}/pause monitoring:PauseChecks write
resume POST /monitoring/api/checks/{id}/resume monitoring:ResumeChecks write
results GET /monitoring/api/checks/{id}/results monitoring:GetCheckResults read
outages GET /monitoring/api/checks/{id}/outages monitoring:GetCheckResults read
locations GET /monitoring/api/locations monitoring:DescribeChecks read

dcloud monitoring checks list

List uptime checks, those that are down first

GET /monitoring/api/checks — IAM monitoring:DescribeChecks — read

dcloud monitoring checks list

dcloud monitoring checks get

Describe one uptime check: its settings, state and why, and its last result

GET /monitoring/api/checks/{id} — IAM monitoring:DescribeChecks — read

dcloud monitoring checks get <id>

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<id> --id string uuid

dcloud monitoring checks create

Create an uptime check

POST /monitoring/api/checks — IAM monitoring:CreateCheck — write

dcloud monitoring checks create --name <value> --url <value> [flags]
Flag In Required Notes
--name <value> body yes Unique in the organization, up to 128 characters
--type <http|keyword> body http: the status decides; keyword: the body must (not) contain a text too
--url <value> body yes http:// or https:// on a public address; any port except 25, 465 and 587
--method <GET|HEAD> body GET by default; keyword checks use GET
--expected-status-min <number> body integer · Lowest status that counts as up (default 200)
--expected-status-max <number> body integer · Highest status that counts as up (default 399)
--keyword <value> body nullable · For keyword checks: the text looked for in the first 1 MiB
--keyword-mode <contains|not_contains> body nullable · contains (default) or not_contains
--timeout-ms <number> body integer · 1000–30000, default 10000
--interval-seconds <number> body integer · 60, 120, 300 (default), 600, 900, 1800 or 3600
--follow-redirects body Follow up to 5 redirects, each re-checked (default true)
--verify-tls body Fail on an invalid certificate (default true)
--failure-threshold <number> body integer · Failed runs in a row before DOWN, 1–5 (default 2)
--confirmations <number> body integer · Locations that must fail in one run for it to count as failed, 1–3 (default 2); fewer failing is "regional"
--alert-on-regional body Treat one failing location as failed, as if confirmations were 1 (default false)
--notify-emails <value> body repeatable · Up to 10 addresses mailed on DOWN and on UP again
--webhook-url <value> body nullable · https URL on a public address, POSTed on DOWN and UP
  • The check runs within a minute, then every intervalSeconds. A failed run is retried once after 3 s; failureThreshold failed runs in a row make it DOWN, two successful runs make it UP again, and both are mailed to notifyEmails and POSTed to webhookUrl. Unconfirmed runs are repeated after a minute. At most 50 checks per organization, and at most 6 requests a minute to one host across every check on Deutsche Cloud.

dcloud monitoring checks update

Change an uptime check; changing what it requests starts it over as pending

PATCH /monitoring/api/checks/{id} — IAM monitoring:UpdateCheck — write

dcloud monitoring checks update <id> [flags]

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<id> --id string uuid
Flag In Required Notes
--name <value> body Unique in the organization, up to 128 characters
--type <http|keyword> body http: the status decides; keyword: the body must (not) contain a text too
--url <value> body http:// or https:// on a public address; any port except 25, 465 and 587
--method <GET|HEAD> body
--expected-status-min <number> body integer
--expected-status-max <number> body integer
--keyword <value> body nullable
--keyword-mode <contains|not_contains> body nullable
--timeout-ms <number> body integer
--interval-seconds <number> body integer
--follow-redirects body
--verify-tls body
--failure-threshold <number> body integer
--confirmations <number> body integer
--alert-on-regional body
--notify-emails <value> body repeatable
--webhook-url <value> body nullable

dcloud monitoring checks delete

Delete an uptime check with its results and outages

DELETE /monitoring/api/checks/{id} — IAM monitoring:DeleteChecks — write

dcloud monitoring checks delete <id>

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<id> --id string uuid

dcloud monitoring checks pause

Stop running a check; an open outage is closed without a notification

POST /monitoring/api/checks/{id}/pause — IAM monitoring:PauseChecks — write

dcloud monitoring checks pause <id>

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<id> --id string uuid

dcloud monitoring checks resume

Run a paused check again, from pending

POST /monitoring/api/checks/{id}/resume — IAM monitoring:ResumeChecks — write

dcloud monitoring checks resume <id>

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<id> --id string uuid

dcloud monitoring checks results

Uptime %, response times per period, and the latest raw results of a check

GET /monitoring/api/checks/{id}/results — IAM monitoring:GetCheckResults — read

dcloud monitoring checks results <id> [flags]

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<id> --id string uuid
Flag In Required Notes
--start <value> query ISO 8601; defaults to a day before end
--end <value> query ISO 8601; defaults to now
--limit <number> query integer · Raw results to return, newest first, 0–500 (default 50)
  • At most 30 days at once; raw results are kept 30 days. uptimePercent is the share of the window not covered by an outage. series has about 300 points whatever the range.

dcloud monitoring checks outages

The outage log of a check, newest first, with who was notified

GET /monitoring/api/checks/{id}/outages — IAM monitoring:GetCheckResults — read

dcloud monitoring checks outages <id> [flags]

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<id> --id string uuid
Flag In Required Notes
--limit <number> query integer · 1–500, default 50

dcloud monitoring checks locations

Where checks run from: the control plane and each probe location, its health and the addresses to allowlist

GET /monitoring/api/locations — IAM monitoring:DescribeChecks — read

dcloud monitoring checks locations
  • Every run asks every healthy location at once; a run fails only when confirmations locations fail. The control plane does not check Deutsche Cloud’s own addresses.

dcloud monitoring logs

What a deployed app printed, shipped by the agent on its machine

Operation Method Path IAM action Effect
filter GET /monitoring/api/logs monitoring:FilterLogEvents read

dcloud monitoring logs filter

Search an app’s log lines, newest first

GET /monitoring/api/logs — IAM monitoring:FilterLogEvents — read

dcloud monitoring logs filter --resource-id <value> [flags]
Flag In Required Notes
--resource-type <app|schedule|function> query
--resource-id <value> query yes uuid
--start <value> query
--end <value> query
--contains <value> query
--stream <value> query
--limit <number> query integer
  • start defaults to a day before end, end to now. contains is a case-insensitive substring. limit is at most 1000. Logs are kept 7 days.

dcloud monitoring status-pages

Public status pages at {slug}.status.{root}, built from uptime checks

Operation Method Path IAM action Effect
list GET /monitoring/api/status-pages monitoring:DescribeStatusPages read
create POST /monitoring/api/status-pages monitoring:CreateStatusPage write
get GET /monitoring/api/status-pages/{id} monitoring:DescribeStatusPages read
update PATCH /monitoring/api/status-pages/{id} monitoring:UpdateStatusPage write
delete DELETE /monitoring/api/status-pages/{id} monitoring:DeleteStatusPage write
put-components PUT /monitoring/api/status-pages/{id}/components monitoring:UpdateStatusPage write

dcloud monitoring status-pages list

List the organization’s status pages and their public URLs

GET /monitoring/api/status-pages — IAM monitoring:DescribeStatusPages — read

dcloud monitoring status-pages list

dcloud monitoring status-pages create

Publish a status page at {slug}.status.{root}

POST /monitoring/api/status-pages — IAM monitoring:CreateStatusPage — write

dcloud monitoring status-pages create --slug <value> --title <value> [flags]
Flag In Required Notes
--slug <value> body yes The host label: {slug}.status.{root}. 3–63 lower-case letters, digits, dashes
--title <value> body yes Shown at the top of the page, up to 120 characters
--description <value> body nullable · Plain text under the title
  • The slug is the host label, unique across Deutsche Cloud; a few words (ews, www, status, api, …) are reserved. At most 5 pages per organization. The page is public at once; add components with put-components.

dcloud monitoring status-pages get

Describe a status page: its components, their current state, subscriber count

GET /monitoring/api/status-pages/{id} — IAM monitoring:DescribeStatusPages — read

dcloud monitoring status-pages get <id>

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<id> --id string uuid

dcloud monitoring status-pages update

Change a status page’s title, description or address

PATCH /monitoring/api/status-pages/{id} — IAM monitoring:UpdateStatusPage — write

dcloud monitoring status-pages update <id> [flags]

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<id> --id string uuid
Flag In Required Notes
--slug <value> body The host label: {slug}.status.{root}. 3–63 lower-case letters, digits, dashes
--title <value> body Shown at the top of the page, up to 120 characters
--description <value> body nullable

dcloud monitoring status-pages delete

Delete a status page, its incidents and its subscribers

DELETE /monitoring/api/status-pages/{id} — IAM monitoring:DeleteStatusPage — write

dcloud monitoring status-pages delete <id>

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<id> --id string uuid

dcloud monitoring status-pages put-components

Replace the page’s components with this ordered list

PUT /monitoring/api/status-pages/{id}/components — IAM monitoring:UpdateStatusPage — write

dcloud monitoring status-pages put-components <id> --components <value>

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<id> --id string uuid
Flag In Required Notes
--components <value> body yes repeatable · The whole ordered list, at most 50
  • Each component follows an uptime check (checkId: up → operational, regional → degraded, down → major outage) or has a state set by hand (manualState). Pass a component’s id to keep it; components left out are removed. At most 50.

dcloud monitoring incidents

Incidents posted on a status page, with their timeline of updates

Operation Method Path IAM action Effect
list GET /monitoring/api/status-pages/{id}/incidents monitoring:DescribeStatusPages read
create POST /monitoring/api/status-pages/{id}/incidents monitoring:CreateIncident write
update POST /monitoring/api/status-pages/{id}/incidents/{incidentId}/updates monitoring:UpdateIncident write
delete DELETE /monitoring/api/status-pages/{id}/incidents/{incidentId} monitoring:DeleteIncident write

dcloud monitoring incidents list

Open incidents, and those resolved in the last days days, newest first

GET /monitoring/api/status-pages/{id}/incidents — IAM monitoring:DescribeStatusPages — read

dcloud monitoring incidents list <id> [flags]

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<id> --id string uuid
Flag In Required Notes
--days <number> query integer · 1–365, default 30

dcloud monitoring incidents create

Post an incident; the page’s confirmed subscribers are emailed and webhooks called

POST /monitoring/api/status-pages/{id}/incidents — IAM monitoring:CreateIncident — write

dcloud monitoring incidents create <id> --title <value> --impact <none|minor|major|critical> --body <value> [flags]

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<id> --id string uuid
Flag In Required Notes
--title <value> body yes
--impact <none|minor|major|critical> body yes none, minor (degraded), major (partial outage), critical (major outage)
--status <investigating|identified|monitoring|resolved> body investigating by default
--body <value> body yes The first update, plain text
--component-ids <value> body repeatable · uuid · Components it affects
  • While open, an incident makes its components at least as bad as its impact says (minor → degraded, major → partial outage, critical → major outage). Bodies are plain text.

dcloud monitoring incidents update

Post an update to an incident; status resolved closes it. Subscribers are told

POST /monitoring/api/status-pages/{id}/incidents/{incidentId}/updates — IAM monitoring:UpdateIncident — write

dcloud monitoring incidents update <id> <incidentId> --status <investigating|identified|monitoring|resolved> --body <value> [flags]

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<id> --id string uuid
<incidentId> --incident-id string uuid
Flag In Required Notes
--status <investigating|identified|monitoring|resolved> body yes
--body <value> body yes Plain text
--impact <none|minor|major|critical> body none, minor (degraded), major (partial outage), critical (major outage)

dcloud monitoring incidents delete

Remove an incident and its updates from the page (nobody is told)

DELETE /monitoring/api/status-pages/{id}/incidents/{incidentId} — IAM monitoring:DeleteIncident — write

dcloud monitoring incidents delete <id> <incidentId>

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<id> --id string uuid
<incidentId> --incident-id string uuid

dcloud monitoring subscribers

Who a status page emails or calls about incidents and components going down

Operation Method Path IAM action Effect
list GET /monitoring/api/status-pages/{id}/subscribers monitoring:DescribeStatusPages read
add POST /monitoring/api/status-pages/{id}/subscribers monitoring:UpdateStatusPage write
remove DELETE /monitoring/api/status-pages/{id}/subscribers/{subscriberId} monitoring:UpdateStatusPage write

dcloud monitoring subscribers list

List a page’s subscribers and whether each has confirmed

GET /monitoring/api/status-pages/{id}/subscribers — IAM monitoring:DescribeStatusPages — read

dcloud monitoring subscribers list <id>

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<id> --id string uuid

dcloud monitoring subscribers add

Add a webhook, or invite an email address (it confirms by link first)

POST /monitoring/api/status-pages/{id}/subscribers — IAM monitoring:UpdateStatusPage — write

dcloud monitoring subscribers add <id> --kind <email|webhook> --target <value>

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<id> --id string uuid
Flag In Required Notes
--kind <email|webhook> body yes
--target <value> body yes An email address, or an https URL on a public address
  • A webhook gets a JSON POST (type ews.monitoring.status-page.incident.created|updated|resolved, component.down|up). An email address gets nothing until it opens the confirmation link. At most 1000 per page.

dcloud monitoring subscribers remove

Remove a subscriber

DELETE /monitoring/api/status-pages/{id}/subscribers/{subscriberId} — IAM monitoring:UpdateStatusPage — write

dcloud monitoring subscribers remove <id> <subscriberId>

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<id> --id string uuid
<subscriberId> --subscriber-id string uuid

Not in the CLI: monitoring routes the surface does not describe

These routes exist and are reachable over HTTP. They are deliberately absent from the description, so there is no command for them. The reason is recorded next to the service so a gap has to be stated out loud and stops being stateable the moment the route goes.

Route Why it has no command
POST /monitoring/api/otlp/v1/metrics The OpenTelemetry OTLP/HTTP wire format (JSON encoding), spoken by an exporter rather than called as an operation; answers ExportMetricsServiceResponse, not the JSON envelope. Same action and limits as custom-metrics put

dcloud vpn

VPN. Base path /vpn/api.

dcloud vpn endpoints

WireGuard gateways, one per VPC — opt-in, and a billed machine

Operation Method Path IAM action Effect
list GET /vpn/api/endpoints vpn:DescribeClientVpnEndpoints read
node-types GET /vpn/api/node-types vpn:DescribeClientVpnEndpoints read
create POST /vpn/api/endpoints vpn:CreateClientVpnEndpoint write
get GET /vpn/api/endpoints/{id} vpn:DescribeClientVpnEndpoints read
events GET /vpn/api/endpoints/{id}/events vpn:DescribeClientVpnEndpoints read
targets GET /vpn/api/endpoints/{id}/targets vpn:DescribeClientVpnEndpoints read
delete DELETE /vpn/api/endpoints/{id} vpn:DeleteClientVpnEndpoint write

dcloud vpn endpoints list

List VPN gateways

GET /vpn/api/endpoints — IAM vpn:DescribeClientVpnEndpoints — read

dcloud vpn endpoints list

dcloud vpn endpoints node-types

List the machine sizes a gateway can run on, with their price

GET /vpn/api/node-types — IAM vpn:DescribeClientVpnEndpoints — read

dcloud vpn endpoints node-types
  • The entry with isDefault is what a gateway runs on when no nodeType is given.

dcloud vpn endpoints create

Create a VPN gateway in a VPC (a billed machine)

POST /vpn/api/endpoints — IAM vpn:CreateClientVpnEndpoint — write

dcloud vpn endpoints create [flags]
Flag In Required Notes
--region-id <value> body 1-32 chars · Region to create in (default: the X-EWS-Region header, else de1). fi1 (Helsinki, Finland) needs the organization setting "allow EU outside Germany".
--vpc-id <value> body
--node-type <value> body 1-32 chars · An instance type from node-types, e.g. performance-2. The provider’s own type names are still accepted, deprecated.
--highly-available body server default false · Two gateways on different hosts behind one floating IP, with automatic failover
--tags <key=value> body repeatable · key=value · Tags for the new resource, e.g. {"env": "prod", "project": "shop"}. Keys your organization marks required must be present, or the create is refused with the missing keys (GET /tags/api/keys lists them).
  • Omit vpcId for the default VPC, where apps and databases run. One gateway per VPC. The response carries the price; the gateway becomes available once its machine reports its WireGuard key, usually within two minutes.

dcloud vpn endpoints get

Describe a VPN gateway

GET /vpn/api/endpoints/{id} — IAM vpn:DescribeClientVpnEndpoints — read

dcloud vpn endpoints get <id>

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<id> --id string /^ewvpn-[0-9a-f]{12}$/

dcloud vpn endpoints events

Read a gateway’s activity: provisioning, peer changes, connections

GET /vpn/api/endpoints/{id}/events — IAM vpn:DescribeClientVpnEndpoints — read

dcloud vpn endpoints events <id> [flags]

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<id> --id string /^ewvpn-[0-9a-f]{12}$/
Flag In Required Notes
--since <value> query
--limit <number> query integer, 1-500

dcloud vpn endpoints targets

List what a peer on this gateway could be granted, with addresses

GET /vpn/api/endpoints/{id}/targets — IAM vpn:DescribeClientVpnEndpoints — read

dcloud vpn endpoints targets <id>

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<id> --id string /^ewvpn-[0-9a-f]{12}$/
  • The VPC itself and every database, cache, app and instance in it that has a private address. A database with a private name lists it as hostname — connect to that name.

dcloud vpn endpoints delete

Delete a VPN gateway; every peer on it stops working

DELETE /vpn/api/endpoints/{id} — IAM vpn:DeleteClientVpnEndpoint — write

dcloud vpn endpoints delete <id>

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<id> --id string /^ewvpn-[0-9a-f]{12}$/

dcloud vpn apps

VPN access from an app’s point of view: its VPC, gateway and what it uses

Operation Method Path IAM action Effect
access GET /vpn/api/apps/{appId}/access vpn:DescribeClientVpnEndpoints read

dcloud vpn apps access

Show the gateway for an app’s VPC and the app’s databases, caches and machines as targets

GET /vpn/api/apps/{appId}/access — IAM vpn:DescribeClientVpnEndpoints — read

dcloud vpn apps access <appId>

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<appId> --app-id string
  • Needs deploy:DescribeApp on the app too. Bound databases and caches come back preselected, the app’s own machines offered; unreachable lists what the app uses that a gateway in its VPC cannot reach. With no gateway yet, gateway says what creating one costs — create it with dcloud vpn endpoints create --vpc-id <vpc.id>. dcloud vpn peers connect --app <appId> does the rest in one step.

dcloud vpn peers

People or machines allowed through a gateway, each to specific resources

Operation Method Path IAM action Effect
list GET /vpn/api/endpoints/{id}/peers vpn:DescribeClientVpnConnections read
create POST /vpn/api/endpoints/{id}/peers vpn:CreateClientVpnPeer write
get GET /vpn/api/peers/{id} vpn:DescribeClientVpnConnections read
revoke POST /vpn/api/peers/{id}/revoke vpn:RevokeClientVpnPeer write

dcloud vpn peers list

List a gateway’s peers with their last handshake and traffic

GET /vpn/api/endpoints/{id}/peers — IAM vpn:DescribeClientVpnConnections — read

dcloud vpn peers list <id>

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<id> --id string /^ewvpn-[0-9a-f]{12}$/

dcloud vpn peers create

Create a peer from a public key and the resources it may reach

POST /vpn/api/endpoints/{id}/peers — IAM vpn:CreateClientVpnPeer — write

dcloud vpn peers create <id> --name <value> --public-key <value> --targets <value> [flags]

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<id> --id string /^ewvpn-[0-9a-f]{12}$/
Flag In Required Notes
--name <value> body yes 1-48 chars, /^[a-z0-9][a-z0-9-]*$/
--public-key <value> body yes
--targets <value> body yes repeatable
--expires-in-days <number> body integer, 1-365 · server default 30
  • Generate the key pair locally (wg genkey | tee key | wg pubkey) and send only the public key — or use dcloud vpn peers connect, which does it for you and writes the .conf. Each target is written type:id (vpc, database, cache, app, instance) and is authorized as vpn:CreateClientVpnPeer on THAT resource’s RN as well as on the gateway. Returns the .conf with a placeholder where the private key goes. Expires after 30 days unless expiresInDays says otherwise.

dcloud vpn peers get

Describe a peer, with its .conf (private key left out — Deutsche Cloud never had it)

GET /vpn/api/peers/{id} — IAM vpn:DescribeClientVpnConnections — read

dcloud vpn peers get <id>

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<id> --id string /^ewpeer-[0-9a-f]{12}$/

dcloud vpn peers revoke

Revoke a peer; the gateway drops it on its next sync, within about 20 seconds

POST /vpn/api/peers/{id}/revoke — IAM vpn:RevokeClientVpnPeer — write

dcloud vpn peers revoke <id>

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<id> --id string /^ewpeer-[0-9a-f]{12}$/
  • The peer stays listed as revoked, so who could reach what stays readable.

dcloud vpn gateways

Site-to-site VPN gateways: two machines behind one public IP, one per VPC, IPsec and WireGuard

Operation Method Path IAM action Effect
list GET /vpn/api/gateways vpn:DescribeVpnGateways read
create POST /vpn/api/gateways vpn:CreateVpnGateway write
get GET /vpn/api/gateways/{id} vpn:DescribeVpnGateways read
modify PATCH /vpn/api/gateways/{id} vpn:ModifyVpnGateway write
events GET /vpn/api/gateways/{id}/events vpn:DescribeVpnGateways read
delete DELETE /vpn/api/gateways/{id} vpn:DeleteVpnGateway write

dcloud vpn gateways list

List site-to-site gateways

GET /vpn/api/gateways — IAM vpn:DescribeVpnGateways — read

dcloud vpn gateways list

dcloud vpn gateways create

Create a site-to-site gateway in a VPC (two billed machines)

POST /vpn/api/gateways — IAM vpn:CreateVpnGateway — write

dcloud vpn gateways create --name <value> [flags]
Flag In Required Notes
--region-id <value> body 1-32 chars · Region to create in (default: the X-EWS-Region header, else de1). fi1 (Helsinki, Finland) needs the organization setting "allow EU outside Germany".
--name <value> body yes 1-48 chars, /^[a-z0-9][a-z0-9-]*$/
--vpc-id <value> body
--node-type <value> body 1-32 chars · Each machine’s instance type, e.g. performance-2; omitted: a small default. The provider’s own type names are still accepted, deprecated.
--asn <number> body integer, 1-4294967294 · server default 64600 · Deutsche Cloud’s side of every BGP session
--allow-transit body server default false · Let two connections of this gateway reach each other (hub and spoke)
--tags <key=value> body repeatable · key=value · Tags for the new resource, e.g. {"env": "prod", "project": "shop"}. Keys your organization marks required must be present, or the create is refused with the missing keys (GET /tags/api/keys lists them).
  • Omit vpcId for the default VPC. Always two machines (de1a and de1b when in stock), active and standby behind one public IP; the standby takes over after 30 s of silence. Available in about two minutes; then add connections. The response carries the price of both machines. asn is Deutsche Cloud’s side of every BGP session (default 64600).

dcloud vpn gateways get

Describe a gateway with its connections and the routes the VPC carries

GET /vpn/api/gateways/{id} — IAM vpn:DescribeVpnGateways — read

dcloud vpn gateways get <id>

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<id> --id string /^ewvgw-[0-9a-f]{12}$/
  • machineRouteCommand is the one line a machine that existed before the gateway runs to reach the tunnels; instances launched since carry it.

dcloud vpn gateways modify

Rename a gateway or let its connections reach each other (allowTransit)

PATCH /vpn/api/gateways/{id} — IAM vpn:ModifyVpnGateway — write

dcloud vpn gateways modify <id> [flags]

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<id> --id string /^ewvgw-[0-9a-f]{12}$/
Flag In Required Notes
--name <value> body 1-48 chars, /^[a-z0-9][a-z0-9-]*$/
--allow-transit body

dcloud vpn gateways events

Read a gateway’s activity: provisioning, tunnels up and down, BGP, failovers, routes

GET /vpn/api/gateways/{id}/events — IAM vpn:DescribeVpnGateways — read

dcloud vpn gateways events <id> [flags]

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<id> --id string /^ewvgw-[0-9a-f]{12}$/
Flag In Required Notes
--since <value> query
--limit <number> query integer, 1-500

dcloud vpn gateways delete

Delete a gateway; every tunnel closes and its VPC routes go

DELETE /vpn/api/gateways/{id} — IAM vpn:DeleteVpnGateway — write

dcloud vpn gateways delete <id>

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<id> --id string /^ewvgw-[0-9a-f]{12}$/

dcloud vpn connections

Site-to-site tunnels: IPsec (IKEv2) or WireGuard, static routes or BGP

Operation Method Path IAM action Effect
list GET /vpn/api/gateways/{id}/connections vpn:DescribeVpnConnections read
create POST /vpn/api/gateways/{id}/connections vpn:CreateVpnConnection write
get GET /vpn/api/connections/{id} vpn:DescribeVpnConnections read
modify PATCH /vpn/api/connections/{id} vpn:ModifyVpnConnection write
delete DELETE /vpn/api/connections/{id} vpn:DeleteVpnConnection write
device-config GET /vpn/api/connections/{id}/device-config vpn:GetVpnConnectionDeviceConfiguration read, sensitive

dcloud vpn connections list

List a gateway’s connections with their state, BGP and traffic

GET /vpn/api/gateways/{id}/connections — IAM vpn:DescribeVpnConnections — read

dcloud vpn connections list <id>

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<id> --id string /^ewvgw-[0-9a-f]{12}$/

dcloud vpn connections create

Create a tunnel to an office, another cloud or another Deutsche Cloud VPC

POST /vpn/api/gateways/{id}/connections — IAM vpn:CreateVpnConnection — write

dcloud vpn connections create <id> --name <value> --type <ipsec|wireguard> [flags]

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<id> --id string /^ewvgw-[0-9a-f]{12}$/
Flag In Required Notes
--name <value> body yes 1-48 chars, /^[a-z0-9][a-z0-9-]*$/
--type <ipsec|wireguard> body yes
--routing <static|bgp> body server default "static"
--remote-address <value> body nullable · server default null
--remote-id <value> body /^[A-Za-z0-9][A-Za-z0-9.@_-]{0,127}$/ · nullable · server default null
--static-routes <value> body repeatable · server default [] · Static routing: the remote networks
--remote-asn <number> body integer, 1-4294967294 · nullable · server default null
--inside-cidr <value> body Inside-tunnel /30; allocated when omitted
--inside-local-is-first body server default false · Deutsche Cloud takes the first host of the /30 (the far side of an EWS-to-EWS pair)
--nat body server default false · Source-NAT traffic from the tunnel to the gateway’s VPC address
--traffic-selectors <route|policy> body server default "route" · IPsec: route-based (0.0.0.0/0) or policy-based (VPC ↔ remote networks)
--psk <value> body /^[A-Za-z1-9.][A-Za-z0-9.]{7,63}$/ · IPsec pre-shared key; generated when omitted
--remote-public-key <value> body WireGuard: the remote’s public key
--remote-port <number> body integer, 1-65535 · nullable · server default null
  • IPsec needs remoteAddress; the pre-shared key is generated unless given (read it with device-config). WireGuard needs remotePublicKey; the gateway’s own key is wireguardPublicKey on the gateway. Static routing names the remote networks; BGP names the remote ASN and the remote announces its networks. Download the remote device’s configuration with dcloud vpn connections device-config --id <id> --format unifi|pfsense|opnsense|fortinet|aws-vgw|strongswan|wireguard|ews|generic.

dcloud vpn connections get

Describe a connection: tunnel state, BGP, learned prefixes, traffic, last log lines

GET /vpn/api/connections/{id} — IAM vpn:DescribeVpnConnections — read

dcloud vpn connections get <id>

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<id> --id string /^ewvcn-[0-9a-f]{12}$/

dcloud vpn connections modify

Change a connection; the gateway restarts the tunnel on its next sync

PATCH /vpn/api/connections/{id} — IAM vpn:ModifyVpnConnection — write

dcloud vpn connections modify <id> [flags]

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<id> --id string /^ewvcn-[0-9a-f]{12}$/
Flag In Required Notes
--remote-address <value> body nullable
--remote-id <value> body /^[A-Za-z0-9][A-Za-z0-9.@_-]{0,127}$/ · nullable
--static-routes <value> body repeatable · Static routing: the remote networks
--remote-asn <number> body integer, 1-4294967294 · nullable
--nat body Source-NAT traffic from the tunnel to the gateway’s VPC address
--traffic-selectors <route|policy> body IPsec: route-based (0.0.0.0/0) or policy-based (VPC ↔ remote networks)
--psk <value> body /^[A-Za-z1-9.][A-Za-z0-9.]{7,63}$/ · IPsec pre-shared key; generated when omitted
--remote-public-key <value> body WireGuard: the remote’s public key
--remote-port <number> body integer, 1-65535 · nullable

dcloud vpn connections delete

Delete a connection; the tunnel closes and its VPC routes go

DELETE /vpn/api/connections/{id} — IAM vpn:DeleteVpnConnection — write

dcloud vpn connections delete <id>

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<id> --id string /^ewvcn-[0-9a-f]{12}$/

dcloud vpn connections device-config

The configuration for the remote device (includes the pre-shared key)

GET /vpn/api/connections/{id}/device-config — IAM vpn:GetVpnConnectionDeviceConfiguration — read, sensitive

dcloud vpn connections device-config <id> [flags]

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<id> --id string /^ewvcn-[0-9a-f]{12}$/
Flag In Required Notes
--format <generic|strongswan|wireguard|unifi|pfsense|opnsense|fortinet|aws-vgw|ews> query server default "generic"
  • A sensitive read, audited. Formats: generic (parameter sheet), strongswan, wireguard, unifi, pfsense, opnsense, fortinet (FortiOS CLI), aws-vgw (Terraform for the AWS side), ews (the matching connection for another Deutsche Cloud VPC).

dcloud privacyvpn

Privacy VPN. Base path /privacyvpn/api.

dcloud privacyvpn locations

Exit locations: country, city, stable addresses, live load

Operation Method Path IAM action Effect
list GET /privacyvpn/api/locations privacyvpn:DescribeExitLocations read
get GET /privacyvpn/api/locations/{id} privacyvpn:DescribeExitLocations read
events GET /privacyvpn/api/locations/{id}/events privacyvpn:DescribeExitLocations read
create POST /privacyvpn/api/locations privacyvpn:CreateExitLocation write
update PATCH /privacyvpn/api/locations/{id} privacyvpn:UpdateExitLocation write
add-address POST /privacyvpn/api/locations/{id}/addresses privacyvpn:UpdateExitLocation write
remove-address DELETE /privacyvpn/api/locations/{id}/addresses/{addressId} privacyvpn:UpdateExitLocation write
delete DELETE /privacyvpn/api/locations/{id} privacyvpn:DeleteExitLocation write

dcloud privacyvpn locations list

List exit locations with their endpoints and load

GET /privacyvpn/api/locations — IAM privacyvpn:DescribeExitLocations — read

dcloud privacyvpn locations list

dcloud privacyvpn locations get

Describe an exit location (the platform org also sees its exits and traffic)

GET /privacyvpn/api/locations/{id} — IAM privacyvpn:DescribeExitLocations — read

dcloud privacyvpn locations get <id>

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<id> --id string /^[a-z]{2}-[a-z]{3,8}$/

dcloud privacyvpn locations events

Read the fleet controller’s decisions for a location (platform org)

GET /privacyvpn/api/locations/{id}/events — IAM privacyvpn:DescribeExitLocations — read

dcloud privacyvpn locations events <id>

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<id> --id string /^[a-z]{2}-[a-z]{3,8}$/

dcloud privacyvpn locations create

Create an exit location; returns the user data for its launch template

POST /privacyvpn/api/locations — IAM privacyvpn:CreateExitLocation — write

dcloud privacyvpn locations create --id <value> --country <value> --city <value> --region-id <value> --zone-id <value> --server-type <value> [flags]
Flag In Required Notes
--id <value> body yes /^[a-z]{2}-[a-z]{3,8}$/ · Country code and city code, e.g. de-fsn
--country <value> body yes /^[A-Z]{2}$/ · ISO 3166-1 alpha-2, e.g. DE
--city <value> body yes 1-64 chars
--region-id <value> body yes 1-32 chars
--zone-id <value> body yes /^[a-z]+[0-9]+[a-z]$/
--scope <eu|global> body server default "eu" · eu: in the EU, every key; global: outside, only keys registered for it
--server-type <value> body yes 1-32 chars · Instance type of the exits; the cheapest in stock is enough (1 vCPU)
--min-exits <number> body integer, 0-50 · server default 1
--max-exits <number> body integer, 1-50 · server default 4
--target-peers-per-exit <number> body integer, 1-10000 · server default 300
--max-exit-age-hours <number> body integer, 1-168 · server default 24
--inspect-ssh body server default false · Open SSH on the exits so they can be inspected by hand (shown on the public page)
  • Platform org only. Makes the location’s WireGuard key and bootstrap token and returns the exit recipe with the token in it, once. Then create a security group (UDP 51820, 443, 3478), a launch template with that user data, an auto scaling group, and Elastic IPs, and attach them with update and add-address — scripts/privacy-vpn/fleet.ts does all of it.

dcloud privacyvpn locations update

Change a location’s size, state, max exit age, or its group

PATCH /privacyvpn/api/locations/{id} — IAM privacyvpn:UpdateExitLocation — write

dcloud privacyvpn locations update <id> [flags]

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<id> --id string /^[a-z]{2}-[a-z]{3,8}$/
Flag In Required Notes
--state <active|disabled> body
--min-exits <number> body integer, 0-50
--max-exits <number> body integer, 1-50
--target-peers-per-exit <number> body integer, 1-10000
--max-exit-age-hours <number> body integer, 1-168
--group-id <value> body /^asg-[0-9a-f]{8}$/ · The auto scaling group that runs the exits (asg-…)
--launch-template-id <value> body /^lt-[0-9a-f]{8}$/
--security-group-id <value> body
--vpc-id <value> body The location’s own VPC: exits outside it are refused at registration

dcloud privacyvpn locations add-address

Give a location a stable address (an Elastic IP the controller keeps on a healthy exit)

POST /privacyvpn/api/locations/{id}/addresses — IAM privacyvpn:UpdateExitLocation — write

dcloud privacyvpn locations add-address <id> --elastic-ip-id <value>

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<id> --id string /^[a-z]{2}-[a-z]{3,8}$/
Flag In Required Notes
--elastic-ip-id <value> body yes An Elastic IP of the platform org

dcloud privacyvpn locations remove-address

Take a stable address out of a location (configs naming it stop working)

DELETE /privacyvpn/api/locations/{id}/addresses/{addressId} — IAM privacyvpn:UpdateExitLocation — write

dcloud privacyvpn locations remove-address <id> <addressId>

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<id> --id string /^[a-z]{2}-[a-z]{3,8}$/
<addressId> --address-id string

dcloud privacyvpn locations delete

Delete an exit location (its group and addresses are deleted through their own APIs)

DELETE /privacyvpn/api/locations/{id} — IAM privacyvpn:DeleteExitLocation — write

dcloud privacyvpn locations delete <id>

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<id> --id string /^[a-z]{2}-[a-z]{3,8}$/

dcloud privacyvpn accounts

VPN accounts: a 16-digit number each, billed on the organization’s invoice

Operation Method Path IAM action Effect
list GET /privacyvpn/api/accounts privacyvpn:ListAccounts read
create POST /privacyvpn/api/accounts privacyvpn:CreateAccount write
get GET /privacyvpn/api/accounts/{id} privacyvpn:ListAccounts read
update PATCH /privacyvpn/api/accounts/{id} privacyvpn:UpdateAccount write
delete DELETE /privacyvpn/api/accounts/{id} privacyvpn:DeleteAccount write
issue-tokens POST /privacyvpn/api/accounts/{id}/tokens privacyvpn:IssueAccessTokens write

dcloud privacyvpn accounts list

List the organization’s VPN accounts and this month’s token use

GET /privacyvpn/api/accounts — IAM privacyvpn:ListAccounts — read

dcloud privacyvpn accounts list

dcloud privacyvpn accounts create

Create a VPN account; its number is shown once

POST /privacyvpn/api/accounts — IAM privacyvpn:CreateAccount — write

dcloud privacyvpn accounts create --name <value> [flags]
Flag In Required Notes
--name <value> body yes 1-64 chars, /^[A-Za-z0-9][A-Za-z0-9 ._-]*$/
--device-limit <number> body integer, 1-20 · server default 5
  • The number is the account’s only credential (for apps that sign in with it); Deutsche Cloud keeps a hash. Preview price: €5 a month flat.

dcloud privacyvpn accounts get

Describe a VPN account

GET /privacyvpn/api/accounts/{id} — IAM privacyvpn:ListAccounts — read

dcloud privacyvpn accounts get <id>

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<id> --id string

dcloud privacyvpn accounts update

Rename an account, change its device limit, suspend or resume it

PATCH /privacyvpn/api/accounts/{id} — IAM privacyvpn:UpdateAccount — write

dcloud privacyvpn accounts update <id> [flags]

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<id> --id string
Flag In Required Notes
--name <value> body 1-64 chars, /^[A-Za-z0-9][A-Za-z0-9 ._-]*$/
--device-limit <number> body integer, 1-20
--state <active|suspended> body

dcloud privacyvpn accounts delete

Delete a VPN account (devices already registered work until the month ends)

DELETE /privacyvpn/api/accounts/{id} — IAM privacyvpn:DeleteAccount — write

dcloud privacyvpn accounts delete <id>

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<id> --id string

dcloud privacyvpn accounts issue-tokens

Have blinded access tokens signed (RFC 9474) for an account

POST /privacyvpn/api/accounts/{id}/tokens — IAM privacyvpn:IssueAccessTokens — write

dcloud privacyvpn accounts issue-tokens <id> --epoch <value> --blinded <value>

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<id> --id string
Flag In Required Notes
--epoch <value> body yes /^\d{4}-(0[1-9]|1[0-2])$/
--blinded <value> body yes repeatable · 300-400 chars, /^[A-Za-z0-9_-]+$/ · Blinded token messages, base64url (RFC 9474)
  • The issuer never sees the tokens, only blinded values, so it cannot tell which device a token later registers. Budget: device limit + 2 per month. dcloud vpn connect does blinding, issue and registration for you.

dcloud email

Email. Base path /email/api.

dcloud email identities

Sender domains, verified by their DKIM record

Operation Method Path IAM action Effect
list GET /email/api/identities email:ListEmailIdentities read
create POST /email/api/identities email:CreateEmailIdentity write
get GET /email/api/identities/{name} email:GetEmailIdentity read
verify POST /email/api/identities/{name}/verify email:VerifyEmailIdentity write
dns-records POST /email/api/identities/{name}/dns-records email:PutEmailIdentityDnsRecords write
update PATCH /email/api/identities/{name} email:UpdateEmailIdentity write
dmarc-reports GET /email/api/identities/{name}/dmarc-reports email:GetEmailIdentity read
delete DELETE /email/api/identities/{name} email:DeleteEmailIdentity write

dcloud email identities list

List sender domains with their state and the DNS records they need

GET /email/api/identities — IAM email:ListEmailIdentities — read

dcloud email identities list

dcloud email identities create

Add a sender domain

POST /email/api/identities — IAM email:CreateEmailIdentity — write

dcloud email identities create --name <value> [flags]
Flag In Required Notes
--name <value> body yes 3-253 chars
--custom-mail-from body server default true
  • Generates a 2048-bit DKIM key. The domain is verified once public DNS returns the DKIM record listed in records; with customMailFrom (default) bounce.<domain> also needs its MX and SPF records so SPF passes aligned. If the domain is in one of your Deutsche Cloud DNS zones, dns-records writes them for you.

dcloud email identities get

One sender domain, its verification state and DNS records

GET /email/api/identities/{name} — IAM email:GetEmailIdentity — read

dcloud email identities get <name>

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<name> --name string 3-253 chars, /^[a-z0-9.-]+$/i

dcloud email identities verify

Check the DNS records now and report what each lookup found

POST /email/api/identities/{name}/verify — IAM email:VerifyEmailIdentity — write

dcloud email identities verify <name>

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<name> --name string 3-253 chars, /^[a-z0-9.-]+$/i

dcloud email identities dns-records

Write the domain's DKIM, MAIL FROM and DMARC records into its Deutsche Cloud DNS zone

POST /email/api/identities/{name}/dns-records — IAM email:PutEmailIdentityDnsRecords — write

dcloud email identities dns-records <name>

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<name> --name string 3-253 chars, /^[a-z0-9.-]+$/i
  • Needs dns:ChangeRecords on the zone too. A record set already at a name is kept (an existing DMARC policy is never replaced); the result says what was created, unchanged or skipped.

dcloud email identities update

Set a sender domain's DMARC policy and report address, and one-click unsubscribe by default

PATCH /email/api/identities/{name} — IAM email:UpdateEmailIdentity — write

dcloud email identities update <name> [flags]

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<name> --name string 3-253 chars, /^[a-z0-9.-]+$/i
Flag In Required Notes
--dmarc-policy <none|quarantine|reject> body
--only-sends-through-ews body
--dmarc-report-address <value> body email, max 254 chars · nullable
--list-unsubscribe body
  • quarantine and reject need onlySendsThroughEws: true: mail other providers send as the domain without DKIM for it would be lost. The DMARC record changes with the next dns-records call (or publish the value under records yourself). Aggregate reports always go to the platform too and show under dmarc-reports.

dcloud email identities dmarc-reports

What receivers reported about mail sent as this domain (DMARC aggregate reports)

GET /email/api/identities/{name}/dmarc-reports — IAM email:GetEmailIdentity — read

dcloud email identities dmarc-reports <name> [flags]

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<name> --name string 3-253 chars, /^[a-z0-9.-]+$/i
Flag In Required Notes
--days <number> query integer, 1-180 · server default 30
  • summary: messages reported, how many passed DMARC, the sources by IP (Deutsche Cloud relays named), and a recommendation for the policy (quarantine after 7 clean days, reject after 30 under quarantine). reports: each report with its rows.

dcloud email identities delete

Remove a sender domain and its DKIM key

DELETE /email/api/identities/{name} — IAM email:DeleteEmailIdentity — write

dcloud email identities delete <name>

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<name> --name string 3-253 chars, /^[a-z0-9.-]+$/i

dcloud email messages

Sending, and the log of what was sent (30 days)

Operation Method Path IAM action Effect
send POST /email/api/send email:SendEmail write
send-raw POST /email/api/send-raw email:SendEmail write
list GET /email/api/messages email:ListEmailMessages read
get GET /email/api/messages/{id} email:GetEmailMessage read

dcloud email messages send

Send a message built from fields

POST /email/api/send — IAM email:SendEmail — write

dcloud email messages send --from <value> --subject <value> [flags]
Flag In Required Notes
--from <value> body yes 3-998 chars
--to <value> body repeatable · 3-320 chars · server default []
--cc <value> body repeatable · 3-320 chars · server default []
--bcc <value> body repeatable · 3-320 chars · server default []
--reply-to <value> body max 998 chars
--subject <value> body yes max 998 chars
--text <value> body
--html <value> body
--headers <key=value> body repeatable · key=value
--attachments <value> body repeatable
--unsubscribe body
  • The From domain must be a verified sender domain; IAM checks email:SendEmail on it. text, html or both; attachments are base64 (10 MB per message in all). Answers 202 with the message id and each recipient as queued, or suppressed when the address is on the suppression list (accepted, never sent). In the sandbox every recipient must be a verified identity of the organization. unsubscribe: true adds RFC 8058 one-click unsubscribe headers to each recipient’s copy (a click puts the address on the suppression list); added anyway when the domain’s listUnsubscribe is on or the organization sent 4,000 or more in 24 hours.

dcloud email messages send-raw

Send a complete RFC 5322 message (base64)

POST /email/api/send-raw — IAM email:SendEmail — write

dcloud email messages send-raw --raw <value> --recipients <value> [flags]
Flag In Required Notes
--raw <value> body yes min 1 chars
--recipients <value> body yes repeatable · 3-320 chars
--unsubscribe body
  • Recipients are taken from recipients, not from the headers, so Bcc stays private. A Message-ID and Date are added when missing. unsubscribe (or the header X-DCLOUD-Unsubscribe: one-click, or X-EWS-Unsubscribe, removed before sending) as for send.

dcloud email messages list

Recent messages, newest first, with each recipient’s delivery state

GET /email/api/messages — IAM email:ListEmailMessages — read

dcloud email messages list [flags]
Flag In Required Notes
--limit <number> query integer, 1-200 · server default 50
--before <value> query
--status <queued|delivered|deferred|bounced|complained|suppressed|rejected> query
--recipient <value> query max 320 chars

dcloud email messages get

One message with every delivery event of every recipient

GET /email/api/messages/{id} — IAM email:GetEmailMessage — read

dcloud email messages get <id>

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<id> --id string uuid

dcloud email account

Quota, sandbox and the bounce and complaint rates of the organization

Operation Method Path IAM action Effect
get GET /email/api/account email:GetEmailAccount read
request-production-access POST /email/api/account/production-access email:RequestProductionAccess write

dcloud email account get

Sandbox state, quotas, use in the last 24 hours and the 7-day reputation

GET /email/api/account — IAM email:GetEmailAccount — read

dcloud email account get

dcloud email account request-production-access

Ask to send to anyone, not only to verified addresses

POST /email/api/account/production-access — IAM email:RequestProductionAccess — write

dcloud email account request-production-access --use-case <value>
Flag In Required Notes
--use-case <value> body yes 20-4000 chars
  • Describe what you send, to whom, roughly how many a day, and how recipients asked for it. Support reviews it; until then only verified identities can receive.

dcloud email suppressions

Addresses nothing is sent to: hard bounces, complaints, and ones added by hand

Operation Method Path IAM action Effect
list GET /email/api/suppressions email:ListSuppressedDestinations read
put PUT /email/api/suppressions email:PutSuppressedDestination write
delete DELETE /email/api/suppressions/{address} email:DeleteSuppressedDestination write

dcloud email suppressions list

List suppressed addresses, newest first

GET /email/api/suppressions — IAM email:ListSuppressedDestinations — read

dcloud email suppressions list [flags]
Flag In Required Notes
--limit <number> query integer, 1-1000 · server default 200
--search <value> query max 320 chars

dcloud email suppressions put

Add an address to the suppression list

PUT /email/api/suppressions — IAM email:PutSuppressedDestination — write

dcloud email suppressions put --address <value>
Flag In Required Notes
--address <value> body yes email

dcloud email suppressions delete

Remove an address from the suppression list, so mail is sent to it again

DELETE /email/api/suppressions/{address} — IAM email:DeleteSuppressedDestination — write

dcloud email suppressions delete <address>

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<address> --address string email

dcloud tags

Tags & saved views. Base path /tags/api.

dcloud tags tags

Key=value tags on resources — the one grouping primitive

The resource is named after its service, so every command in this section reads dcloud tags tags <operation>. That is the literal three-word shape the dispatcher takes; there is no shorter spelling today.

Operation Method Path IAM action Effect
list GET /tags/api/resource tags:ListTags read
set PUT /tags/api/resource tags:TagResource write
remove DELETE /tags/api/resource tags:UntagResource write
keys GET /tags/api/keys tags:ListTags read
values GET /tags/api/values tags:ListTags read
coverage GET /tags/api/coverage tags:ListTags read
bulk POST /tags/api/bulk tags:TagResource write

dcloud tags tags list

The tags on one resource

GET /tags/api/resource — IAM tags:ListTags — read

dcloud tags tags list --resource-type <value> --resource-id <value>
Flag In Required Notes
--resource-type <value> query yes What kind of resource, e.g. ec2:instance
--resource-id <value> query yes 1-200 chars, /^[A-Za-z0-9._:-]+$/ · The resource’s own id as its service issues it (uuid, i-…, ewdb-…)
  • resourceType is service:type, e.g. deploy:app, rds:db, cache:cluster.

dcloud tags tags set

Set one tag on a resource (adds it, or replaces its value)

PUT /tags/api/resource — IAM tags:TagResource — write

dcloud tags tags set --resource-type <value> --resource-id <value> --key <value> --value <value>
Flag In Required Notes
--resource-type <value> body yes What kind of resource, e.g. ec2:instance
--resource-id <value> body yes 1-200 chars, /^[A-Za-z0-9._:-]+$/ · The resource’s own id as its service issues it (uuid, i-…, ewdb-…)
--key <value> body yes 1-64 chars, /^[a-z][a-z0-9_.-]*$/
--value <value> body yes 1-128 chars, /^[A-Za-z0-9][A-Za-z0-9_.:@/-]*$/
  • tags:TagResource is checked on the tagged resource’s RN (e.g. rn:ews:de1::ec2:instance/i-…), not on the tags service. Tagging an app, database or cache with a project’s key puts it in that project.

dcloud tags tags remove

Remove one tag from a resource

DELETE /tags/api/resource — IAM tags:UntagResource — write

dcloud tags tags remove --resource-type <value> --resource-id <value> --key <value>
Flag In Required Notes
--resource-type <value> body yes What kind of resource, e.g. ec2:instance
--resource-id <value> body yes 1-200 chars, /^[A-Za-z0-9._:-]+$/ · The resource’s own id as its service issues it (uuid, i-…, ewdb-…)
--key <value> body yes 1-64 chars, /^[a-z][a-z0-9_.-]*$/
  • tags:UntagResource is checked on the tagged resource’s RN.

dcloud tags tags keys

Tag keys in use, with how many resources carry each

GET /tags/api/keys — IAM tags:ListTags — read

dcloud tags tags keys

dcloud tags tags values

The values one key has across the organization

GET /tags/api/values — IAM tags:ListTags — read

dcloud tags tags values --key <value>
Flag In Required Notes
--key <value> query yes 1-64 chars, /^[a-z][a-z0-9_.-]*$/

dcloud tags tags coverage

Existing resources that lack a key, by service

GET /tags/api/coverage — IAM tags:ListTags — read

dcloud tags tags coverage --key <value>
Flag In Required Notes
--key <value> query yes 1-64 chars, /^[a-z][a-z0-9_.-]*$/
  • Ask this before making a key required: a required key only stops creates, so resources that lack it keep working, and bulk sets a value on them.

dcloud tags tags bulk

Set one key=value on up to 500 resources

POST /tags/api/bulk — IAM tags:TagResource — write

dcloud tags tags bulk --key <value> --value <value> --resources <value>
Flag In Required Notes
--key <value> body yes 1-64 chars, /^[a-z][a-z0-9_.-]*$/
--value <value> body yes 1-128 chars, /^[A-Za-z0-9][A-Za-z0-9_.:@/-]*$/
--resources <value> body yes repeatable
  • tags:TagResource is checked on each resource’s RN; refused ones are listed in refused, the rest are tagged.

dcloud tags policy

Required tag keys — a resource cannot be created without them

Operation Method Path IAM action Effect
set-key PUT /tags/api/policy/keys tags:ManageTagPolicy write
delete-key DELETE /tags/api/policy/keys tags:ManageTagPolicy write

dcloud tags policy set-key

Declare a tag key, and whether every new resource must carry it

PUT /tags/api/policy/keys — IAM tags:ManageTagPolicy — write

dcloud tags policy set-key --key <value> --required [flags]
Flag In Required Notes
--key <value> body yes 1-64 chars, /^[a-z][a-z0-9_.-]*$/
--description <value> body max 200 chars
--required body yes
--backfill-from <actor|none> body

dcloud tags policy delete-key

Forget a declared tag key (tags already set stay)

DELETE /tags/api/policy/keys — IAM tags:ManageTagPolicy — write

dcloud tags policy delete-key --key <value>
Flag In Required Notes
--key <value> body yes 1-64 chars, /^[a-z][a-z0-9_.-]*$/

dcloud tags projects

Projects: a named, saved tag query that groups one product’s resources

Operation Method Path IAM action Effect
list GET /tags/api/projects tags:ListProjects read
resources GET /tags/api/projects/{id}/resources tags:ListProjects read
create POST /tags/api/projects tags:ManageProjects write
update PATCH /tags/api/projects/{id} tags:ManageProjects write
delete DELETE /tags/api/projects/{id} tags:ManageProjects write

dcloud tags projects list

List projects

GET /tags/api/projects — IAM tags:ListProjects — read

dcloud tags projects list

dcloud tags projects resources

The resources a project’s query selects

GET /tags/api/projects/{id}/resources — IAM tags:ListProjects — read

dcloud tags projects resources <id>

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<id> --id string uuid

dcloud tags projects create

Create a project from a tag query

POST /tags/api/projects — IAM tags:ManageProjects — write

dcloud tags projects create --name <value> --query <value> [flags]
Flag In Required Notes
--name <value> body yes 1-100 chars
--description <value> body max 500 chars
--query <value> body yes repeatable
  • query is a conjunction: every clause must match. E.g. [{"key":"product","values":["deutschlandgpt"]}].

dcloud tags projects update

Rename a project or change its query

PATCH /tags/api/projects/{id} — IAM tags:ManageProjects — write

dcloud tags projects update <id> [flags]

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<id> --id string uuid
Flag In Required Notes
--name <value> body 1-100 chars
--description <value> body max 500 chars · nullable
--query <value> body repeatable

dcloud tags projects delete

Delete a project (its resources and tags stay)

DELETE /tags/api/projects/{id} — IAM tags:ManageProjects — write

dcloud tags projects delete <id>

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<id> --id string uuid

dcloud tags topology

What runs in which private network, and what each app uses — read-only

Operation Method Path IAM action Effect
get GET /tags/api/topology tags:ListProjects read

dcloud tags topology get

The networks with their apps, databases, caches and VPN gateway

GET /tags/api/topology — IAM tags:ListProjects — read

dcloud tags topology get [flags]
Flag In Required Notes
--project <value> query /^[a-z0-9][a-z0-9-]{0,62}$/
  • Without project, the whole organization, cut to the services the caller can describe (no permission of its own). With project (a project slug), only the resources its tags select, plus what those apps use, marked inScope=false; that needs tags:ListProjects. Each app lists uses as database:<id> / cache:<id> keys of the data nodes in the same network.

dcloud projects

Projects. Base path /projects/api.

dcloud projects projects

Where resources live: every resource is in exactly one project; Default holds everything not put elsewhere

The resource is named after its service, so every command in this section reads dcloud projects projects <operation>. That is the literal three-word shape the dispatcher takes; there is no shorter spelling today.

Operation Method Path IAM action Effect
list GET /projects/api/projects projects:ListProjects read
create POST /projects/api/projects projects:CreateProject write
update PATCH /projects/api/projects/{slug} projects:UpdateProject write
delete DELETE /projects/api/projects/{slug} projects:DeleteProject write
quotas GET /projects/api/projects/{slug}/quotas projects:ListProjects read
set-quota PUT /projects/api/projects/{slug}/quotas/{quotaId} projects:UpdateProject write
remove-quota DELETE /projects/api/projects/{slug}/quotas/{quotaId} projects:UpdateProject write
of GET /projects/api/resource projects:ListProjects read
move POST /projects/api/move projects:MoveResource write
from-tag POST /projects/api/from-tag projects:CreateProject write

dcloud projects projects list

The organization’s projects, Default first, with how many resources each holds

GET /projects/api/projects — IAM projects:ListProjects — read

dcloud projects projects list
  • Creates go into the project named by the X-EWS-Project header (its slug), or Default when it is left out. Policies can limit creates to a project with the condition key ews:RequestProject.

dcloud projects projects create

Create a project

POST /projects/api/projects — IAM projects:CreateProject — write

dcloud projects projects create --name <value> [flags]
Flag In Required Notes
--name <value> body yes 1-80 chars · What people read; can be changed
--slug <value> body /^[a-z0-9][a-z0-9-]{0,62}$/ · Used in X-EWS-Project and policy conditions; never changes. Default: from the name
--description <value> body max 500 chars · nullable

dcloud projects projects update

Rename a project (its slug never changes)

PATCH /projects/api/projects/{slug} — IAM projects:UpdateProject — write

dcloud projects projects update <slug> [flags]

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<slug> --slug string /^[a-z0-9][a-z0-9-]{0,62}$/
Flag In Required Notes
--name <value> body 1-80 chars · What people read; can be changed
--description <value> body max 500 chars · nullable

dcloud projects projects delete

Delete a project; what is in it moves to Default

DELETE /projects/api/projects/{slug} — IAM projects:DeleteProject — write

dcloud projects projects delete <slug>

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<slug> --slug string /^[a-z0-9][a-z0-9-]{0,62}$/
  • Also needs projects:MoveResource on the Default project. Default cannot be deleted.

dcloud projects projects quotas

The quotas a project can cap, with its cap and use (null without a cap) and the organization’s own limit

GET /projects/api/projects/{slug}/quotas — IAM projects:ListProjects — read

dcloud projects projects quotas <slug>

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<slug> --slug string /^[a-z0-9][a-z0-9-]{0,62}$/
  • Count quotas of resources that land in the project a create names (databases, clusters, machines, buckets…); parts follow their owner and are not capped per project.

dcloud projects projects set-quota

Cap a quota in a project: creates and moves into it beyond the cap are refused

PUT /projects/api/projects/{slug}/quotas/{quotaId} — IAM projects:UpdateProject — write

dcloud projects projects set-quota <slug> <quotaId> --limit <number>

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<slug> --slug string /^[a-z0-9][a-z0-9-]{0,62}$/
<quotaId> --quota-id string /^[a-z0-9-]+.[a-z0-9-]+$/
Flag In Required Notes
--limit <number> body yes integer, 0-1000000 · At most this many in the project; the organization’s own limit still applies
  • A refusal is the usual 409 QuotaExceeded, with quota.project set. The organization’s own quota applies first.

dcloud projects projects remove-quota

Remove a project’s cap on a quota

DELETE /projects/api/projects/{slug}/quotas/{quotaId} — IAM projects:UpdateProject — write

dcloud projects projects remove-quota <slug> <quotaId>

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<slug> --slug string /^[a-z0-9][a-z0-9-]{0,62}$/
<quotaId> --quota-id string /^[a-z0-9-]+.[a-z0-9-]+$/

dcloud projects projects of

The project one resource is in

GET /projects/api/resource — IAM projects:ListProjects — read

dcloud projects projects of --resource-type <value> --resource-id <value>
Flag In Required Notes
--resource-type <value> query yes What kind of resource, e.g. rds:db
--resource-id <value> query yes 1-200 chars, /^[A-Za-z0-9._:-]+$/ · The id the resource is tagged under

dcloud projects projects move

Move a resource, with its parts, to another project

POST /projects/api/move — IAM projects:MoveResource — write

dcloud projects projects move --resource-type <value> --resource-id <value> --project <value>
Flag In Required Notes
--resource-type <value> body yes What kind of resource, e.g. rds:db
--resource-id <value> body yes 1-200 chars, /^[A-Za-z0-9._:-]+$/ · The id the resource is tagged under
--project <value> body yes /^[a-z0-9][a-z0-9-]{0,62}$/ · The target project
  • Checked on the project it leaves and the one it enters. Its parts go with it (a cluster’s node groups and machines, a database’s endpoint and backup bucket).

dcloud projects projects from-tag

Turn a tag key into projects: one per value, each resource carrying it (still in Default) moved in

POST /projects/api/from-tag — IAM projects:CreateProject — write

dcloud projects projects from-tag --key <value>
Flag In Required Notes
--key <value> body yes 1-64 chars, /^[a-z][a-z0-9_.-]*$/
  • May check projects:MoveResource or tags:ManageTagPolicy instead, decided by server-side state the caller cannot see. A caller needs all of them to be sure of not getting a 403.
  • Only the organization’s owner, signed in (not an access key). Resources already moved stay; the tag itself stays. A required key becomes optional (it is the project now), which also needs tags:ManageTagPolicy.

dcloud ai

AI Models. Base path /ai/api.

dcloud ai settings

What the in-console assistant is allowed to do for this organization

Operation Method Path IAM action Effect
get GET /ai/api/settings ai:Chat read
update PATCH /ai/api/settings ai:ConfigureSettings write

dcloud ai settings get

Read the assistant’s switches for the organization

GET /ai/api/settings — IAM ai:Chat — read

dcloud ai settings get

dcloud ai settings update

Turn the assistant’s live-data reading or actions on or off, or choose its model

PATCH /ai/api/settings — IAM ai:ConfigureSettings — write

dcloud ai settings update [flags]
Flag In Required Notes
--ai-answer-questions body The console assistant for the whole organization; off, the chat API answers 403
--ai-read-live-data body Let the assistant read live resources, with the asking user’s permissions
--ai-execute-actions body Let the assistant carry out changes, with the asking user’s permissions
--ai-assistant-model <value> body 1-200 chars · The assistant’s model: auto (the default) or an id from ai assistant-models list; checked against that live list
  • Only the fields sent change. Applies to every member of the organization.

dcloud ai assistant-models

The models the console assistant can use: the AI provider’s live list, EU-hosted chat models only

Operation Method Path IAM action Effect
list GET /ai/api/assistant-models ai:Chat read

dcloud ai assistant-models list

List the models the organization can choose for the assistant, and what Auto is now

GET /ai/api/assistant-models — IAM ai:Chat — read

dcloud ai assistant-models list
  • Read live from the provider’s API (cached 5 minutes). auto is the model Auto resolves to right now. Only models the provider reports as hosted in Germany or the EU are listed.

dcloud ai models

The models the model API (/ai/v1) offers this organization, with residency, location and price

Operation Method Path IAM action Effect
list GET /ai/api/models ai:ListModels read

dcloud ai models list

List the models, whether this organization may use each, and their prices

GET /ai/api/models — IAM ai:ListModels — read

dcloud ai models list
  • Each entry says whether the organization’s model access allows it (available) and whether the caller’s IAM allows ai:InvokeModel on it (canInvoke). Prices are EUR per million tokens.

dcloud ai model-access

Which models the organization may use, how fast, how much it may spend, and whether prompts are logged

Operation Method Path IAM action Effect
get GET /ai/api/model-access ai:ListModels read
update PATCH /ai/api/model-access ai:ConfigureModelAccess write

dcloud ai model-access get

Read the organization’s model access settings and effective limits

GET /ai/api/model-access — IAM ai:ListModels — read

dcloud ai model-access get

dcloud ai model-access update

Set the residency ceiling, allow-list, rate limits, monthly spend cap or prompt logging

PATCH /ai/api/model-access — IAM ai:ConfigureModelAccess — write

dcloud ai model-access update [flags]
Flag In Required Notes
--residency-ceiling <eu|eu-processed|any> body The most the organization lets through: eu (EU providers processing in the EU), eu-processed (also non-EU providers processing in the EU) or any
--allow-list-enabled body Only the models in allowedModels may be used (otherwise every model within the residency ceiling)
--allowed-models <value> body repeatable · 2-64 chars, /^[a-z0-9][a-z0-9.-]*[a-z0-9]$/ · Model ids on the allow-list
--requests-per-minute <number> body integer, 1-100000 · nullable · Requests per minute for the organization; null for the default (600)
--requests-per-minute-per-key <number> body integer, 1-100000 · nullable · Requests per minute per access key; null for no per-key limit
--monthly-spend-cap-eur <number> body 0-1000000 · nullable · Hard monthly spend cap in EUR (calendar month, UTC); null for none
--prompt-logging body Store prompt and response bodies, encrypted under a KMS key, for 30 days
--prompt-log-key-id <value> body uuid · The KMS key to seal prompt logs under (default: the first enabled encrypt/decrypt key)
  • Only the fields sent change. Prompt logging needs a KMS encrypt/decrypt key; bodies are sealed under it and kept 30 days.

dcloud ai usage

The model API usage log: one row per request, never a prompt body

Operation Method Path IAM action Effect
list GET /ai/api/usage ai:GetUsage read
get-prompt GET /ai/api/usage/{id}/prompt ai:GetPromptLogs read, sensitive

dcloud ai usage list

Per-model totals and the request log for a time range

GET /ai/api/usage — IAM ai:GetUsage — read

dcloud ai usage list [flags]
Flag In Required Notes
--from <value> query datetime · Start, ISO 8601 (default: 24 hours ago)
--to <value> query datetime · End, ISO 8601 (default: now)
--model <value> query 2-64 chars, /^[a-z0-9][a-z0-9.-]*[a-z0-9]$/ · Only this model
--limit <number> query integer, 1-500 · Log rows to return (default 100)
--before <value> query datetime · Rows older than this (the createdAt of the last row of the previous page)
  • Default range: the last 24 hours. Rows are kept 90 days.

dcloud ai usage get-prompt

Read the logged prompt and response of one request

GET /ai/api/usage/{id}/prompt — IAM ai:GetPromptLogs — read, sensitive

dcloud ai usage get-prompt <id>

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<id> --id string uuid
  • Only exists for requests made while prompt logging was on, for 30 days. Every read is audited.

Not in the CLI: ai routes the surface does not describe

These routes exist and are reachable over HTTP. They are deliberately absent from the description, so there is no command for them. The reason is recorded next to the service so a gap has to be stated out loud and stops being stateable the moment the route goes.

Route Why it has no command
POST /ai/api/chat Streams the console assistant’s reply as AI SDK UI-message events, not the JSON envelope; an MCP client is itself an assistant and calls the tools directly

dcloud cdn

CDN. Base path /cdn/api.

dcloud cdn distributions

An edge in front of a bucket website, an app, a load balancer or a public origin: caching, purge, web ACL

Operation Method Path IAM action Effect
list GET /cdn/api/distributions cdn:ListDistributions read
create POST /cdn/api/distributions cdn:CreateDistribution write
get GET /cdn/api/distributions/{id} cdn:GetDistribution read
update PATCH /cdn/api/distributions/{id} cdn:UpdateDistribution write
delete DELETE /cdn/api/distributions/{id} cdn:DeleteDistribution write
stats GET /cdn/api/distributions/{id}/stats cdn:GetDistributionStats read

dcloud cdn distributions list

List distributions with their edge state

GET /cdn/api/distributions — IAM cdn:ListDistributions — read

dcloud cdn distributions list

dcloud cdn distributions create

Create a distribution; its platform name .cdn.apps. answers within a minute

POST /cdn/api/distributions — IAM cdn:CreateDistribution — write

dcloud cdn distributions create --name <value> --origin <json> [flags]
Flag In Required Notes
--name <value> body yes 1-64 chars, /^[a-zA-Z0-9][a-zA-Z0-9._-]*$/
--comment <value> body max 256 chars
--origin <json> body yes JSON
--aliases <value> body repeatable · /^(?=.{1,253}$)(?:a-z0-9?.)+[a-z]{2,63}$/
--cache <json> body JSON
--web-acl-id <value> body nullable
--edge-regions <de1|fi1> body repeatable · de1 (Falkenstein + Nuremberg) always; fi1 (Helsinki) for orgs that allow EU outside Germany
--enabled body
--redirect-https body Answer http:// requests with a 308 redirect to https:// (default false). Custom names redirect once their certificate is active.
--tags <key=value> body repeatable · key=value · Tags for the new resource, e.g. {"env": "prod", "project": "shop"}. Keys your organization marks required must be present, or the create is refused with the missing keys (GET /tags/api/keys lists them).
  • origin.type bucket needs the bucket website on; app and lb use the resource’s own name; custom is a public host (never a private or platform address). Aliases must be names in the org’s hosted zones: a CNAME to the platform name is written for each, and they are served once their certificate is issued (aliasCertificate.status active). webAclId attaches a web ACL (needs waf:GetWebAcl on it). edgeRegions: de1 (Falkenstein + Nuremberg); fi1 (Helsinki) needs the org setting for EU outside Germany. Origins see the header X-EWS-CDN-Token: originToken.

dcloud cdn distributions get

Describe a distribution: origin, names, cache settings, web ACL, every edge node serving it

GET /cdn/api/distributions/{id} — IAM cdn:GetDistribution — read

dcloud cdn distributions get <id>

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<id> --id string

dcloud cdn distributions update

Change a distribution (origin, aliases, cache, web ACL, regions); rotateOriginToken: true for a new token

PATCH /cdn/api/distributions/{id} — IAM cdn:UpdateDistribution — write

dcloud cdn distributions update <id> [flags]

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<id> --id string
Flag In Required Notes
--comment <value> body max 256 chars
--origin <json> body JSON
--aliases <value> body repeatable · /^(?=.{1,253}$)(?:a-z0-9?.)+[a-z]{2,63}$/
--cache <json> body JSON
--web-acl-id <value> body nullable
--edge-regions <de1|fi1> body repeatable · de1 (Falkenstein + Nuremberg) always; fi1 (Helsinki) for orgs that allow EU outside Germany
--enabled body
--redirect-https body Answer http:// requests with a 308 redirect to https:// (default false). Custom names redirect once their certificate is active.
--rotate-origin-token body
  • webAclId: null detaches the web ACL. A change reaches the edge nodes within a few seconds.

dcloud cdn distributions delete

Delete a distribution; its names stop answering

DELETE /cdn/api/distributions/{id} — IAM cdn:DeleteDistribution — write

dcloud cdn distributions delete <id>

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<id> --id string

dcloud cdn distributions stats

Cache hit ratio, bytes and WAF counts per minute, and live counters per edge node

GET /cdn/api/distributions/{id}/stats — IAM cdn:GetDistributionStats — read

dcloud cdn distributions stats <id> [flags]

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<id> --id string
Flag In Required Notes
--hours <number> query integer, 1-168

dcloud cdn invalidations

Purges: cached objects removed on every edge node

Operation Method Path IAM action Effect
create POST /cdn/api/distributions/{id}/invalidations cdn:CreateInvalidation write
list GET /cdn/api/distributions/{id}/invalidations cdn:ListInvalidations read

dcloud cdn invalidations create

Purge by path (/a), path prefix (/img/), everything (/) or tag (Cache-Tag / Surrogate-Key)

POST /cdn/api/distributions/{id}/invalidations — IAM cdn:CreateInvalidation — write

dcloud cdn invalidations create <id> [flags]

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<id> --id string
Flag In Required Notes
--paths <value> body repeatable · 1-1024 chars · Exact paths, or a prefix ending in * (/img/*); /* purges everything
--tags <value> body repeatable · 1-128 chars · Tags the origin set in Cache-Tag or Surrogate-Key
  • Applied by each node within a few seconds; status turns completed once every live edge node has applied it (about 10–70 s, the nodes report every 10 s and the control plane checks every minute).

dcloud cdn invalidations list

List a distribution’s purges and the edge nodes that applied each

GET /cdn/api/distributions/{id}/invalidations — IAM cdn:ListInvalidations — read

dcloud cdn invalidations list <id>

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<id> --id string

dcloud cdn edge

The edge nodes: locations, addresses, state and the DDoS settings they report

Operation Method Path IAM action Effect
list GET /cdn/api/edge cdn:ListDistributions read

dcloud cdn edge list

List the edge nodes with their reported DDoS settings (SYN cookies, nftables caps)

GET /cdn/api/edge — IAM cdn:ListDistributions — read

dcloud cdn edge list

dcloud waf

Web application firewall. Base path /waf/api.

dcloud waf web-acls

Rule sets for CDN distributions and application load balancers: Deutsche Cloud Core managed rules, match, IP, country and rate rules

Operation Method Path IAM action Effect
list GET /waf/api/web-acls waf:ListWebAcls read
create POST /waf/api/web-acls waf:CreateWebAcl write
get GET /waf/api/web-acls/{id} waf:GetWebAcl read
update PATCH /waf/api/web-acls/{id} waf:UpdateWebAcl write
delete DELETE /waf/api/web-acls/{id} waf:DeleteWebAcl write
logs GET /waf/api/web-acls/{id}/logs waf:GetWafLogs read

dcloud waf web-acls list

List web ACLs and the distributions and load balancers using each

GET /waf/api/web-acls — IAM waf:ListWebAcls — read

dcloud waf web-acls list

dcloud waf web-acls create

Create a web ACL (without rules: the Deutsche Cloud Core defaults)

POST /waf/api/web-acls — IAM waf:CreateWebAcl — write

dcloud waf web-acls create --name <value> [flags]
Flag In Required Notes
--name <value> body yes 1-64 chars, /^[a-zA-Z0-9][a-zA-Z0-9._-]*$/
--description <value> body max 256 chars
--default-action <allow|block> body
--rules <value> body repeatable · In order. Omitted: the Deutsche Cloud Core defaults (injection groups block, scanners and protocol count)
--body-inspect-bytes <number> body integer, 0-65536
  • Rules run in order; the first allow, block or unpassed challenge decides, count matches are logged and evaluation goes on. Statements: ipSet {cidrs}, geo {countries, ISO alpha-2, XX = unknown}, match {field path|query|uri|method|header|body, header, op exact|prefix|contains|regex, value, negate}, rate {key ip|ipPath, pathPrefix, limit, windowSeconds; counted across all edge nodes, synced every second; 429}, managed {group sqli|xss|traversal|rce|php-java|scanners|protocol, exclude}. challenge: a JavaScript proof of work for browsers, 403 {"error":"challenge_required"} for anything else.

dcloud waf web-acls get

Describe a web ACL

GET /waf/api/web-acls/{id} — IAM waf:GetWebAcl — read

dcloud waf web-acls get <id>

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<id> --id string
  • distributions and loadBalancers: where it is attached (load balancers you may describe). enforcement: how many edge and load balancer nodes run it, and any rule a node on an older build cannot enforce yet (for about two minutes after an update; degraded = a block or challenge rule left out).

dcloud waf web-acls update

Change a web ACL; every distribution and load balancer using it gets the rules within seconds

PATCH /waf/api/web-acls/{id} — IAM waf:UpdateWebAcl — write

dcloud waf web-acls update <id> [flags]

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<id> --id string
Flag In Required Notes
--description <value> body max 256 chars
--default-action <allow|block> body
--rules <value> body repeatable
--body-inspect-bytes <number> body integer, 0-65536

dcloud waf web-acls delete

Delete a web ACL no distribution or load balancer uses

DELETE /waf/api/web-acls/{id} — IAM waf:DeleteWebAcl — write

dcloud waf web-acls delete <id>

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<id> --id string

dcloud waf web-acls logs

The requests the web ACL matched: action, rule, field, value, client, path, node

GET /waf/api/web-acls/{id}/logs — IAM waf:GetWafLogs — read

dcloud waf web-acls logs <id> [flags]

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<id> --id string
Flag In Required Notes
--since <value> query
--limit <number> query integer, 1-500
--distribution-id <value> query
--load-balancer-id <value> query
  • Kept 7 days; stored at about 50 lines/s per distribution or load balancer, blocks first. distributionId or loadBalancerId narrows it to one.

dcloud waf managed-rule-groups

The Deutsche Cloud Core managed rule groups and their rule ids

Operation Method Path IAM action Effect
list GET /waf/api/managed-rule-groups waf:ListWebAcls read

dcloud waf managed-rule-groups list

List the managed rule groups and their rule ids (for exclude)

GET /waf/api/managed-rule-groups — IAM waf:ListWebAcls — read

dcloud waf managed-rule-groups list

dcloud quotas

Service quotas. Base path /quotas/api.

dcloud quotas quotas

Service quotas: the limits of every service, the applied value and usage

The resource is named after its service, so every command in this section reads dcloud quotas quotas <operation>. That is the literal three-word shape the dispatcher takes; there is no shorter spelling today.

Operation Method Path IAM action Effect
list GET /quotas/api/quotas quotas:ListServiceQuotas read
get GET /quotas/api/quotas/{quotaId} quotas:GetServiceQuota read

dcloud quotas quotas list

List every service quota with its applied value and usage

GET /quotas/api/quotas — IAM quotas:ListServiceQuotas — read

dcloud quotas quotas list [flags]
Flag In Required Notes
--service <value> query max 40 chars, /^[a-z0-9]+$/
  • One row per quota: per region for a region quota, the fullest parent for a per-parent quota (e.g. the cluster with the most node groups). usage is null for a rate.

dcloud quotas quotas get

Describe one quota: default, applied value, usage, increase requests

GET /quotas/api/quotas/{quotaId} — IAM quotas:GetServiceQuota — read

dcloud quotas quotas get <quotaId>

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<quotaId> --quota-id string 3-80 chars, /^[a-z0-9]+.[a-z0-9]+(-[a-z0-9]+)*$/

dcloud quotas requests

Quota increase requests

Operation Method Path IAM action Effect
list GET /quotas/api/requests quotas:ListQuotaIncreaseRequests read
request-increase POST /quotas/api/requests quotas:RequestServiceQuotaIncrease write
cancel POST /quotas/api/requests/{id}/cancel quotas:CancelQuotaIncreaseRequest write

dcloud quotas requests list

List increase requests and their outcome

GET /quotas/api/requests — IAM quotas:ListQuotaIncreaseRequests — read

dcloud quotas requests list [flags]
Flag In Required Notes
--status <pending|approved|denied|cancelled> query

dcloud quotas requests request-increase

Ask for a higher value of an adjustable quota

POST /quotas/api/requests — IAM quotas:RequestServiceQuotaIncrease — write

dcloud quotas requests request-increase --quota-id <value> --requested-value <number> --reason <value> [flags]
Flag In Required Notes
--quota-id <value> body yes 3-80 chars, /^[a-z0-9]+.[a-z0-9]+(-[a-z0-9]+)*$/
--scope-id <value> body 1-128 chars
--requested-value <number> body yes integer, 1-9007199254740991
--reason <value> body yes 10-2000 chars
  • Cheap counts are approved at once up to twice the standard default; everything else is decided by Deutsche Cloud staff, and the decision arrives as a "Service Quota Increase Request Updated" event.

dcloud quotas requests cancel

Withdraw a pending request

POST /quotas/api/requests/{id}/cancel — IAM quotas:CancelQuotaIncreaseRequest — write

dcloud quotas requests cancel <id>

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<id> --id string uuid

dcloud quotas preview-access

Requests for services in preview (Kubernetes, Functions, Sandboxes, Cloud shell)

Operation Method Path IAM action Effect
list GET /quotas/api/preview-access quotas:ListPreviewAccessRequests read
request POST /quotas/api/preview-access quotas:RequestPreviewAccess write

dcloud quotas preview-access list

List the preview services the organization has asked for

GET /quotas/api/preview-access — IAM quotas:ListPreviewAccessRequests — read

dcloud quotas preview-access list

dcloud quotas preview-access request

Ask for access to a service in preview

POST /quotas/api/preview-access — IAM quotas:RequestPreviewAccess — write

dcloud quotas preview-access request --feature <eks|functions|sandbox|cloudshell> [flags]
Flag In Required Notes
--feature <eks|functions|sandbox|cloudshell> body yes
--note <value> body max 500 chars
  • One request per service and organization; asking again updates the note. Deutsche Cloud staff grant access; until then the service’s API answers 404 for the organization.

dcloud posture

Security Posture. Base path /posture/api.

dcloud posture summary

The security score, open findings by severity, framework coverage and the trend

Operation Method Path IAM action Effect
get GET /posture/api/summary posture:GetSummary read
resources GET /posture/api/resource-findings posture:GetSummary read

dcloud posture summary get

Show the security score and what is open right now, by severity and service

GET /posture/api/summary — IAM posture:GetSummary — read

dcloud posture summary get [flags]
Flag In Required Notes
--project <value> query /^[a-z0-9][a-z0-9-]{0,62}$/
--resource <value> query max 500 chars, /^rn:(?:dcloud|ews):/
  • Counts only, no finding details. project limits it to a project’s resources; resource (an RN) to one resource. The score is the severity-weighted share of passing checks; accepted findings count as passing in the score but never in framework coverage.

dcloud posture summary resources

Count open findings per resource of one type (the badge on its page and list row)

GET /posture/api/resource-findings — IAM posture:GetSummary — read

dcloud posture summary resources --type <ec2:instance|ec2:security-group|ec2:volume|s3:bucket|rds:db|docdb:cluster|git:repository|ecr:repository|iam:user|iam:access-key>
Flag In Required Notes
--type <ec2:instance|ec2:security-group|ec2:volume|s3:bucket|rds:db|docdb:cluster|git:repository|ecr:repository|iam:user|iam:access-key> query yes
  • Keyed by resource id (a bucket by its name): open findings, the most severe, checks run. Resources with nothing checked are left out. Counts only, no finding details.

dcloud posture controls

The controls that are evaluated: what each checks, why, and how to fix a failure

Operation Method Path IAM action Effect
list GET /posture/api/controls posture:ListControls read
get GET /posture/api/controls/{id} posture:GetControl read

dcloud posture controls list

List every control with its framework mappings and how many resources fail it

GET /posture/api/controls — IAM posture:ListControls — read

dcloud posture controls list

dcloud posture controls get

Describe one control

GET /posture/api/controls/{id} — IAM posture:GetControl — read

dcloud posture controls get <id>

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<id> --id string

dcloud posture findings

Failing checks on your resources, tracked from open to resolved

Operation Method Path IAM action Effect
list GET /posture/api/findings posture:ListFindings read, sensitive
get GET /posture/api/findings/{id} posture:GetFinding read, sensitive
accept POST /posture/api/findings/{id}/acceptance posture:AcceptFinding write
revoke-acceptance POST /posture/api/findings/{id}/acceptance/revoke posture:RevokeAcceptance write

dcloud posture findings list

List findings, worst first (default: open and accepted)

GET /posture/api/findings — IAM posture:ListFindings — read, sensitive

dcloud posture findings list [flags]
Flag In Required Notes
--state <json> query JSON
--severity <json> query JSON
--control <json> query JSON
--service <value> query max 40 chars, /^[a-z0-9]+$/
--project <value> query /^[a-z0-9][a-z0-9-]{0,62}$/
--resource <value> query max 500 chars, /^rn:(?:dcloud|ews):/
--limit <number> query integer, 1-500 · server default 100
--offset <number> query integer, 0-100000 · server default 0
  • Findings name your weak spots: do not paste them into shared channels, tickets or CI logs. Every allowed read is recorded in the audit log.

dcloud posture findings get

Show one finding with its evidence, how to fix it, its history and acceptances

GET /posture/api/findings/{id} — IAM posture:GetFinding — read, sensitive

dcloud posture findings get <id>

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<id> --id string uuid
  • Findings name your weak spots: do not paste them into shared channels, tickets or CI logs. Every allowed read is recorded in the audit log.

dcloud posture findings accept

Accept a finding as a risk, with a reason, an owner and an expiry

POST /posture/api/findings/{id}/acceptance — IAM posture:AcceptFinding — write

dcloud posture findings accept <id> --reason <value> [flags]

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<id> --id string uuid
Flag In Required Notes
--reason <value> body yes 10-2000 chars
--expires-in-days <number> body integer, 1-365 · server default 90
--owner-iam-user-id <value> body uuid
  • May check posture:AcceptCriticalFinding instead, decided by server-side state the caller cannot see. A caller needs all of them to be sure of not getting a 403.
  • A critical finding needs posture:AcceptCriticalFinding as well. At most 90 days for critical and high, 365 for medium and low. The acceptance lapses when the finding gets more severe or lists a CVE it did not list when accepted.

dcloud posture findings revoke-acceptance

End a finding’s acceptance, so it counts as open again

POST /posture/api/findings/{id}/acceptance/revoke — IAM posture:RevokeAcceptance — write

dcloud posture findings revoke-acceptance <id> --reason <value>

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<id> --id string uuid
Flag In Required Notes
--reason <value> body yes 3-2000 chars

dcloud posture evaluations

Evaluation passes: when controls ran, why, and how many resources each checked

Operation Method Path IAM action Effect
list GET /posture/api/evaluations posture:ListEvaluations read
get GET /posture/api/evaluations/{id} posture:ListEvaluations read
start POST /posture/api/evaluations posture:StartEvaluation write

dcloud posture evaluations list

List recent evaluation passes

GET /posture/api/evaluations — IAM posture:ListEvaluations — read

dcloud posture evaluations list [flags]
Flag In Required Notes
--limit <number> query integer, 1-200 · server default 20

dcloud posture evaluations get

Show one evaluation pass

GET /posture/api/evaluations/{id} — IAM posture:ListEvaluations — read

dcloud posture evaluations get <id>

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<id> --id string uuid

dcloud posture evaluations start

Evaluate every control (or the ones named) now

POST /posture/api/evaluations — IAM posture:StartEvaluation — write

dcloud posture evaluations start [flags]
Flag In Required Notes
--controls <ec2.sg.world-open-admin-ports|ec2.instance.security-updates-pending|ec2.volume.unencrypted|s3.bucket.public|rds.db.publicly-accessible|rds.db.tls-not-required|rds.db.storage-unencrypted|rds.db.backup-insufficient|rds.db.deletion-protection-off|rds.db.restore-not-tested|iam.member.no-mfa|iam.access-key.unused-90d|iam.access-key.no-expiry-or-old|iam.policy.full-admin-wildcard|iam.audit.no-destination-or-short-retention|iam.org.sso-not-enforced|ecr.image.critical-fixable-cves|ecr.image.stale|ecr.image.runs-as-root|ecr.image.os-end-of-life|git.repo.default-branch-unprotected|git.repo.vulnerable-dependencies|git.repo.secret-alerts-open|git.repo.secret-push-protection-off|tls.certificate-expiring|lb.listener.http-without-redirect|dns.zone.dnssec-off|eks.cluster.public-endpoint-open|posture.control.error> body repeatable
  • Asynchronous: the evaluation runs within seconds; read the summary afterwards. At most one request a minute per organization. Controls also run on every change to your resources and hourly.

dcloud posture frameworks

ISO 27001 and BSI C5: the status of each control of the framework

Operation Method Path IAM action Effect
get GET /posture/api/frameworks/{id} posture:GetFrameworkStatus read

dcloud posture frameworks get

Show the status of every control of a framework

GET /posture/api/frameworks/{id} — IAM posture:GetFrameworkStatus — read

dcloud posture frameworks get <id>

Arguments, in path order. Each is also accepted as a flag.

Argument Also Type Constraint
<id> --id string

dcloud posture reports

Signed statements for an auditor

Operation Method Path IAM action Effect
export GET /posture/api/reports posture:ExportReport read, sensitive
export-pdf GET /posture/api/reports/pdf posture:ExportReport read, sensitive
keys GET /posture/api/report-keys posture:GetSummary read

dcloud posture reports export

Export a signed statement of what was checked, when, and with what result

GET /posture/api/reports — IAM posture:ExportReport — read, sensitive

dcloud posture reports export [flags]
Flag In Required Notes
--framework <iso27001|c5> query server default "iso27001"
  • Ed25519 over canonicalJson(statement); verify with the public key in the response or from report-keys. The statement names the evidence snapshot and audit chain head it was built from. Findings name your weak spots: do not paste them into shared channels, tickets or CI logs. Every allowed read is recorded in the audit log.

dcloud posture reports export-pdf

Export the signed statement as a PDF for print or an auditor

GET /posture/api/reports/pdf — IAM posture:ExportReport — read, sensitive

dcloud posture reports export-pdf [flags]
Flag In Required Notes
--framework <iso27001|c5> query server default "iso27001"
  • Returns raw bytes with their own content type, written straight to stdout.
  • The same statement as export, laid out per framework control, check, open finding and accepted risk; statement.json and signature.json are attached to the PDF, so the signature can be verified from the file alone. Findings name your weak spots: do not paste them into shared channels, tickets or CI logs. Every allowed read is recorded in the audit log.

dcloud posture reports keys

List the public keys reports are signed with

GET /posture/api/report-keys — IAM posture:GetSummary — read

dcloud posture reports keys
Did this page help you?