dtctl AGENTS.md

AI Agent Development Guide

kubectl-inspired CLI for Dynatrace (dashboards, workflows, SLOs, etc). Go + Cobra framework.

Pattern: dtctl <verb> <resource> [flags]

Quick Start

1. Read docs/dev/API_DESIGN.md Design Principles (lines 17-110)
2. Check IMPLEMENTATION_STATUS.md for feature matrix
3. Copy patterns from pkg/resources/slo/ or pkg/resources/workflow/

Architecture

cmd/          # Cobra commands (get, describe, create, delete, apply, exec, ctx, doctor, commands, plugin)
              # plus the embedding entrypoint: run.go (cmd.Run + per-invocation isolation),
              # session.go, capabilities.go, stdio.go, blocked.go (docs/dev/SERVICE_ENGINE_DESIGN.md)
pkg/
  ├── client/    # Shim over sdk/session's client; keeps CLI-only extras (typed errors, pagination, OTel injection) and pins the dtctl/<version> User-Agent
  ├── config/    # Shim over sdk/session — the config model/keyring implementation lives in the sdk
  ├── auth/      # Shim over sdk/session's OAuth machinery + CLI-owned scope-composition tables
  ├── safety/    # Shim over sdk/session's safety checker
  ├── plugin/    # kubectl-style exec plugin resolution/discovery (docs/dev/PLUGIN_CONVENTIONS.md)
  ├── resources/ # Resource handlers — thin CLI wrappers that delegate to sdk/api/
  ├── output/    # Formatters (table, JSON, YAML, charts, agent envelope, color control)
  ├── exec/      # DQL query execution
  ├── vfs/       # Virtual-filesystem seam: user-supplied file paths resolve against the host disk (CLI) or per-request virtual files (engine)
  ├── engine/    # Embeddable service engine: one dtctl command line per request — multi-tenant session, virtual files, CLI-identical output
  └── serve/     # `dtctl serve <protocol>` — reference servers over pkg/engine, one subcommand per protocol (`serve http` today; wired in main, outside the invocation lock). Experimental: registered only when DTCTL_EXPERIMENTAL_SERVE is set
sdk/            # Separate Go module (github.com/dynatrace-oss/dtctl/sdk)
  ├── session/     # The session layer (docs/dev/CONFIG_CONTRACT.md): config model + load/save, credential stores, OAuth flow/refresh + cross-process lock, client-from-context with parameterized User-Agent, safety semantics
  ├── api/         # Typed API wrappers (one package per Dynatrace API surface)
  │                #   apispec/ is the odd one out: it reads the environment's *own* API index and
  │                #   OpenAPI documents (docs/dev/GENERIC_API_ACCESS.md)
  ├── httpclient/  # HTTP client, response helpers, pagination, typed errors
  ├── auth/        # Token type detection
  ├── urls/        # Environment URL validation/normalization
  ├── agentmode/   # AI agent environment detection
  └── inventory/   # Environment data-inventory discovery over a caller-supplied DQL Runner