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.
Insays which. Booleans take--flagand--no-flag; arrays andkey=valuemaps 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 credentialstrades 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, orsystemctl disable ews-connecton the machine), off (launched with connect: false), not-installed (launched before Connect).enableCommandturns 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:DescribeKeyPairsinstead, 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 inews-key:<keyPairId>, soremove-keytakes 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
ticketvalid 60 s andwebsocketUrl. Open the WebSocket with the subprotocolsews.terminalandews.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.scriptas 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.installedsays 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}$/ |
datais null for an instance that does not run the patch reporter (launched withoutosPatching). 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 listdcloud 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: falseroute 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 listdcloud 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
subnetIdgets 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:RevokeSecurityGroupEgressinstead, 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 listdcloud 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
deregisteredstate — 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 listdcloud 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 listdcloud 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
encryptedis 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.kmsKeyIdwraps the volume key under one of your KMS keys (needskms:Encrypton 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
stateiscompleted. 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 unlessstopInstanceis true: the instance is stopped, the volume copied, reattached and the instance started again (needsec2:StopInstanceson 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 listdcloud 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 listdcloud 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 listdcloud 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-inArguments, 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/lifecycleand completes it withPOST /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 listdcloud 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, andcertificateStatusgoes pending → active) orcertificatePem+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
defaulttarget group. A rule whose group has no target answers 503 and never falls through to another group (the load balancer’sapplication.warningssays 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.storageis "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.backupsis "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 aretaineddatabase 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> --enabledArguments, 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 (
keepsByHandin 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 listdcloud 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> --requiredArguments, 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 listdcloud 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-bundledcloud 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-typesdcloud 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.
creatinguntil 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 whilemodifyingresumes 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 isavailableonce 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 listdcloud 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-typesdcloud docdb clusters ca-bundle
The platform CA (PEM) for tlsCAFile
GET /docdb/api/ca-bundle — IAM docdb:DescribeDocdbClusters — read
dcloud docdb clusters ca-bundledcloud 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 |
creatinguntil 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 withcreateUser, 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> --enabledArguments, 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 aretainedcluster 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 wherekeepsByHandis 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 listdcloud 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-bundledcloud 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-typesdcloud 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).
creatinguntil 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 listdcloud 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-bundledcloud 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-typesdcloud kafka clusters versions
The Apache Kafka releases a new cluster may run
GET /kafka/api/versions — IAM kafka:DescribeKafkaClusters — read
dcloud kafka clusters versionsdcloud 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.
creatinguntil 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> --enabledArguments, 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
enablingwhile the nodes restart (like an upgrade: controlled shutdown, back in every ISR before the next) andonafter 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 listdcloud 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.groupslists 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 listdcloud 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-bundledcloud 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-typesdcloud 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
creatinguntil 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
modifyinguntil new nodes are in sync and every node runs the new majority (a few minutes);addressKindsays 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 isavailableonce 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 listdcloud 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 listdcloud 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 listdcloud 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.heldon 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;
confirmmust 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 (
forcedUpgradeon 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 sourceews-blind-spot, counted as available (blindSpotMinutes).probesis the last decided minute per location;platformAddressesare 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=truekeeps 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-kubeconfigwrites the entry from this, withdcloud eks get-tokenas 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;audis 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 listdcloud 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.
confirmmust 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.
confirmmust 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.statusisstalewithout a verified snapshot for 2 hours,not-enabledfor 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).
evictsnames the on-demand snapshot this one pushes out of the 10 kept. The snapshot ispendinguntil 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 listdcloud 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 listdcloud 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:PassRoleormonitoring:PutMetricAlarminstead, 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:PassRoleormonitoring:PutMetricAlarmormonitoring:DeleteAlarmsinstead, 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 listdcloud 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:CreateAccessKeyinstead, 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:UpdateProjectinstead, 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>andpermissions: id-token: writerequests 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 listdcloud 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:PutTargetsoriam:PassRoleoriam:GetAuditLogsinstead, 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:EnableRuleorevents:DisableRuleorevents:PutTargetsorevents:RemoveTargetsoriam:PassRoleoriam:GetAuditLogsinstead, 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 listdcloud 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:DescribeEventBusoriam:GetAuditLogsinstead, 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:GetAuditLogsinstead, 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:GetAuditLogsinstead, 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:GetAuditLogsinstead, 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 catalogdcloud 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:GetAuditLogsinstead, 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 listdcloud 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:MakeFunctionPublicinstead, 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:MakeFunctionPublicinstead, 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:UseOpenEgressorecr:PullImageorsandbox:ExposePortorsandbox:ExposePublicPortinstead, 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:ExecCommandorsandbox:ReadFilesorsandbox:WriteFilesorsandbox:StartTerminalinstead, 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:ExposePublicPortinstead, 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 listdcloud 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:PullImageorsandbox:UseOpenEgressinstead, 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:PullImageinstead, 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 getdcloud 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 deletedcloud 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 listdcloud 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.
publicis 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-bucketsArguments, 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 }.
availableis 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> --enabledArguments, 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> --enabledArguments, 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 |
- The same rules
aws s3api put-bucket-corswrites over the S3 API, for every bucket. The gateway answers browser preflights (OPTIONS) from them and adds Access-Control-* headers to matching responses, presigned URLs included. Example: --rules '{"allowedOrigins":["https://app.example.com"],"allowedMethods":["GET","PUT"],"allowedHeaders":["*"],"exposeHeaders":["ETag"],"maxAgeSeconds":3000}'
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 listdcloud 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 listdcloud 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.statusgoes 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,
forkedFromRepoIdset); every branch and tag is copied by a job, whose progress isimportState. 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.rejectedRefswithlastStatus: failedinstead 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) andcommitsInYear;pullRequestscounts 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 |
linesis the text split into lines;htmlone 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;
canReadSourcein 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: nullclears the description. Refused for a merged pull request and in an archived repository. Sends apull_requestwebhook withaction: 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.autoMergeBlockedReasonon 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> --viewedArguments, 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> --resolvedArguments, 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 buildsews-readonly-queue/<base>/pr-<n>-<sha>with every pull request ahead of it, runsmerge_groupCI 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 firesreleasewith created, published and released (or prereleased); a draft only created. Answers the release andrunIdsof 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. policyis the first of .github/SECURITY.md, SECURITY.md, docs/SECURITY.md on the default branch (null without git:PullRepository).dependencyScanis 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 overviewdcloud 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.
gapslists 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-fixshows 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
getshows 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 listdcloud 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-installationsdcloud 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> --enabledArguments, 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 listdcloud 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:UseSecretSourceinstead, 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:SyncSecretinstead, 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 listdcloud 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;
defaultin 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_keyfor 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 |
notCoveredlists 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 listdcloud 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
stalewhen that is older than the active version. Last reads need secrets:GetSecretAccessLog; without itreadsis "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:UseSecretSourceinstead, 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, orreference: { ref: "op://vault/item/field", source? }for a synced secret. Withoutsource(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:
resultssays 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 --grouporsecrets 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 providersdcloud secrets sources list
List connected sources with sync status (never the credential)
GET /secrets/api/sources — IAM secrets:ListSecretSources — read
dcloud secrets sources listdcloud 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:CreateSecretinstead, 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:CompareSecretValuesinstead, decided by server-side state the caller cannot see. A caller needs all of them to be sure of not getting a 403. fromandtoare environment ids ordefault(the value every environment falls back to). Equality is computed server-side and needs secrets:CompareSecretValues on both secrets (audited); otherwise the row isunknownwith 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:CreateSecretorsecrets:RotateSecretorsecrets:UseSecretSourceinstead, 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 withsuggestedReference(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:CreateSecretorsecrets:RotateSecretorsecrets:UseSecretSourceorsecrets:CompareSecretValuesinstead, 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: confirmsuggestedReferenceand send it as the item’sreference) or blocked (error). Run the dry run, then the same items withoutdryRun. 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:CompareSecretValuesinstead, 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].resolutionis own, default (no own secret: the Default value) or missing;promotableFromnames an earlier environment that has it.compare=1adds avalueClassletter 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 listdcloud 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 getdcloud 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.
imageslists every image (the first 5,000;totalImagescounts all) withaction,reasonandby, 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) andoffset. The response carrieshasMore; one row per tag, plus one row withtag: nullfor 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) andoffset; the response carrieshasMore. 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-quotadcloud 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 getdcloud 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.iothis 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 listdcloud 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 theregistryconsumer) 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-policydcloud 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-policydcloud 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-tokensdcloud 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 listdcloud 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 createdcloud npm tokens list
List your own live npm tokens (never their values)
GET /npm/api/tokens — IAM npm:GetAuthorizationToken — write
dcloud npm tokens listdcloud 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 getdcloud 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 previewdcloud 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 getdcloud 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 itsgranularityto 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 inpartialwhere 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 withpricesFromandsources; a provider without a verified price list says so inmissing. 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, …) isnotComparedEur. 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 creditsdcloud 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.
currentHouris null when the resource was not metered in the last two hours (stopped, deleted, or storage).capshas one row per machine (a 3-node database has three): charged this month against its monthly cap; oncereached, 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.
operationis 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, …) andbodythe 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 markedbilled: falsefor things that are not metered yet. Allowed with billing:EstimateCost or with the operation’s own action.ews <command> --dry-runprints 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 getdcloud 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 listdcloud 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.
effectiveRecipientsresolves 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. Withagain: trueit 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 listdcloud 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.rangeis 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.
rulesspells 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 carriesresult), 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 toprevious, 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 listdcloud 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) orgeneratePassword: true; a generated one is returned once ingeneratedPassword. Users of typeuseronly.
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: falseends 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 getdcloud 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: falseturns 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 deletedcloud 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 getdcloud 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 listdcloud 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 listdcloud 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 listdcloud 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 listdcloud 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 listdcloud 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 |
documentis 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:SimulateCustomPolicyinstead, 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).contextsets 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:AttachGroupPolicyoriam:AttachRolePolicyinstead, 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:DetachGroupPolicyoriam:DetachRolePolicyoriam:DeletePolicyinstead, 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:expiresAtis in the response. WithscopePolicythe 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 listdcloud 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
noneattaches no preset policy;groupId/roleIdadd the person to a group of this organization or give them a role when they accept.
dcloud iam invitations link
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 digestsdcloud 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-settingsdcloud 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 listdcloud 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 listdcloud 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> --enabledArguments, 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 };noteslists 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.
statusis online, offline or disabled;lastSeenAtis 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.
configCommandregisters GitHub’s own runner (./config.sh --url https://git.{root}/{org}[/{repo}] --token …), which then runs GitHub-syntax jobs withruns-on: self-hosted(plus any labels it carries);installCommandinstalls the Deutsche Cloud agent on a Mac. A runner that will hold deploy credentials belongs in a group withprotectedRefsOnly.
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 listdcloud 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 withdcloud 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 needson: workflow_dispatch; an.ews/workflows/file needson.manual. The file is read at the tip ofref(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 ascursorfor 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-orgdcloud 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.
reviewersare 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 listdcloud 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
nextasafterto tail it while it runs;doneis true once the builder reported itsexitCodeor 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:GetSecretValueordeploy:DeployAppinstead, 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:CreateSecretorsecrets:RotateSecretorsecrets:UseSecretSourceorsecrets:GetSecretValueordeploy:DeployAppinstead, 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
errorinstead ofconnection. No password is returned: read it withdcloud 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:ModifyDBInstanceordeploy:DeployAppinstead, 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:ModifyDBInstanceordeploy:DeployAppinstead, 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:ModifyCacheClusterordeploy:DeployAppinstead, 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:GetSecretValueordeploy:DeployAppinstead, 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:GetSecretValueordeploy:DeployAppinstead, 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:GetSecretValueordeploy:DeployAppinstead, 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:UpdateProjectordeploy:DeployAppinstead, 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:GetSecretValueinstead, 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 resourcesdcloud 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 listdcloud 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
confirmationslocations 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 listdcloud 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 listdcloud 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;
unreachablelists what the app uses that a gateway in its VPC cannot reach. With no gateway yet,gatewaysays what creating one costs — create it withdcloud 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 usedcloud 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 listdcloud 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.
asnis 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}$/ |
machineRouteCommandis 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 listdcloud 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
updateandadd-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 listdcloud 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 connectdoes 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 listdcloud 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-recordswrites 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 getdcloud 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 |
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 |
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 keysdcloud 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
bulksets 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 listdcloud 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). Withproject(a project slug), only the resources its tags select, plus what those apps use, marked inScope=false; that needs tags:ListProjects. Each app listsusesasdatabase:<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:MoveResourceortags:ManageTagPolicyinstead, 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 getdcloud 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).
autois 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 getdcloud 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 listdcloud 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 listdcloud 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 listdcloud 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 listdcloud 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 listdcloud 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.
projectlimits 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 listdcloud 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:AcceptCriticalFindinginstead, 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