Query CubeAPM
from the command line.
Search distributed traces, run PromQL metrics queries, and tail LogsQL logs, all from your terminal, with first-class JSON output for scripts and agents.
01Install
Get the binary
Pick whichever fits your setup. The binary is cubeapm.
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.
02Quick start
Authenticate once, then query
Add -o json to any command for machine-readable output.
# 1. Authenticate, prompts for server, credentials, and ports cubeapm login cubeapm login --name staging # save a named profile # 2. Check connection status cubeapm status # 3. List services that have reported traces cubeapm traces services # 4. Search traces, filter by service, duration, and status cubeapm traces search --service api-gateway --last 1h cubeapm traces search --service payments --min-duration 500ms --status error # 5. Inspect a specific trace as a waterfall view cubeapm traces get abc123def456 # 6. Run a PromQL metrics 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. Pipe JSON to jq for scripting cubeapm traces search --service api-gateway --last 1h -o json | jq
03Auth / Config
Three ways to provide credentials
Precedence: CLI flags > environment variables > saved profile.
interactive loginDefault
Prompts for server, auth method, and ports, tests the connection and saves a profile to ~/.config/cubeapm-cli/.
env varsCI / Agents
Set CUBEAPM_SERVER, CUBEAPM_EMAIL, and CUBEAPM_PASSWORD. Overrides saved profiles.
named profilesMulti-env
Save separate profiles for prod, staging, and dev. Switch with cubeapm config use-profile or pass --profile per command.
Environment variables (CI / agents)
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
04Commands
Full coverage of the CubeAPM API
Every group has its own --help. A selection of the top-level groups:
cubeapm traces
Search and inspect distributed traces (Jaeger-compatible); filter by service, duration, status, tags
cubeapm metrics
Run PromQL queries, list metric names and label values
cubeapm logs
Run LogsQL queries against VictoriaLogs-compatible log storage
cubeapm config
View and set configuration values, manage and switch connection profiles
cubeapm login
Interactive authentication setup, tests the connection and saves a profile
cubeapm status
Connection status and server info
cubeapm version · update · completion
Print CLI version, self-update to the latest release, generate 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, --output
Output format: table, json, yaml
--profile
Use a specific named connection profile
--server
Override the CubeAPM server address for this invocation
--no-color
Disable colored output
--verbose
Enable verbose HTTP request logging