Prerequisites¶

What each script needs before it will run, how to install it, and the edge cases that bite when setting up a dev environment.

Per-script requirements¶

Every bash script needs bash (3.2+, the macOS default is fine); every Python script needs python3. Beyond that:

Script	Mandatory	Notes
`gh-merge-pr.sh`	`gh` (auth), `git`, `jq`	`jq` parses the API JSON.
`gh-create-repo.sh`	`gh` (auth), `git`	—
`gh-rename-repo.sh`	`gh` (auth), `git`	`git` rewrites `origin`.
`gh-enable-pages.sh`	`gh` (auth)	Token needs the `repo` scope; you must own the repo.
`gh-pr-open.sh`	`gh` (auth), `git`	—
`gh-pr-status.py`	`python3`, `gh` (auth)	—
`gh-release.py`	`python3`, `gh` (auth), `git`	—
`gh-rename-org.sh`	`gh` (auth), `git`, `perl`	You must be an org owner; `read:org` scope. The rename itself is a click in org settings.
`gh-issues-sync.py`	`python3`, `gh` (auth)	Token needs `repo` scope to create issues and labels.
`gh-org-ci.sh`	`gh` (auth)	—
`gh-org-clone.sh`	`git`; `gh` (auth) unless `--repos` is given	—
`git-split-repo.sh`	`git`, `git-filter-repo`; `gh` (auth) for `--publish`	`pip install git-filter-repo` or `brew install git-filter-repo`.
`git-replace.sh`	`git`, `perl`	`perl` ships with macOS and most Linux distributions.
`git-conflict-helper.sh`	`git`	—
`git-safe-checkout.sh`	`git`	—
`git-clean-branches.sh`	`git`	—
`git-sync.sh`	`git`	—
`dev-doctor.sh`	`bash`	Checks for everything else and reports.
`proj-bootstrap.sh`	`bash`	`git` optional (skips init with `--no-git`).
`precommit-install.sh`	`git`, `pre-commit`	Offers to pip-install `pre-commit`.
`py-venv-rebuild.sh`	`python3`	`pyenv` optional (resolves a version like `3.12.4`).
`py-check.sh`	`bash`	Runs whichever of `ruff`/`mypy`/`pytest` exist.
`deps-outdated.py`	`python3`	Plus the toolchains to query: `pip`/`npm`/`go`/`cargo-outdated`.
`deps-unused.py`	`python3`	Pure Python (heuristic).
`lockfile-drift.py`	`python3`	Pure Python.
`vuln-scan.py`	`python3`	Plus audit tools: `pip-audit`/`npm`/`cargo-audit`/`govulncheck`.
`lic-audit.py`	`python3`	Reads installed metadata + `node_modules`.
`version-bump.py`	`python3`	Pure Python.
`env-check.py`	`python3`	Pure Python.
`data-convert.py`	`python3`	`PyYAML` only if you use YAML.
`secret-scan.py`	`python3`	`git` only for the default (staged-files) mode.
`clean-artifacts.sh`	`bash`, `find`	—
`snapshot.sh`	`bash`, `tar`	—
`port-kill.sh`	`lsof`	Present on macOS by default; install on minimal Linux.

The polyglot tools (deps-*, vuln-scan, lic-audit) skip any ecosystem whose toolchain isn't installed rather than failing. Scripts that need a tool outright fail fast with a clear message (Required command not found: …).

Install the prerequisites¶

=== "macOS (Homebrew)"

```bash
brew install gh git jq git-filter-repo   # lsof, perl and python3 ship with macOS
# newer bash only if you write bash 4+ features (scripts here don't need it):
brew install bash
```

=== "Debian / Ubuntu"

```bash
sudo apt-get update
sudo apt-get install -y git jq lsof python3 python3-venv git-filter-repo
# GitHub CLI:
sudo apt-get install -y gh   # or follow https://cli.github.com for the latest
```

Set up the GitHub CLI¶

The gh-* scripts assume gh is installed and authenticated:

gh auth login            # interactive: pick GitHub.com, HTTPS or SSH, a browser login
gh auth status           # verify — every gh-* script runs this check internally

For gh-enable-pages.sh the token must carry the repo scope. If you hit a 404/permission error enabling Pages, refresh the scopes:

gh auth refresh -h github.com -s repo

Edge cases when setting up a dev environment¶

These are the ones that actually cost time:

macOS ships bash 3.2

/bin/bash on macOS is from 2007 and lacks mapfile, associative arrays, and ${var,,}. These scripts are written to run on it. If you add bash 4+ features, brew install bash and use #!/usr/bin/env bash (Homebrew bash lands on PATH ahead of /bin/bash).

A virtualenv can outlive its interpreter

If you built .venv with a pyenv/conda Python that was later removed or moved, .venv/bin/python becomes a dangling symlink and every command fails cryptically. Fix: py-venv-rebuild.sh --python 3.12.4.

gh not authenticated, wrong account, or missing scopes

gh auth status tells you who you are and which scopes you hold. Enabling Pages needs repo; a fresh gh auth login via browser usually grants it, older tokens may not — gh auth refresh -s repo.

git identity unset breaks commits (especially in CI)

Without user.name/user.email, git commit aborts. Set them once:

git config --global user.name  "Your Name"
git config --global user.email "you@example.com"

cli/ not on PATH, or scripts not executable

Either add cli/ to PATH (see Home) or run a script explicitly: bash scripts/system-administration/maintenance/port-kill/port-kill.sh 8080. After git clone, chmod +x scripts/**/*.sh if the execute bit didn't survive.

Killing a port hits the wrong process

lsof -i:PORT matches both listeners and clients connected to that port. port-kill.sh targets listeners only by default for exactly this reason. Use --all only when you mean it.

GitHub Pages must be enabled before a deploy can publish

The build job succeeds but deploy 404s until Pages is on. Enable it with gh-enable-pages.sh or in repo Settings → Pages → Source = GitHub Actions. Also: actions/setup-python with cache: pip needs a requirements file to key on — set cache-dependency-path if yours isn't named requirements.txt.

Line endings (CRLF vs LF) cause phantom conflicts

Whole-file diffs with no visible change usually mean line-ending drift. Check with git diff --check and review git config core.autocrlf.

Non-interactive shells refuse confirmation prompts

In CI or piped contexts there's no TTY, so confirm declines by default to avoid acting blindly. Pass -y or set ASSUME_YES=1 to proceed.