webhubworks / package-updater
Bulk-update Composer packages (and Craft / Craft plugins) across all your local repos.
Package info
github.com/webhubworks/package-updater
Type:project
pkg:composer/webhubworks/package-updater
Requires
- php: ^8.2
- laravel-zero/framework: ^12.0.2
Requires (Dev)
- laravel/pint: ^1.25.1
- mockery/mockery: ^1.6.12
- pestphp/pest: ^3.8.4|^4.1.2
Suggests
None
Provides
None
Conflicts
None
Replaces
None
- dev-main
- 1.0.61
- 1.0.60
- 1.0.59
- 1.0.58
- 1.0.57
- 1.0.56
- 1.0.55
- 1.0.54
- 1.0.53
- 1.0.52
- 1.0.51
- 1.0.50
- 1.0.49
- 1.0.48
- 1.0.47
- 1.0.46
- 1.0.45
- 1.0.44
- 1.0.43
- 1.0.42
- 1.0.41
- 1.0.40
- 1.0.39
- 1.0.38
- 1.0.37
- 1.0.36
- 1.0.35
- 1.0.34
- 1.0.33
- 1.0.32
- 1.0.31
- 1.0.30
- 1.0.29
- 1.0.28
- 1.0.27
- 1.0.26
- 1.0.25
- 1.0.24
- 1.0.23
- 1.0.22
- 1.0.21
- 1.0.20
- 1.0.19
- 1.0.18
- 1.0.17
- 1.0.16
- 1.0.15
- 1.0.14
- 1.0.13
- 1.0.12
- 1.0.11
- 1.0.10
- 1.0.9
- 1.0.8
- 1.0.7
- 1.0.6
- 1.0.5
- 1.0.4
- 1.0.3
- 1.0.2
- 1.0.1
- 1.0.0
This package is auto-updated.
Last update: 2026-11-20 18:31:43 UTC
README
A Laravel Zero CLI for bulk-updating Composer packages — and Craft itself /
Craft plugins — across every repo on your machine. Fetches from origin,
then runs git pull on the appropriate long-lived branch (develop →
dev → staging → stag → stage → main → master → prod →
live), picking it up even when it only exists on the remote so far.
After the pull come the package update, optional composer prep, and
optional site-crawler. Skips dirty repos, captures full per-repo
transcripts, summarises everything, and offers to open repos with
uncommitted changes in GitKraken for review.
1. Installation
Global (recommended)
composer global require webhubworks/package-updater
Make sure Composer's global bin directory is on your PATH — typically
~/.composer/vendor/bin (macOS/Linux) or %APPDATA%\Composer\vendor\bin
(Windows). After that, both package-updater and the shorter alias pu
are available from anywhere.
Set REPOS_DIR in your shell (or via .env next to the tool) so it
points at the directory you want scanned (defaults to $HOME/reps). The
walker descends through grouping folders (e.g. ~/reps/my7steps/<repo>),
considers a directory a candidate only when it contains a
composer.lock, and filters out anything that's not a git repo or that
itself declares "type": "craft-plugin".
To upgrade later:
composer global update webhubworks/package-updater
Local clone (for development)
cd ~/reps git clone <repo-url> package-updater cd package-updater composer install ./package-updater list
2. Commands
Run pu <name> (or the longer package-updater <name>). Bare pu
prints the command list. Every command is fully interactive — it will
prompt for any answer it needs.
update
Single-repo helper. Run it from inside a repo: it verifies the working
tree is clean, runs composer update (auto-detecting ddev when
.ddev/config.yaml exists), parses Upgrading / Downgrading / Installing
/ Removing lines from composer's output, and commits the result with
title Package updates and a body listing each change. Optional package
arguments (pu update vendor/foo vendor/bar) restrict the update to
those packages. Use --no-ddev to force host composer, --commit /
--no-commit to skip the commit prompt.
--key=<panoptikum key> runs the update in the repo under the repos
directory whose Panoptikum key (composer name, else origin owner/repo)
matches, so it works from any directory. Panoptikum's cell page shows
copyable commands such as pu update --key=acme/shop guzzlehttp/guzzle.
The update runs on the branch the repo has checked out.
update:all
Universal bulk update — one composer package across every local repo
that depends on it. Pick a vendor/name, pick a target version, pick
which of the matching repos to run on, pick parallelism, confirm. Each
repo runs git fetch --prune → git pull → ddev start →
ddev composer update → composer prep (if defined) → ddev stop
(optional). After checking out the lowest long-lived branch, the run
checks the higher branches (e.g. main/master a teammate committed to
directly) for work it doesn't have. A main that's ahead only by a
merge of this branch into it carries nothing, so the routine merge-down
of develop into main is ignored. Work that this branch really is
missing is merged down for you when git can fast-forward to it, which is
the case whenever the branch has no commits of its own yet. Only a real
divergence, both branches carrying work the other doesn't have, aborts
the repo, because updating a stale branch would base the commit on the
wrong tree; that one is left for you to merge down first. Repos
already at the target version are pre-skipped; with a bare target
version, repos on a different major are pre-skipped too (prefix the
version with ! to force across majors).
--filter-name=<substring> narrows the match set to repos whose
composer.json name contains the given substring — e.g.
pu update:all vendor/foo --filter-name=mvb only considers repos with
mvb in their composer name.
The package argument also accepts a wildcard — e.g.
pu update:all 'laravel-lang/*' matches every locked package under
that vendor prefix and runs composer update laravel-lang/* -W per
repo. Wildcards skip the target-version and transitive-parent prompts
and always pass -W (composer almost always needs it to bump siblings
together). Quote the pattern in your shell so it isn't glob-expanded.
remove
Bulk counterpart for removing a package. Same scan as update:all,
including wildcard support (pu remove 'laravel-lang/*'). Pre-skips
repos where the package is only a transitive dependency (composer
remove only works on declared deps) and pre-skips dirty repos.
For each remaining repo it detects whether the package is in require
or require-dev and groups the removals so composer is called with
--dev for the dev-only ones (plain for the rest). On success it
commits the change with title Remove <package> (or
Remove N packages for wildcards) and a body listing the removed
names.
pu remove vendor/foo # exact name pu remove 'laravel-lang/*' --dry-run # preview which packages would be removed
update:craft
Craft-aware variant. Same flow, but:
- Identifies repos by Craft plugin handle (or the literal
craftto match every site withcraftcms/cmsincomposer.json). - After
ddev start, always syncs the working copy before the update:ddev composer install→ddev php craft migrate/all→ddev php craft project-config/apply. - Runs
ddev php craft update <handle>(with sensible defaults you can edit at the prompt) instead ofcomposer update. - After
composer prep, optionally runssite-crawler crawl:ddevin a second multiselect-chosen subset of repos. Parses the crawler's "Failed requests" table and warns on any 5xx URLs even if the crawler itself exited cleanly. - Skips both verification steps —
composer prepand the crawl — for any repo the run left untouched. They're there to catch breakage the run introduced, so when there was nothing to update,git pullbrought no new commits, and the working tree came out clean, the repo is exactly what it was and re-running the test suite and the crawler only re-confirms what already passed. The summary marks those reposprep + crawl skipped (repo unchanged)and their Tests column reads-. Anything that could have changed the site vetoes the skip: a parsed update, a dirty working tree (which also covers an update whose output we failed to parse), a movedHEAD, or a--maintenancedirty-repo reset. Because a colleague's pushed commits moveHEAD, new code still gets the full tests-and-crawl treatment — what's dropped is only the repeat work on repos nothing happened to. This is what makes a back-to-back run over an already up-to-date set of repos fast.
--filter-name=<substring> works the same way as on update:all:
restricts the match set to repos whose composer.json name contains
the substring.
--maintenance is a one-flag preset for a dedicated update server. It
implies --yes and pre-seeds every prompt with the semi-automated
defaults: handle all (update every Craft package in every matched
repo), --parallel=3, --stop-ddev (stop each project after a
successful update), commit + push, crawl every repo, and a craft command
with --backup=0. When a Slack webhook is configured (see
Configuration) it also posts a run
summary at the end. Any explicit flag still wins, so
pu update:craft --maintenance --parallel=5 --no-push overrides just
those two defaults.
Because a dedicated update server never carries real local work,
--maintenance also hard-resets any repo with uncommitted changes
before updating it (git reset --hard HEAD + git clean -fd) instead of
skipping it, then lets the normal sync steps (ddev composer install,
migrate/all, project-config/apply --force) bring dependencies and
project config back in line. Gitignored paths (vendor/, .env,
storage/) are left untouched. This only happens under --maintenance —
a normal update:craft run still skips dirty repos.
--maintenance also retries the craft update once on a transient
composer download failure (a corrupt/0-byte dist zip, a truncated
download). Before retrying it restores a healthy state — git reset --hard + git clean -fd, ddev composer clear-cache, then ddev composer install from the committed lock — so a half-extracted vendor
tree (which can stop Craft from even booting) can't wedge the retry.
Genuine dependency conflicts are never retried.
--maintenance also resets a diverged branch to origin. When the
branch carries local commits that were never pushed (usually a previous
run whose push was held back by failing tests or crawler errors) and
origin has moved on in the meantime, the fast-forward pull can't work.
Instead of failing, the run does git reset --hard origin/<branch>,
discards the local commits, and rebuilds the update on top. The summary
and the Slack message both name the repo and how many commits were
discarded. A branch that's only ahead of origin is left alone, so its
commit goes out with the next push. A normal update:craft run still
fails on a diverged branch.
Excluding a project
To pause a project, put an empty .nopu file in its root, the way you'd
add a .gitkeep, and commit it. Every command (update:all,
update:craft, remove) then finds the repo but leaves it completely
untouched: no reset, no pull, no ddev. It shows up as excluded via .nopu in the summary, and in its own section of the Slack message
instead of among the failures. To resume, commit the removal.
The marker is read from origin's branch right after the fetch, so a
marker a colleague just pushed takes effect on the next run, and so does
its removal, even though the server's own checkout is still stale. An
untracked .nopu on one machine also works, as a local override that
never leaves that machine.
A marker that is already in the working tree, committed or not, is checked before the fetch, so the repo's remote is never contacted. That protects repos whose git server bans the office IP after failed logins, such as one where only GitKraken holds the credentials. The price: when a colleague removes a committed marker, a machine whose checkout still has it keeps skipping the repo until someone pulls it by hand.
update:npm
Applies the npm fixes that Panoptikum lists, and nothing else. Panoptikum
decides what needs an update: every open npm threat on production cells,
whatever its relevance and including dev dependencies, merged per
repository. Packages without an advisory are never touched. pu update:npm reads that list
from Panoptikum's GET /api/v1/npm-updates and works through every local
repo that appears in it. Configure the endpoint first, see
Panoptikum.
A local folder matches a Panoptikum repository by its composer name, or,
without a composer.json, by the lowercased owner/repo of its origin
remote. That's the same key panoptikum-cell reports, so Node and Nuxt apps
match too. The walker considers any git folder with a package-lock.json.
A key that appears in more than one local folder (a generic composer name
such as laravel/laravel) matches none of them, and the run lists it.
For each repo, the command does the following:
- Prepares the branch exactly like
update:craft: fetch, lowest long-lived branch,.nopu, the higher-branch guard, and under--maintenancethe reset of dirty or diverged repos. - Skips the repo when it has a
yarn.lock. Apackage-lock.jsonwithlockfileVersion1 is converted first withnpm install --package-lock-only --lockfile-version=2, which keeps the installed versions. Version 2 because a server still on npm 6 reads it but failsnpm cion version 3. The conversion gets its own commit,chore: convert package-lock.json to lockfileVersion 2, ahead of the update commit, and the gate checks both. - Updates only fixes on the installed caret line (same major, or same minor below 1.0). A fix that needs a new major, and a package Panoptikum reports as not fixable, are only listed in the run notes.
- Runs
npm update <packages> --ignore-scripts --before=<7 days ago>, so install scripts never run and only releases older than a week get in.--beforeworks on every npm version. - Adds an
overridesentry ("<package>": "^<fixed>") topackage.jsonwhen a transitive package is still below its fix because a parent holds it back, and installs again. - Checks the result against Panoptikum's blocked versions. A package that lands inside a blocked range is dropped from the update and noted as "blocked by WBHB-xxxx". The other packages still update.
- Gates the result:
npm ci --ignore-scripts, the project's production build (npm run build, elseproductionorprodfor Laravel Mix),ddev browser-testwhen.ddev/commands/web/browser-testexists, then the site-crawler.composer prepdoesn't run.npm ciand the build use the Node version in the project's.nvmrcwith its own npm, so the gate installs and builds like the server deploys. Inside ddev,ndownloads that version into ddev's global cache. On the host, nvm provides it and installs a missing version. The update steps before the gate use the same npm when it's 8.3 or later, so the lockfile is the one the server's npm writes. An older pin keeps the default npm for the update, because npm before 8.3 ignores overrides. On Apple Silicon, Node versions before 16 need Rosetta. When the project hasnode-sass, the gate runsnpm rebuild node-sassbefore the build, because its binding comes from an install script. A build that printsERROR infails the gate even when it exits 0, because webpack 1 to 4 do that on module errors. - Commits only
package-lock.json, pluspackage.jsonwhen an override was added, asnpm security updates. The body lists each change with its relevance and advisories, the source files that import a changed package (for a transitive package, the files that import its direct parent), and a GitHub compare link per changed direct dependency. - Pushes only when the tests and the crawl were clean.
Repos with a .ddev/config.yaml run ddev npm. Other repos, such as
Node apps, run the host's npm and get no crawl.
pu update:npm --dry-run # list repos and the packages Panoptikum wants updated pu update:npm --repo=$HOME/reps/mesh # one repo, interactive pu update:npm --key=acme/shop # one repo by its Panoptikum key, from any directory pu update:npm --maintenance # dedicated server: commit, push, Slack summary
It takes the same flags as update:craft, except the handle,
--target-version, --craft-command, and the composer sweep.
--filter-name= matches the Panoptikum key instead of the composer name.
retry
Re-runs the most recent update:all, update:craft, or update:npm non-interactively
using the answers persisted in logs/last-run.json. Useful for working
through a batch in chunks — already-up-to-date repos are skipped by the
target-version filter, so each retry picks up where the previous one left
off.
Without a target version (e.g. --maintenance, which updates all)
nothing is filtered, so a plain retry processes every repo again. Pass
--failed to replay only against the repos marked failed in
logs/last-results.json. The crawler selection is narrowed to match. If
the last run never reached its summary, the stored results don't describe
it and --failed refuses to guess.
A replay never rewrites logs/last-run.json (retry passes the internal
--retrying flag), so every retry replays the original run. It does
write logs/last-results.json, so open and retry --failed see the
latest outcome and each retry --failed only takes on what is still
failing.
open
Opens repos from the most recent run in GitKraken (one tab per repo via
the gitkraken:// URL scheme). By default it surfaces repos that
warrant review: uncommitted working-tree changes, failed steps, failing
tests after composer prep, crawler failures, or 5xx URLs from the
crawler. You can narrow the pool with --filter=changed,
--filter=failed, or --filter=all. Both update:all and
update:craft also offer this prompt directly at the end of a run —
push the resulting commits via GitKraken without context-switching.
Logs and transcripts
logs/transcripts/<repo>-<timestamp>.log— full output of every step for one repo, fromgit statustoddev stop. Always written, success or fail.logs/<repo>-<step>-<timestamp>.log— narrow per-step log written when a specific command fails or its tests don't pass.logs/last-run.json— the resolved command + arguments + options of the last run (powersretry).logs/last-results.json— per-repo results of the last run (powersopen).
In sequential mode (--parallel=1) every step's output streams live to
the terminal. Parallel mode does not stream (output would interleave) —
the transcript and per-step logs are how you investigate.
3. Configuration
Repo directory
REPOS_DIR (env var, or .env next to the tool when running from a
local clone) — single source of truth for where to scan. Default:
$HOME/reps. Per-run override available on every command via
--reps-dir=.
Slack webhook (maintenance runs)
pu update:craft --maintenance posts a run summary to Slack when a
webhook is configured. To set it up:
- At https://api.slack.com/apps, create a Slack app (or reuse one), enable Incoming Webhooks, then Add New Webhook to Workspace and pick the channel the summary should post to.
- Copy the generated
https://hooks.slack.com/services/...URL. - Save it - interactively via
pu setup, or non-interactively:
pu setup --slack-webhook-url="https://hooks.slack.com/services/T.../B.../..." pu setup --no-slack # persist an empty webhook (notifications off)
The URL is stored in ~/.config/package-updater/config.json. Leave it
blank to disable notifications; once you have answered, pu setup won't
keep asking.
The summary groups the run into three buckets: repos updated, committed
and pushed; repos updated but not pushed (uncommitted, or committed with
the push held back by failing tests / PHPStan / a site-crawler issue);
and failed, skipped, or otherwise-flagged repos. The last bucket also
catches an otherwise up-to-date repo that still hit a problem during the
run — a 5xx during the crawl (with the offending URLs listed), a crawler
crash, or failing tests — so those never disappear into the "already up
to date" count. It's only sent on --maintenance runs, and only when a
webhook is configured. Any send error is logged as a warning and never
fails the run.
The message posts under the Slack app's own name and icon (the app the webhook belongs to). Slack ignores per-message sender overrides for app-based webhooks, so rename the Slack app itself if you want a different display name.
Panoptikum (npm updates)
pu update:npm reads its work list from Panoptikum. Save the base URL and
the token once:
pu setup --panoptikum-url=https://panoptikum.example --panoptikum-token=<token>
The token is Panoptikum's PANOPTIKUM_PACKAGE_UPDATER_TOKEN, stored in the
1Password vault "Environment Secrets" as "Panoptikum package-updater
token". Both values go into ~/.config/package-updater/config.json, which
the tool keeps readable for your user only. Panoptikum also checks the
caller's IP address, so the machine that runs the command must be on its
allowlist.
Git credentials (HTTPS remotes)
The tool shells out to git, which uses your CLI credentials — not
GitKraken's. For HTTPS GitHub remotes, install and configure the GitHub
CLI once:
brew install gh gh auth login # pick HTTPS, browser auth gh auth setup-git # register gh as git's credential helper
For Bitbucket / GitLab / Azure DevOps HTTPS remotes, use Git Credential Manager:
brew install --cask git-credential-manager git-credential-manager configure
After either, git pull runs without prompting on matching remotes.
Host SSH agent (SSH remotes)
Repos cloned over SSH (git@bitbucket.org:…, git@github.com:…) bypass
those credential helpers and need your host's SSH agent to have the right
key loaded. Add a per-host block to ~/.ssh/config so macOS loads it on
login:
Host bitbucket.org
AddKeysToAgent yes
UseKeychain yes
IdentityFile ~/.ssh/id_rsa
Then once:
ssh-add --apple-use-keychain ~/.ssh/id_rsa
To find which local key matches the fingerprint shown in your git host's UI:
for f in ~/.ssh/*.pub; do ssh-keygen -lf "$f"; done
DDEV SSH for private composer dependencies
composer update runs inside ddev, which uses a global, shared SSH-agent
container. The tool runs ddev auth ssh for you once at the start of a
real run (after the confirm prompt, before any repo work) so private
GitHub composer sources resolve without per-repo setup. If your SSH keys
have passphrases, you'll be prompted at that point. The step can be
skipped if you've already loaded keys in this shell.
DDEV hostnames / sudo
The first time ddev starts a given project on this device it may need
sudo to add the project's .ddev.site hostname to /etc/hosts. In a
piped/parallel run that would hang forever on the password prompt — the
tool watches for the trigger lines (needs to run with administrative privileges / may need to enter your password for sudo) and kills ddev
immediately, then fails that repo with a hint telling you to run ddev start manually once and then retry.
GitKraken (for the open feature)
Uses the gitkraken://repo/path/<absolute-path> URL scheme via macOS
open. No extra setup beyond installing the GitKraken app.