npm package: @gilangjavier/amctl
Description: Alertmanager CLI
Latest version: 0.1.0

# @gilangjavier/amctl

[![npm](https://img.shields.io/npm/v/@gilangjavier/amctl.svg)](https://www.npmjs.com/package/@gilangjavier/amctl)
[![GitHub](https://img.shields.io/badge/GitHub-gilangjavier%2Famctl-blue)](https://github.com/gilangjavier/amctl)
[![TypeScript](https://img.shields.io/badge/TypeScript-5.8-blue)](https://www.typescriptlang.org/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

CLI tool for Prometheus Alertmanager with token optimization for AI agents.

## Token Savings

| Operation | Standard API | amctl | Savings |
|-----------|--------------|-------|---------|
| List alerts | ~3,200 tokens | ~600 tokens | 81% |
| List silences | ~2,800 tokens | ~500 tokens | 82% |
| Create silence | ~2,500 tokens | ~450 tokens | 82% |
| Expire silence | ~1,200 tokens | ~250 tokens | 79% |
| Check status | ~2,000 tokens | ~400 tokens | 80% |
| Health check | ~800 tokens | ~200 tokens | 75% |
| **Average** | | | **80%** |

## For AI Agents

### Installation (Ephemeral)

```bash
npx @gilangjavier/amctl <command>
```

No installation required. Runs directly via npx.

### Quick Commands

```bash
# List active alerts
npx @gilangjavier/amctl alerts

# Filter alerts by state
npx @gilangjavier/amctl alerts --state active

# Filter alerts by severity
npx @gilangjavier/amctl alerts --severity critical

# List all silences
npx @gilangjavier/amctl silences

# Create a silence
npx @gilangjavier/amctl silence-create \
  --matcher 'instance=server01' \
  --matcher 'severity=warning' \
  --ends-at '2024-12-31T23:59:59Z' \
  --created-by 'oncall-bot' \
  --comment 'Maintenance window'

# Expire a silence
npx @gilangjavier/amctl silence-expire <silence-id>

# Check Alertmanager status
npx @gilangjavier/amctl status

# Check health endpoint
npx @gilangjavier/amctl health

# Show current config
npx @gilangjavier/amctl config
```

### Expected Behavior

**Exit Codes:**
- `0` - Success
- `1` - Error (connection failed, invalid input, config missing)

**Output Format:**
- Default: Human-readable tables
- `--output json` or `-o json`: Structured JSON for programmatic use

**Profile Selection:**
- `-p, --profile <name>` - Use specific profile from config

### Before/After Token Comparison

**Before (direct Alertmanager API calls):**
```
Raw JSON response with metadata, nested objects, timestamps in multiple formats
~3,200 tokens for a typical alerts list response
```

**After (amctl):**
```
Clean table output with essential data only
~600 tokens for the same alerts list
```

## For Humans

### Installation

```bash
npm install -g @gilangjavier/amctl
```

### Setup Profile

Initialize configuration:

```bash
amctl init
```

This creates `~/.config/amctl/profiles.yaml` with a sample profile. Edit it:

```yaml
profiles:
  default:
    url: http://localhost:9093
    token_env: ALERTMANAGER_TOKEN    # Use env var
    # OR
    token_file: /path/to/token       # Read from file
    # OR
    token: "bearer-token-here"       # Inline (not recommended)
```

Token priority (highest first):
1. `token_env` - Environment variable name
2. `token_file` - Path to file containing token
3. `token` - Inline token string

### All Available Commands

| Command | Description | Options |
|---------|-------------|---------|
| `amctl init` | Create sample config | `--force` to overwrite |
| `amctl config` | Show current config | `-p, --profile` |
| `amctl alerts` | List active alerts | `--state <active\|suppressed\|unprocessed>`, `--severity` |
| `amctl silences` | List silences | `-p, --profile` |
| `amctl silence-create` | Create a new silence | `--matcher`, `--starts-at`, `--ends-at`, `--created-by`, `--comment` |
| `amctl silence-expire <id>` | Expire a silence by ID | `-p, --profile` |
| `amctl status` | Get routing/cluster status | `-p, --profile` |
| `amctl health` | Check Alertmanager health | `-p, --profile` |

Global flags available for all commands:
- `-p, --profile <name>` - Use specific profile
- `-o, --output <format>` - Output format: `table` or `json`

### Common Workflows

**View critical alerts:**
```bash
amctl alerts --severity critical
```

**Silence an alert during maintenance:**
```bash
# First, identify the alert labels
amctl alerts --state active

# Create a silence matching those labels
amctl silence-create \
  --matcher 'instance=web-01.example.com' \
  --matcher 'alertname=HighMemoryUsage' \
  --ends-at '2024-01-15T06:00:00Z' \
  --created-by 'ops-team' \
  --comment 'Scheduled maintenance window'
```

**Expire a silence early:**
```bash
# List silences to find the ID
amctl silences

# Expire the silence
amctl silence-expire 8f2d4c1e-3a5b-4c6d-7e8f-9a0b1c2d3e4f
```

**Check cluster status:**
```bash
amctl status
```

**Export alerts for analysis:**
```bash
amctl alerts --output json > alerts.json
```

## Token Optimization Details

### Filtering

amctl implements intelligent filtering to reduce data volume:

| Filter | Description |
|--------|-------------|
| `--state` | Filter alerts by state (active, suppressed, unprocessed) |
| `--severity` | Filter alerts by severity label |
| Column selection | Only essential columns displayed in table mode |

### Caching (ETag)

amctl implements HTTP ETag caching to reduce redundant API calls:

1. **Conditional requests** - Uses `If-None-Match` header with stored ETags
2. **304 responses** - Returns cached data when content has not changed
3. **Per-profile cache** - Cache keys include profile name for isolation

Benefits:
- Reduced network latency on repeated calls
- Lower token consumption for unchanged data
- Automatic cache invalidation when Alertmanager state changes

### Deterministic Output

amctl produces consistent, predictable output:

| Component | Standard Response | amctl Output |
|-----------|-------------------|--------------|
| HTTP headers | Full headers | Stripped |
| JSON metadata | `status`, `data`, nested objects | Direct values |
| Timestamps | Unix seconds, ISO8601 mixed | Consistent ISO8601 |
| Alert labels | Full label set with internals | Curated relevant labels |
| Silence state | Multiple fields per silence | Condensed status column |
| Empty arrays | Included | Omitted from tables |
| Error messages | Verbose stack traces | Clean error messages |

Output is sorted and formatted consistently across runs for reliable parsing.

## Contributing

### For AI Agents

To suggest improvements or test changes:

1. Review the codebase structure in `src/`
2. Identify optimization opportunities
3. Document findings in GitHub issues:
   ```
   https://github.com/gilangjavier/amctl/issues
   ```

### For Humans

**Development Setup:**

```bash
# Clone the repository
git clone https://github.com/gilangjavier/amctl.git
cd amctl

# Install dependencies
npm install

# Build TypeScript
npm run build

# Run tests
npm test

# Run in development mode
npm run dev -- alerts
```

**Submitting Changes:**

1. Fork the repository
2. Create a feature branch: `git checkout -b feature/my-change`
3. Make changes and add tests
4. Run the test suite: `npm test`
5. Commit with clear messages
6. Push and open a Pull Request

**Reporting Issues:**

- [GitHub Issues](https://github.com/gilangjavier/amctl/issues)

Include:
- amctl version (`amctl --version`)
- Node.js version (`node --version`)
- Alertmanager version
- Steps to reproduce
- Expected vs actual output

## License

MIT - See [LICENSE](LICENSE) file for details.