Skip to main content
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.
Source: rayxc-org/raysurfer-code-caching-cli

​
Installation

pip install raysurfer-code-caching-cli

​
Setup

export RAYSURFER_API_KEY=your_key_here

​
Commands

Find cached code matching a task description: 
raysurfer search "Generate a quarterly revenue report"
Show the source code from the top match: 
raysurfer search "Generate a quarterly revenue report" --show-code
Get JSON output for scripting: 
raysurfer search "Generate a quarterly revenue report" --json
Include community public snippets in results: 
raysurfer search "Generate a quarterly revenue report" --public
FlagDescriptionDefault
--top-k, -kMaximum results5
--min-score, -sMinimum verdict score (0-1)0.3
--public, -pInclude community public snippetsoff
--show-code, -cDisplay source from top matchoff
--json, -jOutput as JSONoff

​
Upload

Upload code files to the cache after a successful execution: 
raysurfer upload "Generate a quarterly revenue report" --file report.py
Upload multiple files: 
raysurfer upload "Build a dashboard" --file app.py --file utils.py
FlagDescriptionDefault
--file, -fFile to upload (repeatable)required
--succeeded/--failedWhether the execution succeededsucceeded
--no-auto-voteDisable automatic upvote on uploadoff

​
Vote

Provide feedback on cached code quality: 
# Upvote
raysurfer vote cb_abc123 --up

# Downvote
raysurfer vote cb_abc123 --down
FlagDescriptionDefault
--up/--downUpvote or downvoteup
--task, -tOriginal task descriptionnone

​
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 VariableDescriptionDefault
RAYSURFER_API_KEYAPI key (required)none
RAYSURFER_BASE_URLAPI base URLhttps://api.raysurfer.com
RAYSURFER_TIMEOUTRequest timeout in seconds30