hdi

"How do I" surfaces install, run, test and deploy steps and commands all in your terminal.

hdi parses a given README's Markdown headings looking for keywords like install, setup, prerequisites, run, usage, getting started, etc. It extracts the fenced code blocks from matching sections and presents them as an interactive, executable list.

$ cd some-project
$ hdi
[hdi] some-project

 ▸ Installation
  ▶ npm install
    cp .env.example .env

 ▸ Run
    npm run dev

  ↑↓ navigate  ⇥ sections  ⏎ execute  c copy  q quit

Works on macOS and Linux (probably WSL2 also).

See the website for an interactive demo, and the blog post for more background information and context.

Example

Install

Homebrew

brew install grega/tap/hdi

Update

brew update
brew upgrade hdi

Manual

mkdir -p ~/.local/bin
curl -fsSL https://raw.githubusercontent.com/grega/hdi/main/hdi -o ~/.local/bin/hdi
chmod +x ~/.local/bin/hdi

Make sure ~/.local/bin is on your $PATH.

Usage

hdi                    Interactive picker - shows all sections (default)
hdi install            Just install/setup commands (aliases: setup, i)
hdi run                Just run/start commands (aliases: start, r)
hdi test               Just test commands (alias: t)
hdi deploy             Just deploy/release commands and platform detection (alias: d)
hdi all                All sections (aliases: a)
hdi contrib            Commands from contributor/development docs (alias: c)
hdi needs              Check if required tools are installed (alias: n)
hdi /path/to/project   Scan a different directory
hdi /path/to/file.md   Parse a specific markdown file

Running hdi with no subcommand currently shows all matched sections (equivalent to hdi all). The subcommands exist to filter down to a specific category. In future, if the default output becomes too noisy, hdi may return a curated subset while hdi all continues to show everything.

Short-forms:

hdi i      Install/setup commands
hdi r      Run/start commands
hdi t      Test commands
hdi d      Deploy/release commands
hdi a      All sections
hdi c      Contributor/development docs
hdi n      Check required tools

Flags

-h, --help                   Show help
-v, --version                Show version
-f, --full                   Show surrounding prose, not just commands
    --raw                    Plain markdown output (no colour, for piping)
    --json                   Structured JSON output (includes all sections)
    --ni, --no-interactive   Non-interactive (just print, no picker)

Example: hdi --raw | pbcopy to copy commands to clipboard.

Interactive controls

Key	Action
↑ ↓ / k j	Navigate commands
Tab / Shift+Tab	Jump between sections
Enter	Execute highlighted command
c	Copy highlighted command to clipboard
q / Esc	Quit

Deployment platform detection

Note: this is an experimental feature and may not always be accurate.

The deploy (or d) subcommand makes a best effort to extract what platform(s) a project uses for deployment (eg. Cloudflare, Heroku, Vercel, Netlify, AWS, etc), and displays this in the output:

$ hdi d
[hdi] example-project  [deploy → Cloudflare Pages]
...

Or if the certainty is low:

$ hdi d
[hdi] example-project  [deploy → Netlify?]
...

Development

See DEVELOPMENT.md for instructions on setting up a local development environment, running tests, benchmarking, and generating demo GIFs.

AI transparency

AI tooling (eg. Claude Code) has been used to assist with areas of the project, such as:

• Researching common README formats across a large array of project types, and creating fixtures from these findings
• Prototyping the parsing logic
• Creating the website's data generation pipeline, along with elements of the demo page's terminal simulator
• Converting the use of sed, awk etc into Bash natives (ie. the v0.10.0 performance release)

License

MIT