promql-cli

CLI for querying Prometheus and PromQL-compatible engines (Thanos, Cortex, VictoriaMetrics, Grafana Mimir, Grafana Tempo...) — instant queries, range queries, metric discovery (metrics/labels/meta subcommands), output formats (table/csv/json/graph). Apply when executing PromQL queries, troubleshooting performance issues on a software having observability, investigating latency/error rates/saturation, or analyzing time series data.

6 stars

Best use case

promql-cli is best used when you need a repeatable AI agent workflow instead of a one-off prompt.

CLI for querying Prometheus and PromQL-compatible engines (Thanos, Cortex, VictoriaMetrics, Grafana Mimir, Grafana Tempo...) — instant queries, range queries, metric discovery (metrics/labels/meta subcommands), output formats (table/csv/json/graph). Apply when executing PromQL queries, troubleshooting performance issues on a software having observability, investigating latency/error rates/saturation, or analyzing time series data.

Teams using promql-cli should expect a more consistent output, faster repeated execution, less prompt rewriting.

When to use this skill

  • You want a reusable workflow that can be run more than once with consistent structure.

When not to use this skill

  • You only need a quick one-off answer and do not need a reusable workflow.
  • You cannot install or maintain the underlying files, dependencies, or repository context.

Installation

Claude Code / Cursor / Codex

$curl -o ~/.claude/skills/promql-cli/SKILL.md --create-dirs "https://raw.githubusercontent.com/Harmeet10000/skills/main/skills/backend/promql-cli/SKILL.md"

Manual Installation

  1. Download SKILL.md from GitHub
  2. Place it in .claude/skills/promql-cli/SKILL.md inside your project
  3. Restart your AI agent — it will auto-discover the skill

How promql-cli Compares

Feature / Agentpromql-cliStandard Approach
Platform SupportNot specifiedLimited / Varies
Context Awareness High Baseline
Installation ComplexityUnknownN/A

Frequently Asked Questions

What does this skill do?

CLI for querying Prometheus and PromQL-compatible engines (Thanos, Cortex, VictoriaMetrics, Grafana Mimir, Grafana Tempo...) — instant queries, range queries, metric discovery (metrics/labels/meta subcommands), output formats (table/csv/json/graph). Apply when executing PromQL queries, troubleshooting performance issues on a software having observability, investigating latency/error rates/saturation, or analyzing time series data.

Where can I find the source code?

You can find the source code on GitHub using the link provided at the top of the page.

SKILL.md Source

# promql-cli — Prometheus Query CLI Skill

`promql-cli` (github.com/nalbury/promql-cli) is a Go CLI for querying, analyzing, and visualizing Prometheus metrics, plus PromQL fundamentals.

## Reference Files

Read the relevant reference file(s) before executing tasks:

| File | When to read |
| --- | --- |
| `references/installation.md` | User needs to install promql-cli or set up configuration (hosts, auth, token, password, multi-host) |
| `references/usage.md` | User wants to discover metrics/exporters/labels, run queries, or choose output formats |
| `references/graphing.md` | User wants to visualize Prometheus data as an ASCII chart in the terminal |
| `references/debugging.md` | User is investigating a performance issue, latency, errors, or saturation |
| `references/promql-reference.md` | User needs help writing PromQL, understanding metric types, functions, or aggregations |

For most tasks, read `references/usage.md`. For PromQL help, read `references/promql-reference.md`. When debugging, read both `references/debugging.md` and `references/promql-reference.md`.

## Setup Check

Before running any query, verify that a host is configured:

```bash
promql 'up'   # succeeds if host is reachable; fails with connection error if not configured
# or
promql --host xxx 'up'
```

Recognize these errors as a configuration/auth problem and refer to `references/installation.md`:

| Error | Cause |
| --- | --- |
| `dial tcp ... connection refused` | No host running at the configured address |
| `dial tcp ... no such host` | Hostname not resolved — wrong host in config |
| `error querying prometheus: ...401...` | Bearer token missing or invalid |
| `error querying prometheus: ...403...` | Token valid but insufficient permissions |
| `please specify an authentication type` | Auth flags partially set — use config file instead |

If any of these appear, **do not create config files on behalf of the user** — config files may contain credentials (tokens, passwords) that must never pass through an LLM. Instead, guide the user to set it up themselves:

> "Please create `~/.promql-cli.yaml` manually with your Prometheus host (and credentials if needed). See `references/installation.md` for the exact format. Let me know once it's ready."

Only after the user confirms the config is in place should you proceed with queries.

## Quick Command Reference

```bash
promql 'up'                                          # instant query
promql 'rate(http_requests_total[5m])' --start 1h    # range query (ASCII graph)
promql 'up' --output csv                             # CSV output
promql 'up' --output json                            # JSON output
promql metrics                                       # list all metric names
promql labels <metric>                               # list labels for a metric
promql meta <metric>                                 # show metric type and help
promql --config ~/.promql-cli-prod.yaml 'up'         # target a specific host
```

## Key Principles

1. **Use `rate()` on counters, never raw values** — raw counters only ever increase; the absolute value is meaningless. `rate()` gives the per-second change rate, which is what you actually care about.
2. **When debugging, isolate a single instance** — aggregating across replicas masks per-instance anomalies. A single overloaded pod hidden behind healthy peers won't show up in averages.
3. **Filter early with label matchers in the innermost selector** — Prometheus evaluates selectors before functions, so filtering late means scanning all time series. Early filters reduce data scanned and query latency.
4. **For histograms, keep `le` in the `by` clause** before `histogram_quantile()` — the function needs all `le` buckets to interpolate percentiles; dropping `le` early produces `NaN` or wrong results.
5. **Prefer `--output graph` for range queries** — ASCII sparklines convey trend direction (rising, falling, spiking) in a compact format that LLMs parse well; raw timestamp tables require mental modeling.
6. **Store credentials in `~/.promql-cli.yaml` and `~/.promql_token`, chmod 600** — passing tokens as CLI args exposes them in shell history and process listings.

This skill is not exhaustive. Please refer to the [official promql-cli documentation](https://github.com/nalbury/promql-cli) and examples for up-to-date information. Context7 can help as a discoverability platform.

If you encounter a bug or unexpected behavior in promql-cli itself, open an issue at https://github.com/nalbury/promql-cli/issues.

Related Skills

Goal: Build an LLM-based RAG App

6
from Harmeet10000/skills

Here is the MVP Implementation Plan.

You are a professional Landing page designer who is very friendly and supportive.

6
from Harmeet10000/skills

Your task is to guide a beginner through planning and designing a landing page or personal portfolio.

Workflow & Productivity

You are a professional Chief Marketing Officer. Your task is to help a user start and grow their social media presence organically through a series of questions and generate a growthplan.md blueprint.

6
from Harmeet10000/skills

Follow these instructions:

Marketing Strategy

Convert this into a web based slide deck using reveal.js.

6
from Harmeet10000/skills

Use the following brand colour and logo.

technical-article-writer

6
from Harmeet10000/skills

Write compelling technical articles and blog posts for developer audiences. Use this skill whenever the user asks to write a blog post, technical article, or any long-form technical content. Also trigger when the user says 'write about [technical topic]', 'help me draft an article', 'turn this into a blog post', 'write a post about', 'I want to publish something about', or mentions writing for a developer audience. Covers the full pipeline: idea sharpening, hook/title generation, article structure, body drafting, and editing. Even if the user just says 'I want to write about X' without specifying format, use this skill. Do NOT use for platform-specific optimization, newsletter strategy, or ghostwriting voice matching.

substack-ghostwriting

6
from Harmeet10000/skills

Write, optimize, and grow Substack content — both newsletter issues (email-first) and web posts (web-first articles/essays). Covers ghostwriting with voice matching, Substack algorithm optimization, Notes strategy, email formatting, SEO, growth tactics, and monetization planning. Use when the user mentions Substack, newsletters, write a newsletter issue, Substack post, Substack article, web post on Substack, evergreen content, SEO for Substack, newsletter growth, Notes strategy, ghostwrite for, match someone's voice, write in the style of, newsletter monetization, paid subscribers, or any task involving Substack as a platform. Also trigger for general article/newsletter writing even if Substack isn't named explicitly, or when the user wants to adapt existing content (blog post, talk, thread) into newsletter or web post format. Do NOT use for generic blog post writing without a newsletter/Substack context (-> See samber/cc-skills@technical-article-writer skill).

press-release-writer

6
from Harmeet10000/skills

Write professional press releases for any occasion, media type, and country. Use when the user wants to write, draft, or improve a press release, communiqué de presse, media announcement, news release, or PR statement — including product launches, funding rounds, partnerships, crisis communications, earnings, executive hires, events, M&A, open source milestones, and media advisories. Covers all release types, media targets (print, digital/wire, broadcast, social/SMPR, trade press), and region-specific conventions (Western/Eastern Europe, Americas, Middle East, Africa, Asia, Oceania). Also trigger when the user says 'I need to announce something' or 'how do I tell the press about X.'

pdf

6
from Harmeet10000/skills

Use this skill whenever the user wants to do anything with PDF files. This includes reading or extracting text/tables from PDFs, combining or merging multiple PDFs into one, splitting PDFs apart, rotating pages, adding watermarks, creating new PDFs, filling PDF forms, encrypting/decrypting PDFs, extracting images, and OCR on scanned PDFs to make them searchable. If the user mentions a .pdf file or asks to produce one, use this skill.

linkedin-ghostwriting

6
from Harmeet10000/skills

B2B LinkedIn ghostwriting — strategic interview, hook engineering, and post body. Use when the user wants to write LinkedIn content, create ghostwritten posts, ghostwrite for a founder or executive, develop a B2B social strategy, or needs hooks, post structures, or copywriting frameworks for LinkedIn. Apply when the user shares a story, result, or insight and wants it turned into a post.

docx

6
from Harmeet10000/skills

Use this skill whenever the user wants to create, read, edit, or manipulate Word documents (.docx files). Triggers include: any mention of 'Word doc', 'word document', '.docx', or requests to produce professional documents with formatting like tables of contents, headings, page numbers, or letterheads. Also use when extracting or reorganizing content from .docx files, inserting or replacing images in documents, performing find-and-replace in Word files, working with tracked changes or comments, or converting content into a polished Word document. If the user asks for a 'report', 'memo', 'letter', 'template', or similar deliverable as a Word or .docx file, use this skill. Do NOT use for PDFs, spreadsheets, Google Docs, or general coding tasks unrelated to document generation.

documentation

6
from Harmeet10000/skills

Creates, structures, and reviews technical documentation following the Diátaxis framework (tutorials, how-to guides, reference, and explanation pages). Use when a user needs to write or reorganize docs, structure a tutorial vs. a how-to guide, build reference docs or API documentation, create explanation pages, choose between Diátaxis documentation types, or improve existing documentation structure. Trigger terms include: documentation structure, Diátaxis, tutorials vs how-to guides, organize docs, user guide, reference docs, technical writing.

doc-coauthoring

6
from Harmeet10000/skills

Guide users through a structured workflow for co-authoring documentation. Use when user wants to write documentation, proposals, technical specs, decision docs, or similar structured content. This workflow helps users efficiently transfer context, refine content through iteration, and verify the doc works for readers. Trigger when user mentions writing docs, creating proposals, drafting specs, or similar documentation tasks.