> ## Documentation Index
> Fetch the complete documentation index at: https://datum.net/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Install

> Install datumctl on macOS, Linux, or Windows, log in to Datum Cloud, choose an organization or project, and run your first command.

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.

> [!NOTE]
>
> Prefer a one-click download? Download a pre-built binary from the [GitHub Releases page](https://github.com/datum-cloud/datumctl/releases/latest).

**1. Install datumctl**

Choose the method that fits your platform.

**Homebrew (macOS)**

If you use [Homebrew](https://brew.sh/), install `datumctl` from the official Datum Cloud tap:

```bash theme={null}
# Tap the Datum Cloud formula repository (only needs to be done once)
brew tap datum-cloud/homebrew-tap

# Trust the datumctl formula
brew trust --formula datum-cloud/homebrew-tap/datumctl

# Install datumctl
brew install datumctl
```

Later, upgrade with `brew upgrade datumctl`.

**Pre-built binaries**

Download a pre-built binary from the [GitHub Releases page](https://github.com/datum-cloud/datumctl/releases/latest):

1. Find the archive for your OS and architecture (for example `datumctl_Darwin_arm64.tar.gz`, `datumctl_Linux_x86_64.tar.gz`, or `datumctl_Windows_amd64.zip`).
2. Download and extract it.
3. Move the `datumctl` (or `datumctl.exe`) binary onto your `PATH` — for example `/usr/local/bin` on Linux/macOS.
4. On Linux/macOS, make sure it is executable: `chmod +x /path/to/datumctl`.

**Nix**

If you use [Nix](https://nixos.org/), install `datumctl` from its official flake:

```bash theme={null}
nix profile install github:datum-cloud/datumctl
```

For a one-off invocation without adding `datumctl` to your profile, use `nix run github:datum-cloud/datumctl` instead.

**Windows**

Download the latest Windows release from the [GitHub Releases page](https://github.com/datum-cloud/datumctl/releases/latest), extract it, and move `datumctl.exe` to a directory such as `C:\\Tools\\datumctl\\`.

Add that directory to your `PATH`, then open a new terminal.

**Build from source**

Install [Go](https://go.dev/dl/) 1.21 or later and Git, then clone and build `datumctl`:

```bash theme={null}
git clone https://github.com/datum-cloud/datumctl.git
cd datumctl
go build -o datumctl .
```

Move the resulting `datumctl` binary onto your `PATH`.

Verify the install:

```bash theme={null}
datumctl version
```

This prints the installed client version.

**2. Log in**

Authenticate with Datum Cloud. `datumctl` uses [OAuth 2.0](https://oauth.net/2/) with [PKCE](https://oauth.net/2/pkce/) and stores your credentials securely in your system keyring — there are no API keys to manage.

```bash theme={null}
datumctl login
```

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](https://datum.net/docs/datumctl/auth/logging-in.md); for juggling several accounts see [Managing accounts & tokens](https://datum.net/docs/datumctl/auth/managing-accounts.md).

> [!NOTE]
>
> 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](https://datum.net/docs/datumctl/auth/service-accounts.md) and `datumctl login --credentials` instead, because the device-code flow needs a person to approve it:
>
> ```bash theme={null}
> datumctl login --no-browser
> ```
>
> 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](https://datum.net/docs/datumctl/contexts-and-scoping.md).

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:

```bash theme={null}
datumctl ctx
```

To switch contexts — either interactively or by name using the `org` or `org/project` format:

```bash theme={null}
# Interactive picker
datumctl ctx use

# Switch to a specific project context
datumctl ctx use <org-id>/<project-id>
```

**4. Run your first command**

List the organizations you belong to. This command works without a context selected:

```bash theme={null}
datumctl get organizations
```

Once a context is set, list resources in it — for example the projects in your organization:

```bash theme={null}
datumctl get projects --organization <org-id>
```

Results are shown as a table by default. Add `-o json` or `-o yaml` for scripting or inspection (see [Output formats & scripting](https://datum.net/docs/datumctl/output-and-scripting.md)), and use `datumctl api-resources` to [discover every resource type you can manage](https://datum.net/docs/datumctl/discovering-resources.md).

## Keep datumctl up to date

To upgrade to the latest release, run the following command:

```bash theme={null}
datumctl auto-update
```

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:

```bash theme={null}
datumctl --help
```

To see a command's flags and examples, add `--help` after it. For example:

```bash theme={null}
datumctl get --help
datumctl login --help
```

Commands that come from plugins work the same way. After you [install a plugin](https://datum.net/docs/datumctl/plugins/using-plugins.md), run its help to see what it adds:

```bash theme={null}
datumctl compute --help
```

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](https://datum.net/docs/datumctl/contexts-and-scoping.md)**
>
> Understand how commands choose an organization or project, and how to switch between them.

> **[Reading resources](https://datum.net/docs/datumctl/resources/reading.md)**
>
> List, retrieve, and inspect Datum Cloud resources with get and describe.

> **[Discovering resources & schemas](https://datum.net/docs/datumctl/discovering-resources.md)**
>
> Find which resource types exist and inspect their fields before you author manifests.

> **[Output formats & scripting](https://datum.net/docs/datumctl/output-and-scripting.md)**
>
> Machine-readable output, structured errors, and wrapping datumctl in CI and agents.

> **[Interactive console](https://datum.net/docs/datumctl/console.md)**
>
> Browse and inspect resources in a full-screen, keyboard-driven UI.

> **[Using plugins](https://datum.net/docs/datumctl/plugins/using-plugins.md)**
>
> Extend datumctl with additional commands from a plugin catalog.

> **[Managing accounts](https://datum.net/docs/datumctl/auth/managing-accounts.md)**
>
> Manage multiple accounts, switch users, sign out, and print access tokens.

> **[Overview](https://datum.net/docs/datumctl/overview.md)**
>
> Understand how datumctl is structured and how it talks to Datum Cloud.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.