agentsmesh refresh

Re-fetch and re-apply every installed pack from its recorded source/ref. Branch pins (@main) advance to the current tip; tag pins re-resolve in case the tag moved; SHA pins stay put (content is re-fetched but the SHA is unchanged). Each pack is refreshed atomically — a failure leaves the affected pack at its prior state.

Usage

agentsmesh refresh [<name>[,<name>...]] [flags]

Bare command (no names) refreshes every installed pack in the current scope.

Flags

Flag	Description
`<name>`	Pack name(s) to refresh, comma-separated. Omit to refresh all installed packs.
`--dry-run`	Preview the refresh plan (resolved refs, drift detection) without writing.
`--force`	Non-interactive mode: skip the local-edit consent prompt. Implied by `--json`.
`--json`	Machine-readable JSON envelope on stdout. Implies `--force`.
`--global`	Refresh packs in the global scope (`~/.agentsmesh/`) instead of the project scope.

Exit codes

Code	Meaning
`0`	All requested packs refreshed (or `--dry-run` preview shown). Partially-applied batches where some packs are unchanged still exit `0`.
`1`	At least one pack failed (`data.failed[]` non-empty). Surviving packs still applied; post-operation `generate` still ran.
`2`	Validation failure (no installed packs found, lock contention, or unknown pack name).

Examples

Refresh every installed pack

agentsmesh refresh

Re-fetches every pack from its recorded source and ref. Branch pins resolve to the current tip of their branch.

Refresh specific packs

agentsmesh refresh my-pack,other-pack

Preview without writing

agentsmesh refresh --dry-run

Shows which packs would change, the resolved ref transitions, and any local file drift — without writing anything.

Non-interactive (CI/scripts)

agentsmesh refresh --force

Skips the consent prompt for locally-modified pack files. Use in CI to keep packs up-to-date automatically.

Refresh global packs

agentsmesh refresh --global

Refreshes packs installed in ~/.agentsmesh/.

When refresh detects that pack files have been edited locally since install, it surfaces a consolidated prompt before overwriting:

Pack "my-pack" has 2 locally modified files:
  - skills/demo/SKILL.md (modified)
  - agents/reviewer.md (modified)

Refresh will overwrite these changes. Continue? [y/N]

The prompt has a 5-minute timeout that defaults to “no” on expiry. --force accepts the overwrite non-interactively. --dry-run reports the drift without prompting.

refresh does NOT switch refs

refresh replays the currently recorded source/ref. It does not change which ref a pack tracks.

To move a pack to a different ref, just install with the new ref — install silently updates an existing pack of the same name:

agentsmesh install github:org/repo@v2.0.0

refresh vs `install --sync`

	`refresh`	`install --sync`
Purpose	Update existing installs against their declared sources	Restore missing packs after a fresh clone
When a pack dir exists	Re-fetches and re-applies it	Skips it (already present)
When a pack dir is missing	Skips it (not a restore tool)	Reinstalls it from `installs.yaml`

Use install --sync after git clone or when a teammate added a new pack to installs.yaml. Use refresh to pull in upstream changes for packs you already have.

JSON output

agentsmesh refresh --json

{
  "success": true,
  "command": "refresh",
  "data": {
    "scope": "project",
    "mode": "refresh",
    "refreshed": [
      {
        "name": "my-pack",
        "oldRef": "main",
        "newRef": "main",
        "oldSha": "abc1234",
        "newSha": "def5678",
        "changedFiles": {
          "added": ["skills/new-skill/SKILL.md"],
          "removed": [],
          "modified": ["skills/existing/SKILL.md"]
        }
      }
    ],
    "unchanged": [
      { "name": "stable-pack", "ref": "v1.0.0" }
    ],
    "skipped": [],
    "failed": [],
    "dryRun": false
  }
}

Field reference:

refreshed[].oldRef / newRef — the ref string before and after (identical for SHA pins; branch name for branch pins).
refreshed[].oldSha / newSha — the resolved commit SHA before and after. Both null for local-path packs that have no SHA tracking.
refreshed[].changedFiles — { added, removed, modified } arrays of forward-slash paths relative to the pack root.
unchanged[] — packs whose re-fetched content matched the current on-disk state; no files were written.
skipped[] — packs the user declined at the consent prompt (reason "user-declined").
failed[] — packs that encountered an error during plan, fetch, apply, or manifest-update. Exit code is 1 whenever this array is non-empty.

MCP tool

agentsmesh refresh is also available as an MCP tool.

Name: mcp__agentsmesh__refresh

Input:

Field	Type	Description
`names`	`string[]` (optional)	Pack names to refresh. Omit or pass empty array to refresh every installed pack.
`dry_run`	`boolean` (optional)	Preview the refresh plan without writing.
`global`	`boolean` (optional)	Refresh packs in the global scope (`~/.agentsmesh/`).

MCP calls always run non-interactively (force: true). The response envelope matches the --json output above.