docs: install from the repo, since defib was never published to PyPI

[openipc-ai]

The problem

Two places tell users to install from PyPI:

• README.md — uv tool install defib / pipx install defib
• web/index.html:621 — the fallback shown when the browser build refuses a frame-blast SoC

$ curl -s -o /dev/null -w '%{http_code}\n' https://pypi.org/pypi/defib/json
404

There is no defib package on PyPI, so both commands fail.

Why it matters

OpenIPC/firmware#2299 is a user recovering a bricked hi3518ev200 over UART. hi3518ev200 is a
frame-blast chip, so the web UI showed them precisely the broken line. They got there in the end,
but when #126 landed and they were asked to reinstall and retry, the new copy went somewhere other
than the defib on their PATH — an active virtualenv shadowed ~/.local/bin — and they reported
two more rounds of results from the old build against a bug that was already fixed.

The change

uv tool install git+https://github.com/OpenIPC/defib
# or
pipx install git+https://github.com/OpenIPC/defib

plus a uvx one-liner in both places, which needs no install and cannot be shadowed by an active
virtualenv:

uvx --from git+https://github.com/OpenIPC/defib defib burn -c <chip> -p /dev/ttyUSB0 -t

Not in scope

Publishing to PyPI would also fix this and is probably worth doing — it needs a maintainer with the
account, so the docs fix goes first.

Test plan

• uv tool install git+https://github.com/OpenIPC/defib — installs, defib list-chips prints 123 chips

• uvx --from git+https://github.com/OpenIPC/defib defib list-chips — works with nothing installed

• node --check over all three <script> blocks in web/index.html — parses

• Evaluated the edited template literal; renders as

  ```
  uvx --from git+https://github.com/OpenIPC/defib \
    defib burn -c hi3518ev200 -p /dev/ttyUSB0 -t
  ```
  

[qodo-free-for-open-source-projects]

PR Summary by Qodo

Fix CLI installation and recovery commands to use GitHub

🐞 Bug fix 📝 Documentation 🕐 Less than 10 minutes

AI Description

• Replaces nonexistent PyPI installs with repository-based uv and pipx commands.
• Adds a no-install uvx recovery command to README and browser guidance.

Diagram

graph TD
  U["Recovery User"] --> R["README Guide"] --> I["Git Install"] --> G["GitHub Repository"] --> C["defib CLI"]
  U --> W["Web Fallback"] --> X["uvx Command"] --> G

Loading

High-Level Assessment

The following are alternative approaches to this PR:

1. Publish defib to PyPI

• ➕ Restores conventional short installation commands
• ➕ Supports versioned releases through standard Python tooling
• ➖ Requires maintainer account access and release ownership
• ➖ Does not immediately fix guidance for affected recovery users

2. Pin Git installs to a release tag

• ➕ Makes installations reproducible
• ➕ Avoids unexpected changes from the default branch
• ➖ Requires documentation updates for every release
• ➖ May keep troubleshooting users on already-fixed versions

Recommendation: Merge the GitHub and uvx guidance as the best immediate fix: it works without PyPI access and uvx avoids stale PATH-resolved copies. Publishing versioned releases to PyPI remains the preferable long-term distribution model.

Files changed (2) +11 / -3

Bug fix (1) +1 / -1

index.htmlUse uvx in the frame-blast CLI fallback +1/-1

Use uvx in the frame-blast CLI fallback

• Changes unsupported frame-blast chip guidance to run the current GitHub version through uvx. This avoids both the nonexistent PyPI package and stale executables shadowed on PATH.

web/index.html

Documentation (1) +10 / -2

README.mdDocument Git-based installation and one-shot execution +10/-2

Document Git-based installation and one-shot execution

• Replaces failing PyPI package commands with uv and pipx installs from the GitHub repository. Adds a uvx recovery example for running defib without installation.

README.md

[qodo-free-for-open-source-projects]

Code Review by Qodo

🐞 Bugs (0) 📘 Rule violations (0) 📎 Requirement gaps (0) 🎨 UX issues (0) 🔗 Cross-repo conflicts (0) 📜 Skill insights (0)

1. Placeholder breaks shell command ✓ Resolved 🐞 Bug ≡ Correctness

Description

The new copyable shell command passes the chip as unquoted ``, which POSIX shells parse as
redirection syntax and reject instead of supplying the required -c value. As written, the
advertised one-shot invocation cannot run until the user recognizes and replaces the placeholder.

Code

README.md[27]

+uvx --from git+https://github.com/OpenIPC/defib defib burn -c <chip> -p /dev/ttyUSB0 -t

Evidence

The added README line places ` directly in a Bash command, while the CLI declares -c/--chip` as
requiring a value. The browser version avoids the issue by interpolating the selected chip before
displaying the command.

README.md[24-27]
src/defib/cli/app.py[17-19]
web/index.html[614-621]

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

## Issue description
The one-shot command uses `<chip>` inside a Bash code block. POSIX shells interpret angle brackets as redirection operators, so copying the command as displayed produces a shell syntax error rather than passing a chip name to `defib`.
## Issue Context
The `burn` command requires a value for `-c/--chip`. Use a concrete supported chip in the executable example and explain separately that users should replace it with their target chip.
## Fix Focus Areas
- README.md[24-27]

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

---

Tip of the day

💡 Did you know, you can switch off images and animations for a plain-text comment

More tips ↗ | Customize Qodo ↗ | Qodo docs ↗