Upgrade one package at a time¶
Run ossiq upgrade start, and OSS IQ queues the updates plan lists as steps. Each step shows what
changes, installs it and runs your tests. You then keep it, roll it back or skip it before the next
step begins. A failing step stops one package, not the whole batch.
ossiq upgrade works with npm, pnpm and uv projects. It does not commit anything, so commit between
steps if you want a commit per package.
The session lives in a .ossiq/ directory in the project. It holds update-progress.json and a copy
of the manifest and lockfile from before each step, and it ignores itself, so git add -A skips it.
Every command reads the session from there, so you can close the terminal and come back.
Start a session¶
Start the session with the command that tests your project:
ossiq upgrade start --test-command "npm test"OSS IQ runs the test command once before it changes anything. If that run fails, no session starts, so a failure after a step always points at that step.
Read the queue it prints:
──────────────────────── OSS IQ — Upgrade: step 1 of 7 ───────────────────────── ▶ 1 lodash 4.17.15 → 4.18.1 PENDING 2 qs 6.10.1 → 6.17.1 PENDING 3 semver 7.3.5 → 7.8.6 PENDING 4 uuid 8.3.2 → 14.0.3 PENDING 5 dayjs 1.10.0 → 1.11.23 PENDING 6 chalk 4.0.0 → 6.0.1 PENDING 7 get-intrinsic 1.3.0 → 1.3.1 PENDING
A step is one direct dependency plus the packages that must move with it. Those are the transitive
copies it pulls in and the peers that only work together, such as react and react-dom. The
transitive updates that no direct dependency pulls in share the last step.
OSS IQ orders the steps by:
Install pass (see Install passes).
Packages with a CVE before the rest, highest EPSS (exploit probability) score first.
Smaller version bumps before larger ones.
Name.
start accepts the options of plan, such as
--update-strategy latest, and three of its own:
Option |
Effect |
|---|---|
|
Run |
|
Queue only the first |
|
Queue only the step of one direct dependency |
Read a step¶
start also shows everything OSS IQ knows about the first update:
the row
status --fullprints for the packagethe
inforeport for the target versionthe module-system and engine breaks
a summary of the changelog
A package that moves with it gets its row too.
To read the changelog of every version in the step, run:
ossiq upgrade changelog
Add --web to open the same range on changelogiq.dev in your browser.
The changelogs come from changelog IQ. OSS IQ sends it the ecosystem, the package name and the two versions. The first request for a range can take a while, because the service writes the changelog then. OSS IQ waits and reports progress on stderr. When the service is unreachable, the step shows “Not available” with the web link, and nothing else changes.
Apply a step and test it¶
Install the step and run the test command:
ossiq upgrade applyOSS IQ plans again first. If a newer release appeared since the preview, it shows the new versions and exits with status 3. It never installs versions you haven’t seen.
Check the result:
▶ ● 1 lodash 4.17.15 → 4.18.1 AWAITING_REVIEW Installed. The tests passed. Next ossiq upgrade test ossiq upgrade rollback ossiq upgrade continue ossiq upgrade skip ossiq upgrade finish ossiq upgrade abortKeep the step and move to the next one:
ossiq upgrade continue
Without a test command, apply stops at “Installed. No test command is set, so nothing was checked.”
Fix a step whose tests fail¶
A failing step exits with status 3 and waits in AWAITING_REFACTOR:
▶ ✗ 6 chalk 4.0.0 → 6.0.1 AWAITING_REFACTOR
Installed, but the tests failed (exit 1).
Test command exited with 1. Last output:
banner: (text) => chalk.bold(text),
^
TypeError: chalk.bold is not a function
...
continue and finish refuse until the tests pass. You have three choices:
Fix the code, then run the tests again. Repeat as often as you need, by hand or with a coding agent:
ossiq upgrade testOnce they pass, run
ossiq upgrade continue.Roll the step back to its preview, and decide again:
ossiq upgrade rollbackSkip the step with a reason, which rolls it back first:
ossiq upgrade skip --reason "chalk 6 needs ESM"
A rollback puts the manifest and lockfile back and reinstalls from them. It does not touch your code. Code you changed to fit the new version stays in your working tree, so revert it with git.
Stop early or start over¶
Command |
Effect |
|---|---|
|
Ends the session and keeps what is installed. An applied step whose tests pass counts as kept. It refuses while the tests fail |
|
Puts the manifest and lockfile back as they were at |
The session also ends by itself when you keep or skip the last step.
Work from a menu¶
Add --interactive to start, continue or status, and OSS IQ asks which action to take after
each step, offering only the actions the step allows:
a apply c changelog w web s skip f finish x abort q quit
Choose:
Each key runs the subcommand with the same name, n (next step) runs continue, and w opens the
changelog on the web. q leaves the session as it is. Run ossiq upgrade continue --interactive
to pick it up again. On a step you have not applied yet, continue shows it without changing
anything.
Let a coding agent drive¶
Every subcommand takes --format agent and prints one JSON document on stdout. Output from npm,
uv and your test command goes to stderr, so stdout stays valid JSON.
Exit status |
Meaning |
|---|---|
|
The command did what you asked |
|
An error stopped it. See Troubleshoot a session |
|
The step needs attention: the tests failed, the install was refused, or the versions to install changed |
The loop for an agent:
ossiq upgrade start --format agent --test-command "npm test", then readstep.packages. Each direct package carriesupdate(the entrystatus --format agentprints),update_contextandchangelogwith itsbreakingitems andmigration_guides.ossiq upgrade apply --format agent.On exit status 3, read
step.last_test.output_tail, fix the code, and runossiq upgrade test --format agentuntil it exits 0.ossiq upgrade continue --format agent.rollbackorskipwhen the fix isn’t worth it. Thecommandsfield lists the subcommands that make sense next.
outcome is IN_PROGRESS until the session ends as COMPLETED, FINISHED or ABORTED, or
NOTHING_TO_DO when the plan is empty. ossiq upgrade changelog --format agent adds the whole
changelog as changelogs[].markdown. ossiq install skills
teaches Claude Code, Codex and Copilot this loop.
Set defaults for the project¶
Put the test command and a step limit in the project’s .ossiq.yaml, and start uses them unless
a flag says otherwise:
# .ossiq.yaml
version: 1
upgrade:
limit: 3
test-command: "npm test"
The command runs in your shell, from the project directory, so commit it only if everyone who
runs ossiq upgrade should run it. See Project policy file.
Troubleshoot a session¶
“An upgrade session is already in progress here.”¶
A session already exists for this project. Run ossiq upgrade status to resume it, or
ossiq upgrade abort to discard it.
“The test command already fails before any upgrade”¶
The test command failed on the untouched project, and the message ends with its last output. Fix
those tests first, or start without --test-command.
“ossiq upgrade does not support … projects yet.”¶
Only npm, pnpm and uv projects can step through updates. ossiq apply still applies the whole plan.
“The versions to install changed since the preview.”¶
A newer release appeared between the preview and apply, and the step now shows the new versions.
If the new versions only install with another package’s update, that package joins this step too.
Read them, then run ossiq upgrade apply again.
“No upgrade session in this project.”¶
.ossiq/ holds no session here. Run ossiq upgrade start, or run the command from the project
directory you started in.
“The session file is unreadable”¶
Someone edited the file in .ossiq/, or another OSS IQ version wrote it. Run ossiq upgrade abort with
the version that started the session, or delete .ossiq/ to forget it. Deleting it leaves the project
files as they are now.