CLI

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

uv 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"

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

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

Upload multiple files:

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)

from raysurfer_cli.client import AsyncRaysurferClient

async with AsyncRaysurferClient() as client:
    result = await 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

Get Started

Integrations

SDK Reference

Enterprise

Rate Limits & Pricing

Installation

Setup

Commands

Search

Upload

Vote

Patterns

Examples

Version

Python Library

Configuration

​Installation

​Setup

​Commands

​Search

​Upload

​Vote

​Patterns

​Examples

​Version

​Python Library

​Configuration

Installation

Setup

Commands

Search

Upload

Vote

Patterns

Examples

Version

Python Library

Configuration