Frequently asked questions.

readtheplan: command not found

The entry point installed to a directory not on your PATH. This is common with pip install --user. Run python -m readtheplan.cli analyze plan.json as a workaround, or add the reported scripts directory to your PATH. On Linux/macOS this is typically ~/.local/bin; on Windows it's %APPDATA%\Python\Scripts.

Python version requirements

readtheplan requires Python 3.10 or higher. Check your version with python --version. If you're running 3.9 or earlier, upgrade Python or use a version manager like pyenv (Linux/macOS) or the official Python installer (Windows). You can install readtheplan in a venv with any supported Python version: python3.10 -m venv .venv && source .venv/bin/activate && pip install readtheplan.

pip install fails or takes forever

readtheplan is a pure-Python package with minimal dependencies: PyYAML, python-hcl2 for Vault/Consul configuration, and tomli on Python 3.10. If install is slow, try upgrading pip first: pip install --upgrade pip. If you get permission errors, use a virtual environment or pip install --user. On some platforms you may need pip3 instead of pip.

"Error: invalid JSON in plan.json" — I passed the binary plan!

This is the most common newbie mistake. readtheplan reads the JSON output of terraform show -json, not the binary tfplan file or the human-readable text output. The correct workflow is: terraform plan -out=tfplan && terraform show -json tfplan > plan.json. Then run readtheplan analyze plan.json. The binary tfplan file and the wall of text from terraform plan (without -out) are both invalid inputs.

"Error: plan file does not exist"

The plan JSON path is the last (positional) argument: readtheplan analyze <path-to-plan.json>. Make sure the file exists at that path and that you're running the command from the correct directory. Use an absolute path if needed: readtheplan analyze /full/path/to/plan.json.

"--evidence requires --framework" / "--sign requires --evidence"

These flags have a required dependency chain:

• --evidence produces a compliance evidence envelope, but it needs a framework to map controls against. Add --framework soc2 (or iso27001, hipaa).
• --sign signs the evidence envelope with sigstore, but it needs an envelope to sign. Add --evidence out.json.

Full example: readtheplan analyze --framework soc2 --evidence evidence.json --sign plan.json.

No "Controls" column in output

The Controls column only appears when you pass a compliance framework flag. Without it, readtheplan only classifies risk (safe / review / dangerous / irreversible). Add --framework soc2, --framework iso27001, or --framework hipaa to see the control mappings.

GitHub Action is not working / failing unexpectedly

Common causes:

• The plan-file input points to a binary tfplan instead of JSON. Make sure your workflow generates JSON with terraform show -json tfplan > plan.json.
• The action is set to fail on fail-on-threshold: dangerous and your plan contains dangerous or irreversible changes. Set a higher threshold or leave it empty for report-only mode.
• Missing actions/checkout@v4 step before the analysis step.
• The Terraform plan step hasn't run yet — verify job step order.

How do I use compliance frameworks in the GitHub Action?

The composite action itself doesn't expose a --framework input directly. To use frameworks, run the CLI directly in a workflow step instead of the action: python -m pip install readtheplan && readtheplan analyze --framework soc2 --format json plan.json. See the GitHub Action guide for examples.

Does readtheplan work on Windows?

Yes. readtheplan is pure Python and runs anywhere Python 3.10+ runs, including Windows. Install with pip install readtheplan (or py -m pip install readtheplan if you're using the Python launcher). If readtheplan isn't found after install, use python -m readtheplan.cli analyze plan.json or add %APPDATA%\Python\Scripts to your PATH. All CLI flags and features are fully supported.

Does it work with OpenTofu?

Yes. OpenTofu produces the same JSON plan format as Terraform. Generate the plan with tofu plan -out=tfplan && tofu show -json tfplan > plan.json and analyze it the same way: readtheplan analyze plan.json.

How do I set up the MCP server?

The MCP server is an experimental local stdio-based server for agent and IDE integrations. Install the optional MCP extra and run:

pip install "readtheplan[mcp]"
MCP_ROOT=/absolute/path/to/repository readtheplan mcp

The server communicates over stdio using the Model Context Protocol. Add it to your MCP client config (e.g. Claude Desktop, VS Code extensions) as a stdio endpoint. Set MCP_ROOT in that client configuration and use agent_gate_project to scan the repository through an isolated, descriptor-verified snapshot. Requires Python 3.10+.

MCP server gives "missing dependency" errors

The MCP dependencies are optional extras that are not installed by default. Make sure you installed with the [mcp] extra: pip install "readtheplan[mcp]". This pulls in the required MCP protocol library. If you already have the base package installed, upgrade with the extra: pip install --upgrade "readtheplan[mcp]".

Coverage below threshold when running tests locally

The test suite has a coverage gate set to fail_under=77 in pyproject.toml. If you're seeing a coverage failure, check that you're running the full suite and not a subset: pytest (with no file arguments). If adding new code, write corresponding tests. You can check current coverage with pytest --cov --cov-report=term. See the Contributing guide for the full dev workflow.

How do I set up a dev environment?

Clone the repo and install in editable mode with dev dependencies:

git clone https://github.com/readtheplan/readtheplan
cd readtheplan
python -m venv .venv && source .venv/bin/activate
pip install -e ".[dev]"

This gives you pytest, ruff, and all runtime deps. Optional extras: [sign] for sigstore, [mcp] for the MCP server.

How do I update readtheplan?

Upgrade with pip: pip install --upgrade readtheplan. If you installed optional extras, include them: pip install --upgrade "readtheplan[sign,mcp]". Check the installed version with readtheplan --version (or pip show readtheplan). Release notes are published on the GitHub Releases page.

How do I get help or report a bug?

There are several ways to reach the maintainers and community:

• GitHub Discussions — ask questions, share ideas, show off your workflow.
• GitHub Issues — report bugs or request features. Please check existing issues first.
• Good first issues — if you want to contribute, start here.
• Security policy — report vulnerabilities privately.