rayvise-cli

Open-source ultra-fast AI completions right in your terminal.

A lightning fast Go CLI for generating meta-prompts and AI completions quickly via OpenRouter, with fast model routing, configurable output lengths, customizable prompts, and an interactive mode.

• Responses in Milliseconds: Generate text completions in ~100-900ms using open-source models running on Cerebras chips.
• Interactive Mode: Run rayvise in interactive mode with streaming output and slash commands
• Project Context Awareness: Automatically loads context from CLAUDE.md, AGENTS.md, or .cursor/rules/ files to inform prompt generation
• Custom Prompts: Create and use your own prompts
• Flexible Configuration: Configure via YAML, environment variables, or CLI flags
• OpenRouter Integration: Rayvise can be used with many different LLM providers and models through OpenRouter's API

Installation

Using Homebrew (macOS)

brew install --cask rayvise/tap/rayvise

Using Go Install

go install github.com/rayvise/rayvise-cli@latest

From Source

git clone https://github.com/rayvise/rayvise-cli.git
cd rayvise-cli
./build

Or instead of ./build run manually:

go build -o rayvise
sudo mv rayvise /usr/local/bin/

---

Quick Start

1. Get an OpenRouter API key from openrouter.ai/keys

   1a. (Recommended): Get a Cerebras key from cerebras.ai to set up in OpenRouter > Settings > BYOK (bring your own key) > Cerebras API key.

2. Set your API key for Rayvise (choose one method):

   Option A: Config Command (Recommended)

   rayvise config set api-key <your_api_key_here>

   Option B: Environment Variable

   export RAYVISE_API_KEY=your_api_key_here

   To make it permanent, add to your shell config:

   # For zsh (macOS default)
   echo 'export RAYVISE_API_KEY=your_api_key_here' >> ~/.zshrc
   source ~/.zshrc
   
   # For bash
   echo 'export RAYVISE_API_KEY=your_api_key_here' >> ~/.bashrc
   source ~/.bashrc

   Option C: Config File

   mkdir -p ~/.rayvise
   cp config.yaml.example ~/.rayvise/config.yaml
   # Edit ~/.rayvise/config.yaml and add your API key
   nano ~/.rayvise/config.yaml

   Note: The .env file in the project directory is for reference only. Go programs don't automatically load .env files. You must either export the environment variable or use the config file at ~/.rayvise/config.yaml.

3. Generate your first prompt:

   rayvise "write a blog post about Go CLI projects for platforms like reddit and linkedin"
   # Default prompt is `metaprompt` which aims to assist in rewriting your input
   # as a better prompt to get better outputs

Usage

Instant Complete Mode

Generate an optimized prompt from your input in a single shot. You can invoke it directly without a subcommand:

# Basic Usage (Instant completions)
rayvise "update rayvise to support colors in generate and interactive CLI"

# With flags
rayvise "write a blog post about metaprompts" --length long

# From stdin
echo "my goal" | rayvise

# Specify model
rayvise "optimize this code" -m cerebras-gpt-oss-120b

Flags:

• -l, --length: Output length (short, medium, long) - default: medium
• -m, --model: Model alias or OpenRouter ID - default: cerebras-llama-8b
• -p, --prompt: Prompt template name - default: metaprompt
• --no-copy: Disable auto-copy to clipboard (copying is enabled by default)
• --config: Custom config file path

Config Command

Manage configuration settings via the CLI:

# Set values
rayvise config set api-key sk-or-v1-...
rayvise config set default-model cerebras-llama-8b
rayvise config set default-length short
rayvise config set disable-copy true
rayvise config set temperature 0.8

# Get current values
rayvise config get api-key
rayvise config get default-model
rayvise config get default-length

# Manage custom prompts
rayvise config prompt add my-prompt              # Add a new prompt interactively
rayvise config prompt list                      # List all prompts
rayvise config prompt show metaprompt           # Show prompt details
rayvise config prompt remove my-prompt          # Remove a custom prompt

Available config keys:

Key	Description	Type
api-key	OpenRouter API key	string
default-model	Default model alias or OpenRouter ID	string
default-length	Default output length: short, medium, or long	string
disable-copy	Disable auto-copy to clipboard	boolean
temperature	Sampling temperature (0.0 to 2.0)	float

Config prompt command:

The config prompt subcommand allows you to manage custom prompt templates programmatically:

Subcommand	Description	Example
add	Add a new custom prompt	rayvise config prompt add code-review
list	List all prompts (built-in + custom)	rayvise config prompt list
show	Show prompt details	rayvise config prompt show metaprompt
remove	Remove a custom prompt	rayvise config prompt remove my-prompt --force

Interactive Mode

Start an interactive session with streaming output:

rayvise interactive
# or
rayvise i

Note: Context does not persist between requests in interactive mode. Each message is a fresh, stateless request — the model has no memory of previous exchanges in the session.

Slash Commands:

• /clear - Clear the screen
• /length <short|medium|long> - Change output length
• /model <alias> - Switch model
• /prompt <name> - Switch prompt template
• /copy - Copy last response to clipboard
• /help - Show help
• /quit or /exit - Exit REPL

Keyboard Shortcuts:

• Ctrl+C - Cancel current generation
• Ctrl+D - Exit REPL

Check Version

Check the installed version of rayvise:

rayvise version
rayvise --version
rayvise -v

Configuration

Configuration Hierarchy

Configuration is loaded in the following order (later sources override earlier ones):

1. Default values
2. Config file (~/.rayvise/config.yaml)
3. Environment variables (RAYVISE_*)
4. CLI flags

Config Command

The easiest way to manage configuration is via the config command:

# Set your API key
rayvise config set api-key sk-or-v1-...

# Set default model
rayvise config set default-model cerebras-llama-8b

# Set default output length
rayvise config set default-length medium

# View current settings
rayvise config get api-key
rayvise config get default-model

See Config Command in the Usage section for all available options.

Models

Built-in Models

Alias	Model ID	Provider	Tier
cerebras-llama-8b	meta-llama/llama-3.1-8b-instruct	Cerebras	Fastest
cerebras-gpt-oss-120b	openai/gpt-oss-120b	Cerebras	Fast
openai-gpt5-nano	openai/gpt-5-nano	OpenAI	Fast

Using Custom Models

You can use any OpenRouter model by:

1. Direct model ID: Use the full OpenRouter model ID as the model flag

   rayvise "hello" -m "anthropic/claude-sonnet-4.6"

2. Custom alias: Define in config.yaml

   models:
     sonnet-4.6:
       id: "anthropic/claude-sonnet-4.6"
       provider: "anthropic"
       tier: "powerful"

   Then use: rayvise "hello" -m sonnet-4.6

Output Lengths

Output length controls both the desired response length and the max_tokens parameter:

Length	Max Tokens	Use Case
short	550	Quick, concise prompts (~150 words)
medium	850	Balanced detail (~200-350 words)
long	1600	Comprehensive prompts (400-600+ words)

The system prompt includes guidance for each length to ensure appropriate output.

Colored Output

rayvise automatically formats prompts with colored output:

• Markdown Detection: The CLI automatically detects when output appears to be markdown (based on syntax patterns like headers, lists, code blocks, etc.) and prepares it for potential syntax highlighting in future versions.

• Disabling Colors: Colors respect the NO_COLOR environment variable and terminal capabilities. To disable colors:

  NO_COLOR=1 rayvise "hello world"

Custom Prompt Templates

Built-in Prompts

rayvise includes the following built-in prompts:

Name	Description	Supported Lengths
metaprompt	Generate an optimized meta-prompt from a user's goal	short, medium, long
bulletlist	Organize text by relation and output as a short bulleted list	short, medium

Creating Your First Custom Prompt

Let's create an ASCII art prompt to get you started. This prompt will only support medium mode:

Interactive mode:

rayvise config prompt add ascii-art

This will guide you through entering the description, system prompt, and length directives interactively.

Non-interactive mode (for scripting):

rayvise config prompt add ascii-art \
  --description "Convert text into ASCII art/emoji representation" \
  --system "You are an ASCII art expert. Create creative ASCII art or emoji-based representations of the input text. CRITICAL: Output ONLY the ASCII art itself, no explanations or preamble." \
  --medium "400"

Try it out:

rayvise "coffee cup" -p ascii-art
rayvise "happy cat" -p ascii-art
rayvise "rocket ship" -p ascii-art

Managing Custom Prompts

List all prompts (built-in and custom):

rayvise config prompt list

Show prompt details:

rayvise config prompt show ascii-art

Remove a custom prompt:

rayvise config prompt remove ascii-art

Length Directives

Each length mode (short, medium, long) can have a directive that controls how much output the LLM produces. There are two types:

Token count — a plain integer sets the max_tokens API parameter directly. {{.LengthDirective}} in your system prompt is left empty.

length_directives:
  short: "200"
  medium: "600"
  long: "1500"

Text directive — a string is injected into {{.LengthDirective}} in your system prompt, giving the model natural-language guidance.

length_directives:
  short: "Be concise, 2-3 sentences max."
  medium: "Provide a balanced response with moderate detail."
  long: "Be thorough and comprehensive."

Both types can be mixed across lengths in the same prompt. When using token counts, omit {{.LengthDirective}} from your system prompt (or include it — it will render as empty). When using text directives, include {{.LengthDirective}} where you want the guidance injected.

Creating Custom Prompts

There are two ways to create custom prompts: interactively via the CLI or by creating YAML files directly in ~/.rayvise/prompts/.

Method 1: Using the CLI (Recommended)

Use the config prompt add command with interactive prompts:

rayvise config prompt add sql

The interactive flow will explain directive types and prompt you for each length. Or use flags for non-interactive use:

# Token count directives (controls max_tokens)
rayvise config prompt add sql \
  --description "Write SQL queries" \
  --short "200" \
  --medium "600" \
  --long "1500" \
  --system "Act as an expert database developer. Generate an optimized SQL query based on the input. If text is in single backticks (`), treat it as an exact quote and strictly maintain those exact table/column names, but automatically escape them (e.g., with quotes or brackets) if they clash with reserved SQL keywords. Otherwise, infer logical names. Wrap non-read operations (INSERT, UPDATE, DELETE) inside a transaction (BEGIN/COMMIT). Output length guidance: {{.LengthDirective}}. CRITICAL: Output ONLY raw, valid SQL code. No markdown formatting, explanations, or preamble."

# Text directives (injected into {{.LengthDirective}})
rayvise config prompt add code-review \
  --description "Generate a code review prompt" \
  --short "Keep the review concise, focusing on critical issues only." \
  --medium "Cover functionality, style, and best practices." \
  --long "Include security, performance, testing, and documentation." \
  --system "You are a code review expert. Generate a detailed prompt for reviewing code. Output length guidance: {{.LengthDirective}}. Return only the generated prompt."

Load system prompt from a file:

rayvise config prompt add code-review \
  --description "Generate a code review prompt" \
  --from-file ./my-prompt.txt

Method 2: Manual YAML Files

Create YAML files directly in ~/.rayvise/prompts/:

# ~/.rayvise/prompts/sql.yaml — token count directives
name: sql
description: "Write SQL queries"
system: "Act as an expert database developer. Generate an optimized SQL query based on the input. If text is in single backticks (`), treat it as an exact quote and strictly maintain those exact table/column names, but automatically escape them (e.g., with quotes or brackets) if they clash with reserved SQL keywords. Otherwise, infer logical names. Wrap non-read operations (INSERT, UPDATE, DELETE) inside a transaction (BEGIN/COMMIT). Output length guidance: {{.LengthDirective}}. CRITICAL: Output ONLY raw, valid SQL code. No markdown formatting, explanations, or preamble."
length_directives:
  short: "200"
  medium: "600"
  long: "1500"

# ~/.rayvise/prompts/code-review.yaml — text directives
name: code-review
description: "Generate a code review prompt"
system: |
  You are a code review expert. Generate a detailed prompt for reviewing code.
  Output length guidance: {{.LengthDirective}}
  Return only the generated prompt.
length_directives:
  short: "Keep the review prompt concise, focusing on critical issues only."
  medium: "Generate a balanced review prompt covering functionality, style, and best practices."
  long: "Generate a comprehensive review prompt including security, performance, testing, and documentation."

Restricting Output Lengths: To limit a prompt to specific output lengths, simply omit the unwanted lengths from length_directives. For example, to support only short and medium modes:

length_directives:
  short: "200"
  medium: "600"
  # long is intentionally omitted

Using Custom Prompts

rayvise "get all users joined with orders" -p sql
rayvise "review my API code" -p code-review

Template Variables

• {{.LengthDirective}} — Replaced with the text directive for the active length mode. Empty when a token-count directive is used.
• {{.Context}} — Replaced with project context (when available)

Project Context Awareness

rayvise automatically loads and incorporates project context to make your generated prompts more relevant to your specific project. This feature helps generate better prompts by understanding your project's conventions, architecture, and goals.

Supported Context Files

rayvise looks for context in the following files (in order of priority):

1. .cursor/rules/ - Cursor/Claude AI rules files

   • Useful for documenting project conventions and architecture

2. CLAUDE.md - Claude-specific guidance

   • Instructions and patterns for AI code generation

3. AGENTS.md - Agent-specific configuration

   • Documentation for AI agents working with your project

When found, the context from these files is injected in prompts containing the {{.Context}} template variable.

How It Works

When you generate a prompt, rayvise:

1. Searches your current directory and parent directories for context files
2. Loads the first matching context file found
3. Includes the context in the system prompt via the {{.Context}} template variable
4. Shows you which context file was used in the status message

Example

With a CLAUDE.md file in your project:

rayvise "refactor this to use interfaces" -p metaprompt
# Output includes context from CLAUDE.md, making the generated prompt aware of your project structure

Pipeline with Other Tools

# Generate and pipe to file
rayvise "API documentation structure" > api-docs-prompt.txt

# Use with other CLI tools
cat requirements.txt | rayvise "analyze these dependencies" -l medium

Troubleshooting

API Key Not Found

Error: API key not found. Set RAYVISE_API_KEY environment variable or add to config.yaml

Solution: The CLI looks for your API key in two places:

1. Environment Variable: RAYVISE_API_KEY must be exported in your current shell session

   export RAYVISE_API_KEY=your_api_key_here

2. Config File: ~/.rayvise/config.yaml (note: this is in your home directory, not the project directory)

   mkdir -p ~/.rayvise
   cp config.yaml.example ~/.rayvise/config.yaml
   # Edit the file and add your API key

Common Issues:

• Having a .env file in the project directory won't work - Go doesn't automatically load .env files
• Having config.yaml in the project directory won't work - the CLI looks in ~/.rayvise/config.yaml
• Setting the variable without export won't work - it must be exported to be visible to the program
• You don't need to rebuild the executable after setting the API key

Clipboard Not Working

Warning: Could not copy to clipboard: failed to initialize clipboard: clipboard: cannot use when CGO_ENABLED=0

Root Cause: The clipboard library (golang.design/x/clipboard) requires CGO (C bindings) to access system clipboard APIs on macOS, Linux, and Windows. When binaries are cross-compiled with CGO_ENABLED=0, the clipboard feature fails at runtime.

Solution: We've fixed the build pipeline to compile on native platforms:

• macOS binaries are now built on macos-latest runners with CGO_ENABLED=1
• Linux binaries are built on ubuntu-latest (clipboard may not work on Linux arm64 cross-compilation; use xclip or xsel if installed)
• Windows binaries are built on ubuntu-latest (clipboard may not work; requires CGO cross-compilation setup)

If you're still experiencing this issue:

1. Make sure you're using the latest version: brew upgrade rayvise (macOS) or reinstall from the latest release
2. On macOS, ensure pbcopy is available (built-in utility)
3. Use --no-copy flag to disable clipboard and bypass the warning: rayvise "text" --no-copy
4. On headless/SSH systems, the warning is informational only and doesn't affect functionality

For developers building from source: Ensure CGO_ENABLED=1 when building for your platform:

CGO_ENABLED=1 go build -o rayvise

Model Not Found

Error: failed to resolve model: model not found

Solution: Check that the model alias exists in the built-in models or your custom models. Use a direct OpenRouter model ID if needed.

Connection Timeout

Error: generation failed: context deadline exceeded

Solution: Check your internet connection. The CLI retries once automatically. For longer generations, the timeout is 30 seconds for generate and 60 seconds for interactive mode.

Development

Running Tests

go test ./...

Building from Source

# Using the build script (recommended)
./build

# Or manually
go build -o rayvise

Developer Workflow

This project uses Go 1.24's new tool directive for consistent development tooling.

Prerequisites:

• Go 1.24 or later
• golangci-lint (automatically installed via go tool)

Running Linter Locally:

# Using go tool (recommended - uses pinned version)
go tool golangci-lint run ./...

Running Tests:

# Run all tests
go test ./...

# Run tests (verbose)
go test ./... -v

# Run tests with race detector and coverage
go test ./... -race -coverprofile=coverage.out

# View coverage report
go tool cover -html=coverage.out

Code Formatting:

# Format and fix imports
goimports -w ./cmd ./internal ./pkg

# Or use the built-in formatter
go fmt ./...

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

License

See LICENSE file for details.

Acknowledgments

• Built with Cobra for CLI framework
• Uses OpenRouter for LLM access
• Default model provider Cerebras for fast inference
• Powered by Viper for configuration
• Clipboard support via golang.design/x/clipboard
• Interactive mode with readline