shelf status · shelf docs

shelf status

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

What it does

Opens the project: registers it if this machine hasn't seen it (a fresh clone), follows it if its directory moved, and creates loans for lockfile entries this machine has no loan for.
Returns every overdue loan whose copies have no local edits (deletes the copies, closes the loan).
Reports every remaining loan and derives next steps.

Outside a project it reports initialized: false and suggests nothing to agents. Leave such projects alone unless the user asks to start using shelf there.

Examples

terminal

$ shelf status
docs-site  /home/me/code/docs-site

SKILL          CONTENT   DUE                     USED     POLICY  REVISION
pdf-tools      modified  2026-10-03  4d overdue  34d ago  pinned  15c6167210
release-notes  current   2026-11-06  30d left    today    pinned  0b01b7e535

Next steps:
  shelf promote pdf-tools
      pdf-tools has local edits. Promote them to the library, keep them unmanaged with `shelf detach pdf-tools`, or discard them with `shelf update pdf-tools --force`
  shelf detach pdf-tools
      pdf-tools is overdue but was not returned because it has local edits. Promote or detach it

Column	Meaning
SKILL	The skill name.
CONTENT	`current`, `behind`, `modified`, `diverged` or `missing` (see Concepts).
DUE	The due date and days left (`30d left`, `due today`, `4d overdue`), or `kept`.
USED	Last recorded use in this project: `today`, `27d ago` or `never`.
POLICY	`pinned` or `follow`.
REVISION	The first 10 hex characters of the revision the project holds.

When it returned overdue loans, it says so:

terminal

$ shelf status
storefront  /home/me/code/storefront

SKILL       CONTENT  DUE                   USED   POLICY  REVISION
api-design  current  2026-12-08  63d left  never  pinned  e09cc9a0ed

Returned overdue: pdf-tools

Outside a project:

terminal

$ shelf status
/home/me/code/storefront does not use shelf yet. Run `shelf init` to start.

With no loans it prints No skills borrowed. Find some with `shelf catalog`. Warnings (invalid library skills, lockfile entries for skills this machine's library doesn't have) follow as warning: … lines.

Next steps

Loan	Command	Reason given
`missing`	`shelf sync`	Copies are missing; sync restores them.
`diverged`	`shelf show <name>`	Edited here and in the library: review, then `promote --force` or `update --force`.
`modified`	`shelf promote <name>`	Local edits: promote, detach, or `update --force`.
`behind`, pinned	`shelf update <name>`	The library has a newer revision.
`behind`, follow	`shelf sync`	The library has a newer revision.
overdue, unedited	`shelf sync`	Overdue; sync returns it.
overdue, edited	`shelf detach <name>`	Not returned because of local edits: promote or detach.
`due-soon`	`shelf renew <name> --reason "<why>"`	Unused and due in N days: renew, or `shelf return <name>`.

Actions are deduplicated by command (several behind follow loans give one shelf sync). Commands are runnable as-is except the <why> placeholder.

JSON output

json

{"schemaVersion":1,"ok":true,"data":{"initialized":true,"project":{"id":"4a0c83eb-468d-4cbb-a855-aa9865ca78fb","name":"mobile-app","path":"/home/me/code/mobile-app"},"loans":[{"skill":"react-best-practices","content":"behind","due":"active","dueAt":"2026-11-06T05:51:38.410Z","daysLeft":30,"lastUsedAt":null,"kept":false,"loanDays":30,"policy":"pinned","revision":"sha256:b1ee5d63864a272cee0f8565dd80dfdb80ef4a14c37a8a6b129efdb350a7a348","latestRevision":"sha256:3a1a31ace69218263c958abae2eb5b6e68958d495a00a089b5f9efb743a7b182","targets":[".agents/skills",".claude/skills"]}],"expired":[],"actions":[{"command":"shelf update react-best-practices","reason":"The library has a newer revision of react-best-practices"}],"warnings":[]}}

Outside a project:

json

{"schemaVersion":1,"ok":true,"data":{"initialized":false,"root":"/home/me/code/storefront","actions":[]}}

Field	Meaning
`initialized`	`false` outside a shelf project; then only `root` and `actions` (always empty) follow.
`project`	`id`, `name`, `path`.
`loans[].skill`	Skill name.
`loans[].content`	`current`, `behind`, `modified`, `diverged` or `missing`.
`loans[].due`	`active`, `due-soon` or `overdue`. Always `active` when kept.
`loans[].dueAt`	The due date.
`loans[].daysLeft`	Whole days until the due date, rounded up; negative when overdue.
`loans[].lastUsedAt`	Last recorded use, or `null`.
`loans[].kept`	Whether the loan never expires.
`loans[].loanDays`	The skill's loan length: how far a use or renewal moves the due date.
`loans[].policy`	`pinned` or `follow`.
`loans[].revision`	The revision the project holds.
`loans[].latestRevision`	The library's latest revision.
`loans[].targets`	Directories the skill is copied into.
`expired`	Skills this call returned.
`actions[]`	`{ command, reason }`, most urgent first.
`warnings`	Strings.

Errors

Code	When
`CONFLICT`	The lockfile isn't valid JSON or doesn't match the schema.
`INVALID_ARGUMENT`	The config file is invalid.

shelf sync does the same reconciliation without the report.
shelf projects gives counts for every project without changing anything.
Agents

What it does

Examples

Next steps

JSON output

Errors

Related