{"id":"15597d4b-d0d4-4416-9845-a7c9d56420a0","shortId":"LxXMBy","kind":"skill","title":"promql-cli","tagline":"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 qu","description":"# promql-cli — Prometheus Query CLI Skill\n\n`promql-cli` (github.com/nalbury/promql-cli) is a Go CLI for querying, analyzing, and visualizing Prometheus metrics, plus PromQL fundamentals.\n\n## Reference Files\n\nRead the relevant reference file(s) before executing tasks:\n\n| File | When to read |\n| --- | --- |\n| `references/installation.md` | User needs to install promql-cli or set up configuration (hosts, auth, token, password, multi-host) |\n| `references/usage.md` | User wants to discover metrics/exporters/labels, run queries, or choose output formats |\n| `references/graphing.md` | User wants to visualize Prometheus data as an ASCII chart in the terminal |\n| `references/debugging.md` | User is investigating a performance issue, latency, errors, or saturation |\n| `references/promql-reference.md` | User needs help writing PromQL, understanding metric types, functions, or aggregations |\n\nFor 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`.\n\n## Setup Check\n\nBefore running any query, verify that a host is configured:\n\n```bash\npromql 'up'   # succeeds if host is reachable; fails with connection error if not configured\n# or\npromql --host xxx 'up'\n```\n\nRecognize these errors as a configuration/auth problem and refer to `references/installation.md`:\n\n| Error | Cause |\n| --- | --- |\n| `dial tcp ... connection refused` | No host running at the configured address |\n| `dial tcp ... no such host` | Hostname not resolved — wrong host in config |\n| `error querying prometheus: ...401...` | Bearer token missing or invalid |\n| `error querying prometheus: ...403...` | Token valid but insufficient permissions |\n| `please specify an authentication type` | Auth flags partially set — use config file instead |\n\nIf 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:\n\n> \"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.\"\n\nOnly after the user confirms the config is in place should you proceed with queries.\n\n## Quick Command Reference\n\n```bash\npromql 'up'                                          # instant query\npromql 'rate(http_requests_total[5m])' --start 1h    # range query (ASCII graph)\npromql 'up' --output csv                             # CSV output\npromql 'up' --output json                            # JSON output\npromql metrics                                       # list all metric names\npromql labels <metric>                               # list labels for a metric\npromql meta <metric>                                 # show metric type and help\npromql --config ~/.promql-cli-prod.yaml 'up'         # target a specific host\n```\n\n## Key Principles\n\n1. **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.\n2. **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.\n3. **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.\n4. **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.\n5. **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.\n6. **Store credentials in `~/.promql-cli.yaml` and `~/.promql_token`, chmod 600** — passing tokens as CLI args exposes them in shell history and process listings.\n\nThis 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.\n\nIf you encounter a bug or unexpected behavior in promql-cli itself, open an issue at [https://github.com/nalbury/promql-cli/issues](https://github.com/nalbury/promql-cli/issues).","tags":["promql","cli","skills","samber","agent","agent-skills","antigravity","claude","claude-code","code","codex","coding"],"capabilities":["skill","source-samber","skill-promql-cli","topic-agent","topic-agent-skills","topic-antigravity","topic-claude","topic-claude-code","topic-code","topic-codex","topic-coding","topic-copilot","topic-cursor","topic-gemini","topic-gemini-cli-extension"],"categories":["cc-skills"],"synonyms":[],"warnings":[],"endpointUrl":"https://skills.sh/samber/cc-skills/promql-cli","protocol":"skill","transport":"skills-sh","auth":{"type":"none","details":{"cli":"npx skills add samber/cc-skills","source_repo":"https://github.com/samber/cc-skills","install_from":"skills.sh"}},"qualityScore":"0.489","qualityRationale":"deterministic score 0.49 from registry signals: · indexed on github topic:agent-skills · 79 github stars · SKILL.md body (4,581 chars)","verified":false,"liveness":"unknown","lastLivenessCheck":null,"agentReviews":{"count":0,"score_avg":null,"cost_usd_avg":null,"success_rate":null,"latency_p50_ms":null,"narrative_summary":null,"summary_updated_at":null},"enrichmentModel":"deterministic:skill-github:v1","enrichmentVersion":1,"enrichedAt":"2026-05-02T06:55:37.777Z","embedding":null,"createdAt":"2026-04-18T22:13:35.389Z","updatedAt":"2026-05-02T06:55:37.777Z","lastSeenAt":"2026-05-02T06:55:37.777Z","tsv":"'/.promql-cli-prod.yaml':394 '/.promql-cli.yaml':302,557 '/.promql_token':559 '/nalbury/promql-cli)':48,591 '/nalbury/promql-cli/issues](https://github.com/nalbury/promql-cli/issues).':626 '1':402 '1h':355 '2':435 '3':464 '4':495 '401':234 '403':243 '5':524 '5m':353 '6':553 '600':561 'absolut':416 'across':443 'actual':432 'address':218 'aggreg':145,442 'analyz':55 'anomali':449 'appear':266 'appli':31 'arg':566 'ascii':118,358,531 'auth':91,254 'authent':252 'averag':463 'bash':175,343 'bearer':235 'behalf':273 'behavior':614 'behind':455 'bucket':512 'bug':611 'care':433 'caus':207 'chang':426 'chart':119 'check':164 'chmod':560 'choos':106 'claus':503 'cli':3,4,38,41,45,52,85,565,587,618 'command':341 'compact':541 'compat':11 'config':230,259,270,277,331,393 'configur':89,174,189,217 'configuration/auth':200 'confirm':329 'connect':185,210 'contain':280 'context7':600 'convey':533 'cortex':14 'counter':406,411 'creat':269,301 'credenti':281,309,555 'csv':363,364 'data':115,490 'date':598 'debug':157,437 'dial':208,219 'direct':535 'discov':101 'discover':605 'discoveri':25 'document':588 'drop':516 'earli':466,487,518 'encount':609 'engin':12 'error':131,186,197,206,231,240 'evalu':475 'ever':413 'exact':316 'exampl':593 'execut':33,72 'exhaust':579 'expos':567 'fail':183 'fall':537 'file':64,69,74,260,271,278 'filter':465,480,488 'flag':255 'format':29,108,317,542 'function':143,478,508 'fundament':62 'github.com':47,590,625 'github.com/nalbury/promql-cli)':46,589 'github.com/nalbury/promql-cli/issues](https://github.com/nalbury/promql-cli/issues).':624 'give':421 'go':51 'grafana':16,18 'graph':359,527 'guid':292 'healthi':456 'help':137,153,391,602 'hidden':454 'histogram':497,505 'histori':571 'host':90,96,172,180,192,213,223,228,307,399 'hostnam':224 'http':350 'increas':414 'inform':599 'innermost':472 'instal':82 'instanc':441,448 'instant':20,346 'instead':261,291 'insuffici':247 'interpol':514 'invalid':239 'investig':126 'isol':438 'issu':129,622 'json':369,370 'keep':498 'key':400 'know':320 'label':379,381,468 'late':481 'latenc':130,494 'le':499,511,517 'let':318 'list':374,380,574 'llm':290 'llms':544 'manual':303 'mask':445 'matcher':469 'may':279 'mean':482 'meaningless':419 'mental':551 'meta':386 'metric':24,59,141,373,376,384,388 'metrics/exporters/labels':102 'metrics/labels/meta':26 'mimir':17 'miss':237 'model':552 'multi':95 'multi-host':94 'must':285 'name':377 'nan':520 'need':80,136,311,509 'never':286,407 'offici':584 'open':620 'output':28,107,362,365,368,371,526 'overload':452 'pars':545 'partial':256 'pass':287,562 'password':93,283 'peer':457 'per':424,447 'per-inst':446 'per-second':423 'percentil':515 'perform':128 'permiss':248 'place':334 'platform':606 'pleas':249,300,580 'plus':60 'pod':453 'prefer':525 'principl':401 'problem':201 'proceed':337 'process':573 'produc':519 'prometheus':7,39,58,114,233,242,306,474 'promql':2,10,34,37,44,61,84,139,152,176,191,344,348,360,366,372,378,385,392,586,617 'promql-c':1,36,43,83,585,616 'promql-compat':9 'qu':35 'quantil':506 'queri':6,21,23,40,54,104,168,232,241,339,347,357,493,530 'quick':340 'rang':22,356,529 'rate':349,404,420,427 'raw':408,410,547 'reachabl':182 'read':65,77,149,154,158 'readi':324 'recogn':195 'reduc':489 'refer':63,68,203,342,581 'references/debugging.md':123,160 'references/graphing.md':109 'references/installation.md':78,205,313 'references/promql-reference.md':134,155,162 'references/usage.md':97,150 'refus':211 'relev':67 'replica':444 'request':351 'requir':550 'resolv':226 'result':523 'rise':536 'run':103,166,214 'satur':133 'scan':483,491 'second':425 'see':312 'selector':473,476 'seri':486 'set':87,257,296 'setup':163 'shell':570 'show':387,460 'singl':440,451 'skill':42,576 'skill-promql-cli' 'source-samber' 'sparklin':532 'specif':398 'specifi':250 'spike':538 'start':354 'store':554 'subcommand':27 'succeed':178 'tabl':549 'table/csv/json/graph':30 'target':396 'task':73,148 'tcp':209,220 'tempo':19 'termin':122 'thano':13 'time':485 'timestamp':548 'token':92,236,244,282,563 'topic-agent' 'topic-agent-skills' 'topic-antigravity' 'topic-claude' 'topic-claude-code' 'topic-code' 'topic-codex' 'topic-coding' 'topic-copilot' 'topic-cursor' 'topic-gemini' 'topic-gemini-cli-extension' 'total':352 'trend':534 'type':142,253,389 'understand':140 'unexpect':613 'up-to-d':595 'use':258,403 'user':79,98,110,124,135,276,294,328 'valid':245 'valu':409,417 'verifi':169 'victoriametr':15 'visual':57,113 'want':99,111 'well':546 'won':458 'write':138 'wrong':227,522 'xxx':193","prices":[{"id":"1d29aacb-b1f8-4817-b884-51fc3c5b3697","listingId":"15597d4b-d0d4-4416-9845-a7c9d56420a0","amountUsd":"0","unit":"free","nativeCurrency":null,"nativeAmount":null,"chain":null,"payTo":null,"paymentMethod":"skill-free","isPrimary":true,"details":{"org":"samber","category":"cc-skills","install_from":"skills.sh"},"createdAt":"2026-04-18T22:13:35.389Z"}],"sources":[{"listingId":"15597d4b-d0d4-4416-9845-a7c9d56420a0","source":"github","sourceId":"samber/cc-skills/promql-cli","sourceUrl":"https://github.com/samber/cc-skills/tree/main/skills/promql-cli","isPrimary":false,"firstSeenAt":"2026-04-18T22:13:35.389Z","lastSeenAt":"2026-05-02T06:55:37.777Z"}],"details":{"listingId":"15597d4b-d0d4-4416-9845-a7c9d56420a0","quickStartSnippet":null,"exampleRequest":null,"exampleResponse":null,"schema":null,"openapiUrl":null,"agentsTxtUrl":null,"citations":[],"useCases":[],"bestFor":[],"notFor":[],"kindDetails":{"org":"samber","slug":"promql-cli","github":{"repo":"samber/cc-skills","stars":79,"topics":["agent","agent-skills","ai","antigravity","claude","claude-code","code","codex","coding","copilot","cursor","gemini","gemini-cli-extension","openclaw","opencode","plugin","skills","skillsmp","vibe-coding"],"license":"mit","html_url":"https://github.com/samber/cc-skills","pushed_at":"2026-05-01T17:07:53Z","description":"🧑‍🎨 A collection of agentic skills that works","skill_md_sha":"613d7092ab8499af439b107955f630c4cbbe761f","skill_md_path":"skills/promql-cli/SKILL.md","default_branch":"main","skill_tree_url":"https://github.com/samber/cc-skills/tree/main/skills/promql-cli"},"layout":"multi","source":"github","category":"cc-skills","frontmatter":{"name":"promql-cli","license":"MIT","description":"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.","compatibility":"Requires promql-cli and jq"},"skills_sh_url":"https://skills.sh/samber/cc-skills/promql-cli"},"updatedAt":"2026-05-02T06:55:37.777Z"}}