palm update

palm update re-resolves each source’s ref: against its remote, prints a plan, asks, and installs what changed.

palm update [sources...] [--to <ref>] [--dry-run] [--strict] [--review]

Alias: palm up.

Command	What it does
`palm update`	Plan and apply updates for every git source in `palm.yaml`.
`palm update mattpocock/skills`	Only this source.
`palm update --dry-run`	Print the plan and write nothing. This is the outdated report, with the latest tag for pinned sources.
`palm update --dry-run --strict`	The same, and exit 1 when a source is behind its ref, with a line that says why.
`palm update acme-kit --to ^2`	Move the ref in `palm.yaml` to a new range, then update.
`palm update --review`	Print script diffs of changed programs before the question.
`palm update --yes`	Apply without the plan question. Programs still need consent.

$ palm update --dry-run
Update plan (project scope)
mattpocock/skills   ^1.2   v1.2.3 (2c0db90) → v1.3.0 (3f63d4d)
~ updated   skill   tdd   mattpocock/skills   v1.2.3 (2c0db90) → v1.3.0 (3f63d4d)
= 1 re-pinned (same content)
dry run: nothing written.
$ palm update --yes
Update plan (project scope)
mattpocock/skills   ^1.2   v1.2.3 (2c0db90) → v1.3.0 (3f63d4d)
~ updated   skill   tdd   mattpocock/skills   v1.2.3 (2c0db90) → v1.3.0 (3f63d4d)
= 1 re-pinned (same content)
~ skill  tdd   .agents/skills/tdd/, .claude/skills/tdd/   5 files   (claude gets its own copy in .claude/skills)
1 updated, 1 unchanged.
 M .agents/skills/tdd/SKILL.md
 M .claude/skills/tdd/SKILL.md
 M palm.lock.yaml

Options

Argument	Meaning
`sources`	sources to update (default: all)

Option	Meaning
`--to <ref>`	move the ref in palm.yaml (a tag, branch, sha or range such as ^2)
`--review`	print changed scripts and entities as diffs before asking
`--strict`	with –dry-run: exit 1 when a source is behind its ref
`--allow-local-sources`	palm.yaml may name file:// sources outside the project

The global options also apply.

The plan

palm first plans without writing anything in the scope. For each selected source it resolves the ref against the remote, fetches the new commit into the cache, indexes it and compares every entry.

Update plan (project scope)
mattpocock/skills   ^1.2   v1.2.0 (3f2a1c9) → v1.2.3 (8be01d4)
~ updated           skill   tdd                   mattpocock/skills
+ added             skill   review (plugin:kit)   acme-kit
~ changed program   hook    team-skills           acme-kit
= 1 re-pinned (same content)
! hook team-skills: setup.sh changed (sha256:a7cc… → 3e01…); d shows the diff
! you changed these files since palm wrote them; palm overwrites them only with --force:
    .claude/skills/tdd/SKILL.md  (skill tdd)

Line	Meaning
`<source> <ref> <old> → <new>`	the source, its ref, and the move from the locked tag and commit to the new ones
`latest <tag>`	for a source pinned to a tag or a commit: the newest release tag, and for a commit pin the default branch head too, such as `93f5a2d; main is 063bee9`
`~ updated`	the entity’s content changed
`+ added`, `- removed`	a plugin member the new version declares or dropped
`= N re-pinned (same content)`	the source moved and these entries’ files did not change; palm re-pins them to the new commit, one count line
`~ changed program`, `+ new program`	a hook or stdio server whose command or scripts changed, or that is new; never `same content`, since its scripts can change while its definition does not
`x failed`	the source is unreachable, or no longer has the entity
`⊘ skipped`	an in-repo source, one line per source; `palm update` never touches those, a bare `palm install` does
`! hook ...`	a new or changed program, with its old and new hash; after you allow it, `~ trusted hook <name> sha256:…`
`i new program available`	a hook or stdio server that a plugin you installed now ships; the line names the command that installs it
`! you changed these files`	generated files you edited; palm keeps them unless you pass `--force`

When a source’s ref moves, the plan lists every entry of that source, so review sees each one that is re-pinned. The report after applying prints unchanged entries as one count line.

Then palm asks Apply N changes? [y/N]. The default is no, and no changes nothing: palm prints Nothing changed. and exits 0. Without a terminal, --yes answers it. Without either, palm stops with E_NON_INTERACTIVE and names the command with --yes.

--dry-run --strict exits 1 when a source is behind its ref, and prints the reason for each source. A ref: in palm.yaml that differs from the lock counts too, such as lock records v1.2.3, palm.yaml ^1.2: palm install.

--review shows the scripts of programs, with diffs. A changed skill or agent is marked in the plan, and you read its text in the pull request’s diff. Text diffs in --review for skills and agents arrive in palm 0.3.

Check for updates in CI

palm update --dry-run --strict

Run it on a schedule, not on every pull request, since upstream moves without your changes. It fails for a source behind its ref: a branch with new commits, or a range such as ^1.2 with a newer matching tag.

A commit sha is its own ref, so a source pinned to a sha is never behind it, and --strict exits 0 even when its branch moved on. The plan still shows the branch head beside the pin, such as 93f5a2d; main is 063bee9. To have --strict fail on new commits, pin a branch or a range instead of a sha.

Programs are never covered by `--yes`

A changed or new hook or stdio server goes through consent on its own, after the plan. On a terminal, d pages a unified diff of each changed script against the version you trusted, and v pages the full scripts. palm fetches the trusted commit for the diff when the cache no longer holds it. --review prints those diffs before the question, paged on a terminal. Without a terminal, a changed program stops with E_UNTRUSTED_EXEC and the --allow-exec line to consent to its new hash.

A refused program leaves its source at the locked commit. Declining the new version of a program ends the update with exit 130 and writes nothing. The previous version stays active, and palm prints its trusted hash and the palm remove command that takes it out.

Applying

palm installs the changed entries as palm install does, moves each source’s commit and resolved tag in the lock, and writes the lock. Entries whose content did not change are re-pinned to the new commit, so a second --dry-run reports nothing behind. When the targets of one entry end differently, the entry reports ! partial and palm exits 1. An example is a Claude Code copy kept as modified while the Codex copy could move. A source argument that is not in palm.yaml fails with a hint that installs it at the ref you asked for, such as palm install mattpocock/skills#v1.2.3 tdd. When git is present, palm prints git diff --stat of the scope, so you see what to commit.

--to <ref> moves the range itself. palm writes the new ref: to palm.yaml for the named sources, then plans against it.

Reads and writes

File	Reads	Writes
`palm.yaml`	yes	only with `--to`
`palm.lock.yaml`	yes	new commits, resolved tags, hashes, trust
harness files and `.palm/assets/`	yes	the changed entries
`~/.palm/cache/`	yes	new checkouts and indexes, also under `--dry-run`

Exit codes

Code	When
`0`	The plan was applied, declined, or printed with `--dry-run`.
`1`	A source failed, an entry failed or is partial, a source argument is not in `palm.yaml`, a program needs consent without a terminal, the plan needs `--yes` without a terminal, or `--dry-run --strict` found a source behind its ref.
`2`	An unknown option.
`130`	You declined the new version of a program, or pressed Esc or Ctrl-C at a prompt. palm wrote nothing.