AI assistant - Datum Cloud Docs

datumctl ai translates natural language into Datum Cloud operations. Ask it a question — “list all DNS zones”, “which projects am I in?” — and the assistant figures out which resources to read and shows you the answer. When it wants to make a change, it always pauses and asks you to confirm first.

The assistant reasons over your resources through a large language model, so you supply your own model API key (Anthropic, OpenAI, or Gemini). Your key and requests go directly to the provider you choose.

Before you start

You need two things:

A logged-in datumctl. The assistant reads and writes real Datum Cloud resources, so you must be authenticated. Run datumctl login first.
A model API key for the Anthropic Console, OpenAI, or Google Gemini.

Quick start

datumctl login

Save a model API key

Store the key once so you don’t have to export it in every shell:

datumctl ai config set anthropic_api_key sk-ant-...

Set a default scope (optional)

Point the assistant at the organization or project you work in most:

datumctl ai config set organization my-org-id

Ask a question

datumctl ai "list all DNS zones"

Asking questions

One-shot questions

Pass your question as an argument to get a single answer and return to your shell:

datumctl ai "how many projects are in my organization?"

You can also pipe a question in on standard input, which is handy in scripts:

echo "list projects" | datumctl ai

When input is piped in (no terminal attached), the assistant answers questions but will not perform any write — mutating actions are skipped because they can’t be confirmed. See The confirmation gate.

Interactive session

Run datumctl ai with no question to start an interactive REPL. The assistant keeps conversation context, so you can ask follow-up questions that build on earlier answers:

datumctl ai --project my-project-id

At the > prompt, type your next question. Type exit or quit (or press Enter on an empty line) to leave the session.

Choosing scope

The assistant needs to know which control plane to operate against. You can set scope three ways, from most to least specific:

Per-invocation flags
Active datumctl context
Saved ai defaults

datumctl ai "list projects" --organization other-org-id
datumctl ai --project my-project-id

If you’ve selected a context with datumctl ctx use, the assistant uses it automatically — no flags needed.

datumctl ai config set organization my-org-id
datumctl ai config set project my-project-id

Scope is resolved in this order: command-line flags → environment variables → active datumctl context → saved ai config defaults. Because the active context wins over saved ai defaults, switching with datumctl ctx use is respected without having to clear your ai config values. This mirrors how every other command resolves scope. A few rules:

--organization and --project are mutually exclusive — set one, not both.
--namespace sets the default namespace for the session (defaults to default).
--platform-wide targets the platform root instead of a single org or project. This is a staff-only mode and can’t be combined with --organization or --project.

If no scope is set at all, the assistant still runs, but without resource tools — it can chat, but can’t read or change anything until you give it an organization or project.

The confirmation gate

Reads and writes are treated very differently:

Read operations run immediately. Listing, getting, and describing resources happen without a prompt.
Write operations always pause for confirmation. Before creating, updating, or deleting anything, the assistant prints a preview of the exact action and asks you to approve it.

The preview shows the tool and the full arguments, then waits for your answer:

--- Proposed action ---
Tool:    ...
Details:
{
  ...
}
-----------------------
Apply changes? [y/N]:

Only an explicit y proceeds; anything else declines.

When datumctl ai is run without an attached terminal (for example, with a piped question or in CI), write operations are automatically declined and skipped. Perform mutations only from an interactive terminal session.

Built-in tools

Behind the scenes the assistant works through a fixed set of tools scoped to the current organization or project. Read tools run on their own; the two write tools are gated by the confirmation prompt above.

Tool	What it does	Gated?
`list_resource_types`	Lists the Datum Cloud resource types available in the current context	No
`get_resource_schema`	Returns the schema for a resource type so the assistant knows its fields	No
`list_resources`	Lists resources of a given type	No
`get_resource`	Retrieves a single resource by kind and name	No
`validate_manifest`	Validates a manifest with a server-side dry run, without persisting changes	No
`apply_manifest`	Creates or updates a resource by applying a manifest (upsert)	Yes
`delete_resource`	Deletes a resource by kind and name	Yes
`change_context`	Switches the active organization, project, or namespace for the session	No

Before proposing a write, the assistant can run validate_manifest to check your change with a server-side dry run — the same safety net as datumctl apply --dry-run=server — so you see problems before you approve anything.

Configuration

Saved settings provide defaults for every datumctl ai invocation, so you don’t have to repeat flags or export environment variables. Manage them with datumctl ai config:

# Set a value
datumctl ai config set organization my-org-id

# Show the current configuration (API keys are redacted)
datumctl ai config show

# Remove a value
datumctl ai config unset organization

Configuration keys

Key	Purpose
`organization`	Default organization ID (overridden by `--organization`)
`project`	Default project ID (overridden by `--project`)
`namespace`	Default namespace (defaults to `default`)
`provider`	LLM provider: `anthropic`, `openai`, or `gemini`
`model`	Model override, e.g. `claude-sonnet-4-6`, `gpt-4o`, `gemini-2.0-flash`
`max_iterations`	Agentic loop iteration cap (default `20`)
`anthropic_api_key`	Anthropic API key
`openai_api_key`	OpenAI API key
`gemini_api_key`	Gemini API key

Run datumctl ai config show to print the resolved config path along with your current values; API keys are shown redacted.

Precedence and environment variables

Flags always win over config file values for a single invocation.
API keys can also come from environment variables, which override any key stored in the config file:
```
export ANTHROPIC_API_KEY=sk-ant-...
export OPENAI_API_KEY=...
export GEMINI_API_KEY=...
```

This lets you keep a default key in the config file for everyday use and temporarily override it per shell when needed.

Choosing a provider and model

You don’t have to set a provider explicitly — the assistant selects one using this order:

Model name prefix. claude-* → Anthropic, gpt-* / o1* / o3* → OpenAI, gemini-* → Gemini.
An explicit provider setting, if you set one.
Whichever API key is available (environment variable first, then config file).

Set a model per invocation with --model, or save one as a default:

datumctl ai config set model claude-sonnet-4-6
datumctl ai "list dnszones" --model gpt-4o

Each provider has a sensible default model if you don’t pick one: claude-sonnet-4-6 for Anthropic, gpt-4o for OpenAI, and gemini-2.0-flash for Gemini.

Next steps

Logging in — authenticate datumctl before your first question.
MCP server — prefer a graphical AI client? Connect Claude Desktop, Cursor, or another MCP-aware app to the Datum MCP server.
Datum MCP — install the standalone MCP server and get its full tool catalog.
Contexts & scoping — how scope resolution decides which organization or project the assistant operates against.
Reading resources — the get and describe commands the assistant runs on your behalf.
datumctl overview — new to the CLI? See how datumctl is structured.

​Before you start

​Quick start

​Asking questions

​One-shot questions

​Interactive session

​Choosing scope

​The confirmation gate

​Built-in tools

​Configuration

​Configuration keys

​Precedence and environment variables

​Choosing a provider and model

​Next steps

Before you start

Quick start

Asking questions

One-shot questions

Interactive session

Choosing scope

The confirmation gate

Built-in tools

Configuration

Configuration keys

Precedence and environment variables

Choosing a provider and model

Next steps