<!-- Copyright (c) 2026 defconxt. All rights reserved. -->
<!-- Licensed under AGPL-3.0 — see LICENSE file for details. -->

# API Reference — Security Metrics Program

## Agent Tools

| Tool | Description |
|---|---|
| KPI Definer | `define_kpis(domains)` — Recommend KPIs per domain |
| Trend Analyzer | `calculate_trends(data)` — Detect metric direction |
| Report Generator | `generate_report(metrics, targets)` — Executive summary |

## CLI Usage

```bash
# Define KPIs
node agent.js kpis --domains '["detection", "response"]'

# Calculate trends
node agent.js trends --data '[{"timestamp": "2026-01", "value": 48}]'

# Generate report
node agent.js report --metrics '{"mttd": 18}' --targets '{"mttd": 24}'
```

## Output Format

All commands return JSON with the following structure:

```json
{
  "action": "<command_name>",
  "...": "command-specific fields"
}
```

## Error Handling

- Invalid input returns `{"error": "description"}` with non-zero exit code
- JSON parsing errors are caught and reported with context
- Missing required arguments trigger argparse help display
