cub-scout
GitOps explorer for agents.
Read-only, deterministic evidence about who owns what in your cluster, how it got
there and what changed, for AI agents first and for the people and scripts they
work with. Unknowns are stated, never guessed.
The goal is verified answers with less agent spend: fewer dollars, credits
and minutes than standalone Claude needs with ordinary read-only tools. We
measure that claim, including where scout adds cost. The
3.0 delivery plan sets release criteria for
fair cost comparisons and preserved correctness; general savings are not yet proven.
v2.12.4 release
| Start here
| Is this image deployed?
| Command guide
Why this exists
"Is this deployed?" usually means several questions: did the controller consume
the right revision, did the objects reach the cluster, and is the application
ready? Those answers live in different resources and tools.
cub-scout brings that evidence together without taking over delivery. Start from
a live cluster, follow ownership and source chains, inspect failures, and compare
against supplied or ConfigHub-managed configuration. Missing evidence stays
visible; a healthy Pod is not proof that the intended release was delivered.
What you get
- Tracing and ownership map: explore resources across Argo CD, Flux, Helm, Sveltos,
Modelplane, Crossplane, kro, ConfigHub, and native Kubernetes. Evidence depth
depends on the controller and available metadata.
- Dig into deeper explanations where possible: controller progress, workload
symptoms, source revisions, field differences, and the next read-only checks.
- Data and machine friendly outputs: JSON for scripts and MCP tools for agents, plus
saved bundles and fingerprinted receipts for review. No model inference is
required to classify ownership or compute the reported evidence.
No ConfigHub account or in-cluster Scout installation is needed for standalone
inspection. Live checks need Kubernetes API access; saved-file and bundle
workflows can run offline. Observation does not modify cluster state, but read
permissions, sensitive output, and API load still matter.
Start in Two Minutes
brew install confighub/tap/cub-scout
cub-scout doctor # What needs attention?
cub-scout gitops status # What do delivery controllers report?
cub-scout map # Explore interactively
Homebrew builds the checksum-pinned release source and installs its Go build
dependency. If an old cask is installed, run
brew uninstall --cask confighub/tap/cub-scout first.
Already using cub? Run cub plugin install confighub/[email protected], then
cub scout doctor. Installation and verified downloads
cover macOS, Linux, Windows, and tagged source builds.
Five ways to run cub-scout
| Run mode | Command | Best for | Notes |
|---|
| Standalone client | cub-scout doctor, cub-scout map, cub-scout trace ... | CLI, interactive TUI, or JSON in a script | Uses the current kube context; no ConfigHub dependency. kubectl cub-scout is another invocation of this client, not another service. |
| ConfigHub plugin | cub scout doctor, cub scout compare ... | ConfigHub users who want the same observer inside their existing cub workflow | Same read-only scout behavior, with plugin-aware help text and inherited cub context. |
| MCP server | cub-scout mcp serve | Agents calling structured read-only tools | The MCP host starts a local stdio process. Nothing must already be running. Agents with shell access can also call the CLI directly. |
| Watch stream | cub-scout watch --output-file ./events.jsonl | A long-running local observer feeding incident tooling | Polling-based discovery, ownership-change, drift, and scan events; webhook and receipt output are also available. |
| In-cluster bot | cub-scout bot --webhook <url> | One observer Pod feeding an approved sink | Same polling engine, with ServiceAccount auth and CUB_SCOUT_BOT_* configuration. It does not deploy or trigger sync. See bot setup and container availability limits. |
Standalone or connected — a mode over all five surfaces. By default cub-scout
runs standalone against one kube context, with no ConfigHub dependency. Add
--with-confighub (or use the confighub_* MCP tools) to run connected to
ConfigHub for governed desired-vs-live comparison,
delivery history and live-status, fleet and Resource queries, and import
proposals. Connected mode is read-only and additive: it never writes to the
cluster, and standalone stays fully functional without ConfigHub.
Prefer browsing intended configuration in a connected TUI? The separately
installed companion explorer uses
Scout v2.10.0 in its Resource Evidence tab. Commander v0.3.0 requires an explicit
Target-ID/kube-context binding. Scout's standalone TUI remains available.
User questions
Cub-scout helps users answer questions about k8s and GitOps clusters in one place.
| User question | cub-scout surface | What cub-scout provides |
|---|
| What is running, and who owns it? | doctor, map, trace, explain | Live inventory, ownership, source chain, recent events, and next read-only checks across supported controllers and platforms. |
| Can I inspect one exact resource without running a broad diagnostic sweep? | explain Deployment/api -n prod --bounded --api-version apps/v1 --kube-context <context> --format json; MCP explain with bounded: true; TUI Ctrl+e | v2.10.0: explicit context and API identity; one discovery document and one object GET on a cold read. No controller CLI, ConfigHub, pod/event fan-out, or object LIST. The TUI requires an inventory-bound kube context; unbound/in-cluster inventory, unsupported APIs, RBAC failures, and identity mismatches remain unavailable evidence. |
| Can repeated explorer or agent reads reuse the same observation, and can I force a fresh check? | Bounded MCP explain; TUI Ctrl+e and r; CLI explain --bounded --refresh | v2.10.0: a maximum of 16 object observations reused for less than 15 seconds within one MCP/TUI session. resourceRead exposes availability, scope, timestamps, cache state, and discovery/object read counts. Refresh, expiry, and context/credential-configuration changes invalidate reuse. Leaving the TUI read cancels pending work and rejects late results. Separate CLI processes do not share this cache. |
| What did this narrow check deliberately leave unverified? | Bounded explain JSON, ASCII/Markdown, MCP, and TUI | v2.10.0: structured omissions distinguish source/controller evidence, related pods/events, and desired/live comparison from object-local ownership and readiness. Readiness is not delivery completion or application success. No Secret payload reads. |
| Which source space, unit, and revision does this live resource identify? | explain Deployment/api -n prod --bounded --api-version apps/v1 --kube-context <context> --format json; bounded MCP explain; TUI Ctrl+e | v2.10.0: configHubOrigin parses the already-read confighub.com/origin annotation, preserving space/unit IDs, slugs, and an optional exact integer revision. No additional requests or ConfigHub authentication. This is observed source metadata, not independently verified provenance, a release/target/component/variant join, or proof of delivery. . |
The main path starts from a live cluster. It works standalone with your current kube context, or connected to ConfigHub for governed comparison, history, import, fleet queries, and AI-friendly read-only workflows. Local repo and manifest inputs are available later for adoption, import-preview, and source-file enrichment, but they are not the first mental model.
Resource MCP reads and Application-row joins are v2.9.0 additions. See
release notes for scope and validation. Scoped Resource
queries use ConfigHub rather than Kubernetes, but
each repeated query still runs a fresh cub command. Watch/bot remain polling
observers; output caps and freshness stamps are not API rate limits. Reuse saved
evidence when appropriate. Request-cost proof.
v2.10.0 adds bounded explorer evidence. See the
release notes and upgrade order for Scout/companion
compatibility, request budgets, and explicit validation limits. The companion
is separately packaged; install Scout v2.10.0 before Commander v0.3.0.
v2.10.1 corrects feedback freshness. Missing or future report timestamps
cannot justify success; old success and failure reports ask for a current check.
See patch notes and upgrade guidance.
v2.11.0 added identity-linked release checks
(controller-revision evidence, exact OCI release checks, and opt-in
running-image identity) and cheaper long-running observation (within-cycle read
coalescing, opt-in watch-backed idle observation, and a new resource.deleted
event), plus local bot images built from verified release archives. See the
release notes.
v2.14.2 is the latest release. Live status is read from each Release,
where ConfigHub records it since a server change of 2026-10-03; cub-scout used
to look only at a Space annotation nothing writes any more. See the
v2.14.2 release notes.
v2.14.1: a filter given an empty value is refused where it used to run
unfiltered, and the plugin's skills match v2.14. See the
v2.14.1 release notes.
v2.14.0: cub-scout now reads ConfigHub through the
ConfigHub SDK and checks the session the same way, so a read-only command
whose reads are covered needs no cub binary; cub is still needed to log
in, for every write, and for the reads not yet moved.
CUB_SCOUT_CONFIGHUB_READER=cub reads through cub as before. A new preview
command, gitops tree, shows what is under each Argo CD Application to any
depth. No cost or time saving for an agent is claimed for either. The work
that "v2.14" used to name, the P4 acceptance gates, moved to v2.15 and is not
claimed. See the v2.14.0 release notes.
v2.13.4 made gitops settings available to
agents: an MCP tool, gitops_settings, and a compact JSON --view summary. In
the eval cases that came with it, an agent that already held the raw kubectl
export never called the tool and gained nothing, while an agent with cub-scout
and no export answered a 300-deployer question correctly in four turns; that is
three runs on generated scenarios, not a general saving. A bare
--setting <name> now selects deployers that declare the setting. See the
v2.13.4 release notes.
v2.13.3 added gitops settings, a preview command that shows which Argo CD
and Flux deployers sync on their own, revert manual changes, prune, or apply
with non-default options, grouped by project or namespace. It reports declared
settings only. See the v2.13.3 release notes.
v2.13.2 is a correction release: upgrade from v2.13.1 or earlier for it. A
receipt for a Flux-delivered workload could name its parent's Git repository
instead of its own; a failing Flux delivery could be drawn as healthy; explain
said nothing about a failing delivery chain; and suggest-remedy ran kubectl
through a shell. It also made provenance work without the flux and argocd
CLIs and brought --kube-context to nearly every command that reads a cluster.
See the v2.13.2 release notes.
v2.13.1 added explicit context and namespace binding across investigation
workflows, exact-space ChangeOrder reads, combined-origin revision claims,
separate Sveltos delivery and health reports, and recorded map and explain
input; public Go imports moved to /v2. See the
v2.13.1 release notes.
v2.12.4 improved manual-edit attribution, Argo
tracking identity and workload health, retains useful MCP output on non-zero
exits, and adds compact inventory requests. Plugin-mode hints preserve
cub scout. These changes enable smaller agent reads; a general cost or credit
savings claim remains subject to the controlled benchmark. See the
v2.12.4 release notes.
From v2.12.3, explain and trace report the owner that
ownership detection finds, as map does, instead of the tracer that ran, and
cub-scout mcp serve accepts the MCP stdio transport, so MCP clients such as
Claude Code can connect. See the
v2.12.3 release notes. From v2.12.2, when cub is older than its ConfigHub
server, connected commands now say to run cub upgrade instead of reporting an
expired session, and ConfigHub unit events are classified by their exact values,
so nothing unrecognised is reported as success. See the
v2.12.2 release notes. Image checks, from v2.12.1,
verify complete Deployment ownership and replica coverage, with bounded
credential helpers and API error responses; see the
v2.12.1 release notes and the
image verification guide.
Who reaches for cub-scout?
- SREs and on-call — when a workload is unhealthy and you need to know why and who owns it in seconds, not by clicking across Argo or Flux UIs.
- Platform engineers — when you inherit a cluster and need a trustworthy ownership map across Flux, ArgoCD, Sveltos, Modelplane, Helm, Crossplane, kro, ConfigHub, and naked YAML.
- AI agents and automation — when you need stable, deterministic JSON or a Model Context Protocol (MCP) gateway for read-only cluster facts.
cub-scout vs cub: the boundary
| cub-scout | cub |
|---|
| Role | Observe and explain | Act and govern |
| Cluster state | Read-only observation | Publishes desired releases for deployment controllers to reconcile |
| ConfigHub state | Read-only evidence; explicit import commands can write inventory | Authoring, import, promotion |
| Best for | Diagnosis, ownership, drift, attribution, AI tools | Intended-state authoring, GitOps pipelines |
cub-scout is the read-only witness for cluster state. ConfigHub (driven by cub) is the authority. The binaries ship separately; explicit inventory-import commands are distinguished from read-only observation.
Where Scout fits
Use Scout when you need cross-controller evidence that works in a terminal,
automation, and an agent workflow. Use your delivery controller or approved
deployment tooling to change desired state and reconcile it. Dedicated cluster
and GitOps explorers remain useful for live graphs, logs, and interactive
operations; Scout does not claim to replace every one of their views.
An event-driven delivery bot has a different job: trigger delivery and report
controller status back. Scout reads that feedback and checks it alongside live
evidence. Its bot mode is an observation producer, not a replacement syncer.
See the version-pinned capability comparison
for verified strengths, competing capabilities, and the gaps still on the roadmap.
Capability Map
cub-scout's commands fall into eight groups. Read them as a live-cluster journey first: observe what is running, diagnose one thing, compare live state to governed intent when connected, then use adoption/import paths only when you are ready to bring existing config into ConfigHub.
Each command's Inputs column tells you exactly what it needs — cluster only (standalone), cluster + ConfigHub auth (connected), bundle/file inputs, or a local git checkout for advanced adoption and source-enrichment flows.
Observe — see what's running
| Command | What you get | Inputs |
|---|
doctor | One-screen cluster health summary with concrete next steps and optional bounded ConfigHub delivery evidence | cluster; optional ConfigHub auth for --with-confighub |
map (TUI / list / hooks / orphans / meaning) | Ownership inventory, lifecycle hooks, orphan detection, meaning-first grouping | cluster |
trace | Full ownership chain from K8s object → controller/source evidence, with optional object-correlated ConfigHub delivery evidence | cluster; optional ConfigHub auth for --with-confighub |
tree | Runtime, ownership, git, and composition hierarchies | cluster |
scan | Audit live cluster or manifest files against 46 built-in risk patterns | cluster or file |
graph export | Resource graph as DOT/JSON | cluster |
snapshot | Dump cluster state as GSF JSON | cluster |
watch | Stream observation events to webhook/file sinks | cluster |
bot | Run the watch engine continuously as an in-cluster observer | cluster |
status | Connection mode and cluster context info | cluster |
Diagnose — interpret what you observe
| Command | What you get | Inputs |
|---|
explain | Plain-English ownership and lineage for one resource, with phase-aware next-step hints and optional object-correlated ConfigHub delivery evidence | cluster; optional ConfigHub auth for --with-confighub |
debug | Guided GitOps debugging wizard | cluster |
suggest-remedy | Read-only description of a remediation that would resolve a finding — never applies it | cluster |
patterns (detect / explain / list) | Pattern-engine catalogue + matched findings | cluster or file |
gitops status | GitOps/controller pipeline health across Flux, Argo, Sveltos, and Modelplane controllers | cluster |
gitops settings | Declared sync, self-heal, prune and apply settings of Argo CD Applications and Flux Kustomizations and HelmReleases, grouped by project or namespace (preview since v2.13.3) | cluster |
gitops tree | What is under each deployer, to any depth: child deployers and the resources each reports, with settings and state (Argo CD; a preview since v2.14.0) | cluster |
Compare — intended vs actual
| Command | What you get | Inputs |
|---|
compare (resource mode) | Single-resource DRY/WET/LIVE picture when connected; LIVE-only when standalone | cluster (+ConfigHub for DRY/WET) |
compare drift | Desired (file) vs live drift detection | cluster + file |
compare three-way | Scope-wide DRY/WET/LIVE with agreement summary and conformance verdict; --dry-from supports standalone rendered YAML as DRY | cluster + ConfigHub or rendered YAML |
compare object-set | Set-level desired-vs-live ObjectSetDiffReceipt from rendered YAML, with optional closed-world added/removed object diff | cluster + rendered YAML |
compare source-truth | Strategy-relative PASS / WATCH / ASK / BLOCK evidence for downstream acceptance tools (#393) | cluster + ConfigHub |
compare source-truth still requires connected source-truth evidence. compare three-way --dry-from and compare object-set --dry-from support standalone rendered YAML as desired-state input.
Verify — typed, fingerprinted, immutable evidence artifacts
cub-scout receipts (#446) are the persistence sibling of compare: where compare produces an ephemeral live picture, receipt verify wraps the same evidence into an in-toto Statement v1 envelope that CI/CD gates, audit trails, postmortems, and acceptance-judge tooling can attach to a decision and later re-check for tampering.
| Command | What you get | Inputs |
|---|
receipt verify <kind>/<name> | Build a typed, fingerprinted receipt asserting a resource predicate. Predicates include applied-matches-spec, source-truth-pass, no-manual-edits-since, object-set-matches, workloads-converged, and prerequisites-met. Add --with-confighub to attach bounded, object-correlated delivery evidence as supporting evidence; it does not change which system owns delivery or application-health truth. Verdicts: PASS / WATCH / BLOCK / INCONCLUSIVE. | cluster (+ ConfigHub for source-truth-pass and optional --with-confighub) |
receipt verify --file <path> --scope namespace/<ns> | Build an install/object-set receipt (object-set-matches) proving every desired object in rendered YAML is present live and every authored field still matches. Add --predicate workloads-converged to prove rendered workloads reached a ready runtime state, with --grace-window measured from current-generation progress signals. | cluster + rendered YAML |
receipt verify --fail-on <verdict> | Same, plus CI-gate exit semantics: exit 2 when the receipt's verdict matches the listed set (WATCH / BLOCK / INCONCLUSIVE / any-non-pass). Artifact is preserved on fail. | cluster |
receipt verify --input-attestation <path> | Chain receipts: reference a prior receipt via inputAttestations[]. Each referenced receipt's fingerprint is verified before chaining; tampered receipts are refused. | cluster + prior receipt file |
receipt show <path> | Render a saved receipt (ASCII or JSON). Does NOT verify the fingerprint — works on tampered receipts for forensic inspection. | receipt file |
receipt validate <path> | Recompute and compare the receipt's fingerprint. Exit 0 OK / 1 mismatch / 2 I/O. | receipt file |
receipt list | Walk the local store ($CUB_SCOUT_RECEIPTS_DIR → $XDG_DATA_HOME/cub-scout/receipts → $HOME/.local/share/cub-scout/receipts) newest first, with freshness status for saved TTL-backed receipts. | local store |
|
Wire format: in-toto Statement v1 (_type = "https://in-toto.io/Statement/v1") wrapping https://cub-scout.dev/receipt/v1. SHA-256 fingerprint over RFC 8785 canonical JSON of the full Statement minus only predicate.fingerprint. Read-only by construction — receipts emit artifacts, never mutate.
Attribute — where each value came from
cub-scout's attribution layer (#435) annotates every field mismatch with provenance evidence:
| Signal | Surfaces on | Inputs |
|---|
cause + managerHint (controller-drift / manual-edit / unknown) — from K8s managedFields | compare + explain | cluster |
gitSource.{repoUrl, revision, path} — from Argo Application / Flux GitRepository spec | compare + explain | cluster (needs argocd / flux CLI for tracer) |
gitSource.file + gitSource.line — raw-YAML back-resolution | compare | cluster + --source-path <local-checkout> |
incomingBindings[] — ConfigHub Links influencing this unit | compare | cluster + ConfigHub |
bindingSource — per-field upstream unit + binding path | compare | cluster + ConfigHub |
The verified manager-string enumeration covers Argo CD, Flux (kustomize / helm / source controllers), Helm direct, Crossplane (composite / composed / claim / MRD / refs), kro (applyset / parent / labeller), Sveltos (application/apply-patch), Modelplane via Crossplane composition managers, and kubectl-* interactive paths — strings not in the enumeration fall through to unknown rather than being guessed.
Govern — connected fleet and history
| Command | What you get | Inputs |
|---|
history | Connected ChangeSet timeline for one resource | ConfigHub |
impact | Connected blast-radius preview for one unit | ConfigHub |
fleet outliers | Deprecated in 2.x; planned 3.0 removal unless stable cross-cluster identity and fixture-backed comparisons justify retaining or rebuilding it; no equivalent replacement is available yet (#562) | ConfigHub |
summary (list / slack) | Connected summary storage + Slack delivery | ConfigHub |
views (resolve / open / project) | Resolve, open, and project ConfigHub Views (#391) | ConfigHub |
audit list | Break-glass accept/reject audit trail | ConfigHub |
bundle / catalog | Inspect, replay, diff, and summarize debug bundles + manage catalogs | bundle artifact |
Adopt Existing Config — preview imports after observing live state
Use this when you are bringing an existing cluster, Argo/Flux setup, debug bundle, or manifest repo toward ConfigHub. This is an adoption path, not the first-run troubleshooting path.
| Command | What you get | Inputs |
|---|
import --dry-run | Live-cluster ConfigHub adoption proposal | cluster |
import --from-bundle | Offline adoption proposal from captured bundle facts | bundle artifact |
import --git-path | Advanced local Git-structure preview, no upload or render | git checkout |
import parse-repo | Lower-level repo structure JSON for downstream tools | git checkout or remote URL |
import argocd | Proposal/import for one Argo CD Application's units | cluster + ConfigHub |
import cluster-aggregator | Aggregate import proposals across many clusters/controllers | cluster/bundle proposal files |
import apply | Apply an import proposal JSON to ConfigHub | ConfigHub |
app | Manage ConfigHub Apps | ConfigHub |
Today standalone import --git-path is preview-only. A --output-dir mode that emits proposed unit YAMLs to disk for review/PR/upload is in the next-up list.
Integrate — AI, setup, and infrastructure
| Command | What you get | Inputs |
|---|
setup connect | Import or create a kubeconfig context | none |
setup completion | Shell completion script | none |
quickstart demo | Fixture-backed first-run tour | none |
mcp serve | Read-only Model Context Protocol (MCP) server over stdio for Claude, Codex, agents | cluster (any subset of the above based on the tool invoked) |
bot | In-cluster read-only observation bot using the watch event stream | cluster |
context-pack | Deterministic AI context JSON export | cluster |
version | Build/version info | none |
Read commands expose structured output through --format json or a documented
--json flag; consult each command's help. Ownership and evidence logic are
deterministic for the same inputs. New live observations have new timestamps.
Fast Path (2 Minutes)
No ConfigHub signup required. Live inspection reads your Kubernetes API;
offline analysis uses saved files or bundles.
brew install confighub/tap/cub-scout
cub-scout doctor # cluster health summary
cub-scout explain deploy/api -n prod # who owns this resource?
cub-scout trace deploy/api -n prod # where did it come from?
cub-scout map # interactive TUI
If cub-scout: command not found but you have cub installed, try cub scout doctor instead — see How to invoke.
Install
# cub plugin (preferred for ConfigHub users — one install, shared auth)
cub plugin install confighub/cub-scout
cub scout version
# Homebrew
brew install confighub/tap/cub-scout
For direct downloads and tagged source builds, use the
install guide. The source module now uses
github.com/confighub/cub-scout/v2; proxy installation via
go install github.com/confighub/cub-scout/v2/cmd/cub-scout@latest installs
the latest tagged 2.x module. For a pinned install use
go install github.com/confighub/cub-scout/v2/cmd/[email protected]. Container command
docker run ghcr.io/confighub/cub-scout:v2.14.2 version still needs registry
access verification (#520); the published image is Linux amd64 only.
kubectl krew install cub-scout is not a verified distribution path; use the
kubectl-cub_scout binary included in the archives or Homebrew instead.
make build-kubectl-plugin also produces a kubectl cub-scout ... wrapper. See docs/howto/plugin-install.md for pinned-version, direct-URL, and offline installs.
How to invoke
The same Scout commands, JSON contracts, exit codes, and MCP tool names are
available through three invocation forms:
cub-scout doctor # 1. Standalone — installed directly
cub scout doctor # 2. cub plugin — after `cub plugin install confighub/cub-scout`
kubectl cub-scout doctor # 3. kubectl plugin — from `make build-kubectl-plugin`
Plugin form (cub scout ...) inherits cub's auth automatically — useful when you also use ConfigHub. Standalone form is the path of least resistance and the default for AI/MCP scenarios. Parity is enforced by a release-gate test (TestPluginParity_StandaloneMatchesPlugin).
Host-global flags can differ: cub --context selects a ConfigHub context, while
Scout's bounded --kube-context selects the Kubernetes context to inspect.
Standalone vs Connected
Standalone does not mean disconnected from Kubernetes: live checks need API
access. Saved-file and bundle analysis can run offline. ConfigHub connected
mode is optional and adds intended-state, history, and fleet context.
Standalone (no signup): ownership detection, tracing, health diagnosis, drift hints, risk scanning, JSON, MCP gateway, attribution via managedFields + Flux/Argo/Helm/Sveltos/Modelplane/Crossplane trace resolvers + (with --source-path) raw-YAML file:line resolution.
Connected (cub auth login): adds the historical and cross-cluster context the Kubernetes API doesn't have:
- DRY vs WET vs LIVE — compare what ConfigHub intended, what the renderer produced, and what's actually running. Catches drift the live cluster can't tell you about.
- Per-field binding source — answer "this field's value came from upstream unit X at path Y via link Z."
- Change history —
kubectl events only goes so far; history walks the ConfigHub governed timeline.
- Delivery evidence —
gitops status --with-confighub, doctor --with-confighub, trace --with-confighub, explain --with-confighub, map activity --with-confighub, and single-resource receipt verify --with-confighub add bounded release history, unit events, live-status writeback, event-consumer health, rollups, object-correlated snapshots, timeline rows, fingerprinted evidence, and omissions for a known space/time window.
- Fleet queries — "is this version running everywhere it should?" across many clusters.
- Live-cluster adoption preview — propose how current workloads should be modeled in ConfigHub before writing anything.
Important: connected import writes ConfigHub records, not cluster manifests. cub-scout never modifies the cluster.
Local repository parsing (import --git-path, import parse-repo) is a second-order adoption path: use it when a manifest repo is the thing you are reviewing or when you need source structure to enrich the live-cluster story.
Signature Example
trace is the headline feature — it answers "what created this?" without making you stitch Deployments, Applications, Helm releases, Sveltos profiles, Modelplane model resources, labels, annotations, and controller state by hand:
$ cub-scout trace deploy/frontend -n boutique
TRACE: Deployment/frontend in boutique
Owner: Flux
Source: GitRepository/flux-system/platform-config
Path: clusters/prod/apps/boutique
Status: Ready
Recent events:
Warning BackOff (3x, 5m) kubelet: Back-off restarting failed container
Next:
cub-scout explain deploy/frontend -n boutique
For more, see docs/reference/commands.md#trace.
Interfaces
| Interface | Best for | Start here |
|---|
| TUI | Interactive exploration, keyboard-driven debugging | cub-scout map |
| CLI | One-off triage, shell use, pipelines | doctor, explain, trace |
| JSON | Automation, AI, MCP, downstream tooling | --format json or --json |
Press ? inside the TUI for shortcuts.
Scan Variants
scan is the fastest way to audit a cluster or manifest set for known risk patterns. The built-in scanner covers 46 patterns, and the broader confighub-scan catalog tracks 3,513 risk patterns for deeper policy and detection work.
Common entrypoints:
cub-scout scan --statecub-scout scan --kyvernocub-scout scan --lifecycle-hazardscub-scout scan --timing-bombscub-scout scan --danglingcub-scout scan --file manifest.yamlcub-scout scan --jsoncub-scout scan --normalized-json
Detailed scanner behavior and output shape: docs/reference/commands.md#scan and docs/reference/json-contracts.md.
AI integration
For Claude, Codex, and other AI agents:
cub-scout mcp serve is a read-only MCP server over stdio backed by the same CLI JSON surfaces — same answers, agent-shaped. It's not a Kubernetes write tool, not a multi-gateway router, and not the ConfigHub authority layer (that role belongs to cub).
What's coming next
Honest gaps in the current capability map, with the leverage on filling them:
- Helm / Kustomize provenance back-resolution — #481 extends raw-YAML field attribution from stage B (#440) to templated sources while preserving honesty markers when exact file:line evidence is unavailable.
- Live delivery observability follow-ups — aggregate controller-resource failures with generated-artifact lineage as top-level
doctor findings, audited action events as history/receipt evidence, deeper object-level correlation for release/event/live-status evidence (#502), and parity omissions for controllers without status/source/event/generation evidence.
import --git-path --output-dir — emit proposed unit YAMLs to disk for PR review, then upload via Installer's --merge-external-source once connected. One bundle, two workflows.- Hierarchy-aware adoption/import — preserve ApplicationSet / app-of-apps / Flux Kustomization composition in import proposals so imported ConfigHub state is navigable, not flat.
- Additional manager-string writers — Tekton, Argo Workflows, Cluster API, OIDC-based CD systems — gated on whether the variant-management story demands them.
Documentation Map
Build From Source
git clone https://github.com/confighub/cub-scout.git
cd cub-scout
go build ./cmd/cub-scout
./cub-scout version
Principles
- Read-only, by design — observation uses only
Get, List, Watch. No apply, no delete, no admission webhook. Even suggest-remedy only describes a fix — it does not run it.
- Deterministic — same inputs, same outputs. No AI/ML inference in the ownership logic.
- Parse, don't guess — ownership and attribution come from real labels, annotations, owner references, controller facts, and verified manager-string enumerations. Unknown is preferred over wrong.
- Complement GitOps, don't replace it — cub-scout helps you understand Flux, ArgoCD, Sveltos, Modelplane, Helm, Crossplane, kro, and ConfigHub state. It's not another reconciler.
- Graceful degradation — works without ConfigHub, without internet, and many flows work without a live cluster (debug bundles, manifest scans, Git-path import preview).
- Evidence, not authority — cub-scout is the read-only witness. ConfigHub (via
cub) is the authority for intended state.
For more on the security model, see SECURITY.md.
Contributing
Contributions welcome. See CONTRIBUTING.md.
- Found a bug? Open an issue
- Have an idea? Start a discussion
- Want to contribute? PRs welcome
Community
