shelf Docs

shelf promote

Publishes this project's edits to a borrowed skill back to the library as a new revision. With --propagate, it then updates every other project that borrows the skill, skipping copies with their own edits.

On this page 
shelf promote <skill> [options]
ArgumentDescription
<skill>Skill name
OptionTypeDefaultDescription
--forcebooleanReplace the library revision even if it changed since borrowing
--propagatebooleanThen update every other project borrowing it (skips local edits)

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

What it does

  1. Checks the loan is modified (or diverged with --force) and that every edited copy has the same content.
  2. Validates the edited SKILL.md.
  3. Replaces the library copy with the edited copy and records it as a new revision with source promote.
  4. Rewrites every copy in this project from that revision, so the loan is current again.
  5. With --propagate, runs shelf propagate for the skill.

--force replaces the library's revision even if the library changed since this project borrowed (diverged). The library's newer revision stays in the history, so shelf restore can bring it back.

Review the edits with shelf diff <name> first.

Examples

terminal
shelf promote pdf-tools
Promoted pdf-tools: library ddad27dd34 → d4deea4b55

shelf promote api-design --propagate
Promoted api-design: library e09cc9a0ed → d74c95b92c
api-design → d74c95b92c
  billing-api: updated
  storefront: already current

JSON output

json
{"schemaVersion":1,"ok":true,"data":{"skill":"api-design","previousRevision":"sha256:d74c95b92cffd891a2c5de8a17c11ae8ed067d403dd8993f5c24e94625d29904","revision":"sha256:94dfa1e44815a035ea8d774521be869e9e42594866dbaa7a037058fdf5410753","propagation":null}}

propagation is null without --propagate, otherwise the shelf propagate result.

Errors

CodeWhen
NOT_INITIALIZEDNot inside a shelf project.
NOT_BORROWEDThe project doesn't borrow the skill.
INVALID_ARGUMENTThe copy has no local edits (current or behind).
CONFLICTCopies are missing (run shelf sync); the library changed since borrowing (--force to replace it); or the copies in different targets were edited differently (make them identical).
INVALID_SKILLThe edited SKILL.md isn't a valid skill.
terminal
shelf promote api-design --json
{"schemaVersion":1,"ok":false,"error":{"code":"INVALID_ARGUMENT","message":"The project copy of \"api-design\" has no local edits to promote","hint":null}}