Download the PHP package rtcoder/devdoctor without Composer

DevDoctor

Developer diagnostics for humans.

DevDoctor is a read-only CLI for catching common local, repository, environment, cache, HTTP URL, database, queue, Docker, Composer, Git, Node/frontend, Flutter/Dart, native mobile, monorepos, Python, Ruby/Rails, Go, Rust, Java/JVM, MCP agent config, Terraform/IaC, Kubernetes/Helm, .NET, C/C++, generic web, and CI problems before they turn into manual debugging sessions.

Current version: 1.48.0

Installation

DevDoctor requires PHP 8.5 or newer.

DevDoctor currently runs from the project checkout:

Build a local PHAR:

Tagged releases publish both the PHAR and PHPacker standalone binaries for Linux, macOS, and Windows. The standalone binaries bundle a PHP runtime, so users do not need PHP installed just to run DevDoctor.

Install as a Composer package:

Install locally in a project:

Commands

All public commands support the shared options:

Diagnostic commands also support output shaping without changing the underlying exit code:

Supported diagnostic output formats are table, json, and sarif.

Laravel Zero already defines a global --env option, so DevDoctor exposes the env-file selector as --env-file:

Examples

ports uses platform-specific read-only providers: lsof on macOS/Linux, ss as a Linux fallback, and netstat -ano on Windows. If no supported provider is available, DevDoctor reports DD_PORT_PROVIDER_UNAVAILABLE instead of failing unexpectedly.

Platform Support

DevDoctor targets Linux, macOS, and Windows:

Platform-specific commands are only suggested. DevDoctor never terminates a process automatically.

Diagnostic Details

• Compose interpolation understands required references such as ${VAR} and ${VAR?message}.
• Compose references with defaults such as ${VAR:-default} and ${VAR-default} do not produce missing-variable warnings.
• Git reports DD_GIT_BINARY_MISSING when Git is unavailable instead of treating the path as a non-repository.
• Windows port diagnostics use tasklist when available to resolve a PID to a process name.
• Cache diagnostics inspect known Laravel, Symfony, and Node cache directories, size thresholds, writability, and Laravel cache artifacts without deleting anything.
• HTTP diagnostics validate configured APP_URL, FRONTEND_URL, API_URL, and explicit --url values without making network requests.
• PHP diagnostics compare the active CLI runtime with composer.json, required ext-* packages, memory_limit, loaded php.ini, and Xdebug state in CI.
• Node.js diagnostics inspect package.json, npm/Yarn/pnpm/Bun lockfiles, stale lockfiles, node_modules, engines.node, .nvmrc, .node-version, and risky package scripts.
• Frontend diagnostics inspect Vite, Next.js, Nuxt, Astro, React, Vue, Svelte, Angular, and generic static frontend evidence without running builds.
• Flutter diagnostics inspect pubspec.yaml, pubspec.lock, Dart SDK constraints, local path/Git dependency sources, and Flutter platform markers without running flutter pub get or builds.
• Mobile diagnostics inspect native Android/iOS markers, Gradle wrappers, Android debug flags, CocoaPods locks, and iOS debug entitlements without running Gradle, Xcode, or CocoaPods.
• Monorepo diagnostics inspect Nx, Turbo, Lerna, pnpm workspaces, Rush, Bazel, Pants, workspace lockfiles, and root package scripts without running orchestrators or package managers.
• Utility commands expose project inventory, issue-code explanations, safety policy, and redacted support bundles without modifying project files.
• Python diagnostics inspect pyproject.toml, requirements*.txt, Pipfile, poetry.lock, uv.lock, and Conda files without installing packages.
• Ruby diagnostics inspect Gemfile, Gemfile.lock, .ruby-version, Rails credentials, config/database.yml, and risky gem sources without running Bundler or Rails.
• Go diagnostics inspect go.mod, go.sum, go.work, local replace directives, toolchain declarations, and vendor metadata without running go mod tidy or downloading modules.
• Rust diagnostics inspect Cargo.toml, Cargo.lock, workspaces, rust-toolchain.toml, local path/git dependencies, and release profile settings without running Cargo.
• Java diagnostics inspect Maven, Gradle, Ant, wrappers, Java version declarations, risky build scripts, and Spring production debug flags without running builds or dependency resolution.
• MCP diagnostics inspect .mcp.json, mcp.json, .agents/mcp.json, .claude/mcp.json, .cline/mcp.json, .codex/mcp.json, .continue/mcp.json, .continue/config.json, .cursor/mcp.json, .roo/mcp.json, .vscode/mcp.json, and .windsurf/mcp.json for stdio, sse, and http server definitions, inline secrets, missing env references, insecure remote URLs, unpinned package runners, mutable Docker image tags, optional project policies, and risky shell command patterns without starting servers or making network requests.
• MCP project policy flags let you report remote transports with --disallow-remote, restrict stdio commands with --allow-command=node,npx, or block specific commands with --deny-command=docker.
• IaC diagnostics inspect Terraform, OpenTofu, and Terragrunt files, provider lockfiles, provider version constraints, remote module refs, backend/provider secrets, and secret-like variable defaults without running init, plan, or network access.
• Kubernetes diagnostics inspect manifests, Helm charts, values files, image tags, service exposure, hostPath mounts, and privileged containers without running kubectl, helm, or cluster queries.
• .NET diagnostics inspect .sln, project files, global.json, NuGet.config, packages.lock.json, target frameworks, and restore lock mode without running dotnet restore, build, or test.
• C/C++ diagnostics inspect CMake, Make, Meson, Autotools, vcpkg, Conan, compile command metadata, in-source build artifacts, compiler flags, generator assumptions, and shell portability risks without compiling code.
• Generic web diagnostics inspect static entry files, obvious asset references, public config files, web server config hints, and conflicting local port declarations without running a build.
• Laravel diagnostics inspect .env, APP_KEY, production debug mode, APP_URL, runtime directories, and config cache state.
• Symfony diagnostics inspect .env/.env.local, APP_SECRET, production debug mode, runtime cache/log directories, Symfony Flex recipe drift, and Symfony Composer script risks without running bin/console.
• Database diagnostics inspect DB_CONNECTION, required database keys, valid ports, SQLite file paths, and optional read-only PDO connectivity with --connect.
• Queue diagnostics inspect QUEUE_CONNECTION, common async driver requirements, and production environments that still use the synchronous queue driver.
• Security diagnostics inspect env example secrets, hard-coded secret patterns, risky Composer and package scripts, Docker privileged mode, Docker socket mounts, and .env ignore gaps.
• Health aggregates local project diagnostics across presets, env, cache, http, php, node, laravel, composer, db, queue, git, docker, and security; it adds frontend, flutter, mobile, monorepo, python, ruby, go, rust, java, mcp, iac, kube, dotnet, cpp, web, and symfony automatically when matching presets are detected. Add --include-ports to include common local port checks.
• Composer reports DD_COMPOSER_LOCK_OUTDATED when composer.lock is older than composer.json.
• Process execution uses argument arrays and supports project paths containing spaces.

Project Presets

The presets command detects supported project stacks from files and declared dependencies without running project tools:

v1.24.0 ships devdoctor iac with static diagnostics for Terraform, OpenTofu, and Terragrunt manifests, provider lockfiles, broad provider constraints, unpinned remote modules, and secret-like IaC values.

v1.25.0 ships devdoctor kube with static diagnostics for Kubernetes manifests and Helm charts. It checks Helm dependency locks, literal secrets in values files, mutable image tags, privileged containers, hostPath mounts, and NodePort service exposure without running kubectl or helm.

v1.26.0 ships devdoctor flutter with static diagnostics for Flutter and Dart projects. It checks pubspec lockfiles, Dart SDK constraints, path/Git dependencies, and platform markers without running Flutter commands or builds.

v1.27.0 ships devdoctor mobile with static diagnostics for native Android and iOS projects. It checks Gradle wrapper presence, Android debuggable manifests, CocoaPods lockfiles, and iOS debug entitlements without running platform build tools.

v1.28.0 ships devdoctor monorepo with static diagnostics for workspace tooling. It checks mixed orchestration tools, missing workspace lockfiles, and risky root scripts without running monorepo commands.

v1.29.0 ships utility commands: inventory, explain, policy, and support-bundle. They help inspect detected stacks, understand issue codes, review DevDoctor safety policy, and print redacted support context without writing files.

v1.30.0 ships documentation automation and a richer documentation site. The issue code catalog is generated from schemas/v1/issue-codes.json, includes filtering and copy controls, and the docs include scenario guides for Laravel, frontend, monorepo, and CI baseline rollout.

v1.31.0 adds documentation navigation polish with active navigation, breadcrumbs, copy buttons for command snippets, and additional scenario guides for Python, Kubernetes/Helm, Terraform/IaC, Symfony, and mobile projects.

v1.32.0 adds machine-readable documentation metadata with docs/manifest.json and docs/commands.json so tools can consume page and command references without scraping HTML.

v1.33.0 adds CLI discoverability with devdoctor commands and devdoctor explain --module=..., making command metadata and issue-code hints available without leaving the terminal.

v1.34.0 adds CI policy profiles: local, ci, strict-ci, and security, with documented defaults for warning handling, strict mode, and module selection.

v1.35.0 adds --baseline-report for CI baselines, showing active, suppressed, and resolved fingerprint counts without hiding findings.

v1.36.0 adds a manual Update Homebrew Tap workflow for publishing or repairing the Homebrew formula for an existing release after HOMEBREW_TAP_TOKEN is configured.

v1.37.0 adds update checks for interactive table output and devdoctor self-update, which reports the current version, the latest release, and the safest update command for the detected installation method.

v1.38.0 polishes the composite GitHub Action metadata for GitHub Marketplace publishing, including branding, clearer input descriptions, and updated pinned examples.

v1.38.1 renames the Marketplace Action to DevDoctor CI Diagnostics so GitHub accepts the listing with a unique Action name.

v1.38.2 changes the Marketplace Action branding color to blue.

v1.39.0 adds the repository bump-version helper so release pins can be updated from one command instead of hand-editing every file.

v1.40.0 adds devdoctor version for script-friendly version checks with table and JSON output.

v1.41.0 changes the generated Homebrew formula to install standalone binaries instead of the PHAR, so devdoctor does not depend on the local PHP version.

v1.41.1 fixes the release artifact test on Windows by checking the bump-version PHP shebang instead of POSIX executable permissions.

v1.42.0 adds devdoctor mcp for read-only Model Context Protocol configuration diagnostics across .mcp.json, mcp.json, .cursor/mcp.json, and .vscode/mcp.json.

v1.43.0 expands MCP diagnostics with .agents/.codex config discovery, inline secret checks, env reference checks, insecure remote URL checks, and risky stdio command detection.

v1.44.0 expands MCP client config discovery for Claude, Cline, Continue, Roo, Windsurf, and nested mcp.servers style project files.

v1.45.0 adds MCP supply-chain checks for unpinned package-runner targets and mutable Docker image tags in stdio server definitions.

v1.46.0 adds MCP project policy flags for disallowing remote servers and enforcing stdio command allow/deny lists.

v1.47.0 includes MCP diagnostics in the security CI profile so agent config risks are covered by security-oriented runs.

v1.48.0 expands command documentation with every available CLI option per command and a roomier one-command-per-row layout.

Preset detection is informational and can be included in CI explicitly:

Table Output

Actionable findings may include a hint and a suggested command. Suggested commands are never executed by DevDoctor. Commands that can change system state, such as terminating a process, are marked as destructive in JSON output.

JSON Output

SARIF Output

Use SARIF 2.1.0 for code scanning integrations:

Each result maps the issue code to a SARIF rule id, includes relative file locations when available, and carries a stable devdoctorFingerprint/v1 based on code, module, file, and key. Hints and fix descriptions are included as metadata; suggested commands are never executed.

Health

The health command is a local, broad project overview. It uses the same output formats as other diagnostics and keeps ports opt-in to avoid machine-specific noise:

Unknown health modules return exit code 3.

CI

The CI aggregator runs env, php, node, laravel, composer, git, and docker by default. It adds frontend, flutter, mobile, monorepo, python, ruby, go, rust, java, mcp, iac, kube, dotnet, cpp, web, and symfony automatically when matching presets are detected. ports and security are excluded by default because they can depend on local machine state or intentionally present local files.

CI profiles provide documented defaults:

Unknown modules and unknown profiles return exit code 3. Selected modules are always included in JSON output.

The repository CI workflow runs tests on Linux, macOS, and Windows with PHP 8.5. It also builds and smoke-tests the PHAR and a PHPacker standalone Linux binary.

GitHub Action

The composite GitHub Action downloads a pinned release PHAR, verifies its SHA-256 checksum, and runs CI diagnostics:

The Action metadata is prepared for GitHub Marketplace publishing with branding and explicit input descriptions. Always pin both the Action ref and the version input. The Action does not use latest.

Baselines

Baselines let an existing project acknowledge current warnings and errors while continuing to fail CI for new findings:

Baseline fingerprints use issue code, module, normalized file path, and key. They do not depend on messages or line numbers. Suppressed findings remain visible in table, JSON, and SARIF output, but they do not affect status or exit code. Only warnings and errors are written. Use --baseline-report to show active, suppressed, and resolved fingerprint counts. Use --force to intentionally replace an existing baseline after review.

Configuration

DevDoctor reads devdoctor.yml for env rules:

Use a different config file with:

Generate an initial configuration with the interactive wizard:

The wizard detects supported env files and project presets, previews the YAML, and writes only after confirmation. It never copies environment values into the generated file. Existing files require --force and a second confirmation. In CI or --no-interaction mode, use --dry-run.

Exit Codes

Stable Contracts

• JSON output includes schema_version and follows the stable v1 schema at schemas/v1/devdoctor-output.schema.json.
• schemas/devdoctor-output.schema.json remains an alias for the latest schema.
• Issue identifiers are documented in the human-readable schemas/v1/issue-codes.json.
• Automation should match issue codes rather than human-readable messages.
• Schema v1 will not receive breaking changes during v1.x. Existing issue codes will not be removed or repurposed without deprecation, and new codes may be added.
• The version recorded in composer.json under extra.devdoctor.version matches the Git release tag.

Documentation

Full static documentation lives in changelog, and pinned CI examples for GitHub Actions, GitLab CI, and Bitbucket Pipelines.

Regenerate the human-readable issue code catalog after changing schemas/v1/issue-codes.json:

Safety

DevDoctor is read-only by default:

• It does not rewrite .env, Compose, Composer, Git, or project files.
• It does not run composer install, composer update, Composer scripts, or internet-dependent audits.
• It does not run docker compose up, start, stop, rm, or prune.
• Hints and suggested commands are informational only and are never executed.
• Port diagnostics may suggest kill -TERM <pid>, but never execute it.
• Basic diagnostics do not require telemetry or internet access.

Release Verification

Tagged releases publish devdoctor.phar, PHPacker standalone binaries, SHA-256 checksums, Cosign signatures, and Sigstore certificates.

Standalone release assets:

Verify the PHAR checksum before running a downloaded PHAR:

Verify every executable release asset with the combined checksum file:

Verify the keyless signature with Cosign:

Homebrew

DevDoctor is available from the rtcoder/tap Homebrew tap:

The Homebrew formula installs the platform-specific standalone release binary for macOS or Linux. It does not execute the PHAR through the local php binary, so devdoctor --version works even when the system php points at an older runtime.

The release workflow can update rtcoder/homebrew-tap after each tag when the repository secret HOMEBREW_TAP_TOKEN is configured with write access to the tap.

If the token was added after a release, run the Update Homebrew Tap workflow manually from GitHub Actions and pass the release version, for example 1.48.0 or v1.48.0. The workflow downloads devdoctor.sha256 from the GitHub Release and updates Formula/devdoctor.rb in rtcoder/homebrew-tap.

Development

Update release version pins with:

The helper updates extra.devdoctor.version, Action examples, documentation pins, CI examples, pinned test expectations, and composer.lock. Use --no-lock only when you intentionally want to skip the Composer lock refresh.

Roadmap

See ROADMAP.md for the implementation roadmap and later distribution work.