Skip to main content
The beacon generate command scans a local repository or GitHub URL, analyzes its structure and code, and generates a standards-compliant AGENTS.md file that describes the repository’s agent-usable capabilities.

​
Usage

beacon generate <target> [OPTIONS]

​
Arguments

​
target
string
required
The path to the local repository or a GitHub URL to scan.Examples:
  • ./my-project
  • /home/user/repositories/my-app
  • https://github.com/user/repo

​
Options

​
--output
string
default:"AGENTS.md"
The file path where the generated AGENTS.md file should be written.Short form: -oExample:
beacon generate ./my-app --output docs/AGENTS.md
​
--provider
string
default:"gemini"
The AI provider to use for inferring repository capabilities.Supported providers:
  • gemini - Google’s Gemini (default)
  • claude - Anthropic’s Claude
  • openai - OpenAI’s GPT models
  • beacon-ai-cloud - Beacon’s managed cloud service (requires payment)
Example:
beacon generate ./my-app --provider openai
​
--api-key
string
API key for the chosen AI provider. If not provided, Beacon will look for the corresponding environment variable.Environment variables by provider:
  • GEMINI_API_KEY for gemini
  • CLAUDE_API_KEY for claude
  • OPENAI_API_KEY for openai
Example:
beacon generate ./my-app --provider openai --api-key sk-...

​
How It Works

  1. Scanning - Beacon walks through the repository and collects:
    • README files
    • Package manifests (Cargo.toml, package.json, pyproject.toml, go.mod)
    • OpenAPI/Swagger specifications
    • Source code files (up to 50 files, max 50KB each)
    • Existing AGENTS.md files
  2. Skipped files/directories:
    • target, node_modules, .git, .github, dist, build
    • __pycache__, .venv, venv
    • .DS_Store, Thumbs.db, *.lock, *.sum
    • Hidden directories (starting with .)
  3. AI Inference - The collected context is sent to the selected AI provider to infer:
    • Agent-usable capabilities
    • API endpoints and their schemas
    • Authentication requirements
    • Rate limits
  4. Generation - A standards-compliant AGENTS.md file is written to the specified output path.

​
Examples

​
Basic usage with local repository

beacon generate ./my-project
Output: 
⬛ Beacon — scanning ./my-project...
   📁 Scanning: /home/user/my-project
   ✓ README found
   ✓ Package manifest found: package.json
   ✓ Scan complete — 12 source files collected
📦 Repo: my-project (12 source files)

✅ Done! AGENTS.md written to: AGENTS.md
   Provider:     gemini
   Capabilities: 3
   Endpoints:    5

​
Generate with custom output path

beacon generate ./my-app --output documentation/AGENTS.md

​
Use OpenAI provider with API key

beacon generate https://github.com/user/repo --provider openai --api-key sk-proj-...

​
Use Claude provider with environment variable

export CLAUDE_API_KEY=sk-ant-...
beacon generate ./my-app --provider claude

​
Use Beacon Cloud (managed service)

beacon generate ./my-app --provider beacon-ai-cloud
Note: Beacon Cloud requires payment (default: 0.09 USDC) on Base or Solana. The command will prompt you for payment details if needed.

​
Source Code Reference

The generate command implementation can be found in:
  • Command definition: /home/daytona/workspace/source/src/main.rs:54-62
  • Execution logic: /home/daytona/workspace/source/src/main.rs:380-395
  • Scanner: /home/daytona/workspace/source/src/scanner.rs:21-113
  • validate - Validate generated AGENTS.md files
  • serve - Run Beacon as a web API service

Build docs developers (and LLMs) love

Get started for freeTalk to us