Skip to main content
The beacon validate command validates an AGENTS.md file against the expected schema and structure. Optionally, it can also check if declared endpoints are reachable.

​
Usage

beacon validate <file> [OPTIONS]

​
Arguments

​
file
string
required
The path to the AGENTS.md file to validate.Examples:
  • ./AGENTS.md
  • docs/AGENTS.md
  • /path/to/AGENTS.md

​
Options

​
--check-endpoints
boolean
default:"false"
When enabled, Beacon will attempt to reach all declared endpoints in the AGENTS.md file to verify they’re accessible.Note: This makes actual HTTP requests to the endpoints, so use with caution on production systems.Example:
beacon validate ./AGENTS.md --check-endpoints
​
--provider
string
Optional AI provider for enhanced validation. Currently only beacon-ai-cloud is supported for this option.Example:
beacon validate ./AGENTS.md --provider beacon-ai-cloud

​
Validation Rules

Beacon checks for the following schema requirements:

​
Errors (Must Fix)

  • Missing top-level heading - File must have a # AGENTS.md or similar # heading
  • Missing Capabilities section - File must contain a ## Capabilities section
  • No description blockquote - Recommended to have a > description at the top
  • Empty capabilities - The Capabilities section should declare at least one capability
  • Endpoint missing HTTP method - Endpoints should specify a valid HTTP method (GET, POST, PUT, DELETE, PATCH)
  • Missing generator footer - Should include a “Generated by” footer

​
Examples

​
Basic validation

beacon validate ./AGENTS.md
Output for valid file: 
⬛ Beacon — validating ./AGENTS.md...
   ✅ Schema valid

📋 Validation Report
   Valid:    ✅ Yes
   Errors:   0
   Warnings: 0
Output for invalid file: 
⬜ Beacon — validating ./AGENTS.md...
   ❌ 2 error(s) found
   ⚠️  1 warning(s)

📋 Validation Report
   Valid:    ❌ No
   Errors:   2
   Warnings: 1

❌ Errors:
   • Missing top-level # heading
   • Missing ## Capabilities section

⚠️  Warnings:
   • Missing generator footer

​
Validate with endpoint checks

beacon validate ./AGENTS.md --check-endpoints
Output: 
⬛ Beacon — validating ./AGENTS.md...
   ✅ Schema valid
   🌐 Checking endpoint reachability...
   🔍 Checking: GET https://api.example.com/health
   ✅ https://api.example.com/health → 200
   🔍 Checking: POST https://api.example.com/generate
   ✅ https://api.example.com/generate → 200

📋 Validation Report
   Valid:    ✅ Yes
   Errors:   0
   Warnings: 0

🌐 Endpoint Results:
   ✅ GET /health (200)
   ✅ POST /generate (200)

​
Validate with unreachable endpoint

beacon validate ./AGENTS.md --check-endpoints
Output: 
⬛ Beacon — validating ./AGENTS.md...
   ✅ Schema valid
   🌐 Checking endpoint reachability...
   🔍 Checking: GET https://api.example.com/missing
   ❌ https://api.example.com/missing → error sending request for url...

📋 Validation Report
   Valid:    ✅ Yes
   Errors:   0
   Warnings: 0

🌐 Endpoint Results:
   ❌ GET /missing (—)

​
Use Beacon Cloud validation

beacon validate ./AGENTS.md --provider beacon-ai-cloud
This will use Beacon’s cloud service for enhanced AI-powered validation. Payment may be required.

​
Endpoint Checking Details

When --check-endpoints is enabled:
  1. Base URL extraction - Beacon looks for a base URL in the AGENTS.md file (typically in the Endpoints section)
  2. Endpoint parsing - Extracts all endpoint declarations in the format ### \METHOD /path“
  3. HTTP requests - Makes actual HTTP requests with a 5-second timeout
  4. Status evaluation - Considers endpoints reachable if response status < 500
Supported HTTP methods:
  • GET
  • POST
  • PUT
  • DELETE
  • PATCH

​
Exit Codes

  • 0 - Validation successful (file is valid)
  • 1 - Validation failed or file not found

​
Source Code Reference

The validate command implementation can be found in:
  • Command definition: /home/daytona/workspace/source/src/main.rs:63-69
  • Execution logic: /home/daytona/workspace/source/src/main.rs:396-446
  • Validator: /home/daytona/workspace/source/src/validator.rs:104-173
  • Endpoint checking: /home/daytona/workspace/source/src/validator.rs:175-247
  • generate - Generate AGENTS.md files from repositories
  • serve - Run validation via web API

Build docs developers (and LLMs) love

Get started for freeTalk to us