Query traces, metrics, and logs
from your terminal.
A command-line interface for CubeAPM with full coverage of Jaeger-compatible traces, PromQL metrics, and LogsQL logs. Designed for both humans and AI coding agents.
Install
Pick whichever fits — the install script handles platform detection and PATH setup.
Recommended — install script
curl -sSfL https://raw.githubusercontent.com/piyush-gambhir/cubeapm-cli/main/install.sh | sh
Via Go
go install github.com/piyush-gambhir/cubeapm-cli@latest
Build from source
git clone https://github.com/piyush-gambhir/cubeapm-cli.git
cd cubeapm-cli
make build
# Binary lands at ./bin/cubeapm
From releases
Download a prebuilt binary for your platform from the
releases page
and place it on your PATH.
Quick start
Authenticate once, then query.
# 1. Authenticate (saves a profile to ~/.config/cubeapm-cli/) cubeapm login # 2. List services that have reported traces cubeapm traces services # 3. Search traces in the last hour cubeapm traces search --service api-gateway --last 1h # 4. Find slow, errored traces cubeapm traces search --service payments --min-duration 500ms --status error # 5. Inspect a trace as a waterfall view cubeapm traces get abc123def456 # 6. Run a PromQL query cubeapm metrics query 'http_requests_total{job="api"}' --last 1h # 7. Run a LogsQL query cubeapm logs query '{service="api-gateway"}' --last 30m # 8. Get JSON output for scripting cubeapm traces search --service api-gateway --last 1h -o json | jq
Authentication
Three ways to provide credentials. CLI flags > environment variables > saved profile.
Interactive login
cubeapm login
Prompts for server, auth method, and ports — tests the connection and saves a profile.
Environment variables
export CUBEAPM_SERVER=cubeapm.example.com
export CUBEAPM_EMAIL=user@example.com
export CUBEAPM_PASSWORD=your-password
# Custom ports (defaults shown)
export CUBEAPM_QUERY_PORT=3140
export CUBEAPM_INGEST_PORT=3130
export CUBEAPM_ADMIN_PORT=3199
Multiple profiles
cubeapm login # saves as default cubeapm login --name staging # save a named profile cubeapm config use-profile prod # switch active profile cubeapm traces services --profile staging # one-off override
Commands
Each group has its own --help for full flag and example documentation.
Top-level groups
cubeapm tracesSearch and inspect distributed traces (Jaeger-compatible)cubeapm metricsRun PromQL queries, list metric names and labelscubeapm logsRun LogsQL queries (VictoriaLogs-compatible)cubeapm configView/set configuration, manage profilescubeapm loginInteractive authentication setupcubeapm statusConnection status and server infocubeapm versionPrint CLI versioncubeapm updateSelf-update to the latest releasecubeapm completionGenerate shell completions (bash, zsh, fish)Output formats
cubeapm traces services # table (default) cubeapm traces services -o json # JSON cubeapm traces services -o yaml # YAML
Global flags
-o, --outputOutput format: table, json, yaml--profileUse a specific connection profile--serverOverride CubeAPM server address--no-colorDisable colored output--verboseEnable verbose HTTP request logging