# Shelfdb Usage > Use ShelfDB correctly in this repository when writing code, tests, docs, examples, or answering questions about ShelfDB usage. Trigger this skill when work involves starting the ShelfDB server, using the async remote client, using the local direct DB API, choosing between local and remote access, or pointing users to the right ShelfDB docs and examples. Use when this capability is needed. - Skill: `tomevault-io/shelfdb-usage` (Agent Skill, multi-file: 2 files) - Install (CLI): `npx skillmds@latest add tomevault-io/shelfdb-usage` - Raw SKILL.md: https://api.skillmd.com/api/skills/tomevault-io/shelfdb-usage/raw - Safety review: pending (external: skill-scanner PASS, skillspector PASS) - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Integrations & APIs - Author: tomevault-io (https://skillmd.com/u/tomevault-io) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/tomevault-io/shelfdb-usage --- # ShelfDB usage Use ShelfDB in one of two modes: - **Remote client/server**: start `shelfdb server`, connect with `shelfdb.client.Client`, open async transactions, and end remote reads or writes with `await ...query()`. - **Local direct DB**: open `shelfdb.shelf.DB(...)`, use local transactions, and run queries directly without `.query()`. ## Core rules - Prefer the **remote client** flow for application code and flexible deployment. - Use **local DB access** only when the process can open the database directly. - For remote usage, remember: builder methods do nothing until `await .query()`. - For local usage, do not add `.query()`; local operations run directly. - Use `client.transaction()` for reads and `client.transaction(write=True)` for mutations. - Close remote clients with `await client.close()`. - Start the server with `shelfdb server`; default URL is `tcp://127.0.0.1:31337` and default DB path is `db`. ## Read the bundled docs for details Read the skill-local docs under `ai-skill/shelfdb-usage/docs/` as needed: - `docs/index.md` — overview, fit, and navigation - `docs/usage/installation.md` — install and CLI verification - `docs/usage/server.md` — server startup and URL formats - `docs/usage/remote.md` — async client usage and `.query()` behavior - `docs/usage/local.md` — direct local DB usage - `docs/api/index.md` — API reference index - `docs/api/client.md` — remote client API - `docs/api/local.md` — local DB API - `docs/api/cli.md` — CLI reference ## Practical guidance - If the user asks for app code that talks to a running ShelfDB instance, use the remote client API. - If the user asks for simple in-process storage examples, use `DB(...)` and local transactions. - If the user is confused about why nothing happens remotely, check whether `.query()` is missing. - If the user needs a server command example, prefer `shelfdb server --db-path ./db --url tcp://127.0.0.1:31337` unless they need a Unix socket. --- > Source: [keenlycode/shelfdb](https://github.com/keenlycode/shelfdb) — distributed by [TomeVault](https://tomevault.io).