> ## 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. # Contexts & scoping > How datumctl decides which organization or project a command acts on, and how to switch between them. 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: ```bash theme={null} 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: ```text theme={null} 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: ```bash theme={null} 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: ```bash theme={null} datumctl ctx use ``` Choose an organization or project from the list. This is the easiest way when you do not remember the exact name. ```bash theme={null} # Switch to a project context datumctl ctx use datum/datum-cloud # Switch to an org context datumctl ctx use datum ``` 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: ```text theme={null} ✓ 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: `--organization ` or `--project ` on the command line. These override everything else, but only for that single command. `DATUM_PROJECT` or `DATUM_ORGANIZATION`, if set. Useful in CI or scripts. You cannot set both at once. 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: ```bash theme={null} # 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: Run `datumctl ctx` and look for the `*`. Make sure it points at the org or project that actually contains your resource. An exported `DATUM_PROJECT` or `DATUM_ORGANIZATION` environment variable silently redirects every command. Unset it if it isn't what you want: ```bash theme={null} unset DATUM_PROJECT DATUM_ORGANIZATION ``` Re-run the command with an explicit flag to rule out the active context: ```bash theme={null} datumctl get dnszones --project my-project ``` If the project or organization you expect isn't listed by `datumctl ctx`, refresh the cache — you may have just been granted access: ```bash theme={null} 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](/datumctl/auth/logging-in); to switch between stored accounts, see [Managing accounts & tokens](/datumctl/auth/managing-accounts). ## Related * [Logging in](/datumctl/auth/logging-in) — sign in, verify your identity with `whoami`, and sign out. * [Managing accounts & tokens](/datumctl/auth/managing-accounts) — switch the active user and how each session maps to a context. * [Reading resources](/datumctl/resources/reading) — the `get` and `describe` commands that run against the scope you set here. * [Output formats & scripting](/datumctl/output-and-scripting) — pinning `--organization` and `--project` explicitly and reading `DATUM_PROJECT`/`DATUM_ORGANIZATION` in CI. * [Overview](/datumctl/overview) — how `datumctl` is structured and talks to the Datum API. * `datumctl ctx --help` for the context commands and the `--organization`/`--project` flags.