| name | create-subcommand |
| description | Add a new CLI subcommand to an agent binary (agent, cluster-agent, etc.) |
| allowed-tools | Bash, Read, Write, Edit, Glob, Grep, AskUserQuestion |
| argument-hint | [agent] [subcommand-name] |
| model | sonnet |
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