@iverson-cloud/cli

What breaks if this workload changes — answered in your terminal, before you touch it.

The 30–90 minutes of pre-change spelunking — grepping manifests, asking in Slack who still calls this thing, tracing service selectors by hand — deleted. One command asks the live dependency graph that the Iverson agent already watches in your cluster.

$ iverson what-breaks orders-db

orders-db: 14 workloads go down with it — including 2 user-facing paths
[critical] payments/Deployment/orders-db

direct dependents (4):
  cart                     payments/Deployment/cart
  checkout                 payments/Deployment/checkout
  order-api                payments/Deployment/order-api
  payment-api              payments/Deployment/payment-api
  ...plus 10 more workloads further downstream

user-facing paths:
  api-gateway              edge/Ingress/api-gateway
  storefront               edge/Ingress/storefront

computed from the live dependency graph in your cluster (prod-eu, snapshot 47s ago)

That last line is the point: this is not a guess from YAML. It is computed from the dependency graph the read-only agent observes in your actual cluster, refreshed every minute.

Install

npm i -g @iverson-cloud/cli

Node 18 or newer. Zero runtime dependencies — and that is deliberate, not an accident of scope. This CLI handles a credential to your cluster's topology, so there is no dependency tree to audit, no transitive package that can turn malicious in a minor release, and npm ls on this package will always be one line. Everything it does is built-ins plus fetch; the whole program is one readable file.

Setup

Two environment variables — the same two secrets the Iverson PR-check Action uses. One credential story: get them once from your platform team, use them in CI and in your terminal.

export IVERSON_API_KEY="co_live_..."       # your cluster's read-only agent key
export IVERSON_CLUSTER_ID="<cluster-id>"   # from the dashboard URL: .../app/<cluster-id>

Optional: export IVERSON_API="https://app.iversoncloud.com" (the default). Per-invocation overrides exist as --key, --cluster, --api.

The key is sent in an Authorization header to your Iverson endpoint and nowhere else. It is never written to disk and never printed — not even in error messages.

Usage

Blast radius for one workload

iverson what-breaks orders-db                        # bare name
iverson what-breaks payments/orders-db               # namespace/name
iverson what-breaks payments/Deployment/orders-db    # the full key

A bare name is resolved against the cluster's ranked list. If it is ambiguous, you get the candidates; if it is a near-miss, you get a did-you-mean:

$ iverson what-breaks orders-bd
No workload matching 'orders-bd'. Did you mean:
  iverson what-breaks payments/Deployment/orders-db

The ranked list

No argument gives you the cluster's top 10 by blast radius — whose failure costs the most, worst first:

$ iverson what-breaks

what breaks — top 10 by blast radius

 1. [critical] orders-db    14 down 2 user-facing paths  payments/Deployment/orders-db
 2. [high]     catalog       6 down 1 user-facing path   shop/Deployment/catalog
 3. [moderate] redis         2 down                      infra/StatefulSet/redis
 ...

iverson what-breaks <workload> for the full picture
computed from the live dependency graph in your cluster (prod-eu, snapshot 47s ago)

This is deliberately not a CEI ranking: CEI judges the workload itself, this ranks purely by what it takes down with it. A stable, well-governed service that half the cluster calls belongs at the top of this list.

Ask Iverson AI

Add --ai (or -ai) to analyse a scenario in plain English. The engines still compute every figure and the verdict deterministically; a model — when your Iverson instance has one configured — only rewrites the closing narrative, so the answer is one you can take to a change-approval meeting.

$ iverson what-breaks "what happens if orders-db fails" --ai

Iverson AI — what happens if orders-db fails
[Don't do this without a plan]

Fourteen workloads go down with it, including two user-facing paths.

What breaks (14):
  cart
  checkout
  ...

computed from the live dependency graph in your cluster (prod-eu, snapshot 12s ago)

Everything after what-breaks is the scenario, so an unquoted phrase works too (iverson what-breaks delete orders-db --ai). It uses the same two secrets as the plain command, and --json still returns the raw response.

Raw JSON

iverson what-breaks orders-db --json | jq '.direct_dependents'

--json passes the API response through untouched — pipe it to jq, feed it to a script, wire it into a runbook.

Color

ANSI color is used only when stdout is a TTY, and NO_COLOR is respected. Piped output is always plain.

The ladder

This CLI is the terminal rung of the same product:

• Terminal (this): ask before you touch anything.
• Pull request: the same blast-radius analysis comments on every PR that changes a manifest — a copy-paste GitHub Action, no org admin, same two secrets.
• Dashboard: drift, single points of failure, and prescriptions at app.iversoncloud.com.

License

MIT