devready-cli
Advanced tools
A local-first, read-only CLI that checks a project's environment requirements against what is installed.
A zero-dependency, read-only CLI that checks whether your machine actually meets a project's declared requirements, and tells you exactly what to fix. Built for humans, CI, and AI coding agents (Claude Code, Codex, any MCP client).
One command, every requirement checked, exact fixes shown.
DevReady is a command-line tool that tells you whether your computer is set up to work on a project. Run devready check inside a project folder and it:
.nvmrc, .python-version, package.json engines, pyproject.toml requires-python).1 if a requirement is unmet, so it also works in CI.It only looks. It never installs, changes or deletes anything, makes no network calls and sends no telemetry. Fixing the problem (for example switching Node versions) is up to you.
You clone a repo. npm install explodes. The README says "Node 20", your machine has 16, and the error message says nothing useful. Multiply by every new hire, student, CI runner and AI agent that burns tokens guessing why a build failed.
$ devready check
DevReady - Environment Check
[PASS ] Python 3.15.0 found
[PASS ] Git 2.52.0 found
[PASS ] Node.js 23.5.0 found
[PASS ] npm 11.14.1 found
[FAIL ] Node engines 23.5.0 does not satisfy package.json engines (>=99)
[WARN ] Python pin 3.15.0 does not satisfy .python-version (3.99)
4 passed, 1 warning, 1 failed
No changes were made to your system.
Output above is from a real run (pins deliberately set to impossible values to show failures). Exit code
1when a requirement is unmet, so it drops straight into CI.
| 🎯 Project-aware | Reads what your project declares (.nvmrc, .node-version, .python-version, package.json engines, pyproject.toml requires-python) and compares it to what is installed. Not just "is Node installed?" |
| 🔒 Read-only by design | Never installs, edits or deletes. Never prints env values. No network. No telemetry. |
| 🤖 Agent-ready | Stable, versioned JSON schema, a Claude Code plugin, an MCP server and AGENTS.md. Agents check first instead of guessing. |
| 🛡️ Prompt-injection safe | Output contains only parsed versions and fixed text, never raw file or command output, so a hostile package.json can't smuggle instructions to your agent (tested). |
| 📦 Zero dependencies | Pure Python standard library. Installs in a second, runs anywhere Python 3.10+ does. |
| ⚙️ CI-friendly | Documented exit codes, JSON output, tested on Linux, macOS and Windows in CI. |
devready check in your README's setup steps and cut "it doesn't work" issues.Install from PyPI:
pipx install devready-cli
# or run without installing:
uvx devready-cli check
From npm (runs the same PyPI release through uvx or pipx, so one of them must be installed):
npx devready-cli check
From a clone (for development):
git clone https://github.com/Evalogical-Inc/devReady && cd devReady
python -m venv .venv
# Windows: .venv\Scripts\Activate.ps1 macOS/Linux: source .venv/bin/activate
python -m pip install -e ".[dev]"
devready check # human-readable report for the current directory
devready check --quiet # only non-pass results (text format)
devready check --project ../app # inspect another project's pins
devready check --format json # machine-readable (see docs/schema.json)
devready explain docker.daemon # what a check means and how to fix it
devready check --format junit # or sarif, for CI
devready check --only project --skip project.ports # filter by id or prefix
devready fix --plan # suggested steps only; never runs them
devready check --format json > baseline.json # save a snapshot (commit it for a team baseline)
devready check --baseline baseline.json # show only what changed; fail only on new/worse failures
devready init > .devready.json # optional config: skip ids, require node/python, required env names
devready mcp # run as an MCP server over stdio
devready --version
| Exit code | Meaning |
|---|---|
0 | No blocking failures |
1 | A project requirement is not met |
2 | Invalid usage (e.g. bad --project path) |
3 | Internal error |
| Status | Meaning |
|---|---|
pass | Requirement met |
warn | Tool missing, or a soft pin (.nvmrc, .python-version) differs |
fail | A hard requirement (engines, requires-python) is not met |
skip | Not evaluated (tool absent, or requirement syntax not understood) |
error | DevReady couldn't run the check |
{
"schema_version": 1,
"results": [
{
"check_id": "project.node.engines",
"title": "Node engines",
"status": "fail",
"summary": "23.5.0 does not satisfy package.json engines (>=99)",
"suggestion": "Switch versions with your version manager (nvm, pyenv, mise, ...) or update the requirement.",
"docs_url": ""
}
]
}
- uses: Evalogical-Inc/devReady@v1.3.0
with:
skip: project.ports # optional; also: only, format, project, version
To show findings in GitHub code scanning, save a SARIF report and upload it. Pin findings point at the file that declares the pin (package.json, .nvmrc, go.mod, ...); tool-only findings have no file.
- uses: Evalogical-Inc/devReady@v1.3.0
with:
format: sarif
output: devready.sarif
continue-on-error: true # still upload when a requirement is unmet
- uses: github/codeql-action/upload-sarif@v4
with:
sarif_file: devready.sarif
The job fails when a declared requirement is unmet (fail). It installs devready-cli from PyPI, so flags added after your installed release (--only, --skip, junit/sarif) need a release that includes them; set version: to pin one.
Tell contributors your project declares its requirements and can be checked with one command. Paste this into your README:
[](https://github.com/Evalogical-Inc/devReady)
DevReady ships the same engine three ways, so your agent can verify the environment before it installs, builds or tests.
Claude Code - plugin with a skill, a /devready:doctor command and an MCP server (the MCP server needs uv; the rest works without it once devready-cli is installed):
/plugin marketplace add Evalogical-Inc/devReady
/plugin install devready --marketplace Evalogical-Inc/devReady
Any MCP client (Codex, Cursor, ...) - one read-only tool, check_environment. Also listed in the MCP Registry as io.github.Evalogical-Inc/devready:
# ~/.codex/config.toml (verify keys against your Codex version)
[mcp_servers.devready]
command = "uvx"
args = ["--from", "devready-cli", "devready", "mcp"]
Anything else - drop AGENTS.md in your repo, or copy skills/devready. Details in docs/agents.md.
See docs/security.md for the model, docs/versioning.md for what stays stable, docs/checks.md for every check, and SECURITY.md to report a vulnerability.
.nvmrc, .node-version, .python-version, .tool-versions, package.json engines, pyproject.toml requires-python), .env.example vs .env key names, Docker CLI + daemon, compose file validity and image platform (arm64 vs amd64) mismatch (only when the project has a Dockerfile/compose file), free disk space, Windows long paths, PowerShell policy, line endings, WSL version and Docker Desktop engine, macOS/Linux build tools, and (only when the project declares them) Go, Ruby, Java, Rust, .NET, pnpm, Yarn and Bun pins, .env not git-ignored, node_modules vs lockfile, and declared ports already in use.skip rather than guess..venv/venv, else the first python on PATH), and the result names the interpreter checked. DevReady does not look at other virtualenv locations (poetry, conda, pyenv shims)..tool-versions, .env key-name diff, disk space, git identity, devready explainfix --plan, GitHub Action.devready.json config, --baseline snapshotsfnm)--recursive, org --policy file, VS Code extension (see ROADMAP.md)Have a setup problem DevReady should catch? Open an issue. Early feedback shapes the roadmap.
PRs welcome, especially new read-only checks and platform fixes. Start with CONTRIBUTING.md and the technical plan; background research is in docs/research.md. Please follow the Code of Conduct.
ruff check . && ruff format --check . && pytest
DevReady is built and maintained by Evalogical, a software company offering AI-enabled product engineering, custom software and IT services. Need help with a product or an engineering team? Talk to us.
MIT © Evalogical Inc
If DevReady saved you an afternoon, a ⭐ helps others find it.
FAQs
A local-first, read-only CLI that checks a project's environment requirements against what is installed.
The pypi package devready-cli receives a total of 349 weekly downloads. As such, devready-cli popularity was classified as not popular.
We found that devready-cli demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 1 open source maintainer collaborating on the project.
Security News
GitHub is tightening GitHub Actions security with new restrictions on privileged pull request workflows. Here's what changes and how maintainers are affected.
Security News
/Application Security
A practical guide to securing GitHub Actions against supply chain attacks, covering malicious pull requests, credential theft, dependency risks, and release pipelines.
Security News
Composer 2.11 adds dependency cooldowns, joining package managers that delay new releases to reduce supply chain risks while allowing urgent security updates.