dtctl

dtctl

Your Dynatrace platform, one command away.

dtctl is a CLI for Dynatrace SaaS. Manage workflows, dashboards, queries, and more from your terminal or let AI agents do it for you. Its predictable verb-noun syntax (inspired by kubectl) makes it easy for both humans and AI agents to operate.

Looking for something else? dtmgd covers Dynatrace Managed, and dtwiz helps with Dynatrace setup and onboarding.

dtctl get workflows                           # List all workflows
dtctl query "fetch logs | limit 10"           # Run DQL queries
dtctl apply -f workflow.yaml --set env=prod   # Declarative configuration
dtctl get dashboards -o json                  # Structured output for automation
dtctl exec copilot nl2dql "error logs from last hour"

Active Development: dtctl has stabilized considerably, but some commands and flags are still experimental or development tier (see Stability). If you encounter any bugs or issues, please file a GitHub issue. Contributions and feedback are welcome!

Documentation · Installation · Quick Start · Command Reference

Install

# Homebrew (macOS/Linux)
brew install dynatrace-oss/tap/dtctl

# Shell script (macOS/Linux)
curl -fsSL https://raw.githubusercontent.com/dynatrace-oss/dtctl/main/install.sh | sh

# PowerShell (Windows)
irm https://raw.githubusercontent.com/dynatrace-oss/dtctl/main/install.ps1 | iex

Binary downloads, building from source, shell completion setup, and more in the Installation Guide.

Authenticate

# OAuth login (recommended, no token management needed)
dtctl auth login --context my-env --environment "https://abc12345.apps.dynatrace.com"

# Verify everything works
dtctl doctor

Token-based authentication and multi-environment configuration are covered in the Quick Start.

Why dtctl?

• Familiar CLI conventions: get, describe, edit, apply, delete. If you (or your AI) know kubectl, you already know dtctl.
• Built for AI agents: Structured output (--agent), machine-readable command catalog (dtctl commands), environment data discovery (dtctl inventory), and a bundled Agent Skill that teaches AI assistants how to operate Dynatrace
• Multi-environment: Switch between dev/staging/prod with a single command; safety levels prevent accidental changes
• Watch mode: Real-time monitoring with --watch for all resources
• DQL passthrough: Execute queries directly, with template variables and file-based input
• Embeddable: dtctl serve http (development-tier, opt in with dtctl config set development.serve on) or pkg/engine in Go runs the same command surface in-process for services and Workflow actions — multi-tenant per request, no host config, output byte-identical to the CLI
• NO_COLOR support: Respects NO_COLOR, FORCE_COLOR=1, and auto-detects TTY

Supported Resources

See the Command Reference for the full list of verbs, flags, resource types, and aliases.

AI Agent Skills

dtctl ships with an Agent Skill that teaches AI coding assistants how to use dtctl. Agents can also bootstrap at runtime with dtctl commands, which prints a compact minimal overview of verbs, resources, and subcommands (defaults to TOON); add --brief or --full for progressively more detail. Where dtctl commands answers "what can I run?", dtctl inventory answers "what is there to query?" — it probes the current environment (read-only, budgeted) for fetchable data objects, buckets, filter segments, a live entity-type census, and capabilities present or absent, with the evidence cited for every absent one. The capability set is customizable via --definitions (see docs/dev/examples/inventory-definitions.example.yaml). For onboarding verification, dtctl inventory arrivals --scope '<dql filter>' answers "is data arriving for this source right now?" — a per-signal ingest state (live, stale, empty, no-data, n/a, absent, unknown) with counts and last-seen, gateable in CI with --require.

# Install via skills.sh
npx skills add dynatrace-oss/dtctl

# Or install with dtctl itself
dtctl skills install              # Auto-detects your AI agent
dtctl skills install --for claude # Or specify explicitly
dtctl skills install --global     # User-wide installation

# Or copy manually
cp -r skills/dtctl ~/.agents/skills/   # Cross-client (any agent)

Compatible with GitHub Copilot, Claude Code, OpenAI Codex CLI, Cursor, Kiro, Junie, OpenCode, OpenClaw, and other Agent Skills-compatible tools. See the AI Agent Mode docs for details on the structured JSON envelope and agent auto-detection.

Dynatrace domain skills

For deeper Dynatrace domain knowledge (DQL syntax, observability patterns, dashboards, logs, Kubernetes, and more) install the skills from Dynatrace/dynatrace-for-ai:

npx skills add dynatrace/dynatrace-for-ai

These skills provide the domain context (e.g., how to write DQL queries, which metrics to use for service health, how to navigate distributed traces) while dtctl provides the operational tool to act on it. Together they give AI agents everything they need to work with Dynatrace effectively.

Running as a Service

dtctl serve http exposes the CLI over HTTP for AI agents and automation. It is a development-tier feature: run dtctl config set development.serve on (or set DTCTL_DEVELOPMENT=serve) to enable the command, and expect the contract to change. See Stability for what each tier promises. One request executes one dtctl command line for one tenant (POST /v1/execute) and returns the exact output the CLI would have printed. Each request brings its own environment URL and token, file arguments resolve against per-request virtual files, and host-only commands are unavailable. Go callers can embed pkg/engine directly instead. It is a reference implementation with no authentication of its own — see Server Mode before exposing it beyond localhost.

Observability

dtctl supports W3C Trace Context propagation and OTLP span export via the OpenTelemetry SDK. See docs/OBSERVABILITY.md for full details on distributed tracing, environment variables, and CI/CD pipeline integration.

Documentation

Full documentation lives in the repo's docs/ directory:

• Installation: Homebrew, shell script, binary download, build from source, shell completion
• Quick Start: Authentication, first commands, common patterns
• Configuration: Contexts, credentials, safety levels, aliases
• Command Reference: All verbs, flags, resource types, and examples
• Output Formats: Table, JSON, YAML, CSV, charts
• AI Agent Mode: Structured envelope, auto-detection, agent skill
• Token Scopes: Required API token scopes per safety level
• Server Mode: Running dtctl as a server, the execute API, and embedding pkg/engine
• Stability: What stable, experimental, and development promise, and how to pin a floor

Resource-specific guides: API Discovery · DQL Queries · Workflows · Dashboards · SLOs · Settings · Extensions · Analyzers · CoPilot · and more...

Contributing

See CONTRIBUTING.md for guidelines.

License

Apache License 2.0. See LICENSE.