Skip to main content
Almost every datumctl command runs against a single scope — either one organization or one project inside that organization. Understanding how datumctl chooses that scope is the key to getting the results you expect. If a command returns nothing or the wrong resources, the cause is almost always the active scope.
In short: datumctl remembers an active context (an org or a project). Any command uses that context unless you override it for a single command with --organization or --project.

​
The scope model

Datum Cloud is organized as a two-level hierarchy:
  • Organizations are the top level. You belong to one or more organizations.
  • Projects live inside an organization. Most day-to-day resources (DNS zones, networking, and so on) belong to a project.
A context captures one point in that hierarchy:
  • An org context points at an organization (for example, resources that live at the organization level).
  • A project context points at a specific project inside an organization.
datumctl discovers the organizations and projects you can access from the API and stores them locally as a list of contexts. One of them is the active context — the scope commands use by default.

​
Listing your contexts

Run datumctl ctx (alias: datumctl context) to see every context available to your active user: 
datumctl ctx
This prints a table with the display name, the reference you use to select the context, the type (org or project), and a * marking the current active context. Projects are nested under their organization: 
Display Name                    Name                  Type     Current
Datum Technology, Inc           datum                 org
  Datum Cloud                   datum/datum-cloud     project  *
  Staging                       datum/staging         project
The Name column is the reference you pass to datumctl ctx use: a bare organization ID for an org context (datum), or org/project for a project context (datum/datum-cloud).
datumctl ctx list (alias datumctl ctx ls) prints the same table. Running datumctl ctx with no subcommand is the shortcut most people use.

​
Keeping the list current

The context list is cached locally so listing is instant. When you run datumctl ctx and the cache is more than an hour old, datumctl refreshes it from the API automatically before printing. To force a refresh at any time — for example, right after you have been granted access to a new project — use the --refresh flag: 
datumctl ctx --refresh
--refresh re-runs discovery using your existing session; it does not require you to log in again. There is no separate refresh subcommand — refreshing is a flag on datumctl ctx.

​
Switching the active context

Use datumctl ctx use to change which context is active. You can name the context directly, or run it with no argument to pick from an interactive list: 
datumctl ctx use
Choose an organization or project from the list. This is the easiest way when you do not remember the exact name.
You can identify a context by its resource ID (datum/datum-cloud) or by its display name (for example, the human-friendly project name shown in the table). Resource IDs always take precedence, and a display name is only accepted when it matches exactly one context. If a name is ambiguous or not found, datumctl tells you and suggests running datumctl ctx to see the available choices. On success you’ll see a confirmation of the new scope: 
✓ Switched to project Datum Cloud in Datum Technology, Inc (datum/datum-cloud)
The active context persists across commands and terminal sessions until you switch again.

​
How scope is resolved for each command

When you run a command, datumctl determines its scope by checking these sources in order and using the first one that applies:
1

Per-command flags

--organization <org> or --project <project> on the command line. These override everything else, but only for that single command.
2

Environment variables

DATUM_PROJECT or DATUM_ORGANIZATION, if set. Useful in CI or scripts. You cannot set both at once.
3

The active context

Whatever datumctl ctx use last selected. If the active context is a project, commands run at project scope; if it is an org context, they run at organization scope.
If none of these provide a scope, datumctl falls back to your personal user scope.
--project, --organization, and --platform-wide are mutually exclusive — you can supply at most one. Likewise, DATUM_PROJECT and DATUM_ORGANIZATION cannot both be set. datumctl returns an error rather than guessing when the inputs conflict.

​
Overriding scope for a single command

The flags let you target a different org or project without changing your active context: 
# Run this one command against a different project
datumctl get dnszones --project other-project

# Run against an organization
datumctl get projects --organization datum
The next command with no flag goes back to using your active context.
For advanced access to the platform root rather than a specific project or organization, an opt-in --platform-wide flag is also available. Most users never need it.

​
When a command returns nothing

An empty result is almost always a scope mismatch, not an error. The resource you’re looking for probably lives in a different project or organization than the one your command targeted. Work through this checklist:
1

Confirm the active context

Run datumctl ctx and look for the *. Make sure it points at the org or project that actually contains your resource.
2

Check for an override you forgot about

An exported DATUM_PROJECT or DATUM_ORGANIZATION environment variable silently redirects every command. Unset it if it isn’t what you want:
unset DATUM_PROJECT DATUM_ORGANIZATION
3

Target the right scope explicitly

Re-run the command with an explicit flag to rule out the active context:
datumctl get dnszones --project my-project
4

Refresh if the context is missing

If the project or organization you expect isn’t listed by datumctl ctx, refresh the cache — you may have just been granted access:
datumctl ctx --refresh
Remember that a project’s resources aren’t visible from its parent org context (and vice versa). Switching to the correct project scope with datumctl ctx use org/project resolves most “nothing found” surprises.

​
Contexts and users

Contexts are tied to the user you’re authenticated as. Each stored user session has its own set of discovered contexts. When you switch users, your active context follows that user’s most recently used context. To log in, see Logging in; to switch between stored accounts, see Managing accounts & tokens.
  • Logging in — sign in, verify your identity with whoami, and sign out.
  • Managing accounts & tokens — switch the active user and how each session maps to a context.
  • Reading resources — the get and describe commands that run against the scope you set here.
  • Output formats & scripting — pinning --organization and --project explicitly and reading DATUM_PROJECT/DATUM_ORGANIZATION in CI.
  • Overview — how datumctl is structured and talks to the Datum API.
  • datumctl ctx --help for the context commands and the --organization/--project flags.
Last modified on July 2, 2026