shelf Docs

shelf pull

Updates a skill from the source it was imported from (or linked to) with shelf add. It shows the diff and a fresh audit, and changes the library only with --yes. Then shelf propagate updates borrowing projects.

On this page 
shelf pull <name> [options]
ArgumentDescription
<name>Skill name
OptionTypeDefaultDescription
--yesbooleanApply after review
--forcebooleanApply despite high-severity findings or library edits since import

Also takes the global options --json and --actor (CLI overview).

What it does

  1. Re-fetches the recorded source: the same URL, ref and path (a local directory if the recorded source is a path that exists).
  2. If the source matches the library's latest revision: current, nothing to do.
  3. If the library copy was edited since the last import (its latest revision isn't the one recorded at import), refuses with CONFLICT unless --force, so your edits aren't clobbered.
  4. Diffs the library's latest revision against the source and audits the source.
  5. Without --yes: prints the review (review).
  6. With --yes: blocked on high-severity findings unless --force; otherwise replaces the library copy, records a new revision (source import) and the new commit (imported).

Agents may run the review, but applying a git source with --yes fails with NOT_ALLOWED unless allowAgentImports is set.

Examples

terminal
shelf pull release-notes
release-notes: changes available — nothing applied. Re-run with --yes to apply
--- a/SKILL.md
+++ b/SKILL.md
@@ -3,4 +3,5 @@
 description: Draft release notes from merged pull requests, grouped by user impact. Use when preparing a release.
 ---
 
 - Group by user impact
+- Link each item to its pull request
Audit:
  no findings

shelf pull release-notes --yes
release-notes updated to 3547e8b373. Run `shelf propagate release-notes` to update borrowers
--- a/SKILL.md
…

shelf pull release-notes
release-notes is up to date with /home/me/upstream

JSON output

json
{"schemaVersion":1,"ok":true,"data":{"skill":"release-notes","source":"/home/me/upstream","commit":null,"diff":[{"path":"SKILL.md","status":"modified","patch":"--- a/SKILL.md\n+++ b/SKILL.md\n@@ -3,4 +3,5 @@\n description: Draft release notes from merged pull requests, grouped by user impact. Use when preparing a release.\n ---\n \n - Group by user impact\n+- Link each item to its pull request\n"}],"findings":[],"revision":"sha256:ddc0bd2a5a8d49842f24450c3c8cd13b8be8d8523127a6543aa7a39ad4dd9eec","status":"review"}}
FieldMeaning
statuscurrent, review, blocked or imported.
sourceThe recorded source.
commitThe fetched commit for git sources, null for directories.
diff[]Library latest → source.
findings[]The fresh audit.
revisionThe library's revision before the pull, or the new one when imported.

Errors

CodeWhen
SKILL_NOT_FOUNDNo skill by that name in the library.
INVALID_ARGUMENTThe skill has no source (it wasn't added or linked with shelf add), or fetching failed.
CONFLICTThe library copy was edited since the last import, and --force wasn't given.
INVALID_SKILLThe source no longer holds a valid skill at the recorded path.
NOT_ALLOWEDAn agent tried to apply a git source with --yes.
terminal
shelf pull pdf-tools
error: "pdf-tools" was not imported with `shelf add`; it has no source to pull from