Every command. Every flag.

Installation

pip install readtheplan

Requires Python 3.10+. Signing requires the optional sign extra.

pip install "readtheplan[sign]"

readtheplan scan

Recursively discover supported infrastructure files, run the matching local analyzers, and emit one aggregate project gate. Dependency/build directories and symlinks are skipped by default.

readtheplan scan --framework soc2 .

Flags

Output uses rtp-agent-gate-v1 with adapter: project-scan, aggregate risk counts, per-file summaries, and redacted validation errors. Exit codes are 0 proceed, 1 warn, and 2 block.

readtheplan analyze

Analyze a Terraform plan JSON file and classify every change by risk tier.

readtheplan analyze [flags] plan.json

Flags

Exit codes

0 means analysis succeeded without tripping --fail-on; 1 means a hard error such as invalid input or an I/O failure; 2 means analysis succeeded and one or more changes met or exceeded the configured threshold.

readtheplan agent-gate

Emit a proceed/warn/block decision for CI pipelines and AI coding agents.

readtheplan agent-gate [flags] plan.json

Flags

Output

JSON with schema, decision (proceed/warn/block), risk, required_checks, allowed_next_actions, prohibited_next_actions, pr_comment, evidence_checklist, auditor_summary, and risk_counts.

readtheplan agent-gate plan.json
# → {"schema": "rtp-agent-gate-v1", "decision": "block", "risk": "irreversible", ...}

readtheplan verify

Verify a signed rtp-evidence-v1 envelope.

readtheplan verify evidence.json

readtheplan mcp

Start the experimental local MCP stdio server for agent and IDE integrations. Requires Python 3.10+.

readtheplan mcp

Install the MCP extra if you get missing dependency errors:

pip install "readtheplan[mcp]"

Set MCP_ROOT to the repository boundary, then call agent_gate_project from the MCP client to auto-discover supported infrastructure. Each candidate is descriptor-verified and copied into an isolated temporary snapshot before analysis; the tool also accepts framework, excludes, max_files, and max_file_bytes.

readtheplan cloudformation

Emit an agent-gate decision for a CloudFormation Change Set or template diff.

readtheplan cloudformation change-set.json

See GitHub Action guide for CI integration.

Configuration and pipeline adapters

Use the same rtp-agent-gate-v1 output and proceed / warn / block decisions across popular infrastructure tools.

readtheplan kubernetes --framework soc2 manifests.json
readtheplan azure whatif.json
readtheplan bicep main.bicep
readtheplan cdk cdk.out/manifest.json
readtheplan terraform-lock .terraform.lock.hcl
readtheplan terraform-state state.json
readtheplan terraform-stack stack.tfdeploy.hcl
readtheplan pulumi preview.json
readtheplan pulumi-project Pulumi.yaml
readtheplan ansible playbook.yml
readtheplan ansible-project ansible.cfg
readtheplan ansible-project inventory.yml
readtheplan ansible-project execution-environment.yml
readtheplan ansible-project ansible-navigator.yml
readtheplan salt state.sls
readtheplan salt-project master
readtheplan nix flake.nix
readtheplan dsc configuration.dsc.yaml
readtheplan cfengine promises.cf
readtheplan opa policy.rego
readtheplan sentinel policy.sentinel
readtheplan sops .sops.yaml
readtheplan vagrant Vagrantfile
readtheplan cloud-init user-data.yml
readtheplan docker-bake docker-bake.hcl
readtheplan dockerfile Dockerfile
readtheplan azure-pipelines azure-pipelines.yml
readtheplan bitbucket-pipelines bitbucket-pipelines.yml
readtheplan jenkins Jenkinsfile
readtheplan jenkins-jcasc jenkins.yaml
readtheplan jenkins-project plugins.txt
readtheplan teamcity .teamcity/settings.kts
readtheplan chef default.rb
readtheplan chef-project Policyfile.rb
readtheplan chef-project Berksfile
readtheplan chef-project Berksfile.lock
readtheplan chef-project client.rb
readtheplan chef-project chef-server.rb
readtheplan puppet site.pp
readtheplan puppet-project Puppetfile
readtheplan puppet-project puppet.conf
readtheplan puppet-project bolt-project.yaml
readtheplan puppet-project inventory.yaml
readtheplan github-actions .github/workflows/deploy.yml
readtheplan gitlab-ci .gitlab-ci.yml
readtheplan circleci .circleci/config.yml
readtheplan travis-ci .travis.yml
readtheplan drone-ci .drone.yml
readtheplan woodpecker-ci .woodpecker.yml
readtheplan concourse pipeline.yml
readtheplan bamboo bamboo-specs/bamboo.yml
readtheplan codebuild buildspec.yml
readtheplan cloud-build cloudbuild.yaml
readtheplan codepipeline codepipeline.json
readtheplan docker-bake docker-bake.hcl
readtheplan docker-compose compose.yml
readtheplan nomad job.nomad.hcl
readtheplan packer image.pkr.hcl
readtheplan skaffold skaffold.yaml
readtheplan devspace devspace.yaml
readtheplan tilt Tiltfile
readtheplan cue deploy_tool.cue
readtheplan jsonnet main.jsonnet
readtheplan tanka environments/production/spec.json
readtheplan helmfile helmfile.yaml.gotmpl
readtheplan terramate terramate.tm.hcl
readtheplan spacelift .spacelift/config.yml
readtheplan ytt config.yml
readtheplan vendir vendir.yml
readtheplan kbld kbld.yml
readtheplan imgpkg .imgpkg/images.yml
readtheplan kapp kapp-config.yml

pulumi consumes saved preview output; pulumi-project scans Pulumi.yaml, stack settings, and policy-pack metadata without executing runtimes, compilers, package installers, plugins, or policy code.

Kubernetes accepts JSON/YAML manifests, kind: List, multi-document YAML, and structured diff wrappers, so rendered Helm, Kustomize, Crossplane, Argo CD, Flux, Tekton, Cluster API, and Karpenter artifacts work directly. Argo CD, Flux, Tekton, Cluster API, and Karpenter receive native controller, pipeline, cluster/machine lifecycle, and node provisioning/disruption rules. bicep scans source before compilation; azure accepts Bicep/ARM deployment What-If JSON with FullResourcePayloads for operation-level analysis. Pulumi accepts structured preview digest JSON and streaming JSON events. SOPS accepts .sops.yaml policy and encrypted YAML, JSON, dotenv, or INI data, but never decrypts values or contacts a key service. Ansible playbooks, controller configuration, Galaxy requirements, static YAML/INI inventory, and dynamic inventory plugin configuration are parsed without executing inventory code, resolving Vault values, contacting APIs, or connecting to hosts. Jenkins JCasC, Bamboo Specs, Concourse, AWS CodeBuild, Google Cloud Build, static Salt SLS, rendered Salt project configuration/top/roster files, and cloud-init cloud-config input are parsed as structured YAML; puppet.conf is parsed as duplicate-safe sectioned configuration for agent, server, CA, trust, execution, and reporting settings; AWS CodePipeline accepts JSON or YAML definitions. Docker Buildx Bake accepts HCL, JSON, and Compose-backed build definitions but never invokes Buildx, reads secret files, fetches contexts/caches, or publishes artifacts. Templated inputs receive conservative scanning. Jenkinsfiles, TeamCity Kotlin DSL, Chef, Puppet manifests/projects, Vagrant, and Dockerfiles use conservative syntax-aware scanners. GitHub Actions, GitLab CI, CircleCI, Azure Pipelines, Bitbucket Pipelines, and Docker Compose parse YAML structurally; external templates, protected-resource settings, secured variables, Compose files, and build contexts are not resolved. Nomad accepts HCL/JSON jobspec source or the structured job-plan HTTP API response. Packer accepts saved human or machine-readable inspect output. None of the adapters execute user configuration or contact infrastructure services.

Adapter exit codes are 0 for proceed, 1 for warn, and 2 for block. Add any built-in framework — soc2, iso27001, hipaa, pci_dss, fedramp_moderate, or hitrust — to include required control checks.