📝 HIVE.yaml Format

The HIVE.yaml file is the heart of every Beepack package. It describes your API and enables AIs to discover it.

Complete Example

name: notion-sync
version: 1.2.0
description: Bidirectional sync with Notion API
author: guillaume
license: MIT

# For discovery
keywords:
  - notion
  - sync
  - database
  - productivity

# What the API does (for AIs)
capabilities:
  - read_database
  - write_pages
  - search_content
  - sync_bidirectional

# Required dependencies
requires:
  env:
    - NOTION_API_KEY
  deps:
    - node >= 18

# Compatible runtimes
compatible:
  - cursor
  - copilot
  - claude
  - openclaw
  - windsurf

# Optional metadata
homepage: https://github.com/guillaume/notion-sync
repository: https://github.com/guillaume/notion-sync
bugs: https://github.com/guillaume/notion-sync/issues

# Test configuration
tests:
  command: npm test
  coverage_min: 70

Field Reference

Required Fields

Discovery Fields

Dependency Fields

requires:
  # Required environment variables
  env:
    - API_KEY
    - SECRET_TOKEN
  
  # System dependencies
  deps:
    - node >= 18
    - python >= 3.10
  
  # Required binaries
  bins:
    - curl
    - jq

Metadata Fields

Best Practices

✅ Do

• Use descriptive, actionable capabilities
• Document ALL required environment variables
• Include a detailed README.md
• Add usage examples

❌ Don't

• Generic names (api, helper)
• Vague capabilities (do_stuff)
• Forget to declare dependencies
• Hardcode secrets (use requires.env)