@gilangjavier/amctl

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)

npx @gilangjavier/amctl <command>

No installation required. Runs directly via npx.

Quick Commands

# 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

npm install -g @gilangjavier/amctl

Setup Profile

Initialize configuration:

amctl init

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

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:

amctl alerts --severity critical

Silence an alert during maintenance:

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

# List silences to find the ID
amctl silences

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

Check cluster status:

amctl status

Export alerts for analysis:

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:

# 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

Include:

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

License

MIT - See LICENSE file for details.