User guide
1. Compare two versions of a manifest
npx deploysutra-ai analyze --before fixtures/k8s/before.yaml --after fixtures/k8s/after.yaml --profile production --out report
Open report/deploy-readiness.html. Read in this order: the banner (gate and reasons), Findings, Changes, Blast radius, Rollback, Verification boundaries. Exit code 2 means BLOCKED.
2. Reading the gate
| Gate | Meaning | Never means |
|---|---|---|
BLOCKED | A rule in the profile's blocking set fired, or rollback evidence is missing | "Cannot ever ship" (a human may accept the risk) |
HUMAN_REVIEW_REQUIRED | Static checks found no blocker under this profile | Safe, approved or ready |
3. Choosing a profile
development and staging block on HIGH; production blocks on HIGH and MEDIUM. The report records whether you chose it or the default (staging) applied.
4. Multi-document files
Put a whole stack in one YAML file separated by --- (see fixtures/k8s/stack-*.yaml). Resources are matched by kind, namespace and name. Anything missing from AFTER is reported removed (DS-K8S-019).
5. Rules
npx deploysutra-ai rules
npx deploysutra-ai explain DS-K8S-012
npx deploysutra-ai policy --input app.yaml --fail-on HIGH
policy is a quick lint of one file; --fail-on makes it a CI step.
6. Rollback evidence
Create a JSON file with previousRevision, backupVerified, restoreTestPassed, rollbackProcedure, operatorApprovalVerified and pass --rollback file.json. Each present item shows as DECLARED_NOT_VERIFIED. Only an actual restore drill, observed by a person, closes the gap; this tool cannot do it.
7. Terraform / OpenTofu plans
tofu show -json plan.out > plan.json # contains secrets: keep private
npx deploysutra-ai tofu --input plan.json --out plan-report
Only counts per action and resource type remain. Sections such as variables and prior_state are named as discarded, never copied.
8. CI example (GitHub Actions)
- run: npx -y deploysutra-ai analyze --before base/app.yaml --after app.yaml --profile production --out report
- if: always()
uses: actions/upload-artifact@v4
with: {name: deploysutra-report, path: report}
The step fails with exit 2 when BLOCKED. It needs no secrets.
9. Verify and audit
npx deploysutra-ai verify --report report/deploy-readiness.json
npx deploysutra-ai audit --out audit-out
Open audit-out/audit-report.html.
10. Use it from an AI assistant
npx deploysutra-ai install-skills --host claude --target . # also: cursor, codex, gemini, copilot, opencode
Start with the deploysutra-prime skill. Skills only run the same read-only commands; they cannot deploy. For a tool-calling host add the MCP server:
{"mcpServers": {"deploysutra": {"command": "npx", "args": ["-y", "deploysutra-ai", "mcp", "--root", "."]}}}
Tools: compare_manifests, explain_policy, list_policies, summarize_plan_actions, list_rollback_gaps, verify_evidence.
11. Troubleshooting
| Message | Cause | Fix |
|---|---|---|
Invalid manifest: Unsupported YAML syntax (template)… | Helm/Go template in the file | Render to plain YAML first |
Unsupported YAML syntax (anchor, alias or tag) | &x, *x, !!tag | Expand them or convert to JSON |
Mismatched Kubernetes resource identity | Two different single resources | Compare the same resource, or use multi-document files |
Input must be a regular non-symlink file <= 1 MiB | Symlink or large file | Copy a plain file |
Duplicate resource identity | Same kind/namespace/name twice in one file | Remove the duplicate |
Exit 3 on verify | Report was edited | Regenerate it |