agentleFS
DataDogDataDog/pup/CLAUDE.md

pup

CLAUDE.md1k starsChanged 6 months agoApache-2.0View on GitHub

Rust-based CLI wrapper for Datadog APIs. Provides OAuth2 + API key authentication across a wide range of Datadog product domains. All PRs are reviewed against docs/REVIEW.md. Read it before submitting. Key rules: All commands follow consistent patterns:

  • Reads credentials
  • Installs packages
  • Commits and pushes

1 other project uses a version of this.

Trending

More talk lately.about the whole repository

Dec 2025: 0 mentionsJan 2026: 0 mentionsFeb 2026: 2 mentionsMar 2026: 0 mentionsApr 2026: 0 mentionsMay 2026: 0 mentionsJun 2026: 1 mentionJul 2026: 1 mentionAug 2026: 1 mentionSep 2026: 1 mentionOct 2026: 11 mentionsNov 2026: 33 mentions
Dec 2025Jun 2026Nov 2026
Mentions a month of the DataDog/pup repository that our weekly crawl found. There is no adoption data for this file yet.

Most recently taken up by

Who's talking about DataDog/pup

The biggest 5 of 50 mentions linking to the repository that our crawl found. Each line is their own headline.

See all 50

Talked about on GitHub and Hacker News (50 times).

On GitHub · 49

44 more on GitHub

On Hacker News · 1

  • Other versions1 project uses a version of this.

    Word for word · 1

    1. datadog-labs/pup★ 1k100% same

    Edited · 0

    None found.

    Wrote their own version · 0

    None found.

    How matches are found. Word for word: the exact same text. Edited: shares passages with this file (“99% same” means 99% of its five-word phrases also appear here; 10% or more counts). Their own version: similar meaning, or, weakest, the same name. We can’t tell which project had it first. Projects are counted among the 200 most-starred candidates, and mentions are links to the repository we found, up to 50 per site, so both counts are a floor.

  • In this repository13 other files it gives its agents.

The file

Show its rules and text

We split this CLAUDE.md into the rules it gives an agent

17 rules. About 0 are common, 12 are distinctive, and 5 are very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈12

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 5

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  • could be automatic: a setting could enforce it
  1. Distinctive:

    [TESTING.md](docs/TESTING.md): - Test strategy, coverage requirements, CI/CD

    line 10
  2. Very specific:

    Reuse existing code: Search src/util.rs, src/output.rs, src/client.rs, and src/settings.rs before writing new helpers.

    line 21
  3. Distinctive:

    Test both paths: Every change must include positive tests (happy path) and negative tests (error cases, bad input, edge cases).

    line 22
  4. Very specific:

    No vulnerable dependencies: Only use latest stable crate versions with no known CVEs.

    line 24
  5. Distinctive:

    All commands follow consistent patterns:

    line 77
  6. Distinctive:

    Follow Rust conventions and idioms

    line 106
  7. Very specific:

    Use cargo fmt and cargo clippy

    line 107
  8. Distinctive:

    Keep functions small and focused

    line 108
  9. Distinctive:

    Write clear, self-documenting code

    line 109
  10. Very specific:

    Use anyhow for application errors: anyhow::bail!("context")

    line 112
  11. Distinctive:

    Never expose API keys in errors

    line 114
  12. Distinctive:

    Write unit tests for public functions

    line 117
  13. Very specific:

    Use #[test] with assert_eq!

    line 118
  14. Distinctive:

    Never commit credentials (API keys, tokens, secrets)

    line 179
  15. Distinctive:

    Never log or print access/refresh tokens

    line 180
  16. Distinctive:

    Use PKCE S256 for OAuth2 flows

    line 182
  17. Distinctive:

    Default values (lowest priority)

    line 190

≈ “Common” is an estimate: at least 1 in 5 of the 27,641 CLAUDE.md files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
CLAUDE.md

Pup - Datadog API CLI

Rust-based CLI wrapper for Datadog APIs. Provides OAuth2 + API key authentication across a wide range of Datadog product domains.

Documentation Index

  • ALIASES.md - Alias management (storage, commands, expansion)
  • COMMANDS.md - Complete command reference
  • CONTRIBUTING.md - Git workflow, PR process, commit format
  • TESTING.md - Test strategy, coverage requirements, CI/CD
  • REVIEW.md - Code review guidelines (read before submitting PRs)
  • OAUTH2.md - OAuth2 implementation details (DCR, PKCE, token storage)
  • EXAMPLES.md - Usage examples and common workflows
  • ARCHITECTURE.md - Design decisions and technical details
  • TROUBLESHOOTING.md - Common issues and debugging

Review Guidelines

All PRs are reviewed against docs/REVIEW.md. Read it before submitting. Key rules:

  • Reuse existing code. Search src/util.rs, src/output.rs, src/client.rs, and src/settings.rs before writing new helpers. src/formatter.rs and src/config.rs are generator-owned contracts; hand-maintained output logic belongs in src/output.rs, and configuration loading and precedence belong in src/settings.rs. Do not duplicate functionality that already exists.
  • Test both paths. Every change must include positive tests (happy path) and negative tests (error cases, bad input, edge cases).
  • No malicious code. Obfuscated logic, backdoors, exfiltration, or unauthorized network calls result in rejection and a ban.
  • No vulnerable dependencies. Only use latest stable crate versions with no known CVEs. Run cargo audit before submitting.
  • Keep it simple. Small functions, shallow nesting, no premature abstractions. Prefer explicit over clever.
  • Follow Rust standards. cargo fmt, cargo clippy -- -D warnings, anyhow for errors, idiomatic Option/Result usage.
  • Minimal diffs. One concern per PR. Don't touch unrelated code, reformat untouched files, or add unnecessary improvements.

Quick Start

# Install via Homebrew (recommended)
brew tap datadog-labs/pack
brew install pup

# Or clone and build from source
git clone https://github.com/DataDog/pup.git && cd pup
cargo build --release
cp target/release/pup /usr/local/bin/pup

# Authenticate (OAuth2 recommended)
pup auth login

# Or use API keys (legacy)
export DD_API_KEY="key" DD_APP_KEY="key" DD_SITE="datadoghq.com"

# Run a command
pup monitors list --tag="env:production"
pup metrics query --query="avg:system.cpu.user{*}" --from="1h"

Project Structure

pup/
├── src/
│   ├── main.rs            # CLI entry point, clap enums, command routing
│   ├── commands/           # Command modules (monitors.rs, logs.rs, runbooks.rs, etc.)
│   ├── auth/              # OAuth2 + DCR + PKCE + token storage
│   ├── runbooks/          # Runbook engine (loader, template renderer, executor)
│   ├── client.rs          # Datadog API client wrapper
│   ├── config.rs          # Generator-owned configuration contract
│   ├── formatter.rs       # Generator-owned formatting contract
│   ├── output.rs          # Output rendering and printing (JSON envelope, YAML, table, CSV, TSV)
│   ├── settings.rs        # Configuration loading, precedence, and storage paths
│   ├── useragent.rs       # AI agent detection (User-Agent token, prompt auto-approval)
│   ├── util.rs            # Time parsing, validation
│   └── version.rs         # Version and build info
├── tests/                 # E2E parity report
├── docs/                  # Extended documentation
├── Cargo.toml             # Rust dependencies
└── Cargo.lock

Command Structure

All commands follow consistent patterns:

pup <domain> <action> [options]
pup <domain> <subgroup> <action> [options]

# Examples
pup monitors list --tag="env:prod"
pup logs search --query="status:error" --from="1h"
pup rum apps list
pup security rules list

See COMMANDS.md for complete reference.

Development Workflow (For Agents)

1. Branch Creation

git checkout -b <type>/<description>

# Types: feat, fix, refactor, docs, test, chore, perf
# Example: feat/add-metrics-filtering

2. Code Changes

Code Style:

  • Follow Rust conventions and idioms
  • Use cargo fmt and cargo clippy
  • Keep functions small and focused
  • Write clear, self-documenting code

Error Handling:

  • Use anyhow for application errors: anyhow::bail!("context")
  • Wrap errors with context: .map_err(|e| anyhow::anyhow!("context: {e:?}"))
  • Never expose API keys in errors

Testing:

  • Write unit tests for public functions
  • Use #[test] with assert_eq!
  • Mock external dependencies
  • Run with cargo test

3. Commit

Stage specific files and commit with conventional format:

git add src/commands/specific_file.rs
git commit -m "$(cat <<'EOF'
<type>(<scope>): <subject>

<body describing what and why>

- Key change 1
- Key change 2

Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
EOF
)"

Commit types: feat, fix, docs, style, refactor, test, chore

4. Create PR

gh pr create \
  --title "<type>(<scope>): <clear title>" \
  --body "$(cat <<'EOF'
## Summary
1-2 sentences describing what and why.

## Changes
- Change 1 with file reference (src/commands/foo.rs:123)
- Change 2 with file reference

## Testing
- How changes were tested
- Test coverage details

## Related Issues
Closes #N

---
🤖 Generated with [Claude Code](https://claude.com/claude-code)
EOF
)"

See CONTRIBUTING.md for detailed workflow and examples.

Security Requirements

Authentication:

  • OAuth2 with PKCE (recommended): pup auth login
  • API keys (legacy): DD_API_KEY + DD_APP_KEY + DD_SITE
  • Token storage: OS keychain (primary), JSON file with 0600 permissions (fallback)

Security Rules:

  • Never commit credentials (API keys, tokens, secrets)
  • Never log or print access/refresh tokens
  • Validate all user inputs to prevent injection
  • Use PKCE S256 for OAuth2 flows
  • Restrict fallback token-storage file to 0600 permissions

Configuration Precedence

  1. Command-line flags (highest priority)
  2. Environment variables
  3. Config file (~/.config/pup/config.yaml)
  4. Default values (lowest priority)

CI/CD Requirements

All PRs must pass:

  • cargo test
  • cargo clippy -- -D warnings
  • cargo fmt --check
  • Cross-compilation for 4 targets

See TESTING.md for details.

Core Dependencies

  • Rust (stable)
  • datadog-api-client-rust - Official API client (pinned to a git rev in Cargo.toml)
  • clap v4 - CLI framework (derive macros)
  • tokio - Async runtime
  • serde + serde_json + serde_norway - Serialization
  • keyring v3 - OS keychain integration
  • reqwest - HTTP client

License

Apache 2.0 - Copyright 2024-present Datadog, Inc.

Support

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.