CLI reference

The CLI has one command: mirops scan. The inputs you give pick the checks. Every flag has an environment-variable equivalent, MIROPS_<FLAG> (dashes become underscores); flags take precedence over env vars, and a variable that doesn't parse stops the CLI with exit 2.

mirops scan --source <mirror report> [-n <namespaces>] [--upgrade --upgrade-source <analysis report>] [--enforce] [--output table|json]

Flags

Flag	Env var	Default	Purpose
--source	MIROPS_SOURCE	—	The ClusterMirror report (<name>.mirops): path, file://, s3://, azure://, http(s)://. An UpgradeAnalysis report here is gated on directly, as in 0.1.0.
-n, --namespace	MIROPS_NAMESPACE	—	Namespaces to show the state of: one, a comma-separated list, or all. Never blocks.
--upgrade	MIROPS_UPGRADE	false	Run the upgrade check.
--upgrade-source	MIROPS_UPGRADE_SOURCE	—	The UpgradeAnalysis report (<name>.mirops) to gate on. Required with --upgrade.
--enforce	MIROPS_ENFORCE	false	Exit 1 when the upgrade verdict blocks
--enforce-level	MIROPS_ENFORCE_LEVEL	critical	Minimum level that blocks: critical | warning
-f, --file	MIROPS_FILE	—	Reserved for the deploy check of manifests; not available yet (exit 2).
--output	MIROPS_OUTPUT	table	Output format: table | json
--version	—	—	Print the CLI version
-h, --help	—	—	Help

--api-url, --api-token and --cluster exist for a hosted mode that isn't implemented yet.

The upgrade check

With --upgrade, the CLI:

1. Reads the mirror report. If it says upgrade analysis is off in the cluster, it exits 2 with the command to turn it on.
2. Reads the analysis report at --upgrade-source. The target version comes from that report.
3. If the cluster (per the mirror) already runs the target version, reports skipped and passes.
4. Otherwise prints the analysis and its verdict; with --enforce, a blocked verdict exits 1.

The CLI never looks the analysis up by itself — you give its URL.

Exit codes

Code	Meaning
0	Passed, or nothing to check on purpose (no upgrade pending)
1	The upgrade verdict blocked, and --enforce is set
2	Couldn't evaluate: missing or unreadable source, unknown report kind, bad flag or variable, nothing to scan, --upgrade without --upgrade-source, a namespace the mirror doesn't have, upgrade analysis off. Never a pass.

Examples

export MIROPS_SOURCE=s3://bucket/prod/default.mirops

# a namespace's state — never fails
mirops scan -n payments
mirops scan -n payments,checkout
mirops scan -n all                      # only namespaces with something at risk

# CI gate — fail on CRITICAL
mirops scan --upgrade --upgrade-source s3://bucket/prod/to-1-35.mirops --enforce

# stricter — also fail on WARNING
mirops scan --upgrade --upgrade-source s3://bucket/prod/to-1-35.mirops --enforce --enforce-level warning

# JSON for another tool
mirops scan -n all --output json | jq '.checks'

JSON output

--output json prints one document:

Field	Meaning
schemaVersion	1. Bumped only for a breaking change; new optional fields don't bump it.
source	The --source that was read.
mirror	The mirror's name, generatedAt, clusterVersion, and summary.
checks.namespaces[]	Each requested namespace: namespace, risk, components, atRisk, atRiskComponents.
checks.otherHealthyNamespaces	With all: how many namespaces were left out because nothing in them is at risk.
checks.upgrade	status (evaluated | skipped), source, blocking, allow, level, blockers, reason, targetVersion, …

checks.upgrade.blocking says whether this verdict fails the pipeline under --enforce at the current --enforce-level.

Sources

Scheme	Auth
local / file://	—
http://, https://	— (the operator's report endpoint)
s3://bucket/key	IRSA / instance profile / env vars / static keys
azure://account/container/blob	DefaultAzureCredential (Workload/Managed Identity, az login, service principal)

Cloud credentials (for remote sources)

The CLI reads reports from the cloud (it doesn't write — that's the operator's job). Each source resolves credentials for its own scheme, so the mirror and the analysis reports can live in different places. In CI, the simplest option is the provider's standard environment variables:

Source	Environment variables
S3	AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, AWS_REGION (and AWS_SESSION_TOKEN for temporary creds)
Azure Blob	AZURE_CLIENT_ID, AZURE_TENANT_ID, AZURE_CLIENT_SECRET

Inside the cloud you can set nothing and rely on IRSA (S3) or Workload / Managed Identity (Azure); from a laptop, az login or an AWS profile works too.

export MIROPS_SOURCE="azure://myacct/reports/default.mirops"
export AZURE_CLIENT_ID=... AZURE_TENANT_ID=... AZURE_CLIENT_SECRET=...
mirops scan -n all

See Use it in CI/CD for a full pipeline example.