promql-formatter-cli

Format PromQL from your terminal.
A small Go library + CLI that prettifies PromQL queries.

---

✨ Features

• 🧹 Prettify any PromQL / MetricsQL query into a readable, multi-line form.
• 🔀 Two backends — vic (VictoriaMetrics metricsql.Prettify, the default) and main (a custom Prometheus-AST formatter with Grafana $variable support).
• 📦 Library and CLI — drop it into your Go code, or run it from the shell.
• 🪶 Zero config, no network — pure Go, formats locally.
• 🧩 Powers the promql-formatter Chrome extension via WebAssembly.

🎬 Example

$ promql-formatter 'sum(rate(http_requests_total[1m]))by(job) / sum(rate(http_requests_total[1m] offset 1d))by(job) > 1.5'

(
  sum(rate(http_requests_total[1m])) by(job)
    /
  sum(rate(http_requests_total[1m] offset 1d)) by(job)
)
  >
1.5

📦 Install

go install github.com/xhinliang/promql-formatter-cli/cmd/promql-formatter@latest

Or grab a source build:

git clone https://github.com/XhinLiang/promql-formatter-cli.git
cd promql-formatter-cli
go build -o promql-formatter ./cmd/promql-formatter

🚀 Usage

CLI

# format an argument (default backend: vic)
promql-formatter 'sum(rate(http_requests_total[1m])) by (job)'

# read from stdin, pick a backend
echo 'sum(rate(http_requests_total[1m])) by (job)' | promql-formatter --formatter main

Flag	Description	Default
--formatter	Backend: vic or main	vic
--version	Print version and exit

Library

import promqlfmt "github.com/xhinliang/promql-formatter-cli"

func main() {
    out, err := promqlfmt.Format("sum(rate(x[1m]))by(a)", "vic")
    // or: promqlfmt.FormatVic(...) / promqlfmt.FormatMain(...)
    _ = err
    println(out)
}

🔧 Backends

Backend	Engine	Notes
vic (default)	VictoriaMetrics metricsql.Prettify	Robust, MetricsQL-aware prettifier.
main	Prometheus parser + custom AST visitor	Adds Grafana $variable / $__interval handling and offset fix-ups.

🤝 Contributing

Issues and PRs are welcome — see CONTRIBUTING.md. Run go test ./... and go vet ./... before opening a PR.

📄 License

Apache-2.0.

🙏 Acknowledgements

The main backend originates from the o11y.tools PromQL prettifier (Apache-2.0). The vic backend wraps VictoriaMetrics metricsql.