Clippy Prometheus

CLI que traduz linguagem natural em queries Prometheus (PromQL) usando IA.

$ clippy "show CPU usage percentage per instance"

  📎 Clippy Prometheus — natural language → PromQL

  PromQL: 100 - (avg by (instance) (rate(node_cpu_seconds_total{mode="idle"}[5m])) * 100)
  Info:   Calculates CPU usage % by subtracting idle time from 100 for each instance

Setup

bun install

# Defina sua chave (gratis em https://openrouter.ai/keys)
export OPENROUTER_API_KEY=sk-or-...

Uso

# Query direta
bun run clippy "which targets are down?"

# Modo interativo
bun run clippy -i

# Saida raw (para piping)
bun run clippy -r "HTTP error rate" | clipboard

# Trocar modelo
bun run clippy -m "google/gemma-3-27b-it:free" "memory usage"

# Ver exemplos
bun run clippy --examples

Opcoes

-r, --raw            Imprime apenas o PromQL (sem formatacao)
-v, --verbose        Mostra qual modelo respondeu
-m, --model <model>  Usar outro modelo LLM
-i, --interactive    Modo REPL interativo
--examples           Mostra queries de exemplo

Modo interativo

$ bun run clippy -i

  📎 Clippy Prometheus — natural language → PromQL

  clippy> which services have high error rate?

  PromQL: sum by (job) (rate(http_requests_total{status=~"5.."}[5m])) / ...
  Info:   Shows services where more than 5% of requests return 5xx

Configuracao

| Variavel | Obrigatorio | Default | | -------------------- | ----------- | ------------------------------------ | | OPENROUTER_API_KEY | Sim | — | | CLIPPY_MODEL | Nao | google/gemini-3-flash-preview |

Modelos free disponiveis

# Gemini 3 Flash (default)
CLIPPY_MODEL=google/gemini-3-flash-preview

# Gemini 3 Pro
CLIPPY_MODEL=google/gemini-3-pro-preview

# Free router (escolhe o melhor free automaticamente)
CLIPPY_MODEL=openrouter/free

Arquitetura

src/
├── cli.ts          # Entry point (commander)
├── client.ts       # API client OpenRouter + parser
├── config.ts       # Leitura de env vars
├── display.ts      # Output formatado (chalk)
├── interactive.ts  # Modo REPL
├── prompt.ts       # System prompt com conhecimento PromQL
├── types.ts        # TypeScript types
└── *.test.ts       # Testes

Fluxo: pergunta → OpenRouter (LLM free) → parse PROMQL/EXPLANATION → output

Dev

bun test          # Rodar testes
bun run dev       # Watch mode

License

MIT