CLI reference

radar (or kubectl radar when installed via Krew) starts the local server by default. Defaults come from ~/.radar/config.json when present - see Configuration files.

Commands

Command	Purpose
`radar [flags]`	Start the Radar server and open the UI.
`radar diagnose <kind>/<name> [-n namespace]`	Run an AI investigation using a local Claude Code, Codex, or Cursor CLI. Uses a running Radar when available, otherwise starts a temporary one. See Diagnose with AI.
`radar cloud install`	Install or adopt Radar in the selected kubeconfig context and connect it to Radar Cloud.
`radar cloud status`	Inspect the installation, agent readiness, ownership, and Cloud tunnel health without changing the cluster.

`radar diagnose`

Flag	Description
`-n`, `--namespace`	Namespace of the target resource.
`--agent`	Agent backend: `claude`, `codex`, or `cursor-agent`. Empty uses Radar’s configured choice.
`--profile`	`safeguarded` or `full-local`, where the selected agent supports both.
`--server`	Radar server URL. Empty discovers the running instance from `~/.radar/mcp-port`.
`--standalone`	Start a temporary in-process Radar instead of using a running instance.
`--kubeconfig`	Kubeconfig used with `--standalone`.
`--json`	Print the final verdict as JSON; progress stays on stderr.
`--open`	Also open the investigation in the Radar UI.
`--yes`	Acknowledge the first-run consent disclosure non-interactively.

`radar cloud`

cloud install supports --context, --namespace, --release, --chart-version, --name, --hub-url, --dry-run, --no-browser, and --browser. When adopting an existing installation, non-interactive runs require --adopt-existing; interactive runs can ask for consent. For an adopted installation, --enable-cloud-features adds optional Cloud feature RBAC. On any install, --no-self-upgrade omits the self-upgrade Role and RoleBinding. -y / --yes skips current-context confirmation but never grants adoption consent. cloud status accepts --context. Pass --namespace and --release together to inspect one exact installation instead of discovering visible installations.

General

Flag	Default	Description
`--port`	`9280`	HTTP port the UI / API serve on.
`--listen-address`	`127.0.0.1`	Bind to loopback by default. Set `0.0.0.0` only for an intentionally shared listener.
`--base-path`	`""`	Serve under a URL prefix such as `/radar` when an ingress forwards the prefix without stripping it. Not supported in Radar Cloud mode.
`--no-browser`	`false`	Don’t auto-open the browser.
`--browser`	`""`	Browser to open the UI in, overriding the OS default launcher. Local runs only (in-cluster and Cloud can’t open a user browser). On macOS, app names and `.app` bundles work, e.g. `--browser Safari` or `--browser "Google Chrome"`. Empty uses the OS default.
`--namespace`	`""`	Initial namespace filter (empty = all namespaces).
`--namespaces`	`""`	Initial namespace filters as a comma-separated list. Useful when the identity can list resources in selected namespaces but cannot list namespaces cluster-wide.
`--version`	-	Print version and exit.
`--debug-events`	`false`	Verbose event-drop logging.

Cluster connection

Flag	Description
`--kubeconfig`	Path to a kubeconfig file. Falls back to `KUBECONFIG` env or `~/.kube/config`.
`--kubeconfig-dir`	Comma-separated directories whose kubeconfigs are merged. Mutually exclusive with `--kubeconfig`.

Timeline storage

Flag	Default	Description
`--timeline-storage`	`memory`	`memory` or `sqlite`. SQLite persists across restarts.
`--timeline-db`	`~/.radar/timeline.db`	Path to the SQLite database when `--timeline-storage=sqlite`.
`--timeline-retention`	`168h`	Age limit for SQLite events. `0` disables age-based cleanup.
`--history-limit`	`10000`	Max events retained in the timeline (memory mode).
`--timeline-max-size`	`1Gi`	Max SQLite timeline size (DB + WAL) before the oldest events are pruned, e.g. `800Mi`, `8Gi`. `0` disables size-based pruning.

Metrics & traffic

Flag	Description
`--prometheus-url`	Manual Prometheus / VictoriaMetrics URL. Skips auto-discovery (handy for out-of-cluster Prometheus).
`--prometheus-header`	HTTP header to send with Prometheus requests, e.g. `'Authorization=Bearer <token>'` (repeatable). Required for auth-protected backends.
`--prometheus-header-from-env`	Like `--prometheus-header`, but the value is read from an env var, e.g. `'Authorization=PROMETHEUS_TOKEN'` (repeatable) - keeps secrets out of `ps`.
`--beyla-job-selector`	PromQL job-label matcher used to scope Grafana Beyla traffic series. Empty matches the built-in Beyla / Alloy job-name defaults.

Feature toggles

Flag	Effect
`--no-mcp`	Disable the MCP server (AI tools won’t be able to connect).
`--mcp-catalog-only`	Start only the MCP endpoint for registry / inspector catalog introspection (e.g. Glama); skips Kubernetes initialization.
`--mcp-catalog-stdio`	Start only the MCP catalog over stdio for registry / inspector introspection; skips Kubernetes initialization.
`--disable-helm-write`	Read-only Helm: hide install / upgrade / rollback / uninstall buttons.
`--disable-exec`	No pod terminal / debug shell.
`--disable-local-terminal`	Disable the local-machine terminal pane.
`--pod-shell-default`	Override the default pod exec shell (runs as `sh -c <value>`; empty falls back to `bash -il → ash → sh`).
`--debug-image`	Image for ephemeral debug containers and node debug pods. Defaults to `busybox:latest`; point at a mirror for air-gapped / private-registry clusters.
`--reachability-image`	Image for in-cluster reachability probe Jobs. Empty uses Radar’s running pod image when discoverable, then `RADAR_IMAGE`, then the version-matched published Radar image.
`--list-page-size`	Paginate the initial LIST of high-cardinality kinds (Pods, ReplicaSets) at this size. Defaults to `0` (single LIST). Helps very large clusters whose initial sync fails; only used when WatchList streaming is unavailable on the apiserver. Try `2000`.
`--namespace-scope`	Pin namespaced informer caches to a single namespace instead of watching the whole cluster - for very large clusters where cluster-wide caches are too heavy. Cluster-scoped resources (Nodes, Namespaces, PVs, and cluster-scoped CRDs) still load cluster-wide. Requires `--namespace`, a namespace on the kubeconfig context, or a saved local pick. Scoping to multiple namespaces is not supported yet. Local sessions can switch the scoped namespace from the picker (rebuilds the cache in place); auth / shared deployments lock it to the startup namespace so one user can’t reshape the shared cache for everyone.
`--ai-history`	Persist AI investigation transcripts and verdicts to `~/.radar/ai-runs.db`. Defaults to `true`.

Tuning for slow or large clusters

Clusters reached over high-latency tunnels, or with thousands of namespaces, can trip Radar’s default deadlines. Each flag also reads from the matching RADAR_* env var.

Flag	Default	Env	Description
`--context-switch-timeout`	`30s`	`RADAR_CONTEXT_SWITCH_TIMEOUT`	Max time a kubeconfig context switch may take. Widen to `120s`+ for clusters over high-latency tunnels.
`--first-paint-backstop`	`5m`	`RADAR_FIRST_PAINT_BACKSTOP`	Hard upper bound on the initial critical-cache sync wait before Radar falls through to a partial-data render.
`--namespace-list-timeout`	`5s`	`RADAR_NAMESPACE_LIST_TIMEOUT`	Timeout for the cluster-wide namespace LIST that decides if you’re RBAC-namespace-restricted. Widen to `30s`+ on slow control planes - a timeout here is otherwise misreported as “Limited list - RBAC”.
`--max-scope-candidates`	`20`	`RADAR_MAX_SCOPE_CANDIDATES`	Cap on the namespace-fallback probe fanout for users who can list namespaces cluster-wide but not a specific kind. Raise above 20 for clusters with more namespaces to avoid silently marking kinds denied.

Authentication

See Authentication for the full setup. Common flags:

Flag	Description
`--auth-mode`	`none` (default), `proxy`, or `oidc`.
`--auth-secret`	HMAC secret for session cookies. Auto-generated when empty - set this for multi-replica deployments.
`--auth-cookie-ttl`	Sliding session TTL. Default `4h`.

Proxy mode (oauth2-proxy / Pomerium / etc.):

Flag	Default	Description
`--auth-user-header`	`X-Forwarded-User`	Header carrying the username.
`--auth-groups-header`	`X-Forwarded-Groups`	Header carrying the comma-separated groups.
`--auth-proxy-logout-url`	`""`	Upstream proxy logout URL. Empty clears only Radar’s session cookie.

OIDC mode (Google / Okta / Keycloak / etc.):

Flag	Description
`--auth-oidc-issuer`	OIDC issuer URL.
`--auth-oidc-internal-issuer`	Internal issuer base used for discovery and server-side endpoints while tokens are still validated against `--auth-oidc-issuer`.
`--auth-oidc-authorization-url`	Browser-facing authorization endpoint override.
`--auth-oidc-token-url`	Server-side token endpoint override.
`--auth-oidc-userinfo-url`	Server-side userinfo endpoint override.
`--auth-oidc-jwks-url`	Server-side JWKS endpoint override.
`--auth-oidc-client-id`	Client ID from your IdP.
`--auth-oidc-client-secret`	Client secret.
`--auth-oidc-redirect-url`	The `/auth/callback` URL registered with the IdP.
`--auth-oidc-groups-claim`	JWT claim that carries groups. Default `groups`.
`--auth-oidc-scopes`	Comma-separated scopes. Defaults to `openid,profile,email,groups`.
`--auth-oidc-post-logout-redirect-url`	URL to redirect to after IdP logout (must be registered with the IdP).
`--auth-oidc-username-prefix`	Username prefix for K8s impersonation - must match kube-apiserver’s `--oidc-username-prefix`.
`--auth-oidc-groups-prefix`	Groups prefix for K8s impersonation - must match kube-apiserver’s `--oidc-groups-prefix`.
`--auth-oidc-insecure-skip-verify`	Skip TLS verification on the IdP (dev / test only).
`--auth-oidc-ca-cert`	Path to a custom CA bundle for the IdP.
`--auth-oidc-backchannel-logout`	Enable the back-channel logout endpoint. Single-replica only.
`--auth-oidc-enable-pkce`	Enable PKCE (S256) for the authorization-code flow. Opt-in.

Radar Cloud

These flags wire an in-cluster Radar to a hosted Radar Cloud. Each is also readable from the matching RADAR_CLOUD_* env var (so secrets stay out of ps).

Flag	Env	Description
`--cloud-url`	`RADAR_CLOUD_URL`	Cloud WS endpoint (e.g. `wss://api.radarhq.io/agent`). Empty = local-only.
`--cloud-token`	`RADAR_CLOUD_TOKEN`	Cluster token from the Cloud install wizard (`rhc_<random>`).
`--cluster-name`	`RADAR_CLOUD_CLUSTER_NAME`	Human-readable name (required with `--cloud-url`).
`--cloud-insecure-skip-verify`	`RADAR_CLOUD_INSECURE_SKIP_VERIFY`	Skip Hub tunnel TLS verification for a self-hosted trial using a self-signed certificate. Insecure: traffic is encrypted but the Hub is not authenticated.

Setting RADAR_CLOUD_MODE=true additionally forces --auth-mode=proxy and pins X-Forwarded-User / X-Forwarded-Groups so the in-cluster Radar impersonates the Cloud-authenticated user against the K8s API. Don’t set this for local installs.

Internal / development

Flag	Description
`--dev`	Serve the frontend from disk instead of the embedded bundle.
`--fake-in-cluster`	Pretend Radar is running in-cluster (useful for testing the in-cluster UX off-cluster).

Get started

Views

In-cluster capabilities

Integrations

Self-hosted setup

Cloud

Reference

CLI reference

Commands

`radar diagnose`

`radar cloud`

General

Cluster connection

Timeline storage

Metrics & traffic

Feature toggles

Tuning for slow or large clusters

Authentication

Radar Cloud

Internal / development

​Commands

​radar diagnose

​radar cloud

​General

​Cluster connection

​Timeline storage

​Metrics & traffic

​Feature toggles

​Tuning for slow or large clusters

​Authentication

​Radar Cloud

​Internal / development

Commands

`radar diagnose`

`radar cloud`

General

Cluster connection

Timeline storage

Metrics & traffic

Feature toggles

Tuning for slow or large clusters

Authentication

Radar Cloud

Internal / development