close
Skip to content

Install

portcheck is a single static binary with no runtime dependencies.

One command

Installs portcheck and connects it to your browsers for the browser extension:

curl -fsSL https://roystondwork-dev.github.io/portcheck/install.sh | sh

With Homebrew, it installs the Homebrew package. Otherwise it downloads the latest release, checks it against the release's checksums, and installs it to ~/.local/bin (PORTCHECK_INSTALL_DIR=/somewhere to choose). Read the script.

irm https://roystondwork-dev.github.io/portcheck/install.ps1 | iex

It downloads the latest release, checks it against the release's checksums, installs it to %LOCALAPPDATA%\Programs\portcheck and adds that folder to your user PATH. No administrator rights are needed. Read the script.

Both finish with portcheck browser install; set PORTCHECK_NO_BROWSER=1 to skip it, or PORTCHECK_VERSION=0.9.0 for a specific version.

Package managers

brew install roystondwork-dev/tap/portcheck

npx portcheck-cli 3000       # run without installing
npm install -g portcheck-cli # or install the portcheck command

On first run, the portcheck-cli package downloads portcheck for your platform from the GitHub release, checks it against the checksums published with the package, and caches it (PORTCHECK_CACHE to choose where). Node.js 18 or later.

pipx install portcheck-tool  # or: uv tool install portcheck-tool / pip install portcheck-tool

The portcheck-tool wheels carry the native binary for each platform and put portcheck on your PATH; there's no Python code and nothing is downloaded at runtime.

winget install roystondwork-dev.portcheck

Open a new terminal afterwards so portcheck is on your PATH.

Note

The package is waiting for review in microsoft/winget-pkgs. Until it's merged, use Scoop or the zip from the releases page.

scoop bucket add portcheck https://github.com/roystondwork-dev/scoop-bucket
scoop install portcheck

Download the .deb, .rpm or .apk for your architecture from the latest release, then:

sudo apt install ./portcheck_*_amd64.deb            # Debian, Ubuntu (arm64: *_arm64.deb)
sudo dnf install ./portcheck-*.x86_64.rpm           # Fedora, RHEL (arm64: *.aarch64.rpm)
sudo apk add --allow-untrusted ./portcheck_*_x86_64.apk  # Alpine (arm64: *_aarch64.apk)

Download the archive for your OS and CPU from the latest release, extract it, and put portcheck (portcheck.exe on Windows) on your PATH.

Requires Go 1.26 or newer:

go install github.com/roystondwork-dev/portcheck/cmd/portcheck@latest

Check the installation:

portcheck version
man portcheck      # man pages ship with Homebrew and the Linux packages

Shell completion

portcheck completion bash > /etc/bash_completion.d/portcheck          # bash
portcheck completion zsh  > "${fpath[1]}/_portcheck"                  # zsh
portcheck completion fish > ~/.config/fish/completions/portcheck.fish # fish
portcheck completion powershell | Out-String | Invoke-Expression      # PowerShell (current session)

Homebrew installs completions for you.

Verifying downloads

Every release publishes checksums.txt, signed with Sigstore cosign using GitHub's OIDC identity (no long-lived keys). It also publishes SPDX SBOMs and SLSA build provenance.

  1. Verify that the checksum file was produced by this repository's release workflow:

    cosign verify-blob \
  --bundle checksums.txt.sigstore.json \
  --certificate-identity 'https://github.com/roystondwork-dev/portcheck/.github/workflows/release.yml@refs/heads/main' \
  --certificate-oidc-issuer https://token.actions.githubusercontent.com \
  checksums.txt

  2. Verify your download against it:

    sha256sum --ignore-missing -c checksums.txt     # Linux
shasum -a 256 --ignore-missing -c checksums.txt # macOS

  3. Optionally, verify the build provenance with the GitHub CLI:

    gh attestation verify portcheck_*_linux_amd64.tar.gz --repo roystondwork-dev/portcheck

Running with elevated privileges

Some information is only visible to root or Administrator; see Permissions by OS. sudo often resets PATH, so pass the full path:

sudo "$(command -v portcheck)" list -l

Uninstall

Run portcheck browser uninstall first if you connected browsers. Then remove the binary (the one-command installer put it in ~/.local/bin or %LOCALAPPDATA%\Programs\portcheck), or use your package manager (brew uninstall portcheck, scoop uninstall portcheck, apt remove portcheck, …). portcheck writes no other configuration or cache files.