selfauth diff and selfauth upgrade
Generated code is yours, so a new SelfAuth release never changes it behind your back. diff shows what a newer release would change, and upgrade applies the safe part and leaves the rest for you to merge.
selfauth diff
selfauth diff [dir]Compares your project with the templates of the CLI you're running and prints a diff for each file. It writes nothing.
Output when there's nothing to do:
Templates 0.15.0 → 0.15.0
• kept (your edit; template unchanged) src/routes/index.ts
25 file(s) unchanged.To compare against a newer release, run the newer CLI:
npx @selfauth/cli@latest diffselfauth upgrade
selfauth upgrade [dir] [options]| Option | Meaning |
|---|---|
-y, --yes | Apply without asking |
--dry-run | Show the plan, write nothing |
--reorganize | Move a project made with SelfAuth 0.3 or earlier into the current layout (see below) |
What happens to each file
SelfAuth compares each file with the fingerprint stored in selfauth.manifest.json when it was generated.
| Your file | Did the template change? | Result |
|---|---|---|
| Unchanged since generation | yes | Updated |
| Edited by you | yes | Kept. A proposal <file>.selfauth-new is written next to it for you to merge, then delete |
| Edited by you | no | Kept |
| Deleted by you | – | Stays deleted |
| New in the release | – | Added (never over an existing file) |
The steps to follow
- Commit your work first, so you can review the changes with
git diff. - Run
npx @selfauth/cli@latest diff, thennpx @selfauth/cli@latest upgrade. - Merge each
.selfauth-newproposal.git diff --no-index file file.selfauth-newhelps. Delete the proposal when you're done, andselfauth validatewill tell you if any are left. - Review and apply new migrations with
npx selfauth db plan, thennpx selfauth db migrate, thennpm run db:seed. Never edit a migration that's been applied. - Run your tests and
npx selfauth doctor. - If you installed the agent skill, update it with
npx selfauth skill install --agent claude --update.
Versioning
SelfAuth is 0.x, so minor versions can change generated code and behavior. Each change is in the changelog along with the steps to take. Security fixes ship as patch releases, so upgrade promptly and use diff to see exactly which files a fix touches.
Moving old layouts
| Your project was made with | Layout | Move with |
|---|---|---|
| SelfAuth 0.3 or earlier | Files side by side in src/ | upgrade --reorganize into the grouped layout (config/, email/, db/, http/, routes/) |
| An earlier full-stack layout | API at the root, frontend in web/ | upgrade --reorganize into server/ and client/ in one workspace |
Both keep working until you move, but upgrade refuses to touch the old flat layout, because the new templates import each other from the new locations.
git commit -am "before reorganizing"
npx selfauth upgrade --reorganize --dry-run # lists every move
npx selfauth upgrade --reorganize # asks first; --yes to skip
npm run typecheck && npm testOnly paths and imports change, never any file's logic. If a target file already exists, it stops without changing anything.
Without the CLI
If you installed by hand, compare your files with the new release's templates/ folder (or two release tags, with git diff v0.14.0 v0.15.0 -- templates/express) and copy over the changes you want. Copy the new selfauth.manifest.json too, so a later diff stays accurate. New migration folders are additive: copy them and apply them, and never edit one that's already been applied.