promql-exec – PromQL Query Tester

promql-exec is a small Go CLI to test PromQL queries against a Prometheus-compatible endpoint. Connection profiles and reusable query definitions are kept separate for better reuse.

Installation

go mod download
go build -o promql-exec

Usage

1. Define connection profiles in profiles/profiles.yaml (copy from profiles/profiles.sample.yaml).
2. Define PromQL queries as .yaml files in the queries/ directory (for example based on queries/queries.sample.yaml).
3. Combine a profile and a query when running the CLI.

# List available profiles
./promql-exec -list-profiles

# List available queries
./promql-exec -list-queries

# Execute a query with a profile
./promql-exec -profile example -query http-requests-rate

# Pretty-print the JSON response
./promql-exec -profile example -query list-jobs -pretty

# Verbose output (shows rendered query and values)
./promql-exec -profile example -query http-requests-rate -verbose

# Override template values from the command line
./promql-exec -profile example -query http-requests-rate \
  -set job=my-job -set instance=my-instance:9090

# Use a custom profiles file and queries directory
./promql-exec -profiles profiles/custom.yaml -queries my-queries/ \
  -profile dev -query custom

Configuration

profiles/profiles.yaml

Defines connection profiles with server connection details and optional template values. The file is listed in .gitignore and should be copied from profiles/profiles.sample.yaml and adjusted locally:

profiles:
  example:
    serverAddress: "https://prometheus.example.com"
    user: "your-user"
    password: "your-password"
    values:
      job: "example-job"
      instance: "example-instance:9090"

Values (optional template values)

values in a profile are a free key/value set used to populate template variables in your queries:

• Keys correspond to template names in the queries (for example job → {{ .job }}, instance → {{ .instance }} or zone → {{ .zone }}).
• Optional: you do not have to define any values. If they are missing, template variables stay empty or can be provided via -set.
• Sample files:
  • profiles/profiles.sample.yaml defines job and instance.
  • queries/queries.sample.yaml uses {{ .job }} and {{ .instance }} in the PromQL queries.

queries/ directory

Defines reusable queries in YAML files. All .yaml and .yml files in the directory are loaded and merged.

Example: queries/example.yaml

queries:
  http-requests-rate:
    description: "Rate of HTTP requests per second"
    query: 'sum(rate(http_requests_total{job="{{ .job }}", instance="{{ .instance }}"}[1m]))'

  list-jobs:
    description: "List all jobs"
    query: 'group by (job) (up)'

Template variables in queries (for example {{ .job }}) are replaced with the values from the selected profile (or CLI overrides).

Benefits:

• Organize queries by topic in separate files.
• Add new query files without changing existing ones.
• Keep large sets of queries manageable.

Overriding template variables

Values can be defined in the profile and/or passed via the command line:

# Use values from the profile
./promql-exec -profile example -query http-requests-rate

# Override a single value
./promql-exec -profile example -query http-requests-rate -set job=my-job

# Override multiple values
./promql-exec -profile example -query http-requests-rate -set job=my-job -set instance=my-instance:9090

Precedence:

1. CLI values (-set) have highest precedence.
2. Profile values are used when no CLI values are given.
3. Missing values result in empty template variables.

Examples

# Show all available jobs (see sample query file)
./promql-exec -profile example -query list-jobs -pretty

# HTTP requests rate for the example profile
./promql-exec -profile example -query http-requests-rate

# Same query with a different instance
./promql-exec -profile example -query http-requests-rate -set instance=another-instance:9090

Features

• ✅ Separate connection profiles and queries
• ✅ Reusable query definitions in YAML
• ✅ Template variable support (profiles + CLI overrides)
• ✅ CLI values override profile values
• ✅ Multi-file query definitions (queries/ directory)
• ✅ Basic authentication support
• ✅ Verbose and pretty-print modes
• ✅ Profile/query listing

Project structure

promql-exec/
├── promql-exec                  # Binary
├── .gitignore                   # Ignore real profiles/queries
├── profiles/                    # Local connection profiles (gitignored)
│   ├── profiles.sample.yaml     # Sample profiles (in the repo)
│   └── profiles.yaml            # Your local profiles (do not commit)
├── queries/                     # Query definitions
│   ├── queries.sample.yaml      # Sample queries (in the repo)
│   └── *.yaml                   # Your local queries (do not commit)
└── README.md

License

This project is licensed under the MIT License. See LICENSE for details.

Contributing

Contributions are welcome! Please see CONTRIBUTING.md for guidelines.