dipto0321 · dipto0321 · Jul 1, 2026 · Jul 1, 2026
@@ -63,30 +63,62 @@ A few things worth knowing before you run `nodeup`:
 
 ## Installation
 
-### Homebrew (macOS, Linux)
+Pick the channel that matches how you manage other tools. Use the
+matrix below as the entry point — the per-channel sections below it
+spell out exactly what to run.
+
+### Pick by who you are
+
+| If you… | Use | Why |
+|---|---|---|
+| Already use Homebrew for dev tooling on macOS / Linux | **Homebrew** | One command, auto-updates with `brew upgrade`, lives outside any Node install, uninstalls cleanly with `brew uninstall`. |
+| Already use Scoop on Windows | **Scoop** | Same shape as Homebrew on the Windows side — `scoop update nodeup` keeps it current, no admin shell needed. |
+| Already manage dev tools via `npm install -g` and want a one-liner | **npm wrapper** | No new package manager to set up; the install travels with the Node version it's installed against. Slight catch: a `nodeup` upgrade ships when the wrapper version bumps. |
+| Are blocked from system package installs but can `npm i -g` | **npm wrapper** | Sandboxed / corp-locked-down machines often allow npm globals where they block system installers. |
+| Maintain `nodeup` itself, or want a version pinned to a specific tag without any postinstall network step | **Direct binary download** | You choose the exact release; no installer, no auto-update, no Node coupling. Best for reproducible CI installs. |
+| Are a Go developer hacking on `nodeup` and want the latest commit | **`go install`** | Pulls the current source and builds it locally. Fastest iteration loop for contributors. |
+
+### Channels
+
+#### Homebrew (macOS, Linux)
 
 ```bash
 brew install dipto0321/tap/nodeup
 ```
 
-### Scoop (Windows)
+Best for: macOS / Linux users who already use Homebrew for tools. The
+formula is auto-managed by GoReleaser from `brew: {}` in
+`.goreleaser.yaml`, so a `v*.*.*` tag updates the tap.
+
+#### Scoop (Windows)
 
 ```powershell
 scoop bucket add dipto0321 https://github.com/dipto0321/scoop-bucket
 scoop install nodeup
 ```
 
-### npm wrapper (any platform)
+Best for: Windows users who already use Scoop. The manifest is
+auto-managed by GoReleaser from `scoop: {}` in `.goreleaser.yaml`.
+
+#### npm wrapper (any platform with Node ≥ 14)
 
 ```bash
 npm install -g nodeup
 ```
 
-The npm wrapper downloads the right binary for your platform at install time.
+Best for: anyone who treats their global npm install as the source of
+truth for CLI tools — typical in JavaScript / TypeScript projects.
+The wrapper is a thin downloader (`scripts/install.js`) that fetches
+the matching static Go binary from the GitHub release tagged by this
+package's `binaryVersion` field. See
+[`nodeup-npm/README.md`](./nodeup-npm/README.md) for the install
+mechanics, updating behavior, and uninstall behavior.
 
-### Direct binary download
+#### Direct binary download
 
-Grab the archive for your OS/arch from the [Releases page](https://github.com/dipto0321/nodeup/releases):
+Best for: CI pipelines, lock-down environments, and anyone who wants
+zero install ceremony. Grab the archive for your OS/arch from the
+[Releases page](https://github.com/dipto0321/nodeup/releases):
 
 ```bash
 # macOS Apple Silicon
@@ -96,14 +128,21 @@ sudo mv nodeup /usr/local/bin/
 # Linux x86_64
 curl -L https://github.com/dipto0321/nodeup/releases/latest/download/nodeup_*_linux_amd64.tar.gz | tar xz
 sudo mv nodeup /usr/local/bin/
+
+# Windows (PowerShell)
+curl -L https://github.com/dipto0321/nodeup/releases/latest/download/nodeup_$(curl -s https://api.github.com/repos/dipto0321/nodeup/releases/latest | grep tag_name | cut -d'"' -f4 | tr -d v)_windows_amd64.zip -OutFile nodeup.zip
+Expand-Archive nodeup.zip -DestinationPath .
 ```
 
-### From source
+#### From source
 
 ```bash
 go install github.com/dipto0321/nodeup/cmd/nodeup@latest
 ```
 
+Requires Go 1.22+. Best for: `nodeup` contributors and anyone who
+wants to track `main` between releases.
+
 ## Quickstart
 
 ```bash

@@ -13,6 +13,22 @@ automatically on every `v*.*.*` tag (see `.github/workflows/release.yml`).
 | Linux | arm64, amd64 | Most distros; glibc-based |
 | Windows | amd64 | nvm-windows supported |
 
+## Pick a channel
+
+Each channel is a deliberate trade between **convenience**, **how
+strongly you trust the package manager you already use**, and **how
+much you want `nodeup` coupled to anything else on your system**. Use
+the table below to pick — the per-channel sections below it show
+exactly what to run.
+
+| Channel | One-line install | Auto-updates? | Lives in… | Best for… | Avoid if… |
+|---|---|---|---|---|---|
+| **Homebrew** | `brew install dipto0321/tap/nodeup` | Yes — `brew upgrade` | `/opt/homebrew/bin/` (macOS) or `/home/linuxbrew/.linuxbrew/bin/` (Linux) | macOS / Linux devs already using Homebrew for tooling | You don't have Homebrew and don't want to set it up just for one tool |
+| **Scoop** | `scoop install nodeup` (after adding the bucket) | Yes — `scoop update` | `%USERPROFILE%\scoop\apps\nodeup\` | Windows devs already using Scoop | You prefer winget / Chocolatey — neither is wired up today |
+| **npm wrapper** | `npm install -g nodeup` | Semi — `npm update -g nodeup` only when a wrapper version bumps | Inside a Node install, on your global `node_modules/` path | JS devs who already treat `npm i -g` as the source of truth for CLIs; locked-down machines that block system installers but allow npm globals | You want a CLI that lives completely outside any Node install, or you want to track Go-binary releases the moment they tag (the wrapper lags by one publish) |
+| **Direct binary** | `curl … \| tar xz` | No — you re-run to update | Wherever you put the extracted binary | CI pipelines, reproducible installs, lock-down environments without npm or brew | You want auto-updates; you'll forget to re-run |
+| **From source** | `go install ./cmd/nodeup@latest` | No — re-run against a new tag | `$GOBIN` or `$GOPATH/bin` | `nodeup` contributors and Go developers who want HEAD | Anyone who doesn't have Go installed and isn't trying to hack on the tool |
+
 ## Channels
 
 ### Homebrew (macOS, Linux)
@@ -21,35 +37,132 @@ automatically on every `v*.*.*` tag (see `.github/workflows/release.yml`).
 brew install dipto0321/tap/nodeup
 ```
 
+**Who this is for:** developers on macOS or Linux who already use
+Homebrew for dev tooling (`brew` is the package manager for
+command-line apps, distinct from the App Store). The tap
+[`dipto0321/homebrew-tap`](https://github.com/dipto0321/homebrew-tap)
+holds the formula and is auto-pushed by GoReleaser on every
+`v*.*.*` tag.
+
+**Tradeoffs:** upgrades happen via `brew upgrade`, which all Homebrew
+users already run on a schedule. The install lives in Homebrew's
+prefix (typically `/opt/homebrew/bin` on Apple Silicon), completely
+independent of any Node install — safe for `nvm`/`fnm`/`Volta` users
+who don't want a Node coupling.
+
 ### Scoop (Windows)
 
 ```powershell
 scoop bucket add dipto0321 https://github.com/dipto0321/scoop-bucket
 scoop install nodeup
 ```
 
-### npm wrapper
+**Who this is for:** Windows developers already using Scoop as their
+package manager. The bucket
+[`dipto0321/scoop-bucket`](https://github.com/dipto0321/scoop-bucket)
+holds the manifest and is auto-pushed by GoReleaser.
+
+**Tradeoffs:** user-level install (no admin shell), upgrades via
+`scoop update nodeup`. Same Node-decoupled shape as Homebrew.
+
+### npm wrapper (any platform with Node ≥ 14)
 
 ```bash
 npm install -g nodeup
 ```
 
-### Direct binary
+**Who this is for:** developers who already treat `npm install -g` as
+the canonical way to install CLIs. Common in JavaScript-heavy
+projects where the team's onboarding script already runs `npm i -g
+<tool1> <tool2> …`. Also a good fit when system package installs are
+blocked but npm globals are allowed.
+
+**Tradeoffs:**
+
+- **Slight version lag.** The wrapper pins to the Go-binary version
+  in its `binaryVersion` field. A new Go release needs a new wrapper
+  publish — `npm update -g nodeup` only gets you a new Go binary
+  after the wrapper version that pins to it ships. To jump to a
+  brand-new release ahead of that, use a direct-binary install.
+- **Coupled to a Node install.** The wrapper and binary live inside
+  a Node install (the one you ran `npm i -g` against). For `nvm` /
+  `fnm` / `Volta` users this means re-installing the wrapper after
+  every Node bump — exactly what `nodeup` is supposed to remove.
+  For those users, prefer Homebrew / Scoop / direct-binary.
+- **No Node runtime needed at runtime.** The wrapper's
+  `postinstall` script downloads a static Go binary; the `node`
+  runtime is used only during install (for the script itself) and
+  is never invoked by `nodeup` once installed.
+
+See [`nodeup-npm/README.md`](../nodeup-npm/README.md) for the full
+install / update / uninstall flow.
+
+### Direct binary download
+
+Best for CI, locked-down environments, and anyone who wants zero
+install ceremony. Grab the archive for your OS/arch from the
+[Releases page](https://github.com/dipto0321/nodeup/releases):
 
-See the [Releases page](https://github.com/dipto0321/nodeup/releases).
+```bash
+# macOS Apple Silicon
+curl -L https://github.com/dipto0321/nodeup/releases/latest/download/nodeup_$(curl -s https://api.github.com/repos/dipto0321/nodeup/releases/latest | grep tag_name | cut -d'"' -f4 | tr -d v)_darwin_arm64.tar.gz | tar xz
+sudo mv nodeup /usr/local/bin/
+
+# Linux x86_64
+curl -L https://github.com/dipto0321/nodeup/releases/latest/download/nodeup_*_linux_amd64.tar.gz | tar xz
+sudo mv nodeup /usr/local/bin/
+
+# Windows (PowerShell)
+curl -L https://github.com/dipto0321/nodeup/releases/latest/download/nodeup_$(curl -s https://api.github.com/repos/dipto0321/nodeup/releases/latest | grep tag_name | cut -d'"' -f4 | tr -d v)_windows_amd64.zip -OutFile nodeup.zip
+Expand-Archive nodeup.zip -DestinationPath .
+# Move nodeup.exe somewhere on $PATH
+```
 
-### From source
+**Who this is for:** anyone who wants a deterministic install — no
+package manager metadata, no postinstall hook, no auto-update. Pin
+the URL to a specific tag (not `latest`) to make the install
+reproducible across CI runs.
 
-Requires Go 1.22+.
+**Tradeoffs:** you own the upgrade lifecycle. Re-run the command (or
+script it) when you want a new version. The binary is fully
+self-contained — no runtime, no Node, no manager.
+
+### From source
 
 ```bash
 go install github.com/dipto0321/nodeup/cmd/nodeup@latest
 ```
 
+Requires Go 1.22+.
+
+**Who this is for:** `nodeup` contributors and Go developers who want
+to track `main` between tagged releases. The binary lands in
+`$GOBIN` (or `$GOPATH/bin`), which Go is configured to put on
+`$PATH` for you.
+
+**Tradeoffs:** the slowest to upgrade (you recompile), but the
+closest to the bleeding edge. Not appropriate for end users — they
+should pick one of the channels above.
+
 ## Verifying
 
 ```bash
 nodeup version
 ```
 
-Should print a version, git commit, build date, and Go runtime info.
+Should print a version, git commit, build date, and Go runtime info.
+
+## Picking once and sticking
+
+You can install via multiple channels at once if you want — they'll
+write to different paths and the first one on `$PATH` wins. To
+avoid the version-skew that causes, pick one and use it for upgrades
+and uninstalls consistently:
+
+- **Homebrew** owns upgrades → use `brew upgrade nodeup`.
+- **Scoop** owns upgrades → use `scoop update nodeup`.
+- **npm** owns upgrades → use `npm update -g nodeup`.
+- **Direct binary** owns upgrades → re-run the curl one-liner (or
+  pin a specific tag in CI).
+- **From source** owns upgrades → `go install -u
+  github.com/dipto0321/nodeup/cmd/nodeup@latest`.
@@ -0,0 +1,42 @@
+# Node-up wrapper published artefacts — what `npm publish` ships:
+#   scripts/install.js   — postinstall downloader
+#   scripts/check.js     — preinstall platform check
+#   README.md            — install / usage notes
+#   LICENSE              — MIT
+#
+# Everything else in nodeup-npm/ is local dev scaffolding and is excluded
+# from the published tarball.
+
+# Local artefacts — populated at install time by scripts/install.js
+# (the postinstall downloads the right binary from the GitHub release
+# into ./bin/). Anything already in bin/ before publish would be wrong
+# for every user except the one who built it.
+/bin/
+
+# Wrapper dev / CI scratch
+/.github/
+/scripts/__tests__/
+*.test.js
+.coverage
+.nyc_output
+
+# Editor / OS noise
+.DS_Store
+Thumbs.db
+*.swp
+*.swo
+.idea/
+.vscode/
+
+# Node / npm noise (we're shipped, not installed)
+node_modules/
+package-lock.json
+yarn.lock
+.npm/
+.npmrc
+*.log
+
+# VCS
+.git/
+.gitignore
+.gitattributes
@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 dipto0321
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.