Documentation Index
Fetch the complete documentation index at: https://docs.raysurfer.com/llms.txt
Use this file to discover all available pages before exploring further.
The Raysurfer CLI (raysurfer) is a standalone Python tool for interacting with the code cache. Use it in scripts, CI pipelines, or directly from your terminal.
Installation
pip install raysurfer-code-caching-cli
Setup
export RAYSURFER_API_KEY=your_key_here
Commands
Search
Find cached code matching a task description:
raysurfer search "Generate a quarterly revenue report"
raysurfer search "Generate a quarterly revenue report" --show-code
raysurfer search "Generate a quarterly revenue report" --json
raysurfer search "Generate a quarterly revenue report" --public
| Flag | Description | Default |
|---|
--top-k, -k | Maximum results | 5 |
--min-score, -s | Minimum verdict score (0-1) | 0.3 |
--public, -p | Include community public snippets | off |
--show-code, -c | Display source from top match | off |
--json, -j | Output as JSON | off |
Upload
Upload code files to the cache after a successful execution:
raysurfer upload "Generate a quarterly revenue report" --file report.py
raysurfer upload "Build a dashboard" --file app.py --file utils.py
| Flag | Description | Default |
|---|
--file, -f | File to upload (repeatable) | required |
--succeeded/--failed | Whether the execution succeeded | succeeded |
--no-auto-vote | Disable automatic upvote on upload | off |
Vote
Provide feedback on cached code quality:
# Upvote
raysurfer vote cb_abc123 --up
# Downvote
raysurfer vote cb_abc123 --down
| Flag | Description | Default |
|---|
--up/--down | Upvote or downvote | up |
--task, -t | Original task description | none |
Patterns
Get proven task-to-code mappings:
raysurfer patterns "data analysis"
Examples
Get few-shot examples for prompting:
raysurfer examples "data analysis"
Version
raysurfer version
raysurfer version --json
Python Library
The CLI also exports sync and async clients for use in your own code:
from raysurfer_cli.client import RaysurferClient
with RaysurferClient() as client:
result = client.search(task="Generate a quarterly report")
for match in result.matches:
print(match.code_block.name, match.combined_score)
Configuration
| Environment Variable | Description | Default |
|---|
RAYSURFER_API_KEY | API key (required) | none |
RAYSURFER_BASE_URL | API base URL | https://api.raysurfer.com |
RAYSURFER_TIMEOUT | Request timeout in seconds | 30 |
