Skip to content
Agent Package Manager

Update and refresh

Two things drift out of date in an APM project:

  1. The package versions pinned in apm.lock.yaml.
  2. The apm CLI binary on your machine.

They are managed by separate commands. Pick the right one.

Refresh project dependencies

Section titled “Refresh project dependencies”
Terminal window
apm update

Re-resolves every dependency in apm.yml to its latest matching version or ref, prints the planned changes, and prompts for consent before applying ref changes and redeploying primitives. If refs are unchanged but the locked apm_modules/ cache is empty, APM restores it without prompting. Pass one or more package names (apm update org/pkg-a org/pkg-b) to refresh only those.

Mutable Git refs are established from the authenticated upstream. If APM cannot reach that source, update exits non-zero instead of silently substituting a stale ref from the local bare Git cache. Once the fresh SHA is known, cached content for that SHA may still be reused.

Useful flags:

  • --dry-run -- show the resolution plan and exit; never writes.
  • --yes -- skip the consent prompt (for scripts and CI).
  • -v, --verbose -- show per-dependency resolution detail.
  • -g, --global -- refresh user-scope dependencies under ~/.apm/ instead of the current project (pairs with apm outdated -g).
  • --force -- overwrite locally-authored files and deploy despite critical security findings. It does not weaken the upstream freshness check. Use only after independent verification.
  • --parallel-downloads N -- cap concurrent downloads (default 4; 0 disables parallelism).

This is the command that actually changes versions in your project. It is a strict superset of the deprecated apm deps update.

Inspect first

Section titled “Inspect first”
Terminal window
apm outdated

Compares each entry in apm.lock.yaml against its remote source and reports which dependencies have new commits or new tags available. Read-only. An unavailable remote reports unknown; cached bare refs are not reported as current upstream state.

Useful flags:

  • -v, --verbose -- show available tags for outdated tag-pinned deps.
  • -g, --global -- check user-scope dependencies under ~/.apm/ instead of the current project.
  • -j, --parallel-checks N -- cap concurrent remote checks (default 4; 0 for sequential).

Run apm outdated before apm update to know what you are about to bump.

Plain apm install is a sync

Section titled “Plain apm install is a sync”
Terminal window
apm install

With no flags, apm install reproduces exactly the versions pinned in apm.lock.yaml. New entries you have added to apm.yml get resolved and locked; entries whose ref was changed in apm.yml are re-resolved to the new pin; entries whose spec is unchanged stay on their locked SHAs.

When the lockfile is already satisfied, install prints:

[i] Run 'apm update' to check for newer versions.

That is the nudge: install never silently bumps versions. Use apm update when you want to.

Use apm install --refresh when you need both current upstream refs and a content re-download. It re-resolves mutable refs and bypasses cached package content; apm update may reuse content already cached at the fresh SHA.

Use apm lock --update when you need the same upstream ref refresh but want to rewrite only apm.lock.yaml, without deploying or deleting harness files.

See Promise 1: Portable by manifest for why this matters in CI and for new contributors.

Lock down for CI

Section titled “Lock down for CI”
Terminal window
apm install --frozen

Lockfile-only install. Refuses to resolve anything new and exits with status 1 if apm.yml and apm.lock.yaml have drifted. Mirrors npm ci. Use this in CI to catch a manifest change that was not followed by an apm update.

--frozen is mutually exclusive with --update: one trusts the lockfile, the other rewrites it.

apm install --force does not refresh remote refs. It overwrites local collisions and may deploy despite critical built-in scan findings; the scan still runs. If you want new commit SHAs, run apm update.

Update the apm CLI binary

Section titled “Update the apm CLI binary”
Terminal window
apm self-update

Downloads the latest release of the apm CLI from the official installer URL and replaces the binary in place. Use --check to see whether an update exists without installing it:

Terminal window
apm self-update --check

That is the entire surface. It does not read apm.yml. It does not touch apm_modules/. It does not modify the lockfile.

When to use which

Section titled “When to use which”
You want to...Run
See which deps have new versionsapm outdated
Preview a dep refreshapm update --dry-run
Bump deps and rewrite the lockfileapm update
Refresh only the lockfile from upstream refsapm lock --update
Reproduce the locked versions exactlyapm install
Fail CI on lockfile driftapm install --frozen
Update the apm CLI itselfapm self-update
See if a CLI update existsapm self-update --check

Next steps

Section titled “Next steps”