hpds-cli

hpds is the command-line tool for the Stanford Health Policy Data Science lab. It is a single binary for macOS, Linux, and Windows that does three jobs:

1. Scaffold projects from lab templates (hpds init, hpds use ...).
2. Set up machines with the lab toolchain (hpds install ..., hpds setup).
3. Audit repos against lab standards, locally and across the GitHub org (hpds audit, hpds audit all).

Formatting and linting are provided by the lab's separate togi tool.

Everything works with zero configuration; hpds.toml only overrides defaults. The defaults encode several of the lab's agreements.

Install

The install script downloads a prebuilt binary for your platform and places it on your PATH:

curl --proto '=https' --tlsv1.2 -LsSf https://github.com/StanfordHPDS/hpds-cli/releases/latest/download/hpds-installer.sh | sh

On Windows, use the PowerShell installer:

powershell -ExecutionPolicy Bypass -c "irm https://github.com/StanfordHPDS/hpds-cli/releases/latest/download/hpds-installer.ps1 | iex"

With Homebrew:

brew install StanfordHPDS/tap/hpds

From source with Cargo (needs a stable Rust toolchain):

cargo install --git https://github.com/StanfordHPDS/hpds-cli hpds

Confirm the install:

$ hpds version
hpds 0.1.0   # no-verify

Quickstart

Scaffold a project

hpds init walks you through a new or existing project interactively. For scripts and CI, drive it non-interactively with flags:

$ hpds init
$ hpds init --yes --language both --use pipeline,readme

Add individual components to a project that already exists. hpds use with no argument lists what's available:

$ hpds use
$ hpds use hpds.toml
$ hpds use readme
$ hpds use pipeline --kind targets

Formatting and linting the code you write there is togi's job (togi format, togi lint); install it with hpds install togi.

Set up a machine

Install a single tool:

$ hpds install quarto
✓ quarto 1.8.27 already installed

hpds setup runs the whole toolchain bundle. Preview the plan before it runs:

$ hpds setup --plan
$ hpds setup --profile dev

The server profile provisions a full lab server (Linux only); dev (the default) installs the toolchain on your own machine.

Audit a repo

Audit the current repo against lab standards, or emit JSON for the bot:

$ hpds audit
errors:
  ✗ [lifecycle-metadata] the repo has no hpds.toml
    fix: run `hpds use hpds.toml`
  ✗ [readme] the repo has no README
    fix: add one, for example with `hpds use readme`

$ hpds audit --format json

Sweep every repo in the org into one report:

$ hpds audit all --limit 50

Git & GitHub helpers

Apply the lab's global git ignore patterns, configure sensible git defaults, and create a repo the lab-manual way:

$ hpds git vaccinate
✓ added 21 ignore pattern(s) to ~/.gitignore

$ hpds git setup
$ hpds repo create

Documentation

• docs/audit-bot.md: how the audit bot files issues and comments on pull requests.

Development

Requires a stable Rust toolchain (Rust 2024 edition; rust-toolchain.toml pins the channel and components). See CONTRIBUTING.md for the developer workflow. CI requires these gates on Linux, macOS, and Windows (the typos check runs on Linux only):

cargo fmt --check
cargo clippy --all-targets --all-features --locked -- -D warnings
cargo test --locked
RUSTDOCFLAGS="-D warnings" cargo doc --no-deps --locked
typos

CI also runs cargo test --features online-tests in a separate job that is allowed to fail; those tests exercise the network and real tool downloads and are not required.

License

MIT. See LICENSE.