broomva Prompt Library
Manage versioned, parameterized prompts stored in a database and distributed via a JSON API.
Quick Start
Pull a prompt
python3 scripts/prompt-sync.py pull code-review-agent
List available prompts
python3 scripts/prompt-sync.py list
Pull with variable substitution
python3 scripts/prompt-sync.py pull code-review-agent --var language=python --var strictness=strict
Push a prompt remotely (over the air)
python3 scripts/prompt-sync.py remote-push \
--title "My Prompt" \
--category system-prompts \
--body "You are a helpful assistant..." \
--tags "tag1,tag2" \
--token "$BROOMVA_API_TOKEN"
Commands
Read Commands
| Command | Description |
|---|---|
list |
List all prompts (supports --category, --tag, --model filters) |
pull <slug> |
Fetch a prompt by slug, print raw content |
Local Write Commands
| Command | Description |
|---|---|
push |
Write a new prompt MDX file to local content/prompts/ |
update <slug> |
Update an existing local prompt, optionally bump version |
Remote Write Commands (API-based)
| Command | Description |
|---|---|
remote-push |
Create a prompt via the remote API (requires auth token) |
remote-update <slug> |
Update a prompt remotely (owner or admin only) |
remote-delete <slug> |
Soft-delete a prompt remotely (owner or admin only) |
All commands accept --endpoint URL to target a different prompt repository. Default: https://broomva.tech/api/prompts.
Authentication
Remote commands require an API token. Get yours by:
- Log in at broomva.tech via OAuth (Google/GitHub)
- Visit
https://broomva.tech/api/auth/api-tokento get your session token - Set it:
export BROOMVA_API_TOKEN="your-token-here"
Or pass --token directly to any remote command.
The token is your OAuth session token — it's user-scoped and auto-expires. No static API keys needed.
Admin Features
For the admin user (carlosdavidescobar@gmail.com), remote pushes and updates also:
- Commit the prompt as an MDX file to the GitHub repo
- Trigger a Vercel redeploy automatically
Prompt Schema
See references/prompt-schema.md for the full frontmatter specification.
Key fields:
category: system-prompts, agent-instructions, templates, chains, evaluatorsversion: Semver string for tracking prompt evolutionvariables: Declared template variables with{{name}}syntax and defaultsmodel: Target model (optional)tags: Searchable tag array
Category Taxonomy
See references/categories.md for the full taxonomy.
API Endpoints
| Method | Endpoint | Auth | Description |
|---|---|---|---|
GET |
/api/prompts |
Public | List prompts (DB + MDX fallback) |
POST |
/api/prompts |
Required | Create a new prompt |
GET |
/api/prompts/[slug] |
Public | Get prompt by slug |
PUT |
/api/prompts/[slug] |
Owner/Admin | Update a prompt |
DELETE |
/api/prompts/[slug] |
Owner/Admin | Soft-delete a prompt |
GET |
/api/auth/api-token |
Session | Get your bearer token |
For Other Repositories
Anyone can host their own prompt library:
- Create a database table for prompts (or use
content/prompts/with.mdxfiles) - Add the API routes:
GET /api/prompts,GET /api/prompts/[slug],POST /api/prompts - Use
--endpoint https://your-site.com/api/promptswith the sync script
The schema and API contract are the standard. The endpoint is configurable.