CLI reference
Every kubehero command — cost, logs, profiles, network, rightsizing, alerts, ask, mcp, policies and undo.
kubehero is a single static Go binary. Download it from GitHub Releases. It talks to the control plane over Connect-RPC and is also KubeHero's MCP server.
Configuration
Settings resolve in this order — flags, then environment, then ~/.kubehero/config.yaml (written by kubehero auth login):
| Flag | Environment | Meaning |
|---|---|---|
--endpoint | KUBEHERO_ENDPOINT | Control-plane URL, e.g. https://kubehero.example.com or a port-forward http://localhost:8080 |
--token | KUBEHERO_TOKEN | Bearer token (API key or admin token) |
--org | KUBEHERO_ORG | Organization slug |
-o, --output | table (default) · json · yaml · wide | |
--insecure | Skip TLS verification (development only) |
kubehero auth login # save endpoint + token to ~/.kubehero/config.yaml
kubehero auth status
kubehero healthCost
kubehero cost allocation --aggregate namespace --window 7d --idle --share-idle weighted
kubehero cost timeseries --window 30d --group-by team --top 5
kubehero cost efficiency --window 7d
kubehero cost export --format focus --window 30d --aggregate workload --file focus.csvcost allocation flag | Default | |
|---|---|---|
--aggregate | namespace | comma-separated: cluster, namespace, workload, controller, pod, container, node, nodepool, team, cost_center, zone, label:<key> |
--window | 7d | 24h · 7d · 30d · today · yesterday · week · month · lastmonth · "<RFC3339>,<RFC3339>" |
--idle | off | add an __idle__ row per cluster |
--share-idle | weighted · even | |
--filter | key=value, repeatable | |
--shared-namespaces | namespaces redistributed to the rest | |
--cluster, --limit |
cost timeseries takes --window (30d), --step (1h · 1d), --group-by (namespace · team · cluster · nodepool · workload), --top (5), --filter, --cluster. cost export takes --format focus, --window (30d), --aggregate (workload · namespace · cluster) and --file. See Cost allocation.
Logs
kubehero logs '{namespace="payments", level="error"}' --since 1h
kubehero logs '{namespace="payments"} |= "timeout"' -f
kubehero logs '{namespace="payments"}' --patterns --since 24h
kubehero logs '{level="error"}' --volume --group-by namespace
kubehero logs 'sum by (namespace) (count_over_time({level="error"}[5m]))'| Flag | Default | |
|---|---|---|
--since | 1h | lookback, e.g. 15m, 6h, 7d |
--from, --to | RFC 3339; --from overrides --since | |
--limit | 100 | lines (1–5,000) or patterns |
--direction | backward | backward (newest first) · forward |
-f, --tail | stream new lines | |
--patterns | cluster lines into Drain templates | |
--volume, --group-by | level | line volume by a label, with $/mo |
--cluster | or {cluster="…"} in the query |
--tail, --patterns and --volume are mutually exclusive. See Logs.
Profiles
kubehero profile targets --since 1h
kubehero profile top --service checkout-api --since 30m --order self
kubehero profile flame --service checkout-api --diff-since 24h --depth 14Shared flags: --service (required for top / flame), --namespace, --type (cpu default · alloc_space · alloc_objects · inuse_space · inuse_objects · goroutine · mutex · block), --since (30m), --cluster. top adds --limit (20) and --order (self · total); flame adds --diff-since, --depth (14) and --min-pct (1). See Profiling.
Network
kubehero network map --namespace checkout --since 1h --max-edges 25
kubehero network costs --since 24h --limit 25See Network.
Rightsizing
kubehero rightsize # all recommendations
kubehero rightsize list checkout-api --namespace payments
kubehero rightsize --percentile p99 --headroom 25 --window 14d --min-savings 50Flags: --namespace, --window (7d), --headroom (server default 15), --percentile (p90 · p95 · p99 · max), --min-savings, --limit (50), --cluster. See Rightsizing.
Alerts
kubehero alerts list --state firing
kubehero alerts rules --kind logs
kubehero alerts test --kind logs \
--query 'sum by (namespace) (count_over_time({level="error"}[5m]))' --op '>' --threshold 100
kubehero alerts silence --matcher alertname="OOM kills" --matcher namespace=batch --duration 2h --comment "known"
kubehero alerts silence list --include-expired
kubehero alerts silence delete <silence-id>See Alerting.
Ask KubeHero
kubehero ask "why did checkout-api spend jump last night?"
kubehero ask "which workloads pay the most for egress?" --window 7d --cluster eks-use1-prod --speakStreams each tool call as it runs, then prints the answer, evidence and proposals. Flags: --cluster (default fleet-wide), --window (1h · 24h · 7d), --context (a dashboard path the question is about), --speak (also print the spoken summary), -q, --quiet. See Agents & MCP.
kubehero mcp
kubehero mcp # stdio — for Claude Desktop, Claude Code and other MCP hosts
kubehero mcp --http :8765 # streamable HTTP; a bare port binds 127.0.0.1See Agents & MCP for client configuration.
Policies
kubehero apply -f policies/prod-budget.yaml
kubehero cap --arm --policy prod-ceiling --cluster eks-use1-prod --reason "runaway GPU spend"
kubehero cap --disarm --policy prod-ceiling --cluster eks-use1-prodcap arms or disarms a policy through the control plane, writes an audit row with your --reason, and notifies the configured channels. Policies are also plain CRDs — kubectl apply -f works. See the CRD reference.
kubehero undo
kubehero undo rs-5f2c9a1e
kubehero undo rs-5f2c9a1e --namespace payments --dry-runRestores the requests and limits a rightsizing change replaced. The change ID (rs-…) is in the policy's status.plannedChanges, the rightsize.apply audit event and the RightsizeApplied Kubernetes event on the workload. undo runs kubectl with your kubeconfig and RBAC, reverts later changes too, and marks the workload kubehero.io/rightsize-reverted so the operator leaves it alone until you remove the annotation. It refuses if someone else changed the resources since KubeHero's last change (--force overrides). Flags: -n, --namespace, --kubeconfig, --context, --force, --dry-run.
Clusters and pricing
kubehero cluster list
kubehero cluster add --name eks-use1-prod --cloud aws --region us-east-1 # prints a one-time enrollment token
kubehero quote --cloud gcp --sku n2-standard-8 --region europe-west4 --lifecycle spotcluster add creates a registration and prints its enrollment token exactly once — only its SHA-256 hash is stored. Use it for federated collectors.