Commands

Reference

A small command surface, grouped by operator task.

The CLI is intentionally compact. The important distinction is not command count, but which scope you are diagnosing, how much context you want to gather, and whether the next consumer is a human or another system.

Diagnosis scopesReport generationRule introspectionConfig helpers

Diagnose

Scope commands

Use pod, deployment, namespace, and cluster commands to match the size of the problem you are investigating.

Inspect

Rules and config

Use rule and config commands when you need to understand why kubediag behaves a certain way or how it is currently configured.

Publish

Report output

Use report generation when the audience is an incident document, handoff, or postmortem rather than a live terminal.

Integrate

Completions and JSON

Use completion scripts and JSON output when you want kubediag to feel native in shells and automation pipelines.

Diagnosis scopes

Pod

Diagnose one workload instance.

Best when you already know which pod is failing and want the fastest path from symptom to evidence.

kubediag pod my-pod -n default

This is the most useful first command for learning how the tool thinks.

Deployment

Diagnose rollout and owned pods together.

Best when availability is failing at the controller layer and you need rollout conditions plus pod-level context in one view.

kubediag deployment web -n prod

Namespace and cluster

Widen the diagnosis surface when the incident is systemic.

Best when you suspect service selection issues, namespace-wide warning events, or cluster resource pressure.

kubediag namespace prod
kubediag cluster

Reporting and renderers

Markdown report

Generate an artifact for incident sharing.

The report command forces markdown output and raises the finding cap so the result works as a handoff or post-incident summary.

kubediag report namespace prod > triage-report.md

`kubediag report cluster` is reserved for a future release and currently returns a not-yet-implemented error.

Output formats

Pick the renderer that matches the next consumer.

Use terminal text for live operations, JSON for tooling, and markdown for human-readable artifacts.

kubediag pod my-pod -o text
kubediag pod my-pod -o json
kubediag namespace prod -o markdown

Rule and configuration helpers

Rules

Inspect the built-in diagnosis surface.

These commands are useful when you need to understand which rules exist or explain one rule in more detail.

kubediag rules list
kubediag rules list --category Runtime
kubediag rules explain TRG-POD-OOMKILLED

Config

Understand the resolved runtime configuration.

These commands help when config precedence or environment overrides are part of the debugging path.

kubediag config view
kubediag config init
kubediag config path

Global flags that matter most

Flag	Why you would care
-o, --output	Choose text, JSON, or markdown depending on whether the consumer is a human, report, or machine.
-n, --namespace	Required for pod and deployment diagnoses unless your kube context already resolves the right namespace.
--severity-min	Useful when you want to suppress lower-priority findings during noisy incidents.
--confidence-min	Useful when you want kubediag to report only higher-certainty diagnoses.
--include-events	Controls whether related Kubernetes Events are pulled into the evidence surface.
--include-related	Controls whether related Services, PVCs, and adjacent resources are included.
--max-findings	Caps output size for dense namespace- or cluster-level runs.
--timeout	Bounds total cluster-call time for the run.
--config	Points kubediag at a specific config file instead of the default path.

Kubernetes client flags such as --context, --kubeconfig, --cluster, and --user are also available because kubediag uses the standard Kubernetes CLI runtime stack.

Shell integration

Completion

Make the small command surface feel native.

Shell completion is worth enabling because the commands are few, but the value is in fast recall during incident response.

kubediag completion bash
kubediag completion zsh
kubediag completion fish
kubediag completion powershell

Version

Check the binary identity.

Useful when validating a release artifact or comparing behavior across environments.

kubediag version