How to Update AG-Kit to the Latest Version: A Complete CLI Guide

Run ag-kit update --dry-run to preview changes, then ag-kit update to apply the upgrade while the CLI automatically preserves your local modifications and creates timestamped backups in .agents/.ag-kit/.

Updating the vudovn/ag-kit toolkit follows a deterministic, merge-aware workflow that safeguards your local customizations. The upgrade process centers on the .agents/ directory, where the CLI tracks all managed components—including agents, skills, workflows, rules, and memory files—via manifest.json and manifest.lock.json. This guide walks through the exact commands and validation steps required to update AG-Kit to the latest version without losing work.

Prerequisites: Validate Your Workspace Health

Before initiating any update, confirm your current installation is stable. The AG-Kit CLI expects a healthy workspace state to compute accurate diffs.

Run the built-in validation suite:

npm run check:agents

This command audits the integrity of files defined in .agents/manifest.json, ensuring no corruption exists before the upgrade planner executes. If this check fails, resolve the reported issues before proceeding to update AG-Kit to the latest version.

Preview Changes With Dry-Run Mode

The AG-Kit CLI implements a deterministic diff engine that compares your installed version against the newest release. To inspect the upgrade plan without modifying files, use the --dry-run flag.

ag-kit update --dry-run

During this phase, the CLI calculates exactly which generated files—such as updated manifest.json schemas, new Antigravity runtime contracts in .agents/antigravity.json, or hook scripts like .agents/hooks/validate-tool-call.mjs—will change. Locally modified managed files remain untouched in the preview, allowing you to review incoming changes safely.

Execute the Update Safely

When ready to apply the upgrade, run the standard update command. The CLI executes a five-stage merge-aware process:

ag-kit update

Stage 1: Backup Creation. The CLI immediately writes a timestamped backup to .agents/.ag-kit/ and maintains a secondary copy in .ag-kit-backups/ outside the managed tree.

Stage 2: Merge Application. The tool applies new generated files (including updated manifest definitions and Antigravity layer contracts) while preserving user-owned changes. If conflicts arise, the CLI writes both the incoming version and a machine-readable conflict report to facilitate manual review.

Stage 3: Post-Upgrade Validation. The update triggers an automated re-check of the toolkit integrity.

Post-Update Validation Protocol

After the CLI finishes merging files, verify the installation across all layers. According to the cli/package.json entry point configuration, run the full validation suite:

# Re-validate the core agent toolkit

npm run check:agents

# Verify Antigravity integration integrity

npm run check:antigravity

# Run the Antigravity test suite

npm run test:antigravity

# Build the Antigravity plugin to confirm compatibility

npm run build:antigravity-plugin

These commands ensure that the updated runtime contracts in .agents/antigravity.json and safety hooks such as .agents/hooks/validate-tool-call.mjs function correctly with the new version.

Rollback to Previous Versions

If validation fails or you encounter breaking changes, revert immediately using the rollback command. This restores the workspace to the pre-update state using the most recent backup stored in .agents/.ag-kit/:

ag-kit rollback

Because backups are created automatically before any file modifications, you can safely experiment with updates knowing the previous state is recoverable. For detailed migration strategies and breaking change notes between specific versions, consult the MIGRATION.md guide in the repository root.

Summary

• Validate first: Always run npm run check:agents before updating to ensure the workspace is healthy.
• Preview changes: Use ag-kit update --dry-run to see a deterministic diff of incoming modifications without applying them.
• Automatic backups: The CLI creates timestamped backups in .agents/.ag-kit/ and .ag-kit-backups/ before touching any managed files.
• Verify after updating: Execute the full validation chain (check:agents, check:antigravity, test:antigravity, build:antigravity-plugin) to confirm integrity.
• Instant rollback: Run ag-kit rollback to restore the previous version from backups if issues arise.

Frequently Asked Questions

What happens if the update fails halfway through?

The AG-Kit CLI is atomic in its backup phase. If the update process interrupts after the backup is created in .agents/.ag-kit/ but before completion, run ag-kit rollback to restore the previous state. The conflict reports generated during merge conflicts also allow you to resume manually without re-running the full update.

Can I preview exactly which files will change before updating?

Yes. The --dry-run flag on ag-kit update computes a deterministic diff between your current installation and the latest release. This preview shows modifications to managed files like .agents/manifest.json and .agents/antigravity.json without writing any changes to disk.

Where does AG-Kit store update backups?

Backups are stored in two locations: a primary copy inside .agents/.ag-kit/ (within the managed directory) and a secondary copy in .ag-kit-backups/ outside the managed tree. Both locations use timestamped archives to preserve the exact state prior to the upgrade.

How do I know the update succeeded?

After running ag-kit update, execute npm run check:agents to verify the core toolkit, followed by npm run check:antigravity and npm run test:antigravity to validate the Antigravity integration. Successful completion of these commands, along with a successful npm run build:antigravity-plugin build, confirms the update AG-Kit to the latest version process completed correctly.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}