Skip to main content
The Shelv OpenClaw skill lets your agent convert PDFs into structured Markdown filesystems and hydrate them directly into the OpenClaw workspace. Once hydrated, your agent explores the output with standard Unix tools — ls, cat, grep, find.

​
Setup

  1. Get an API key — see Authentication
  2. Set the SHELV_API_KEY environment variable in your OpenClaw config:
export SHELV_API_KEY="sk_..."
The skill requires SHELV_API_KEY to be set before running any commands.

​
Workflows

The skill provides three shell scripts that your agent calls in sequence:

​
1. Upload a document

SHELF_ID=$(shelv-upload.sh /path/to/document.pdf --name "My Document")
Options:
  • --name — display name for the shelf
  • --template book|legal-contract|charter-party|academic-paper — structuring template (auto-detected if omitted)
  • --review — pause at review status before finalizing
  • --wait — block until processing completes

​
2. Poll for completion

shelv-poll-status.sh $SHELF_ID
Polls GET /v1/shelves/{id} every 5 seconds. Exits 0 on ready or review, exits 1 on failed or timeout (10 minutes). Processing flow: uploading → parsing → structuring → verifying → ready

​
3. Hydrate into workspace

shelv-hydrate.sh $SHELF_ID
Downloads the archive, verifies the checksum, and extracts files to: 
~/.openclaw/workspace/shelves/<name>/
Options:
  • --name — override the directory name
  • --force — replace an existing shelf directory
After hydration, explore with standard tools: 
ls ~/.openclaw/workspace/shelves/my-contract/
cat ~/.openclaw/workspace/shelves/my-contract/README.md
grep -r "force majeure" ~/.openclaw/workspace/shelves/my-contract/

​
Quick example

Give your agent a prompt like: 
Upload contract.pdf, wait for it to process, then hydrate it into my
workspace so I can search through the clauses.
The agent will:
  1. Upload the PDF to Shelv
  2. Poll until processing completes
  3. Download and extract the structured Markdown
  4. Use find, cat, and grep to explore the result

​
Requirements

  • curl, tar, jq, and shasum (or sha256sum) must be available
  • macOS or Linux

​
Templates

TemplateDescription
bookChapters, sections, and subsections
legal-contractArticles, clauses, definitions, and appendices
charter-partyPart I terms, clauses, riders, and annexes
academic-paperAbstract, sections, references, and figures
Omit the --template flag to let Shelv auto-detect the document structure.