Skip to main content
This guide takes you from nothing installed to running your first command against Datum Cloud. Follow the steps in order; it takes a few minutes.
Prefer a one-click download? Download a pre-built binary from the GitHub Releases page.
1

Install datumctl

Choose the method that fits your platform.
If you use Homebrew, install datumctl from the official Datum Cloud tap:
Later, upgrade with brew upgrade datumctl.
Verify the install:
This prints the installed client version.
2

Log in

Authenticate with Datum Cloud. datumctl uses OAuth 2.0 with PKCE and stores your credentials securely in your system keyring — there are no API keys to manage.
This opens your browser to complete sign-in, then discovers the organizations and projects you can access. For the full sign-in flow — the browser and device-code flows, whoami, and signing out — see Logging in; for juggling several accounts see Managing accounts & tokens.
On a headless machine you sit at, such as an SSH session or a container with no browser, add --no-browser to authenticate with a device-code flow instead. For unattended jobs such as CI, use a service account and datumctl login --credentials instead, because the device-code flow needs a person to approve it:
To sign in against a custom environment — such as a self-hosted Datum Cloud deployment — point at its auth server with --hostname, for example datumctl login --hostname auth.example.com.
3

Select your working context

A context is the organization or project that commands target by default, so you do not have to pass --organization or --project every time. For the full picture of how scope is resolved, read Contexts & scoping.Right after login, datumctl shows the organizations and projects you can access and prompts you to pick one interactively.To see your contexts again at any time:
To switch contexts — either interactively or by name using the org or org/project format:
4

Run your first command

List the organizations you belong to. This command works without a context selected:
Once a context is set, list resources in it — for example the projects in your organization:
Results are shown as a table by default. Add -o json or -o yaml for scripting or inspection (see Output formats & scripting), and use datumctl api-resources to discover every resource type you can manage.

​
Keep datumctl up to date

To upgrade to the latest release, run the following command:
To upgrade automatically, run datumctl auto-update enable. When a newer release is available, datumctl then upgrades itself the next time you run any command, and re-runs that command on the new version. To go back to a warning only, run datumctl auto-update disable, and to see the current setting, run datumctl auto-update status. If you installed datumctl with a package manager such as Homebrew, you can upgrade it there instead. Plugins update separately. To upgrade every plugin you have installed, run datumctl plugin upgrade --all.

​
Get help from the CLI

datumctl documents itself. These docs explain how to use it; the built-in help is the full, current list of commands and flags for the version you have installed. To list every command, grouped by area (Authentication, Context, Resource Management, and more), run the following command:
To see a command’s flags and examples, add --help after it. For example:
Commands that come from plugins work the same way. After you install a plugin, run its help to see what it adds:
To check which version you are running, run datumctl version.

​
Next steps

You are now installed, authenticated, and pointed at a context. From here you can explore what else the CLI can do.

Contexts & scoping

Understand how commands choose an organization or project, and how to switch between them.

Reading resources

List, retrieve, and inspect Datum Cloud resources with get and describe.

Discovering resources & schemas

Find which resource types exist and inspect their fields before you author manifests.

Output formats & scripting

Machine-readable output, structured errors, and wrapping datumctl in CI and agents.

Interactive console

Browse and inspect resources in a full-screen, keyboard-driven UI.

Using plugins

Extend datumctl with additional commands from a plugin catalog.

Managing accounts

Manage multiple accounts, switch users, sign out, and print access tokens.

Overview

Understand how datumctl is structured and how it talks to Datum Cloud.
Last modified on October 23, 2026