API & CLI

Sign in from a terminal, and drive the platform from anything that speaks HTTP.

This console is a client of an HTTP API, and that API is described in one place. The ews command line is generated from that description rather than written against it, so the 1185 operations below are the routes the console itself calls: same arguments, same permissions, same audit trail.

Install the CLI

This console serves the CLI built against its own API, as one file for Linux and macOS on x64 and arm64, with nothing else to install. The installer picks the build for your machine, checks its SHA-256 before installing it, and makes this console the CLI’s default, so it works the same for a self-hosted Deutsche Cloud.

Install

curl -fsSL https://console.platform-development.deutschecloud.app/api/cli/install.sh | sh

Installs to ~/.local/bin. Add `-s -- --system` after `sh` for /usr/local/bin (uses sudo), or `-s -- --dir <dir>`.

Then sign in

dcloud login

Short for `dcloud auth login`.

Later, to match this console again

dcloud upgrade

Reads this console's manifest, verifies the download and replaces itself. The CLI also mentions it, at most once a day, when the console serves a different build.

Every command is listed in the CLI command reference. Without the installer, the files are at /api/cli/manifest: one URL and checksum per platform, plus a single-file build for any machine with Node 20 or later at /api/cli, which is what CI uses.

From source, for contributors

In a checkout of the platform repository, the CLI under cli/ runs straight from its TypeScript, resolving its one dependency from the repository’s node_modules.

Run it from source

npx tsx cli/src/index.ts ec2 instances list

Or build it and put it on PATH

node cli/scripts/build.mjs
cd cli && npm link

cli/package.json declares bin: { ews }, so after linking the short spelling works.

Signing in

A CLI cannot hold a browser session, so it signs in by asking you to approve it in one. This is the device-authorization flow from RFC 8628, and it means a long-lived credential never has to be created by hand, shown on a screen, or moved through a clipboard.

Sign in

dcloud auth login
  1. 1The CLI prints a short code (eight characters, in an alphabet with no 0/O or 1/I to misread) and opens /activate in a browser. If there is no browser (over SSH, in a container), the URL is on screen to open elsewhere.
  2. 2You confirm that code while signed in to the console. Approving binds your identity to the request; the short code authorizes nothing on its own.
  3. 3The CLI, which has been polling, collects an access key exactly once and writes it to ~/.dcloud/credentials.json at mode 0600.

Two lifetimes worth knowing

  • The code expires after 10 minutes. If it does, run dcloud auth login again.
  • The key it produces expires after 90 days. That is the point of getting it this way: a credential sitting on a laptop should not be valid forever.

Somewhere without a browser

Pasting a key is still supported, and is what CI should do. A key supplied this way is whatever you created in the console, including its expiry, or lack of one.

Paste a key instead

dcloud auth login --with-key

Prompts without echoing. --key <id:secret> and --stdin take it non-interactively; --key is visible to `ps`.

Or skip the file entirely

export EWS_ACCESS_KEY=EWS1XXXXXXXXXXXXXXXX:<secret>

Set in the environment, no credentials file is read. This is the CI shape.

dcloud auth whoami asks the API who the stored credential is and which organization it acts in: the server’s answer, not the CLI’s guess.

The shape of a command

Every command

ews <service> <resource> <verb> [arguments] [flags]

Stop at any level to list what comes next: `ews`, `dcloud rds`, `dcloud rds instances`. Add --help to any of them.

$ ews ec2 instances list
GET /ec2/api/instancesec2:DescribeInstancesread

List instances Every command is a service, a resource and a verb, in that order.

$ ews rds instances stop <id>
PATCH /rds/api/instances/{id}rds:StopDBInstancewrite

Stop a running database instance Path parameters are positional, in the order they appear in the path, and are also accepted as flags.

$ ews iam policies create --name ReadOnlyCompute --document @policy.json
POST /iam/api/policiesiam:CreatePolicywrite

Create a customer-managed policy Any string flag takes @path to read the value from a file, or @- for standard input.

$ ews git repositories list --json
GET /git/api/repositoriesgit:ListRepositoriesread

List repositories Add --json for the raw response, for piping into jq or a script.

Arguments are not invented by the CLI either. Path parameters are positional in the order they appear in the path; query and body fields become flags named by kebab-casing the field; the type, the permitted values of an enum and the bounds all come from the operation’s schema, and are checked before anything is sent. Global flags worth remembering: --json for the API’s own response body, and --dry-run to print the request that would be sent and stop.

What you can drive

40 services, 1185 operations. This table is generated from the API description when the page renders, so it is the same tree the CLI walks. Within those services, 82 further routes are deliberately left undescribed and so have no CLI verb; they are still reachable over HTTP.

ews ec2
Compute
instances, nat-gateways, vpcs, subnets, availability-zones, instance-type-offerings, security-groups, key-pairs, sessions, machine-images, snapshot-policies, volumes, snapshots, elastic-ips
76
49
ews autoscaling
Auto Scaling
launch-templates, groups, policies, scheduled-actions, instance-refreshes
25
21
ews lb
Load balancing
load-balancers, targets, services, rules
14
11
ews rds
Postgres
instances, backups, query-insights, data, extensions, server-types, ca-bundle, tls, replication, replication-slots, branches, logins
69
39
ews mysql
MySQL
clusters, snapshots
15
7
ews docdb
Document Database
clusters, users, backups
22
12
ews rabbitmq
RabbitMQ
brokers, users, exports
21
13
ews kafka
Apache Kafka
clusters, topics, users, replications, snapshots
33
21
ews cache
Caches
clusters, snapshots
15
8
ews efs
File Storage
file-systems, snapshots
9
5
ews eks
Kubernetes
versions, clusters, deleted-clusters, snapshots, nodegroups, access-entries, pod-identity-associations, addon-versions, addons
44
27
ews queue
Queues
queues, messages
15
12
ews scheduler
Schedules
schedules
11
5
ews errors
Error Tracking
projects, keys, issues, events, traces, profiles, transactions, releases, alert-rules, queries, release-health, auth-tokens, connections
37
18
ews events
Event bus
buses, rules, archives, replays, patterns
27
12
ews functions
Functions
functions, event-source-mappings
12
8
ews sandbox
Sandboxes
sandboxes, files, ports, pools
20
13
ews cloudshell
Cloud shell
environment, environments
6
4
ews s3
Object Storage
buckets, bucket-objects, bucket-access, bucket-encryption, bucket-remote-copy, bucket-replication, bucket-versioning, bucket-cors, bucket-lifecycle, access-keys, temporary-credentials
53
35
ews git
Git
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
76
ews kms
KMS
ssh-key-pairs, keys
21
15
ews secrets
Secrets
secrets, groups, sources, environments
38
24
ews ecr
Container registry
repositories, lifecycle-policy, expired-images, lifecycle-defaults, images, storage, registry-aliases, pull-through-cache, signing, scan-results, auth
40
24
ews npm
npm registry
packages, tokens, lifecycle-defaults
15
10
ews billing
Billing
summary, costs, estimates, invoices, account, budgets, cost-report, cost-views, savings, budget-proposals, payment-methods
41
16
1–25 of 40
Rows
1 / 2

Whether you may run any of them is the server’s decision. The CLI sends the request under your access key and reports the answer, from the same IAM policy evaluation the console goes through, with the same audit entry on a write.

Access keys

Both paths end in the same credential: Authorization: EWS-ACCESS-KEY EWS1<id>:<secret>. The difference is who created it and how long it lives. A key collected by dcloud auth login expires after 90 days. A key you create in the console does not expire on its own: it is valid until you disable or delete it, which makes it the right shape for a build server and the wrong shape for a laptop.

The secret half is shown once, at creation, and is stored only as a hash. There is no endpoint that reads it back, and nothing to recover if it is lost. Create another and delete the old one.

You cannot manage access keys

Your permissions do not include iam:ListAccessKeys. Sign in with dcloud auth login instead (the device flow mints a key for you without needing that permission), or ask an administrator.

Machine-readable surfaces

The CLI is not the only consumer of the description. Two more are generated from it, so neither can drift from what the console does.

The MCP server exposes one tool per operation, named dcloud_<service>_<resource>_<operation>. Assistants sign in to it with OAuth, so there is no key to paste; Connect an AI assistant has the steps for each app. Headless agents can send the access key header instead.