service-catalog

description: Explore and manage Datadog service and software catalog data with verified Pup commands, including ownership, definitions, kinds, and relationships.

Service Catalog Agent

Help users understand and maintain Datadog's service and software catalog. Use the narrowest Pup surface that matches the request, and inspect live command help when a flag is uncertain.

Route the request

• Use `pup idp kinds list` to inspect available entity schemas and `pup idp entities query` when a read needs connected service context: ownership, on-call, systems, code, dependencies, health, work, operations, or security. UEG can return selected service and dependency context in one bounded request. Load the `dd-idp` skill for its schema-first workflow and DSL guidance when available.
• Use `pup service-catalog list` for the legacy typed service registry.
• Use `pup idp assist` for a fast curated single-service summary, metadata gaps, and suggested next actions; use `owner` for convenient owner/on-call resolution. These trade graph fidelity for a narrower opinionated result.
• Treat `find` as a simple paginated literal service-name lookup. Explicit `kind:` and `ref:` queries remain compatibility paths; use `entities query` for non-service kinds, another lookback, broader relation families, selected fields, counts, pagination, and traversal. Use `deps` as a convenient one-hour UEG runtime service-to-service summary.
• Use `pup software-catalog entities list` for Catalog inventory. Only `entities` and `kinds` expose mutations; `relations` is read-only.
• Use `pup idp register` to preserve the familiar file-oriented workflow across v1, v2, v2.1, v2.2, and v3 Catalog definitions. It sends raw YAML or JSON to the Catalog entity API and accepts multi-document YAML.

Do not invoke the incomplete `pup idp kinds` group without a subcommand; use `list` or `describe`.

Service registry

pup --read-only service-catalog list
pup --read-only service-catalog get <service-name>

Connected service context

pup --read-only idp kinds describe service
pup --read-only idp entities query 'kind:service AND name:"<service-name>"' \
  --field name,display_name,owner,service_health_status,active_incidents_count,alert_monitors_count,breached_slos_count \
  --include owner_teams,systems,code_locations,upstream_services,downstream_services \
  --relation-limit 3 \
  --timeseries-interval 24h \
  --limit 1

This is the graph's central value: service identity, ownership, health, and declared dependencies in one call. Choose a small relation family and report relation counts/truncation. Add runtime dependencies, datastores, queues, deployments, incidents, monitors, SLOs, or security relations only when the request needs them.

Convenience service helpers

pup --read-only idp assist <service-name>
pup --read-only idp owner <service-name>
pup --read-only idp find '<service-name>'
pup --read-only idp deps <service-name>

General entity graph

Discover and describe before querying unfamiliar fields or relations:

pup --read-only idp kinds list
pup --read-only idp kinds describe service
pup --read-only idp entities query 'kind:service AND owner:"<team-handle>"' \
  --field name,display_name,owner,contacts \
  --include owner_teams,systems \
  --limit 25

Treat relationship expansions as bounded samples, follow returned refs, honor cursors, and treat null as unknown rather than zero or false.

Software Catalog inventory

pup --read-only software-catalog entities list --filter-kind service
pup --read-only software-catalog entities list --filter-owner <team>
pup --read-only software-catalog kinds list
pup --read-only software-catalog relations list

The Software Catalog entity API and the IDP entity graph are related but distinct contracts. Catalog inventory/mutations do not have the same query or relationship semantics as UEG.

Write workflows

Pup auto-approves CLI prompts when it detects an AI agent (and when `--yes` or `DD_AUTO_APPROVE` is set). Obtain the user's explicit authorization immediately before any remote mutation even when Pup would not prompt.

Register Catalog entities

Inspect the YAML and confirm the target org before running:

pup idp register path/to/service.datadog.yaml

This accepts v1 through v3 definitions and posts them to the Catalog entity API. YAML files may contain multiple documents separated by `---`; the server validates and ingests each supported schema without local conversion. Success returns the Catalog JSON:API entity response (`202 Accepted`), not the legacy service-definition response (`200 OK`). A successful response can still contain schema warnings under `included[].attributes.schema.metadata.managed.status.warnings`; resolve them before treating the definition as clean. For v3, omit `metadata.namespace`; the server assigns the default namespace.

Verify a returned ref against Catalog inventory before assuming it has propagated to UEG:

pup --read-only software-catalog entities list --filter-ref service:default/<service-name>

Catalog is the immediate source of truth after a write. UEG creation and deletion may lag by tens of seconds, so retry a bounded exact-ref query before concluding propagation failed.

Migrate a definition to v3

pup idp migrate-schema path/to/service.datadog.yaml

This may call the conversion API and writes a local result after choosing a destination. Review the generated v3 identity, ownership, links, integrations, systems, and relationships before any upload.

Catalog entities and kinds

Use valid JSON payloads and confirm the target org and intended mutation:

pup software-catalog entities upsert --file entity.json
pup software-catalog entities delete <entity-id>
pup software-catalog kinds upsert --file kind.json
pup software-catalog kinds delete <kind-id>

Never delete as cleanup or guess an entity identifier. Read