pi-doctor is a read-only CLI for checking common Raspberry Pi problems:
identity mismatches, thermal throttling, config.txt drift, GPIO conflicts,
camera detection failures, and Python environment pitfalls.
It is designed for both interactive troubleshooting and automation. Human
output explains what changed and what to run next; JSON output gives scripts
stable schemas. The current stable package release is 1.0.0.
version=1.0.0
target=x86_64-unknown-linux-gnu
curl -fsSLO "https://github.com/Halfblood-Prince/pi-doctor/releases/download/v${version}/pi-doctor-v${version}-${target}.tar.gz"
curl -fsSLO "https://github.com/Halfblood-Prince/pi-doctor/releases/download/v${version}/pi-doctor-v${version}-${target}.tar.gz.sha256"
sha256sum -c "pi-doctor-v${version}-${target}.tar.gz.sha256"
tar -tzf "pi-doctor-v${version}-${target}.tar.gz"
tar -xzf "pi-doctor-v${version}-${target}.tar.gz"
mkdir -p ~/.local/bin
install -m 0755 "pi-doctor-v${version}-${target}/pi-doctor" ~/.local/bin/pi-doctorVerify release provenance when GitHub CLI is available:
gh attestation verify "pi-doctor-v${version}-${target}.tar.gz" \
--repo Halfblood-Prince/pi-doctorReleases also publish SHA256SUMS, SHA256SUMS.sha256, and provenance
attestations for the checksum files.
curl -fsSLO https://github.com/Halfblood-Prince/pi-doctor/releases/latest/download/install.sh
curl -fsSLO https://github.com/Halfblood-Prince/pi-doctor/releases/latest/download/install.sh.sha256
sha256sum -c install.sh.sha256
gh attestation verify install.sh --repo Halfblood-Prince/pi-doctor
bash install.sh --version 1.0.0 --bin-dir ~/.local/binThe manual archive route above has the smallest installer trust base: download the archive, checksum, and attestation yourself before extracting the binary.
Use an explicit target such as aarch64-unknown-linux-gnu for Raspberry Pi OS
64-bit, armv7-unknown-linux-gnueabihf for 32-bit ARM, or the matching musl
target when you want the static build.
Rollback and uninstall are handled by the installer:
bash install.sh --rollback --bin-dir ~/.local/bin
bash install.sh --uninstall --bin-dir ~/.local/binDebian packaging lives in debian/ and is prepared for mentors
review. Until the package is accepted into Debian, build it locally:
sudo apt install devscripts equivs build-essential lintian autopkgtest
sudo mk-build-deps --install --remove --tool "apt-get -y" debian/control
dpkg-buildpackage -us -uc -b
sudo apt install ../pi-doctor_1.0.0_*.debOnce accepted into Debian, installation will be the normal apt path:
sudo apt install pi-doctorA Homebrew formula is provided at
packaging/homebrew/pi-doctor.rb and should
be published only after the matching signed release artifacts exist.
pi-doctor check
pi-doctor --json check
pi-doctor --timeout 5 check
pi-doctor explain throttling
pi-doctor explain config
pi-doctor explain python
pi-doctor doctor camera
pi-doctor doctor gpio
pi-doctor support-bundle --dry-run
pi-doctor support-bundle --output ./bundlesSupport bundles are sanitized by default and include manifest.txt with
SHA-256 hashes for payload files. Sensitive bundles require an explicit
acknowledgement:
pi-doctor support-bundle --include-sensitive --acknowledge-sensitive-datapi-doctor check exits with:
| Code | Meaning |
|---|---|
| 0 | healthy |
| 1 | warning |
| 2 | degraded |
| 3 | critical |
| 4 | unexpected runtime failure |
Automation should prefer:
pi-doctor --json checkJSON includes probe_health so scripts can tell a healthy subsystem from an
incomplete inspection.
Operational logs are written to stderr. For CI or field debugging, use privacy-preserving JSON-lines logs:
PI_DOCTOR_LOG=debug PI_DOCTOR_LOG_FORMAT=json pi-doctor --json check > report.json 2> pi-doctor.log.jsonlThe JSON contract is documented in docs/cli-contract.md,
docs/json-schema.md, and the schema files in
schema/.
- Security policy:
SECURITY.md - Contributing guide:
CONTRIBUTING.md - Maintainer policy:
MAINTAINERS.md - Release process:
docs/release-process.md - Known limitations:
docs/known-limitations.md
pi-doctor is licensed under the Apache License 2.0.