Upgrading from npm
agb migrate: move an npm-global or checkout install onto the native plugin, and roll it back
If you installed agb with npm install -g antigravity-booster or run it from a source checkout, agb migrate moves that install onto the native Antigravity plugin. Before it changes anything, it snapshots your current plugins, shim, import manifest entries and skill links, so agb migrate --rollback can always restore the previous state.
agb migrate # migrate (resumes an interrupted run)
agb migrate --rollback # restore the pre-migration stateFlags
As parsed in bin/agb.mjs (C15):
| Flag | Effect |
|---|---|
| (none) | Run the migration, or resume one that was interrupted. |
--force | Re-run a migration that already reached MIGRATED, which otherwise exits 1. With --break-lock, skip the confirmation prompt. |
--rollback | Restore from the pre-migration baseline snapshot. |
--force-rollback | Roll back even if the staged plugins changed since migration. Without it, rollback refuses and lists the changed plugins (lib/migrate.mjs). |
--break-lock | Remove a stale migration lock. It shows the holder's pid and start time, warns if that process still appears to be running, and asks Break the migration lock? [y/N]. With no TTY, the answer is no unless you pass --force. It never runs a migration (lib/migrate.mjs). |
What a migration does
- Snapshot. Copies the current plugin trees,
~/.local/bin/agband booster's import manifest entries into a timestamped snapshot. The first run also writes a read-onlypre-migration.baseline.json, which every restore reads from (lib/migrate.mjs). - Record symlinks. Records the skill symlinks in
~/.gemini/skillsthat the old install owns. - Stage plugins. Installs and validates the
antigravity-boosterandadlc-antigravityplugins. - Finalize. Removes the recorded old skill links and writes the terminal shim
~/.local/bin/agb, replacing any existing one (lib/migrate.mjs).
On success it prints:
Migration successful. Global npm package may be uninstalled: npm uninstall -g antigravity-booster. CLI commands remain available via ~/.local/bin/agb and slash commands (/agb-doctor, /agb-bootstrap, /agb-migrate).
(lib/migrate.mjs). Until you uninstall the npm package, agb doctor warns that a secondary install is on your PATH.
State machine
Each step writes its state before moving on, so an interrupted migration resumes where it stopped (migrateLocked, rollbackLocked).
SNAPSHOT_CREATED,SYMLINKS_RECORDED,PLUGINS_STAGED: in progress. Runningagb migrateagain resumes from the recorded state. Rolling back before staging has started (and when the system has never migrated) just deletes the snapshot and state, because nothing live had changed.MIGRATED: done.agb migraterefuses without--force.--rollbackrestores the baseline, guarded by--force-rollbackas described above.ROLLBACK_IN_PROGRESS: a rollback was interrupted.agb migraterefuses until you runagb migrate --rollbackto finish restoring.ROLLED_BACK_PENDING_UNINSTALL: files are restored, but uninstalling the booster plugin is handed to a separate process. The nextagb migrate(or--rollback) finishes the uninstall first.ROLLED_BACK: back at the baseline. A lateragb migratearchives the old state and starts fresh.
Any unknown state makes agb migrate exit 1 and tells you to run agb migrate --rollback or inspect the data directory.
Migrations and rollbacks hold a lock. If a crashed process left it behind, use agb migrate --break-lock, then re-run agb migrate or agb migrate --rollback.