> ## Documentation Index
> Fetch the complete documentation index at: https://docs.shelv.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# OpenClaw Skill

> Use Shelv as an OpenClaw skill to upload PDFs, poll for processing, and hydrate structured Markdown into your agent's workspace.

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](/guides/authentication#get-an-api-key)
2. Set the `SHELV_API_KEY` environment variable in your OpenClaw config:

```bash theme={"theme":{"light":"github-light","dark":"poimandres"}}
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

```bash theme={"theme":{"light":"github-light","dark":"poimandres"}}
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

```bash theme={"theme":{"light":"github-light","dark":"poimandres"}}
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

```bash theme={"theme":{"light":"github-light","dark":"poimandres"}}
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:

```bash theme={"theme":{"light":"github-light","dark":"poimandres"}}
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

| Template         | Description                                    |
| ---------------- | ---------------------------------------------- |
| `book`           | Chapters, sections, and subsections            |
| `legal-contract` | Articles, clauses, definitions, and appendices |
| `charter-party`  | Part I terms, clauses, riders, and annexes     |
| `academic-paper` | Abstract, sections, references, and figures    |

Omit the `--template` flag to let Shelv auto-detect the document structure.