dtctl

https://dynatrace-oss.github.io/dtctl/docs/
Admin
dtctl is a kubectl-inspired CLI for Dynatrace that provides command-line and AI agent management of...
Tokens:65,291
Snippets:696
Trust Score:9.7
Update:1 month ago
Show doc for...
Tokens:
Raw
### List and describe apps with dtctl

Source: https://dynatrace-oss.github.io/dtctl/docs/apps

Use `dtctl get apps` to list all installed apps and `dtctl describe app app-123` to view details of a specific app.

```bash
# List all installed apps
dtctl get apps

# Describe a specific app
dtctl describe app app-123
```

--------------------------------

### Quick dtctl command examples

Source: https://dynatrace-oss.github.io/dtctl

Quick examples of common dtctl commands: list workflows, run DQL queries, apply configuration with template variables, get dashboards as JSON, execute workflows with wait and show-results, and ask Davis CoPilot a question.

```bash
# List all workflows
dtctl get workflows

# Run a DQL query
dtctl query 'fetch logs | filter status == "ERROR" | limit 10'

# Apply configuration from a YAML file with template variables
dtctl apply -f workflow.yaml --set env=prod

# Get dashboards as JSON for automation
dtctl get dashboards -o json

# Execute a workflow and wait for completion
dtctl exec workflow "Daily Health Check" --wait --show-results

# Ask Davis CoPilot a question
dtctl exec copilot nl2dql "error logs from last hour"

```

--------------------------------

### Install built dtctl system-wide

Source: https://dynatrace-oss.github.io/dtctl/docs/installation

Options to install the built binary system-wide: using make install or copying to /usr/local/bin.

```bash
make install          # installs to $GOPATH/bin
# or
sudo cp bin/dtctl /usr/local/bin/
```

--------------------------------

### Install Dynatrace domain skills

Source: https://dynatrace-oss.github.io/dtctl/docs/skills

Install the Dynatrace domain skills from the Dynatrace/dynatrace-for-ai repository using npx skills add.

```bash
npx skills add dynatrace/dynatrace-for-ai

```

--------------------------------

### Example pipeline YAML for settings object

Source: https://dynatrace-oss.github.io/dtctl/docs/settings

Example YAML file for creating a settings object. Defines a log pipeline with processing, storage, and routing configurations.

```yaml
customId: my-log-pipeline
displayName: Production Log Pipeline
processing:
  - name: extract-severity
    description: Extract severity from log message
    processor:
      type: dql
      dqlScript: |
        parse content, "LD 'severity=' WORD:severity"
  - name: normalize-timestamp
    description: Normalize timestamp format
    processor:
      type: dql
      dqlScript: |
        fieldsAdd timestamp = toTimestamp(raw_timestamp)
storage:
  catch_all:
    bucketName: default_logs
    enabled: true
  custom:
    - bucketName: logs-production
      enabled: true
      matcher: severity == "ERROR" or severity == "CRITICAL"
routing:
  catch_all:
    pipelineId: default
    enabled: true
```

--------------------------------

### Install dtctl using shell script

Source: https://dynatrace-oss.github.io/dtctl/docs/installation

Downloads the latest release and verifies installation. Extracts to ~/.local/bin on Linux or /usr/local/bin on macOS.

```bash
curl -fsSL https://raw.githubusercontent.com/dynatrace-oss/dtctl/main/install.sh | sh
```

--------------------------------

### Install dtctl with Homebrew, PowerShell, or from source

Source: https://dynatrace-oss.github.io/dtctl

Install dtctl on macOS/Linux via Homebrew, on Windows via PowerShell, or build from source. The binary download URL is provided as a comment.

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

```

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

```

```bash
# Binary download
# https://github.com/dynatrace-oss/dtctl/releases/latest

# Build from source
git clone https://github.com/dynatrace-oss/dtctl.git && cd dtctl && make install

```

--------------------------------

### Enable and start dtctl serve with DTCTL_EXPERIMENTAL_SERVE

Source: https://dynatrace-oss.github.io/dtctl/docs/serve

Enables the experimental server mode and starts the HTTP server. Without the DTCTL_EXPERIMENTAL_SERVE variable, dtctl serve is an unknown command and does not appear in --help or the dtctl commands catalog.

```bash
export DTCTL_EXPERIMENTAL_SERVE=1
dtctl serve http

```

--------------------------------

### Install dtctl skill with skills.sh

Source: https://dynatrace-oss.github.io/dtctl/docs/skills

Use npx skills add to install the dtctl skill from the dynatrace-oss/dtctl repository.

```bash
npx skills add dynatrace-oss/dtctl

```

--------------------------------

### List and describe buckets with dtctl

Source: https://dynatrace-oss.github.io/dtctl/docs/buckets

Use `dtctl get buckets` to list all buckets and `dtctl describe bucket logs-production` to get details of a specific bucket.

```bash
# List all buckets
dtctl get buckets

# Describe a specific bucket
dtctl describe bucket logs-production

```

--------------------------------

### Verify Setup

Source: https://dynatrace-oss.github.io/dtctl/docs/quick-start

Checks connectivity, authentication, and API permissions to ensure the environment is correctly configured.

```bash
dtctl doctor
```

--------------------------------

### SQL Server Extension Configuration

Source: https://dynatrace-oss.github.io/dtctl/docs/extensions

Example configuration for monitoring a SQL Server instance.

```yaml
scope: HOST_GROUP-SQL01
description: SQL Server monitoring
version: "2.5.1"
featureSets:
  - sqlserver
sqlServer:
  endpoints:
    - host: sql-prod.internal
      port: 1433
      authentication:
        scheme: basic
        username: dt_monitor
        password: "{{ .sql_password }}"
      databases:
        - name: OrdersDB
```

--------------------------------

### Install dtctl with custom directory

Source: https://dynatrace-oss.github.io/dtctl/docs/installation

Use the DTCTL_INSTALL_DIR environment variable to override the default install location.

```bash
curl -fsSL https://raw.githubusercontent.com/dynatrace-oss/dtctl/main/install.ps1 | iex
```

--------------------------------

### Install extension from Hub with dtctl create extension --hub-extension

Source: https://dynatrace-oss.github.io/dtctl/docs/extensions

Installs an extension from the Hub. Use --hub-extension to specify the extension ID and optionally --version to pin a specific version. Requires the extensions:definitions:write scope.

```shell
# Latest version
dtctl create extension --hub-extension com.dynatrace.extension.host-monitoring

# Specific version
dtctl create extension --hub-extension com.dynatrace.extension.host-monitoring --version 1.2.3

```

--------------------------------

### Install dtctl skill with dtctl commands

Source: https://dynatrace-oss.github.io/dtctl/docs/skills

Install the dtctl skill using dtctl skills install, with options for auto-detection, explicit agent, global installation, cross-client installation, and status check.

```bash
dtctl skills install              # Auto-detects your AI agent
dtctl skills install --for claude # Or specify explicitly
dtctl skills install --global     # User-wide installation
dtctl skills install --cross-client  # Cross-client (.agents/skills/)
dtctl skills status               # Check installation status

```

--------------------------------

### Install dtctl with Homebrew on macOS/Linux

Source: https://dynatrace-oss.github.io/dtctl/docs/installation

Use Homebrew tap to install dtctl and automatically set up shell completions.

```bash
brew install dynatrace-oss/tap/dtctl
```

--------------------------------

### Example inventory output

Source: https://dynatrace-oss.github.io/dtctl/docs/inventory

A synthetic example showing the structure of the inventory report, including capabilities, entity counts, and available data objects.

```text
Context:      example
Generated:    2026-01-02T03:04:05Z
Capabilities: hosts, logs, spans
Absent (what was checked)
  rum — user.events is in the catalog, but all its buckets are empty (0 records within retention)
Unknown (no verdict — not evidence of absence)
  genai — probe failed: scan limit exceeded
Entities:     K8S_POD:200 SERVICE:40 HOST:12
Data objects: logs, spans (+2 dt.entity.* lookback views)
Query-only:   metrics (no fetch — see notes)
Buckets:      default_logs, default_spans
Segments (apply with -S <name>)
  prod — production workloads
```

--------------------------------

### CI/CD Pipeline Integration

Source: https://dynatrace-oss.github.io/dtctl/docs/dql-queries

Example of a loop to verify all .dql files in a directory, failing the pipeline if any query contains warnings.

```bash
# In a CI pipeline — verify all .dql files before deploying
for f in queries/*.dql; do
  dtctl verify query -f "$f" --fail-on-warn || exit 1
done
```

--------------------------------

### View Extension Versions

Source: https://dynatrace-oss.github.io/dtctl/docs/extensions

Retrieve all installed versions for a specific extension identifier.

```bash
dtctl get extension com.dynatrace.extension.postgres
```

--------------------------------

### dtctl apply command usage

Source: https://dynatrace-oss.github.io/dtctl/docs/configuration

Examples of applying configurations with various hook control flags.

```bash
dtctl apply -f dashboard.yaml            # pre- and post-apply both run
dtctl apply -f dashboard.yaml --no-hooks # skip both hooks
dtctl apply -f dashboard.yaml --dry-run  # pre-apply runs, post-apply is skipped
dtctl apply -f dashboard.yaml -v         # verbose: logs hook command and duration
```

--------------------------------

### Describe Extension Details

Source: https://dynatrace-oss.github.io/dtctl/docs/extensions

Get full metadata and configuration schema for a specific extension version.

```bash
dtctl describe extension com.dynatrace.extension.postgres --version 2.9.3
```

--------------------------------

### SLO evaluation output example

Source: https://dynatrace-oss.github.io/dtctl/docs/slos

Example output from dtctl exec slo showing SLO value, target, warning, error budget, and timeframe.

```text
Name:           Checkout Availability
Status:         SUCCESS
SLO Value:      99.94%
Target:         99.90%
Warning:        99.95%
Error Budget:   0.04% remaining
Timeframe:      last 7 days

```

--------------------------------

### Example segment output

Source: https://dynatrace-oss.github.io/dtctl/docs/segments

Sample output format when describing a segment.

```text
Name:          my-k8s-segment
UID:           abc123-def456
Description:   Filters data for Kubernetes cluster alpha
Public:        Yes
Owner:         user@example.invalid
Version:       3

Includes:
  DATA OBJECT         FILTER
  All data objects    k8s.cluster.name = "alpha"
  Logs                dt.system.bucket = "custom-logs"

Variables:
  Type:     query
  Value:    data record(ns="namespace-a"), record(ns="namespace-b")
```

--------------------------------

### Install dtctl dependency

Source: https://dynatrace-oss.github.io/dtctl/docs/serve

Use this command to add the dtctl package to your Go project.

```bash
go get github.com/dynatrace-oss/dtctl@latest
```

--------------------------------

### Install dtctl on Windows PowerShell

Source: https://dynatrace-oss.github.io/dtctl/docs/installation

Downloads the latest binary, extracts to %LOCALAPPDATA%\dtctl, and adds it to your PATH. Restart the terminal afterwards.

```powershell
irm https://raw.githubusercontent.com/dynatrace-oss/dtctl/main/install.ps1 | iex
```

--------------------------------

### SNMP Extension Configuration

Source: https://dynatrace-oss.github.io/dtctl/docs/extensions

Example configuration for monitoring network devices via SNMP v3.

```yaml
scope: HOST_GROUP-NETWORK
description: Network device monitoring
version: "2.3.0"
featureSets:
  - snmpDefault
snmp:
  devices:
    - address: 10.0.1.1
      snmpVersion: v3
      authentication:
        username: dtmonitor
        authProtocol: SHA
        authPassword: "{{ .snmp_auth }}"
        privProtocol: AES
        privPassword: "{{ .snmp_priv }}"
```

--------------------------------

### List and describe monitoring configurations with dtctl get extension-configs

Source: https://dynatrace-oss.github.io/dtctl/docs/extensions

Lists monitoring configurations for an extension using the full command or the ext-configs alias. The describe subcommand shows details for a specific configuration ID.

```shell
# List all monitoring configs for an extension
dtctl get extension-configs --extension com.dynatrace.extension.postgres

# Using the alias
dtctl get ext-configs --extension com.dynatrace.extension.postgres

# Describe a specific monitoring config
dtctl describe extension-config <config-id>

```

--------------------------------

### Example output for anomaly detector description

Source: https://dynatrace-oss.github.io/dtctl/docs/anomaly-detectors

Sample output showing the configuration, query, event template, and recent problems for an anomaly detector.

```text
Title:                 Aurora cluster CPU utilization
Object ID:             vu9U3hXa3q0AAAA
Enabled:               true
Source:                 Clouds
Description:           Monitors Aurora cluster CPU utilization

Analyzer:
  Type:                Static Threshold
  Alert Condition:     ABOVE 90
  Sliding Window:      3 violating samples in 5 minutes
  De-alerting Samples: 5
  Missing Data Alert:  false

Query:
  timeseries cpu=avg(cloud.aws.rds.CPUUtilization), interval:1m

Event Template:
  event.type:          PERFORMANCE_EVENT
  event.name:          Aurora cluster high CPU
  event.description:   CPU utilization is high

Recent Problems (last 7 days):
  DISPLAY ID        STATUS    START                 CATEGORY
  P-2603120042      CLOSED    2026-03-28 14:22:00   PERFORMANCE
  (1 problem in the last 7 days)
```

--------------------------------

### Manual installation of dtctl skill

Source: https://dynatrace-oss.github.io/dtctl/docs/skills

Copy the skill directory into your agent's skills path for various agents: cross-client, GitHub Copilot, Claude Code, and OpenClaw.

```bash
cp -r skills/dtctl ~/.agents/skills/                       # Cross-client (any agent)
cp -r skills/dtctl ~/.github/skills/                       # GitHub Copilot
cp -r skills/dtctl ~/.claude/skills/                       # Claude Code
cp -r skills/dtctl ~/.openclaw/workspace/skills/dtctl/     # OpenClaw

```

--------------------------------

### Example output of dtctl describe analyzer

Source: https://dynatrace-oss.github.io/dtctl/docs/analyzers

Shows the output format of the describe command, including input and output fields, and a run command hint.

```text
Name:         dt.statistics.GenericForecastAnalyzer
Display Name: Forecast Analysis
Category:     Forecasting
Type:         AnalyzerFactory

Input (required):
  timeSeriesData   string    DQL timeseries query to forecast
  forecastHorizon  integer   Number of intervals to predict

Input (optional):
  coverageProbability  number   Confidence band width (e.g. 0.9)

Output:
  forecastQualityAssessment  object   Quality metrics for the forecast
  output                     array    Predicted values with confidence bands

  Run it:  dtctl exec analyzer dt.statistics.GenericForecastAnalyzer --query <dql>
  Docs:    dtctl describe analyzer dt.statistics.GenericForecastAnalyzer --doc

```

--------------------------------

### Authenticate and verify dtctl with OAuth login

Source: https://dynatrace-oss.github.io/dtctl

Authenticate with OAuth, verify the setup with dtctl doctor, and start using dtctl by listing workflows.

```bash
# OAuth login (recommended)
dtctl auth login --context my-env --environment "https://abc12345.apps.dynatrace.com"

# Verify
dtctl doctor

# Start using dtctl
dtctl get workflows

```

--------------------------------

### Describe resources with structured output flags

Source: https://dynatrace-oss.github.io/dtctl/docs/output-formats

All `describe` subcommands support the `-o` / `--output` flag for structured output. The examples show JSON, YAML, and agent mode envelope (`-A`) outputs.

```bash
# JSON output for scripting
dtctl describe workflow wf-123 -o json

# YAML output for round-tripping
dtctl describe slo my-slo -o yaml

# Agent mode envelope
dtctl describe dashboard my-dash -A

```

--------------------------------

### Manage trash with dtctl get, describe, restore, and delete

Source: https://dynatrace-oss.github.io/dtctl/docs/dashboards

List items in the trash, inspect a trashed document, restore it, or permanently delete it (bypassing the 30-day retention).

```bash
# List items in the trash
dtctl get trash

# Inspect a trashed document
dtctl describe trash dash-123

# Restore a document from the trash
dtctl restore trash dash-123

# Permanently delete (bypasses the 30-day retention)
dtctl delete trash dash-123 --permanent
```

--------------------------------

### Example output of dtctl get apis

Source: https://dynatrace-oss.github.io/dtctl/docs/api-discovery

Illustrative table output from `dtctl get apis` showing the DTCTL column. A blank DTCTL cell means no native command exists; a row with no base path (like `Elsewhere API`) is an external API documented on another host, marked with `EXTERNAL: true` when using `-o wide`.

```text
NAME               BASE PATH               OPS   DTCTL
Widget Service     /platform/widget/v1     14    widget
Sprocket Service   /platform/sprocket/v1   3
Cog Service        /platform/cog/v1
Elsewhere API

```

--------------------------------

### Build dtctl from source

Source: https://dynatrace-oss.github.io/dtctl/docs/installation

Clone the repository and build with Go 1.24+ and Make.

```bash
git clone https://github.com/dynatrace-oss/dtctl.git
cd dtctl
make build
./bin/dtctl version
```

--------------------------------

### Create and apply bucket with dtctl

Source: https://dynatrace-oss.github.io/dtctl/docs/buckets

Use `dtctl create bucket -f bucket.yaml` to create a new bucket and `dtctl apply -f bucket.yaml` to create or update an existing one.

```bash
# Create a new bucket
dtctl create bucket -f bucket.yaml

# Apply (create or update)
dtctl apply -f bucket.yaml

```

--------------------------------

### curl POST /v1/execute example

Source: https://dynatrace-oss.github.io/dtctl/docs/serve

Sends a command execution request to the HTTP server. The JSON body includes the command line, environment URL, token, safety level, and a virtual file. The server shuts down gracefully on SIGINT/SIGTERM.

```bash
curl -s http://127.0.0.1:7211/v1/execute \
  -H 'Content-Type: application/json' \
  -d '{
    "command": "apply -f workflow.yaml --write-id --agent",
    "environmentUrl": "https://abc12345.apps.dynatrace.com",
    "token": "dt0s16.XXXXXXXX.YYYYYYYY",
    "safetyLevel": "readwrite-mine",
    "files": {
      "workflow.yaml": "title: Daily Health Check\ntasks: {}\n"
    }
  }'

```

--------------------------------

### dtctl serve http usage

Source: https://dynatrace-oss.github.io/dtctl/docs/serve

Starts the HTTP server with default settings or with custom listen address and maximum request body size. The default address is 127.0.0.1:7211 and default max request bytes is 10485760 (10 MiB).

```bash
dtctl serve http
dtctl serve http --addr 0.0.0.0:8080 --max-request-bytes 33554432

```

--------------------------------

### dtctl HTTP API response envelope

Source: https://dynatrace-oss.github.io/dtctl/docs/serve

Example JSON response from a dtctl /v1/execute request. The 'files' field contains the complete final state of the virtual filesystem, including any files written by the command. A non-zero 'exitCode' indicates a failed command, but the HTTP status is still 200.

```json
{
  "exitCode": 0,
  "stdout": "{\"ok\":true,\"result\":{...}}\n",
  "stderr": "",
  "files": {
    "workflow.yaml": "id: wf-abc123\ntitle: Daily Health Check\ntasks: {}\n"
  },
  "durationMs": 412
}
```

--------------------------------

### Troubleshoot: permission denied

Source: https://dynatrace-oss.github.io/dtctl/docs/installation

Make the binary executable to fix this error.

```bash
chmod +x dtctl
```

--------------------------------

### Troubleshoot: exec format error

Source: https://dynatrace-oss.github.io/dtctl/docs/installation

Rebuild for your current platform if using a binary built for another OS/architecture.

```bash
make clean && make build
```

--------------------------------

### Example SLO YAML definition

Source: https://dynatrace-oss.github.io/dtctl/docs/slos

Example SLO YAML defining a service availability SLO with a custom SLI indicator, target, warning, and tags.

```yaml
name: Service Availability
description: 97% of requests are successful over the last 7 days
criteria:
  - timeframeFrom: -7d
    target: 97.0
    warning: 98.0
customSli:
  indicator: |
    timeseries { total=sum(dt.service.request.count), failures=sum(dt.service.request.failure_count) }
    , by: { dt.smartscape.service }
    | fieldsAdd sli=(((total[]-failures[])/total[])*(100))
    | fieldsAdd dt.smartscape.entity.name = getNodeName(dt.smartscape.service)
    | fieldsRemove total, failures, smartscapeIds
tags:
  - slo-type:availability

```

--------------------------------

### List analyzers with dtctl get analyzers

Source: https://dynatrace-oss.github.io/dtctl/docs/analyzers

Lists all available analyzers. Use --filter to filter by name, -o json for structured output, and dtctl get analyzer <name> for a raw definition.

```bash
# List all available analyzers
dtctl get analyzers

# Get a single analyzer's raw definition
dtctl get analyzer dt.statistics.GenericForecastAnalyzer

# Filter the list (DQL-style expression)
dtctl get analyzers --filter "name contains 'forecast'"

# Structured output
dtctl get analyzers -o json

```

--------------------------------

### Deploy settings to staging and production

Source: https://dynatrace-oss.github.io/dtctl/docs/settings

Commands to deploy the template to staging and production. Uses --set env=staging and --set env=production, and switches context with dtctl ctx use production.

```bash
# Deploy to staging
dtctl create settings -f pipeline-template.yaml \
  --schema builtin:openpipeline.logs.pipelines --scope environment \
  --set env=staging

# Deploy to production
dtctl ctx use production
dtctl create settings -f pipeline-template.yaml \
  --schema builtin:openpipeline.logs.pipelines --scope environment \
  --set env=production
```

--------------------------------

### Troubleshoot: command not found

Source: https://dynatrace-oss.github.io/dtctl/docs/installation

Add the binary's directory to your PATH or use the full path to resolve this error.

```bash
export PATH="$PATH:/path/to/dtctl/bin"
```

--------------------------------

### Deploy Extension Configurations with dtctl

Source: https://dynatrace-oss.github.io/dtctl/docs/extensions

Commands to deploy the PostgreSQL extension template to staging and production environments using the --set flag.

```bash
# Deploy to staging
dtctl create extension-config -f extension-template.yaml \
  --extension com.dynatrace.extension.postgres \
  --set env=staging \
  --set host_group=HOST_GROUP-STAGING \
  --set db_host=db-staging.internal \
  --set db_password=staging-pass

# Deploy to production
dtctl ctx use production
dtctl create extension-config -f extension-template.yaml \
  --extension com.dynatrace.extension.postgres \
  --set env=production \
  --set host_group=HOST_GROUP-PROD \
  --set db_host=db-prod-01.internal \
  --set db_password=prod-pass
```

--------------------------------

### GET /healthz

Source: https://dynatrace-oss.github.io/dtctl/docs/command-reference

Liveness probe for the server.

```APIDOC
## GET /healthz

### Description
Liveness probe for the server.

### Method
GET

### Endpoint
/healthz

### Parameters
None

### Response
#### Success Response (200)
No response body is documented.
```

--------------------------------

### List dashboards and notebooks with dtctl get

Source: https://dynatrace-oss.github.io/dtctl/docs/dashboards

Use `dtctl get` to list dashboards or notebooks. Options include filtering by name, showing only your own, wide output, sorting, adding fields, admin access, and raw Document API filters.

```bash
# List all dashboards
dtctl get dashboards

# List all notebooks
dtctl get notebooks

# Filter by name substring
dtctl get dashboards --name "Production"

# Show only your own dashboards
dtctl get dashboards --mine

# Wide output with owner, tile count, and last modified date
dtctl get dashboards -o wide

# Sort by name ascending, last-modified descending
dtctl get dashboards --sort "name,-modificationInfo.lastModifiedTime"

# Request fields the API omits by default
dtctl get dashboards --add-fields "originExtensionId,labels,shareInfo.isShared"

# List all documents as effective owner (requires document:documents:admin)
dtctl get dashboards --admin-access

# Raw Document API filter expression — sent verbatim, overrides --name/--mine
dtctl get dashboards --filter "originAppId exists"
dtctl get documents --filter "type in ('dashboard','notebook') and name contains 'report'"
```

--------------------------------

### Initialize .dtctl.yaml

Source: https://dynatrace-oss.github.io/dtctl/docs/configuration

Run this command in your project root to generate a template configuration file.

```bash
dtctl config init
```

--------------------------------

### Example segment YAML

Source: https://dynatrace-oss.github.io/dtctl/docs/segments

YAML definition for a segment.

```yaml
name: my-k8s-segment
description: Filters data for Kubernetes cluster alpha
isPublic: true
includes:
  - dataObject: _all_data_object
    filter: 'k8s.cluster.name = "alpha"'
  - dataObject: logs
    filter: 'dt.system.bucket = "custom-logs"'
variables:
  type: query
  value: 'data record(ns="namespace-a"), record(ns="namespace-b")'
```

--------------------------------

### List settings objects with output formats

Source: https://dynatrace-oss.github.io/dtctl/docs/settings

List settings objects for a specific schema and scope. Use -o json or -o yaml to change the output format for scripting or readability.

```bash
# List objects for a specific schema
dtctl get settings --schema builtin:openpipeline.logs.pipelines --scope environment

# Output as JSON for scripting
dtctl get settings --schema builtin:openpipeline.logs.pipelines --scope environment -o json

# Output as YAML
dtctl get settings --schema builtin:openpipeline.logs.pipelines --scope environment -o yaml

```

--------------------------------

### List APIs with dtctl get apis

Source: https://dynatrace-oss.github.io/dtctl/docs/api-discovery

Shows common invocations of `dtctl get apis` to list published APIs, filter uncovered ones, show operation counts, and output JSON. `--ops-count` is off by default because it costs one request per API.

```bash
# What does this environment publish?
dtctl get apis

# Which of those has no native dtctl command yet?
dtctl get apis --uncovered

# Operation counts and categories (one request per API)
dtctl get apis --ops-count -o wide

# Structured output
dtctl get apis -o json

```

--------------------------------

### Set Up GCP Service Account

Source: https://dynatrace-oss.github.io/dtctl/docs/cloud-integrations

Sets up a GCP service account for monitoring. Creates the service account, grants the monitoring.viewer role, and notes that workload identity federation/impersonation must be configured per dtctl describe gcp.

```shell
# Create a service account
gcloud iam service-accounts create dynatrace-monitoring \
  --display-name "Dynatrace Monitoring"

# Grant monitoring read permissions
gcloud projects add-iam-policy-binding <project-id> \
  --member "serviceAccount:dynatrace-monitoring@<project-id>.iam.gserviceaccount.com" \
  --role "roles/monitoring.viewer"

# Configure workload identity federation / impersonation
# (follow the instructions from dtctl describe gcp)

```

--------------------------------

### List and describe settings schemas with dtctl

Source: https://dynatrace-oss.github.io/dtctl/docs/settings

Use these commands to discover available settings schemas, filter by name, and inspect a specific schema's fields and constraints. The describe command requires a schema ID like builtin:openpipeline.logs.pipelines.

```bash
# List all settings schemas
dtctl get settings-schemas

# Filter schemas by name
dtctl get settings-schemas --name "openpipeline"

# Describe a specific schema to see its fields and constraints
dtctl describe settings-schema builtin:openpipeline.logs.pipelines

```

--------------------------------

### Create Simple Aliases

Source: https://dynatrace-oss.github.io/dtctl/docs/configuration

Define a shortcut for a frequently used command sequence.

```bash
dtctl alias set wf "get workflows"
dtctl wf
# Expands to: dtctl get workflows
```

--------------------------------

### Service-to-team ownership DQL example

Source: https://dynatrace-oss.github.io/dtctl/docs/lookups

Mapping service entities to their respective owning teams.

```dql
fetch events
  | lookup [/lookups/production/service_owners], sourceField:dt.entity.service, lookupField:service_id, prefix:"team_"
  | fields timestamp, dt.entity.service, team_name, team_slack_channel
```

--------------------------------

### IP-to-location mapping DQL example

Source: https://dynatrace-oss.github.io/dtctl/docs/lookups

Mapping client IP addresses to geographic locations.

```dql
fetch logs
  | lookup [/lookups/production/ip_locations], sourceField:client_ip, lookupField:ip, prefix:"geo_"
  | summarize count(), by: {geo_country, geo_city}
```

--------------------------------

### Runtime bootstrapping commands

Source: https://dynatrace-oss.github.io/dtctl/docs/skills

Commands for AI agents to discover dtctl capabilities at runtime: dtctl commands for overviews and catalogs, and dtctl inventory for environment data.

```bash
# Minimal overview: verbs, resources, subcommands (TOON default, ideal for system prompts)
dtctl commands

# Brief catalog: adds mutating status, access levels, flag types, and scopes
dtctl commands --brief -o json

# Full catalog with descriptions, flag defaults, and global flags
dtctl commands --full -o json

# Human-readable how-to guide
dtctl commands howto

# What data exists in THIS environment: fetchable objects, buckets, entity census, capabilities
dtctl inventory

```

--------------------------------

### Extract and run dtctl from binary download

Source: https://dynatrace-oss.github.io/dtctl/docs/installation

Manual steps to extract the archive, make executable, handle macOS quarantine, move to PATH, and verify.

```bash
# Extract the archive
tar -xzf dtctl_*.tar.gz

# Make it executable
chmod +x dtctl

# macOS only: remove quarantine attribute
sudo xattr -r -d com.apple.quarantine dtctl

# Move to a directory in your PATH
sudo mv dtctl /usr/local/bin/

# Verify
dtctl version
```

--------------------------------

### Create service principal and assign Reader role (Client Secret)

Source: https://dynatrace-oss.github.io/dtctl/docs/cloud-integrations

Creates a service principal with a client secret, captures the output, and assigns the Reader role. The client secret is printed only once, so capture it immediately.

```bash
SP_OUTPUT=$(az ad sp create-for-rbac --name "$CONNECTION_NAME" -o json)
CLIENT_ID=$(echo "$SP_OUTPUT" | jq -r .appId)
CLIENT_SECRET=$(echo "$SP_OUTPUT" | jq -r .password)

az role assignment create \
  --assignee "$CLIENT_ID" \
  --role Reader \
  --scope "/subscriptions/$SUBSCRIPTION_ID"

```

--------------------------------

### Lookup table path hierarchy

Source: https://dynatrace-oss.github.io/dtctl/docs/lookups

Examples of valid lookup table paths organized by environment.

```text
/lookups/production/error_codes
/lookups/production/service_owners
/lookups/staging/error_codes
```

--------------------------------

### Error code enrichment DQL example

Source: https://dynatrace-oss.github.io/dtctl/docs/lookups

Enriching error logs and summarizing by description and severity.

```dql
fetch logs
  | filter loglevel == "ERROR"
  | lookup [/lookups/production/error_codes], sourceField:error_code, lookupField:code, prefix:"err_"
  | summarize count(), by: {err_description, err_severity}
```

--------------------------------

### List OpenPipeline settings schemas

Source: https://dynatrace-oss.github.io/dtctl/docs/settings

Lists available OpenPipeline schemas to find the one you need. Use the --name filter to narrow results.

```bash
dtctl get settings-schemas --name "openpipeline"
```

--------------------------------

### Apply Configuration from YAML

Source: https://dynatrace-oss.github.io/dtctl/docs/quick-start

Applies resource configurations defined in a YAML file.

```bash
dtctl apply -f workflow.yaml
```

--------------------------------

### Example CSV format

Source: https://dynatrace-oss.github.io/dtctl/docs/lookups

The expected structure for a CSV file used to create a lookup table.

```csv
code,description,severity,action
ERR001,Database connection timeout,critical,page-oncall
ERR002,Rate limit exceeded,warning,notify-slack
ERR003,Authentication failed,high,review-logs
ERR004,Disk space low,warning,expand-volume
```

--------------------------------

### Get workflow as YAML

Source: https://dynatrace-oss.github.io/dtctl/docs/output-formats

Outputs a workflow in YAML format, useful for round-tripping with `dtctl apply`.

```bash
dtctl get workflow wf-123 -o yaml

```

--------------------------------

### Troubleshoot: dtctl not recognized on Windows

Source: https://dynatrace-oss.github.io/dtctl/docs/installation

Check your PATH to find the missing directory where the binary should be located.

```powershell
$env:Path -split ';' | Select-String dtctl
```

--------------------------------

### dtctl query and verify command examples

Source: https://dynatrace-oss.github.io/dtctl/docs/command-reference

Shows the dtctl query and verify commands with their common options: inline, file-based, stdin, template variables, query parameters, spilling, segments, and verification. Use these to run DQL queries and validate query syntax or OpenPipeline components. The verify openpipeline commands exit non-zero if invalid.

```bash
# Inline query
dtctl query "fetch logs | limit 10"

# File-based query
dtctl query -f query.dql

# Stdin (heredoc)
dtctl query -f - <<'EOF'
fetch logs | filter status = "ERROR" | limit 100
EOF

# With template variables
dtctl query -f query.dql --set host=my-server --set limit=500

# Query parameters
dtctl query "..." --max-result-records 5000
dtctl query "..." --default-timeframe-start "2024-01-01T00:00:00Z"
dtctl query "..." --timezone "Europe/Paris"
dtctl query "..." --metadata                    # Include execution metadata
dtctl query "..." --no-progress                  # Disable the live progress bar (shown by default)
dtctl query "..." --live --interval 5s           # Live mode

# Spill a large result to a file, return a summary (see dql-queries#spilling-large-results-to-a-file)
dtctl query "..." --spill                         # always spill (bare flag)
dtctl query "..." --spill=auto --spill-threshold 100KB  # spill only above the size
dtctl query "..." --spill-to ./out.jsonl          # explicit destination; --spill-format jsonl|json|csv|parquet

# Filter segments
dtctl query "..." --segment my-segment-uid       # By UID or name (repeatable)
dtctl query "..." -S seg-1 -S seg-2              # Short form, AND-combined
dtctl query "..." -S "seg?var=val"               # Bind variables inline
dtctl query "..." --segments-file segments.yaml  # Segments with variables from file

# Verify query syntax
dtctl verify query "fetch logs | limit 10"
dtctl verify query -f query.dql --canonical --fail-on-warn

# Verify OpenPipeline components (restricted DQL subset; exits non-zero if invalid)
dtctl verify openpipeline-matcher 'matchesValue(content, "error")'
dtctl verify openpipeline-matcher -f matcher.dql --context ROUTING_RULE
dtctl verify openpipeline-dql-processor 'parse content, "IPV4:ip"' --config-id logs
```

--------------------------------

### Enable Bash shell completion for dtctl

Source: https://dynatrace-oss.github.io/dtctl/docs/installation

Generates completion script and installs it to /etc/bash_completion.d, then reloads .bashrc.

```bash
dtctl completion bash > /tmp/dtctl-completion.bash
sudo mkdir -p /etc/bash_completion.d
sudo cp /tmp/dtctl-completion.bash /etc/bash_completion.d/dtctl
source ~/.bashrc
```

--------------------------------

### Successful Response Structure

Source: https://dynatrace-oss.github.io/dtctl/docs/ai-agent-mode

Example of a successful JSON response containing the result and context for follow-up actions.

```json
{
  "ok": true,
  "result": [
    {
      "id": "wf-abc123",
      "name": "Daily Health Check",
      "state": "enabled"
    }
  ],
  "context": {
    "verb": "get",
    "resource": "workflow",
    "suggestions": [
      "dtctl describe workflow wf-abc123",
      "dtctl exec workflow wf-abc123"
    ]
  }
}
```

--------------------------------

### Country code resolution DQL example

Source: https://dynatrace-oss.github.io/dtctl/docs/lookups

Resolving country codes to country names and calculating revenue.

```dql
fetch bizevents
  | lookup [/lookups/production/country_codes], sourceField:country, lookupField:iso_code, prefix:"country_"
  | summarize revenue = sum(amount), by: {country_name}
```

--------------------------------

### Error Response Structure

Source: https://dynatrace-oss.github.io/dtctl/docs/ai-agent-mode

Example of an error JSON response, including a stable error code and suggestions for resolution.

```json
{
  "ok": false,
  "error": {
    "code": "auth_required",
    "message": "No valid authentication found. Run 'dtctl auth login' or configure a token.",
    "suggestions": [
      "dtctl auth login --context my-env --environment https://abc12345.apps.dynatrace.com",
      "dtctl config set-credentials my-token --token <your-token>"
    ]
  }
}
```

--------------------------------

### dtctl commands catalog usage

Source: https://dynatrace-oss.github.io/dtctl/docs/ai-agent-mode

Shows how to generate the command catalog for AI agents. The bare overview defaults to TOON and is ideal for system prompts; --brief and --full add more detail, and 'howto' provides a Markdown guide.

```bash
# Minimal overview -- verbs, resources, and subcommands only (defaults to TOON)
dtctl commands

# Brief catalog -- adds mutating status, access levels, flag types, and scopes
dtctl commands --brief -o json

# Full catalog -- detailed command descriptions, flag defaults, and global flags
dtctl commands --full -o json

# Human-readable how-to guide in Markdown
dtctl commands howto

```

--------------------------------

### dtctl get workflows -v --agent

Source: https://dynatrace-oss.github.io/dtctl/docs/ai-agent-mode

Use -v or --verbose for additional debugging information.

```bash
dtctl get workflows -v --agent

```
Tokens:
Raw