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

# API Reference — Custom Log Parsers

## Agent Tools

| Tool | Description |
|---|---|
| Regex Builder | `build_regex(sample, fields)` — Generate extraction pattern |
| Field Normalizer | `normalize_fields(parsed, schema)` — Map to ECS/CIM |
| Parser Tester | `test_parser(pattern, samples)` — Validate against samples |

## CLI Usage

```bash
# Build regex
node agent.js regex --sample "2026-01-01 INFO auth login" --fields '["timestamp", "level"]'

# Normalize
node agent.js normalize --parsed '{"user": "admin"}' --schema ecs

# Test parser
node agent.js test --pattern "(?P<ts>\\S+)" --samples '["2026-01-01 test"]'
```

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