Skip to content
Agents Pack

Update, pin, and rollback

Update, pin, and rollback

Section titled “Update, pin, and rollback”

CLI application updates and content-pack updates are separate. The commands on this page update instructions, skills, subagents, and release notes. They do not update the CLI executable. To upgrade the CLI, rerun the public installer.

Keep the CLI current before updating content; older CLIs lack some of the options below. See Upgrade the CLI.

Ask your coding agent:

Use ap-manage-agents-pack to check for a pack update and show me newly added
skills, subagents, and instructions. Help me choose additions, preview the
combined changes, and apply my selection.

Agents Pack preserves your explicit component selection. New optional or recommended components become available but are not silently installed. User-owned canonical content is not part of the official update and is preserved during rollback.

Check for a new official pack

Section titled “Check for a new official pack”
agents-pack update --check

The check downloads and validates the registry’s current candidate, then reports installed and candidate versions, whether an update is available, current pin state, candidate release notes, selected components the candidate removed, and newly introduced components compatible with your selected agents. It does not cache or apply the candidate.

--check cannot be combined with --yes, --dry-run, or --add.

Preview and apply an update

Section titled “Preview and apply an update”
agents-pack update --dry-run

Interactively:

agents-pack update

The menu offers newly introduced skills, subagents, and instructions, grouped by category. Use the arrow keys to move, Space to toggle a category or individual component, and Enter to continue. Leave everything unselected to skip additions. Required components are added automatically. You review the combined version update and selected additions before confirming.

Non-interactively:

agents-pack update --yes

--yes skips the selection menu and preserves existing choices without opting into new optional or recommended components.

Select additions explicitly

Section titled “Select additions explicitly”

Use component IDs for agent-driven updates, scripts, or dry runs:

agents-pack update --add ap-design-studio,ap-design-critic --dry-run
agents-pack update --add ap-design-studio,ap-design-critic --yes

--add skips the picker, adds to the existing selection, and never removes components. It can also select older compatible components you previously declined. The pack update and selected additions apply together in one transaction. It does not need a version change: running update --add <id> when you are already on the current version just adds the component.

--check and --dry-run list new components without prompting. Discovery compares the full cached installed pack with the candidate, so previously declined components do not keep appearing as new. If that cache is missing or invalid, the CLI reports the limitation and still permits the update. Use --add explicitly, or run agents-pack list --available and install components after updating.

When a new pack removes a component

Section titled “When a new pack removes a component”

If the candidate pack no longer contains a component you selected, the update still proceeds. update --check and the update plan warn once for each removed component, the update uninstalls its managed files, and your configuration keeps only the remaining selections. The release notes name any replacement; add it with --add <id> or agents-pack install <id>.

Older CLIs refuse such an update, so upgrade the CLI first.

Update from a local candidate

Section titled “Update from a local candidate”

For an installation initialized from a local pack:

agents-pack update --check --pack /path/to/new-local-pack
agents-pack update --pack /path/to/new-local-pack --dry-run
agents-pack update --pack /path/to/new-local-pack --yes

Official installations use the registry by default. Local installations require --pack.

Pin and unpin

Section titled “Pin and unpin”

Keep the current version:

agents-pack pin

A pinned installation can still check for updates, install available components, and remove optional components. Applying a different pack version stops until you unpin:

agents-pack unpin

pin and unpin take effect immediately and do not accept --yes or --dry-run. Both are idempotent and still validate that managed outputs are clean.

Roll back

Section titled “Roll back”

Rollback only uses previously cached packs with the same pack ID. It never downloads a missing historical version.

Newest cached older version

Section titled “Newest cached older version”
agents-pack rollback --dry-run
agents-pack rollback --yes

Without a version argument, Agents Pack chooses the newest cached version older than the installed version.

Exact cached version

Section titled “Exact cached version”
agents-pack rollback 0.24.0 --dry-run
agents-pack rollback 0.24.0 --yes

A successful rollback automatically pins the restored version so a later update does not immediately undo your decision. Run agents-pack unpin when you are ready to move forward again.

Section titled “Related”