dtctl is the Dynatrace command-line tool.
It brings your Dynatrace platform one command away, so you can manage workflows, dashboards, DQL queries, SLOs, and more from your terminal, from a script, or from an AI agent. It's for anybody who wants to use Dynatrace platform functionality via CLI, set up CI/CD pipelines that read or write Dynatrace data, or integrate Dynatrace with AI coding assistants.
This page provides an introduction to dtctl. For more information, see the relevant pages in the dtctl GitHub repository:
dtctl for various use cases.To use dtctl, you need:
An active Dynatrace SaaS environment running Latest Dynatrace.
OAuth or token credentials with the required scopes for your use case.
dtctl is compatible with Dynatrace SaaS environments only.
If you have a Dynatrace Managed environment, use dtmgd instead, because it's designed specifically for Managed environments.
You can install dtctl, set up authentication, verify connectivity, and run command examples for common use cases.
dtctlInstall dtctl with a single command.
This page describes how to install dtctl on macOS, Linux, or Windows.
For binary downloads, building from source, and shell completion setup for bash, Zsh, Fish, and PowerShell, see the complete installation guide in the GitHub repository.
Choose the method that fits your platform.
macOS and Linux
With Homebrew (also sets up shell completions):
> brew install dynatrace-oss/tap/dtctl
Without Homebrew:
> curl -fsSL https://raw.githubusercontent.com/dynatrace-oss/dtctl/main/install.sh | sh
Windows PowerShell
irm https://raw.githubusercontent.com/dynatrace-oss/dtctl/main/install.ps1 | iex
Restart your terminal afterward so the updated PATH takes effect.
Verify the binary is on your PATH.
> dtctl version
The output will show the dtctl version, relevant Git commit, and date that the binary was built.
You can authenticate via OAuth or platform tokens, and also pass credentials through environment variables:
DTCTL_ENVIRONMENT, DTCTL_TOKEN) without running interactive commands. Multi-environment setup, safety levels, and per-project config files are covered in the configuration reference.To authenticate via OAuth:
Find your environment URL. Your environment URL has the form https://<environment-id>.apps.dynatrace.com.
Log in and create a context. A context names an environment and its credentials so you can switch between them later.
> dtctl auth login --context my-env --environment "https://abc12345.apps.dynatrace.com"
Complete the login in your browser. dtctl opens your browser for SSO login and stores the returned tokens in your OS keyring.
Use dtctl doctor to check that dtctl can reach the environment, that your credentials are valid, and that your token carries the scopes common commands need.
> dtctl doctor
An example output is shown below.
[OK] dtctl version 0.39.0 (commit: 2aae6cc, built: 2026-09-18T21:31:33Z)[OK] Configuration /Users/alex.example/Library/Application Support/dtctl/config[OK] Current context my-env (environment: https://abc12345.apps.dynatrace.com, safety: readwrite-all)[OK] Environment URL URL pattern looks correct[OK] Token storage macOS Keychain[OK] Token retrieved from keyring (macOS Keychain) (eyJh...Jz4g)[OK] OAuth session access expires in 4m54s; refresh token present[OK] Connectivity https://abc12345.apps.dynatrace.com is reachable[OK] Authentication authenticated as c4f3c4f3-c4f3-c4f3-c4f3-c4f3c4f3c4f3 (alex.example@email.com)
dtctl uses a predictable verb-noun syntax inspired by kubectl.
If you know kubectl, you already know how dtctl is organized, and so does any AI agent trained on the same conventions.
--agent) and a machine-readable command catalog (dtctl commands) that let AI agents operate Dynatrace reliablydtctl operates on the resource types below. The resource reference, with supported operations, flags, output, required token scopes, and examples, is available in the linked GitHub repository.
| Resource | What you do with it |
|---|---|
Automate tasks: list, create, edit, run, and inspect workflow executions and their logs. | |
Run Dynatrace Query Language against Grail, with template variables, live mode, and large-result spill. | |
Create, edit, share, version, and restore dashboards and notebooks. | |
Define, apply, and evaluate service-level objectives. | |
Read schemas and get, create, update, and delete Settings objects. | |
Connect and monitor AWS, Azure, and Google Cloud accounts. | |
Create, manage, and watch Grail storage buckets. | |
Manage reusable filter segments for queries and dashboards. | |
Manage lookup tables, with CSV auto-detection on apply. | |
Manage Extensions 2.0 and Hub extensions and their monitoring configurations. | |
Discover and run app functions and intents, and open deep links into apps. | |
Run Davis statistical analyzers on your data. | |
Chat with Dynatrace Assist, convert natural language to DQL, and search documents. | |
Create, edit, and manage anomaly detectors. | |
Set breakpoints, filter workspaces, and decode snapshots. | |
Manage platform documents and restore items from trash. | |
Create, describe, and delete EdgeConnect configurations. | |
Get, describe, delete, and watch platform notifications. | |
Explore the APIs an environment publishes and inspect individual operations. | |
Create, list, and delete account platform tokens. | |
Look up users and groups. |
dtctl is built to be operated by AI coding agents as well as people. It exposes a structured output mode, auto-detects agent environments, ships a machine-readable command catalog, and bundles an installable Agent Skill.
The --agent flag (short form -A) wraps every response in a structured JSON envelope with an ok flag, a result payload, stable error codes, and follow-up suggestions. This lets an agent parse responses, branch on errors, and pick a next action without scraping human-readable text. Agent mode also implies --plain, so there are no colors, prompts, or spinners.
dtctl enables agent mode automatically when it detects a known agent environment, such as Claude Code, GitHub Copilot, Cursor, or OpenCode, based on environment variables those tools set. Use --no-agent to force human-readable output.
To bootstrap an agent's knowledge of the command surface, use the built-in catalog:
> dtctl commands # minimal overview of verbs, resources, and subcommands> dtctl commands --brief -o json> dtctl commands --full -o json
You can also use dtctl inventory, which answers "what is there to query?".
dtctl inventory probes the current environment read-only for fetchable data, buckets, segments, and capabilities. For more information, see Use cases.
dtctl ships an agent skill that teaches AI assistants how to use dtctl and Dynatrace. Install it with dtctl itself or through the skills registry:
> dtctl skills install # auto-detects your AI agent> dtctl skills install --for claude # or specify the agent> dtctl skills install --global # user-wide installation
> npx skills add dynatrace-oss/dtctl
The skill is compatible with GitHub Copilot, Claude Code, OpenAI Codex CLI, Cursor, Kiro, Junie, OpenCode, and other Agent Skills-compatible tools. For the full JSON envelope contract and detection details, see the AI agent mode documentation and AI agent skills documentation, plus the skills directory in the GitHub repository.
The examples below span several resource types.
Output is shown in its default table form unless a structured format is requested.
Add -o json, -o yaml, -o csv, or --agent to any command for machine-readable output.
If a command fails with an authentication or permission error, run dtctl doctor first.
It pinpoints whether the problem is connectivity, an expired or missing login, or an insufficient token scope, and prints the next step to take. Add dtctl auth whoami to confirm which identity is active, and --check-scopes on any command to see the scopes it requires without running it.
> dtctl get workflowsID NAME STATE LAST RUNwf-abc123 Daily Health Check enabled 2026-09-03 06:00wf-def456 Release Gate enabled 2026-09-03 12:15
> dtctl query "fetch logs | limit 10"TIMESTAMP LOGLEVEL CONTENT2026-09-03 12:14:59 ERROR Connection reset by peer2026-09-03 12:14:58 INFO Request completed in 42ms
> dtctl get dashboards -o json{"dashboards": [{ "id": "dash-001", "name": "Service overview", "owner": "team-a" }]}
> dtctl apply -f workflow.yaml --dry-run+ workflow "Nightly backup" would be createdtrigger: schedule (0 2 * * *)
> dtctl inventoryBUCKETS 12SEGMENTS 8ENTITY TYPES HOST, SERVICE, PROCESS_GROUP, ...CAPABILITIES logs: present, metrics: present, spans: present
> dtctl exec copilot nl2dql "error logs from the last hour"fetch logs| filter loglevel == "ERROR"| filter timestamp > now() - 1h
To get structured output for scripts and agents, do not parse the table output.
Request -o json or --agent and read the fields directly.
See output formats for the full set of formats and the agent envelope.
This section provides a short reference for all dtctl flags and required environment variables.
For complete reference documentation, see the command reference in the GitHub repository.
These flags apply to every dtctl command.
| Flag | Description |
|---|---|
| Agent output mode: wrap output in a structured JSON envelope with metadata. |
| Disable auto-detected agent mode and return human-readable output. |
| Output format: |
| Apply a jq filter to structured output. Non-structured formats are auto-promoted to JSON. |
| Plain output for machine processing: no colors and no interactive prompts. |
| Use a specific context for this invocation. Reads |
| Config file to use. Searches for |
| Print what would be done without doing it. |
| Check that the active token has the scopes this command requires, then exit without running it. |
| Paginate through all results in chunks of this size. |
| Verbose output. Use |
| Enable debug mode with full HTTP request and response logging. Equivalent to |
dtctl reads the following environment variables. Use them to configure dtctl without interactive commands, which is convenient for containers and CI/CD.
| Variable | Purpose |
|---|---|
| Environment URL to use when no context is configured interactively. |
| Platform token to authenticate with when no context is configured interactively. |
| Environment URL placeholder referenced by |
| Platform token placeholder referenced by |
| Account API token for Account Management operations, such as platform tokens. |
| Account UUID for account-scoped operations. |
| Context to use for this invocation. Never persisted. |
| Explicit, trusted config file path. Bypasses auto-discovery and honors aliases and apply hooks. |
| Command profile to activate, which limits the exposed command surface. |
| Default output format when |
| Large-result spill mode for |
| Directory for spilled query results. |
| Set to |
| Disable use of the OS keyring for token storage. |
| Install directory override for the shell installer script. |
| Set to |
| Disable or force colored output. dtctl also auto-detects whether it is writing to a terminal. |
Go deeper with dtctl by exploring the GitHub repository.
dtctl on GitHub