dtctl

command module
v0.46.0 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Nov 18, 2026 License: Apache-2.0 Imports: 3 Imported by: 0

README

dtctl

OpenSSF Scorecard

Release Build Status Go Report Card License Go Version

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"

dtctl dashboard workflow demo

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/dtctl/main/install.sh | sh
# PowerShell (Windows)
irm https://raw.githubusercontent.com/Dynatrace/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

Resource Operations
Workflows get, describe, create, edit, delete, apply, execute, logs, history, restore, diff, watch
Dashboards & Notebooks get, describe, create, edit, delete, apply, share, history, restore, diff, watch
Documents & Trash get, describe, create, edit, delete, share, history, restore
DQL Queries execute, verify, template variables, live mode, filter segments, wait conditions, spill large results to a file + local inspect (rows/schema/stats)
SLOs get, describe, create, edit, delete, apply, evaluate, watch
Settings get schemas, get/create/update/delete objects
Buckets get, describe, create, delete, apply, watch
Segments get, describe, create, edit, delete, apply, watch
Lookup Tables get, describe, create, delete, apply (CSV auto-detection)
Anomaly Detectors get, describe, create, edit, delete, apply
Extensions 2.0 get, describe, apply monitoring configs
Hub Extensions get, describe, list releases, filter by keyword
App Functions & Intents get, describe, execute, find, open (deep linking)
Analyzers & CoPilot statistical analyzers, CoPilot chat, NL-to-DQL, document search
Cloud Integrations AWS, Azure & GCP connections and monitoring (get, describe, create, delete, apply, update, enable)
EdgeConnect get, describe, create, delete
Notifications get, describe, delete, watch
Users & Groups get, describe
Live Debugger breakpoints, workspace filters, snapshot decoding
Platform Tokens account create/list/delete token (dt0s16.* via Account Management API)
API Discovery get apis (with --uncovered), describe api (operation index, one operation in full, raw spec)

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/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.

Documentation

The Go Gopher

There is no documentation for this package.

Directories

Path Synopsis
cmd
pkg
auth
The OAuth flow, token manager, and cross-process refresh lock moved to github.com/Dynatrace/dtctl/sdk/session: every long-running consumer of the shared token store must refresh through the same locked path, so the machinery is part of the shared session layer.
The OAuth flow, token manager, and cross-process refresh lock moved to github.com/Dynatrace/dtctl/sdk/session: every long-running consumer of the shared token store must refresh through the same locked path, so the machinery is part of the shared session layer.
client
Package client re-exports the authenticated Dynatrace HTTP client from github.com/Dynatrace/dtctl/sdk/session, where the implementation moved: client construction from a context — token resolution, OAuth refresh, the 401 retry — is shared session behavior, and the User-Agent is parameterized there so each consumer ships its own identity.
Package client re-exports the authenticated Dynatrace HTTP client from github.com/Dynatrace/dtctl/sdk/session, where the implementation moved: client construction from a context — token resolution, OAuth refresh, the 401 retry — is shared session behavior, and the User-Agent is parameterized there so each consumer ships its own identity.
commands
Package commands builds a machine-readable catalog of dtctl's command tree.
Package commands builds a machine-readable catalog of dtctl's command tree.
config
Package config re-exports the dtctl session layer from github.com/Dynatrace/dtctl/sdk/session, where the implementation moved: the config model, load/save, credential stores, and token resolution are the shared contract consumed by dtctl and dtctl-* plugins; this package remains so the root module's import surface is stable.
Package config re-exports the dtctl session layer from github.com/Dynatrace/dtctl/sdk/session, where the implementation moved: the config model, load/save, credential stores, and token resolution are the shared contract consumed by dtctl and dtctl-* plugins; this package remains so the root module's import surface is stable.
dqlhint
Package dqlhint turns a DQL error reported by the Grail query API into repair hints: a caret-marked snippet of the offending query text, and — for a small table of known authoring traps — a corrected query.
Package dqlhint turns a DQL error reported by the Grail query API into repair hints: a caret-marked snippet of the offending query text, and — for a small table of known authoring traps — a corrected query.
engine
Package engine executes dtctl command lines in-process for services.
Package engine executes dtctl command lines in-process for services.
inspect
Package inspect implements `dtctl inspect`: a small, fixed set of pure-Go analytics primitives over a spilled query-result file (Layer 2 of the result spill design).
Package inspect implements `dtctl inspect`: a small, fixed set of pure-Go analytics primitives over a spilled query-result file (Layer 2 of the result spill design).
plugin
Package plugin implements dtctl's kubectl-style exec plugin convention: an executable named dtctl-<name> on PATH extends dtctl with the `dtctl <name>` command.
Package plugin implements dtctl's kubectl-style exec plugin convention: an executable named dtctl-<name> on PATH extends dtctl with the `dtctl <name>` command.
resources/anomalydetector
Package anomalydetector provides a handler for custom anomaly detectors (Settings schema: builtin:davis.anomaly-detectors).
Package anomalydetector provides a handler for custom anomaly detectors (Settings schema: builtin:davis.anomaly-detectors).
resources/api
Package api is the CLI layer over the platform's own OpenAPI documents.
Package api is the CLI layer over the platform's own OpenAPI documents.
resources/awsconnection
Package awsconnection implements CRUD operations for the Settings 2.0 schema builtin:hyperscaler-authentication.connections.aws (AWS authentication for Dynatrace data acquisition extensions, e.g.
Package awsconnection implements CRUD operations for the Settings 2.0 schema builtin:hyperscaler-authentication.connections.aws (AWS authentication for Dynatrace data acquisition extensions, e.g.
resources/awsmonitoringconfig
Package awsmonitoringconfig manages monitoring configurations for the Dynatrace AWS data acquisition extension (com.dynatrace.extension.da-aws).
Package awsmonitoringconfig manages monitoring configurations for the Dynatrace AWS data acquisition extension (com.dynatrace.extension.da-aws).
resources/classicpipelinestranslate
Package classicpipelinestranslate is the CLI resource layer for the OpenPipeline classic pipelines translation endpoint.
Package classicpipelinestranslate is the CLI resource layer for the OpenPipeline classic pipelines translation endpoint.
resources/dqlprocessorverify
Package dqlprocessorverify is the CLI resource layer for the OpenPipeline DQL processor verify endpoint.
Package dqlprocessorverify is the CLI resource layer for the OpenPipeline DQL processor verify endpoint.
resources/matcherlqltodql
Package matcherlqltodql is the CLI resource layer for the LQL-to-DQL translation endpoint.
Package matcherlqltodql is the CLI resource layer for the LQL-to-DQL translation endpoint.
resources/matcherverify
Package matcherverify is the CLI resource layer for the OpenPipeline matcher verify endpoint.
Package matcherverify is the CLI resource layer for the OpenPipeline matcher verify endpoint.
resources/previewprocessor
Package previewprocessor is the CLI resource layer for the OpenPipeline preview processor endpoint.
Package previewprocessor is the CLI resource layer for the OpenPipeline preview processor endpoint.
resources/schedulingrule
Package schedulingrule provides the CLI resource handler for Dynatrace scheduling rules.
Package schedulingrule provides the CLI resource handler for Dynatrace scheduling rules.
safety
Package safety re-exports the safety-level semantics from github.com/Dynatrace/dtctl/sdk/session, where the implementation moved: a readonly context must mean the same thing in dtctl and every dtctl-* plugin, so the checker is part of the shared session layer.
Package safety re-exports the safety-level semantics from github.com/Dynatrace/dtctl/sdk/session, where the implementation moved: a readonly context must mean the same thing in dtctl and every dtctl-* plugin, so the checker is part of the shared session layer.
serve
Package serve is the command surface for running dtctl as a server on top of pkg/engine.
Package serve is the command surface for running dtctl as a server on top of pkg/engine.
skills
Package skills provides installation and management of AI coding assistant skill files for dtctl.
Package skills provides installation and management of AI coding assistant skill files for dtctl.
stability
Package stability declares and resolves dtctl's command stability contract: what we promise about a command's, flag's or output field's shape over time.
Package stability declares and resolves dtctl's command stability contract: what we promise about a command's, flag's or output field's shape over time.
tracing
Package tracing configures OpenTelemetry for dtctl using the OTLP HTTP exporter.
Package tracing configures OpenTelemetry for dtctl using the OTLP HTTP exporter.
usage
Package usage keeps dtctl's opt-in local usage ledger: a per-day tally of the DQL queries this machine's dtctl ran and the data they scanned.
Package usage keeps dtctl's opt-in local usage ledger: a per-day tally of the DQL queries this machine's dtctl ran and the data they scanned.
util/unknownfields
Package unknownfields lets a typed struct carry the JSON object members it does not model through a decode/encode round trip.
Package unknownfields lets a typed struct carry the JSON object members it does not model through a decode/encode round trip.
vfs
Package vfs is the file-access seam between dtctl commands and the filesystem.
Package vfs is the file-access seam between dtctl commands and the filesystem.
sdk module
skills
dtctl
Package dtctlskill embeds the full dtctl skill content (SKILL.md and all reference files) so that other packages can access it without filesystem reads or build-time code generation.
Package dtctlskill embeds the full dtctl skill content (SKILL.md and all reference files) so that other packages can access it without filesystem reads or build-time code generation.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL