datadog Add a new CLI subcommand to a Datadog Agent binary. Each agent binary uses Cobra commands registered via a central subcommands.go file.
Agent Binaries
| Agent | Subcommands dir | Registration file |
|---|---|---|
| Core Agent | cmd/agent/subcommands/ |
cmd/agent/subcommands/subcommands.go |
| Cluster Agent | cmd/cluster-agent/subcommands/ |
cmd/cluster-agent/subcommands/subcommands.go |
| Process Agent | cmd/process-agent/subcommands/ |
cmd/process-agent/subcommands/subcommands.go |
| Security Agent | cmd/security-agent/subcommands/ |
cmd/security-agent/subcommands/subcommands.go |
| System Probe | cmd/system-probe/subcommands/ |
cmd/system-probe/subcommands/subcommands.go |
| DogStatsD | cmd/dogstatsd/subcommands/ |
cmd/dogstatsd/subcommands/subcommands.go |
Instructions
Step 1: Gather information from the user
Use AskUserQuestion to collect the following. If $ARGUMENTS provides values, skip those questions.
- Target agent: Which agent binary? (Core Agent is most common)
- Subcommand name: e.g.
health,hostname,flare - Description: What does the subcommand do?
- Complexity: Simple (no Fx, e.g.
version) or with config/IPC (fxutil.OneShot, e.g.hostname)? - Shared across agents?: Yes →
pkg/cli/subcommands/<name>/, No →cmd/<agent>/subcommands/<name>/
Step 2: Read reference examples
Read the reference matching the chosen pattern, plus the target agent's registration file:
| Pattern | Reference file |
|---|---|
| Simple (no Fx) | cmd/agent/subcommands/version/command.go |
| With config/IPC | cmd/agent/subcommands/hostname/command.go |
| Shared across agents | pkg/cli/subcommands/health/command.go + cmd/agent/subcommands/health/command.go |
Also read the target agent's command/command.go for available GlobalParams fields.
Step 3: Create the subcommand
Create cmd/<agent>/subcommands/<name>/command.go following the reference patterns exactly.
Step 4: Register
Edit the agent's subcommands.go: add an import with the cmd<Name> alias convention and add cmd<Name>.Commands to the factory slice. Follow the existing entries.
Step 5: Verify
- Build:
dda inv agent.build --build-exclude=systemd - Test:
./bin/agent/agent <name> --help - Lint:
dda inv linter.go
Usage
/create-subcommand— Interactive: prompts for all details/create-subcommand agent my-command— Pre-fills agent and name