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

# API Reference — Security Budget Management

## Agent Tools

| Tool | Description |
|---|---|
| ROI Calculator | `calculate_roi(investment, reduction, ale)` — Quantify returns |
| Budget Allocator | `allocate_budget(total, priorities)` — Distribute by weight |
| Spend Analyzer | `analyze_spend(actuals, planned)` — Variance analysis |

## CLI Usage

```bash
# Calculate ROI
node agent.js roi --investment 100000 --reduction 0.3 --ale 500000

# Allocate budget
node agent.js allocate --total 2500000 --priorities '{"personnel": 5}'

# Variance analysis
node agent.js variance --actuals '{"tooling": 600000}' --planned '{"tooling": 500000}'
```

## 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
