feat(costs): add Cloud Cost Management commands and restructure cost group

README.md

@@ -169,7 +169,7 @@ See [docs/COMMANDS.md](docs/COMMANDS.md) for detailed command reference.
 | API Domain | Status | Pup Commands | Notes |
 |------------|--------|--------------|-------|
 | Usage Metering | ✅ | `usage summary`, `usage hourly` | Usage and billing metrics |
-| Cost Management | ✅ | `cost projected`, `cost attribution`, `cost by-org`, `cost aws-config`, `cost azure-config`, `cost gcp-config` | Cost attribution plus AWS/Azure/GCP cloud cost config management |
+| Cost Management | ✅ | `costs datadog projected`, `costs datadog attribution`, `costs datadog by-org`, `costs datadog aws-config`, `costs datadog azure-config`, `costs datadog gcp-config`, `costs ccm custom-costs`, `costs ccm tag-descriptions`, `costs ccm tag-metadata`, `costs ccm tags`, `costs ccm tag-keys`, `costs ccm budgets`, `costs ccm commitments` | Cost attribution, cloud cost configs (AWS/Azure/GCP), and Cloud Cost Management (custom costs, tag descriptions, budgets, commitment programs) |
 | Product Analytics | ✅ | `product-analytics events send`, `product-analytics query` | Server-side product analytics events and queries |
 | Integrations | ✅ | `integrations slack`, `integrations pagerduty`, `integrations webhooks`, `integrations jira`, `integrations servicenow`, `integrations google-chat` | Third-party integrations with Jira, ServiceNow, and Google Chat support |
 | Observability Pipelines | ✅ | `obs-pipelines list`, `obs-pipelines get`, `obs-pipelines create`, `obs-pipelines update`, `obs-pipelines delete`, `obs-pipelines validate` | Full pipeline CRUD and validation |

docs/COMMANDS.md

@@ -57,7 +57,7 @@ pup <domain> <subgroup> <action> [options] # Nested commands
 | usage | summary, hourly | src/commands/usage.rs | ✅ |
 | apm | services (list, stats, operations, resources), entities (list), dependencies (list), flow-map, troubleshooting (list), service-config (get), service-library-config (get) | src/commands/apm.rs | ✅ |
 | containers | list, images (list) | src/commands/containers.rs | ✅ |
-| cost | projected, attribution, by-org, aws-config (list, get, create, delete), azure-config (list, get, create, delete), gcp-config (list, get, create, delete) | src/commands/cost.rs | ✅ |
+| costs | datadog (projected, attribution, by-org, aws-config, azure-config, gcp-config), ccm (custom-costs, tag-descriptions, tag-metadata, tags, tag-keys, budgets, commitments) | src/commands/cost.rs, src/commands/cost_ccm.rs | ✅ |
 | product-analytics | events send | src/commands/product_analytics.rs | ✅ |
 | datasets | list, get, create, update, delete | src/commands/datasets.rs | ✅ |
 | data-deletion | requests (list, create, cancel) | src/commands/data_deletion.rs | ✅ |
@@ -193,7 +193,7 @@ pup infrastructure hosts list
 
 ### Cost & Usage
 - **usage** - Usage and billing (summary, hourly)
-- **cost** - Cost management (projected, attribution, by-org, aws-config, azure-config, gcp-config)
+- **costs** - Cost management: `datadog` subgroup (projected, attribution, by-org, aws-config, azure-config, gcp-config) and `ccm` subgroup (custom-costs, tag-descriptions, tag-metadata, tags, tag-keys, budgets, commitments)
 
 ### Configuration & Data Management
 - **obs-pipelines** - Observability pipelines (list, get, create, update, delete, validate)
@@ -242,7 +242,7 @@ Available on all commands:
 - ✅ **llm-obs** (new) — LLM Observability: projects (create, list), experiments (create, list, update, delete, summary, events (list, get), metric-values, dimension-values), datasets (create, list), spans (search)
 - ✅ **reference-tables** (new) — Reference table management (list, get, create, batch-query)
 - ✅ **obs-pipelines** (upgraded from placeholder) — Full CRUD: list, get, create, update, delete, validate
-- **cost** — Added cloud cost configs: `aws-config`, `azure-config`, `gcp-config` (list, get, create, delete each)
+- **costs** — Added cloud cost configs: `aws-config`, `azure-config`, `gcp-config` (list, get, create, delete each)
 
 ### v0.27.0 — Major Expansion
 

docs/EXAMPLES.md

@@ -832,6 +832,180 @@ pup idp owner payments-api
 pup idp deps payments-api
 ```
 
+## Costs
+
+### Datadog Cost (Usage Metering)
+```bash
+# Projected cost for current month
+pup costs datadog projected
+
+# Cost breakdown by org for a date range
+pup costs datadog by-org --start-month="2024-01-01T00:00:00Z" --end-month="2024-03-01T00:00:00Z"
+
+# Monthly cost attribution
+pup costs datadog attribution --start="2024-01-01T00:00:00Z"
+
+# AWS CUR config management
+pup costs datadog aws-config list
+pup costs datadog aws-config get 42
+pup costs datadog aws-config create --file=aws-cur.json
+pup costs datadog aws-config delete 42
+
+# Azure UC config management
+pup costs datadog azure-config list
+
+# GCP usage cost config management
+pup costs datadog gcp-config list
+```
+
+### Cloud Cost Management (CCM)
+
+#### Custom Costs
+```bash
+# List uploaded custom cost files
+pup costs ccm custom-costs list
+
+# Filter by status or sort
+pup costs ccm custom-costs list --status=SUCCESS --sort=created_at
+
+# Get a specific custom cost file
+pup costs ccm custom-costs get <file-id>
+
+# Upload a custom cost CSV (multipart PUT)
+pup costs ccm custom-costs upload --file=costs.csv
+
+# Upload with a schema version
+pup costs ccm custom-costs upload --file=costs.csv --version=2
+
+# Delete a custom cost file
+pup costs ccm custom-costs delete <file-id>
+```
+
+#### Tag Descriptions
+```bash
+# List all tag descriptions
+pup costs ccm tag-descriptions list
+
+# Filter by cloud provider
+pup costs ccm tag-descriptions list --cloud=aws
+
+# Get description for a specific tag key
+pup costs ccm tag-descriptions get --tag-key=env
+
+# Generate an AI-suggested description for a tag
+pup costs ccm tag-descriptions generate --tag-key=team
+
+# Create or update a tag description
+pup costs ccm tag-descriptions upsert --tag-key=env --description="Deployment environment"
+
+# Delete a tag description
+pup costs ccm tag-descriptions delete --tag-key=env
+```
+
+#### Tag Metadata
+```bash
+# List all tag metadata for a month
+pup costs ccm tag-metadata list --month=2024-01
+
+# Filter by provider and metric
+pup costs ccm tag-metadata list --month=2024-01 --provider=aws --metric=aws.cost
+
+# List tag sources
+pup costs ccm tag-metadata tag-sources --month=2024-01
+
+# List available metrics
+pup costs ccm tag-metadata metrics --month=2024-01
+
+# List orchestrators
+pup costs ccm tag-metadata orchestrators --month=2024-01
+
+# List supported currencies
+pup costs ccm tag-metadata currency --month=2024-01
+```
+
+#### Tags and Tag Keys
+```bash
+# List all CCM tags
+pup costs ccm tags list
+
+# Filter by metric
+pup costs ccm tags list --metric=aws.cost
+
+# List tag keys
+pup costs ccm tag-keys list
+
+# Get details for a specific tag key
+pup costs ccm tag-keys get env
+```
+
+#### Budgets
+```bash
+# List all budgets
+pup costs ccm budgets list
+
+# Get a specific budget
+pup costs ccm budgets get <budget-id>
+
+# Get with actual and forecasted spend for a time range
+pup costs ccm budgets get <budget-id> \
+  --start="2024-01-01T00:00:00Z" \
+  --end="2024-03-01T00:00:00Z" \
+  --actual --forecast
+
+# Create or update a budget (upsert)
+pup costs ccm budgets upsert --file=budget.json
+
+# Delete a budget
+pup costs ccm budgets delete <budget-id>
+
+# Validate a budget payload without saving
+pup costs ccm budgets validate --file=budget.json
+```
+
+#### Commitment Programs (Reserved Instances & Savings Plans)
+```bash
+# Utilization of RIs over a time range
+pup costs ccm commitments utilization \
+  --provider=aws --product=EC2 \
+  --from=2024-01-01T00:00:00Z --to=2024-02-01T00:00:00Z
+
+# Coverage by Savings Plans
+pup costs ccm commitments coverage \
+  --provider=aws --product=EC2 \
+  --from=2024-01-01T00:00:00Z --to=2024-02-01T00:00:00Z \
+  --commitment-type=SP
+
+# Savings summary
+pup costs ccm commitments savings \
+  --provider=aws --product=RDS \
+  --from=2024-01-01T00:00:00Z --to=2024-02-01T00:00:00Z
+
+# On-demand hot spots (unreserved spend)
+pup costs ccm commitments hotspots \
+  --provider=aws --product=EC2 \
+  --from=2024-01-01T00:00:00Z --to=2024-02-01T00:00:00Z
+
+# Utilization time series
+pup costs ccm commitments utilization-ts \
+  --provider=aws --product=EC2 \
+  --from=2024-01-01T00:00:00Z --to=2024-02-01T00:00:00Z
+
+# Coverage time series
+pup costs ccm commitments coverage-ts \
+  --provider=aws --product=EC2 \
+  --from=2024-01-01T00:00:00Z --to=2024-02-01T00:00:00Z
+
+# Savings time series
+pup costs ccm commitments savings-ts \
+  --provider=aws --product=EC2 \
+  --from=2024-01-01T00:00:00Z --to=2024-02-01T00:00:00Z
+
+# List all commitment programs
+pup costs ccm commitments list \
+  --provider=aws --product=EC2 \
+  --from=2024-01-01T00:00:00Z --to=2024-02-01T00:00:00Z
+```
+
 ## Output Formatting
 
 ### JSON Output (Default)

scripts/test_harness.py

@@ -1361,10 +1361,10 @@ def status(self) -> str:
         "category": "no_auth",
         "expect_json": True,
     },
-    # ── cost ──────────────────────────────────────────────────────────────
+    # ── costs ─────────────────────────────────────────────────────────────
     {
-        "label": "cost projected",
-        "args": ["cost", "projected"],
+        "label": "costs datadog projected",
+        "args": ["costs", "datadog", "projected"],
         "category": "auth_required",
         "expect_json": True,
     },
@@ -1398,16 +1398,16 @@ def status(self) -> str:
         "expect_json": True,
     },
     {
-        "label": "cost attribution",
-        "args": ["cost", "attribution", "--start=2024-01"],
+        "label": "costs datadog attribution",
+        "args": ["costs", "datadog", "attribution", "--start=2024-01"],
         "category": "auth_required",
         "expect_json": True,
         "timeout": 90,
         "note": "pup bug: --start is routed through the generic relative-time parser instead of accepting YYYY-MM format; exits with parse error.",
     },
     {
-        "label": "cost by-org",
-        "args": ["cost", "by-org", "--start-month=2024-01"],
+        "label": "costs datadog by-org",
+        "args": ["costs", "datadog", "by-org", "--start-month=2024-01"],
         "category": "auth_required",
         "expect_json": True,
         "timeout": 90,
@@ -1468,22 +1468,22 @@ def status(self) -> str:
         "category": "auth_required",
         "expect_json": True,
     },
-    # ── cost cloud configs ─────────────────────────────────────────────────
+    # ── costs cloud configs ────────────────────────────────────────────────
     {
-        "label": "cost aws-config list",
-        "args": ["cost", "aws-config", "list"],
+        "label": "costs datadog aws-config list",
+        "args": ["costs", "datadog", "aws-config", "list"],
         "category": "auth_required",
         "expect_json": True,
     },
     {
-        "label": "cost azure-config list",
-        "args": ["cost", "azure-config", "list"],
+        "label": "costs datadog azure-config list",
+        "args": ["costs", "datadog", "azure-config", "list"],
         "category": "auth_required",
         "expect_json": True,
     },
     {
-        "label": "cost gcp-config list",
-        "args": ["cost", "gcp-config", "list"],
+        "label": "costs datadog gcp-config list",
+        "args": ["costs", "datadog", "gcp-config", "list"],
         "category": "auth_required",
         "expect_json": True,
     },
@@ -1641,25 +1641,25 @@ def status(self) -> str:
         "category": "auth_required",
         "expect_json": True,
     },
-    # ── cost cloud config gets ────────────────────────────────────────────
+    # ── costs cloud config gets ───────────────────────────────────────────
     {
-        "label": "cost aws-config get",
-        "args": ["cost", "aws-config", "get", "{id}"],
-        "id_from": {"args": ["cost", "aws-config", "list"], "json_path": ["data", 0, "id"]},
+        "label": "costs datadog aws-config get",
+        "args": ["costs", "datadog", "aws-config", "get", "{id}"],
+        "id_from": {"args": ["costs", "datadog", "aws-config", "list"], "json_path": ["data", 0, "id"]},
         "category": "auth_required",
         "expect_json": True,
     },
     {
-        "label": "cost azure-config get",
-        "args": ["cost", "azure-config", "get", "{id}"],
-        "id_from": {"args": ["cost", "azure-config", "list"], "json_path": ["data", 0, "id"]},
+        "label": "costs datadog azure-config get",
+        "args": ["costs", "datadog", "azure-config", "get", "{id}"],
+        "id_from": {"args": ["costs", "datadog", "azure-config", "list"], "json_path": ["data", 0, "id"]},
         "category": "auth_required",
         "expect_json": True,
     },
     {
-        "label": "cost gcp-config get",
-        "args": ["cost", "gcp-config", "get", "{id}"],
-        "id_from": {"args": ["cost", "gcp-config", "list"], "json_path": ["data", 0, "id"]},
+        "label": "costs datadog gcp-config get",
+        "args": ["costs", "datadog", "gcp-config", "get", "{id}"],
+        "id_from": {"args": ["costs", "datadog", "gcp-config", "list"], "json_path": ["data", 0, "id"]},
         "category": "auth_required",
         "expect_json": True,
     },

skills/dd-pup/SKILL.md

@@ -256,22 +256,22 @@ pup reference-tables batch-query --file query.json
 ### Cost Cloud Configs
 ```bash
 # AWS CUR configs
-pup cost aws-config list
-pup cost aws-config get <account-id>
-pup cost aws-config create --file config.json
-pup cost aws-config delete <account-id>
+pup costs datadog aws-config list
+pup costs datadog aws-config get <account-id>
+pup costs datadog aws-config create --file config.json
+pup costs datadog aws-config delete <account-id>
 
 # Azure UC configs
-pup cost azure-config list
-pup cost azure-config get <account-id>
-pup cost azure-config create --file config.json
-pup cost azure-config delete <account-id>
+pup costs datadog azure-config list
+pup costs datadog azure-config get <account-id>
+pup costs datadog azure-config create --file config.json
+pup costs datadog azure-config delete <account-id>
 
 # GCP usage cost configs
-pup cost gcp-config list
-pup cost gcp-config get <account-id>
-pup cost gcp-config create --file config.json
-pup cost gcp-config delete <account-id>
+pup costs datadog gcp-config list
+pup costs datadog gcp-config get <account-id>
+pup costs datadog gcp-config create --file config.json
+pup costs datadog gcp-config delete <account-id>
 ```
 
 ## Subcommand Discovery