Pup CLI

The Datadog integration provides two distinct ways to interact with Datadog data:

Use Pup CLI When:

• You need immediate results.
• You are exploring or experimenting with Datadog data.
• You are performing one-off queries or operations.
• You are troubleshooting quickly.
• You want to test a query before implementing it in code.

Generate Code When:

• You need to integrate Datadog functionality into an application.
• You are automating recurring operations.
• You are building custom tools or dashboards.
• You have specified a programming language (TypeScript, Python, Java, Go, or Rust).

Pup extensions are standalone executables that add new subcommands to the pup CLI. When you run pup <command>, pup first checks if <command> is a built-in. If not, it searches for an installed executable named pup-<command> and runs it, passing your arguments and authentication credentials.

This allows teams to ship experimental features or custom tools independently of the core pup release cycle. Extensions can be written in any language (Shell, Python, Rust, etc.) as long as they are executable files.

# If an extension named 'pup-foo' is installed,
# this command dispatches to the 'pup-foo' executable
pup foo --some-flag value

Most Pup commands require valid authentication to function.

• Workflow Commands: All workflow commands require both DD_API_KEY and DD_APP_KEY. Note that OAuth2 bearer tokens are not supported for workflow operations.
• Command Status: In the command index, commands marked with ✅ are working and require valid auth. Commands marked with ⚠️ are waiting for API client library updates, and ⏳ are skeleton implementations.

Adhere to these security practices to protect user data and credentials:

Data Handling

• Never commit: API keys, secrets, OAuth tokens, client secrets, environment variables with credentials, or real user test data.
• Always: Validate user inputs to prevent injection and use parameterized queries for data storage.
• Error Messages: Wrap errors using anyhow::Context but ensure sensitive data is never included in the error string.

OAuth2 Security

• Use PKCE S256 for code challenges.
• Validate the state parameter to prevent CSRF.
• Never log or print access/refresh tokens.
• Use the OS keychain for primary token storage.
• If falling back to file-based storage, restrict permissions to 0600.

Pup uses two primary locations for testing:

1. Module Tests (src/): Unit tests are co-located with the source code using #[cfg(test)] modules. This is the preferred pattern for testing logic within specific files like auth, client.rs, config.rs, etc.
2. Integration Tests (tests/): These are located in the tests/ directory and are used for end-to-end testing and output comparison (e.g., tests/compare/).

Capture expressions allow you to use dot notation for fields and brackets for array indexing to extract specific data points. You can also use --template to create custom log messages using {variable} placeholders.

Capture specific fields and array elements:

# Dot notation and array indexing
--capture "user.name"
--capture "orders[0].total"
--capture "items[len(items)].name"

Combine capture expressions with a template:

pup debugger probes create \
  --service my-service --env prod \
  --probe-location "MyClass:myMethod" \
  --capture "user.id" \
  --template "Processing request for user={user.id}, took {@duration}ms"

Use conditions to filter probe triggers:

--condition "status == 'error'"
--condition "@duration > 100"

Pup uses a hierarchical command structure based on domains and actions. Commands follow two primary patterns depending on whether they are simple or nested:

1. Simple commands: pup <domain> <action> [options]
2. Nested commands: pup <domain> <subgroup> <action> [options]

You can always view the live, exhaustive list of commands available in your specific binary by running pup --help or pup agent schema --compact.

When Pup is in agent mode, it wraps all command outputs in a JSON envelope containing status, data, and metadata.

Warning: If you write a script or runbook that a user will execute in a standard shell (where agent mode is NOT active), the output will be the raw payload, not the envelope. A script relying on the envelope structure (e.g., jq '.data[]') will break when run outside an agent session.

Best Practice: Always append --no-agent to commands in scripts intended for end-users to ensure consistent raw output.

# This might break if the user isn't in agent mode:
pup monitors list | jq '.data[]'

# This is safe for scripts:
pup --no-agent monitors list | jq '.[].name'

pup --no-agent monitors list --tag='env:prod' | jq '.[].name'