For AI agents: the documentation index is at /llms.txt, and any docs page is available as Markdown by appending .md to its URL.
CLI
Every Shelf command, its options, and shelf.config.json.
Install @shelfui/cli as a dev dependency, then run shelf through your package manager, such as npx shelf add button. Every command takes --cwd <dir> and --help, and none of them prompt. search, status, check and diff take --json for machine-readable output.
Commands
init --registry <location>: Create shelf.config.json and .shelf/, copy path aliases from tsconfig.json, and write agent instructions (an AGENTS.md block and a skill).--no-agentsskips the agent files.search [query...]: List registry items that match every term.--registrysearches another registry than the configured one, and works before init.add <items...>: Copy items and the Shelf items they build on, install their packages, and record provenance. Keeps files you changed, and merges Shelf's changes into them when both changed.status [items...]: List installed items, which ones you changed, and which have a newer version. Read-only. With--jsonit also reports the project: package manager, registry, paths, and aliases.diff <item> [--local]: Show what an update would bring, as a unified diff from what you installed.--localshows your changes instead.update [items...]: Update every item with a newer version, or the ones named, merging Shelf's changes into files you changed. Takes the same options as add.check [--only <steps>]: Check that installed files, their Shelf and package dependencies, and their imports are intact, and list what you changed. Exits 1 on failure. Each step lists its first 30 details;--verboselists them all.docs [topic]: Print documentation as markdown for a topic such asinstallation,ownership,clioragents, or for a component such asbutton. With no topic, list what is available. It reads the registry, so it matches the version you install.usage [dirs...]: Show where installed items are used: which each project imports, which are out of date or changed, and which come through a shared package.--repoadds other repositories,--githubadds every Shelf repository in a GitHub organization, and--jsonwrites the graph.build [dir] --out <dir>: Validate a registry and write the files that install, every revision in its git history, and the Shelf Registry site, for static hosting.--storybookand--usageadd previews and usage;--no-siteleaves the site out.serve [dir] --port <port>: Serve a registry directory on 127.0.0.1.
JSON output
--json prints one JSON object to stdout and nothing else. Exit codes do not change: 0 on success, 1 when a check fails or a command cannot finish.
Every check issue names the problem and, when Shelf knows it, the command that fixes it. status --json leaves out registry request headers, which can hold a token. Errors still go to stderr as one line, with exit code 1.
Options for init
--header <header>: A request header for a private http(s) registry, such as'Authorization: Bearer ${SHELF_REGISTRY_TOKEN}'. Repeatable. Quote it so the variable is written as-is and expanded only when Shelf makes a request.--no-agents: Do not write the AGENTS.md block or the agent skill.
Options for add and update
--overwrite: Replace locally modified files, or files Shelf didn't install, with the registry's version instead of merging.--skip-install: Copy files and record provenance, but leave package installs to you.
Configuration
registry: A directory, relative to this file, or an http(s) URL. For a private registry, an object with url and headers.paths: Where each kind of item is copied, relative to the project.aliases: Optional, in the same form as compilerOptions.paths. Without it, imports between installed files are relative.$schema: Autocomplete and validation in your editor. Unknown keys are an error, so typos don't pass silently.
Hosting a registry
build checks every item the way add reads it, including that its imports resolve, and leaves out stories and tests. Upload the output to any static host and point registry at its URL.
It also writes revisions/, one snapshot for every revision the items have had in git, and never deletes it. That is how a product gets back the exact files it installed. Build from a full clone; a shallow one only has current revisions, and build says so. See ownership and provenance.