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

GateMeaningNever means
BLOCKEDA rule in the profile's blocking set fired, or rollback evidence is missing"Cannot ever ship" (a human may accept the risk)
HUMAN_REVIEW_REQUIREDStatic checks found no blocker under this profileSafe, 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

MessageCauseFix
Invalid manifest: Unsupported YAML syntax (template)…Helm/Go template in the fileRender to plain YAML first
Unsupported YAML syntax (anchor, alias or tag)&x, *x, !!tagExpand them or convert to JSON
Mismatched Kubernetes resource identityTwo different single resourcesCompare the same resource, or use multi-document files
Input must be a regular non-symlink file <= 1 MiBSymlink or large fileCopy a plain file
Duplicate resource identitySame kind/namespace/name twice in one fileRemove the duplicate
Exit 3 on verifyReport was editedRegenerate it