Rayu CLI

Rayu CLI is a terminal-based AI coding agent. Bring your own API key and connect to any provider — Anthropic, OpenAI, NVIDIA, DeepSeek, Kimi/Moonshot, OpenRouter, Google Gemini, AWS Bedrock, local servers, or any OpenAI-compatible endpoint — with free model switching, full MCP support, and a complete built-in tool suite.

Website: https://rayucode.com
Docs: https://rayucode.com/docs
Changelog: https://rayucode.com/changelog

Installation

One command, any machine. The installer downloads the pre-bundled CLI (and a private Node runtime if the machine has none), so it does not depend on your Node/npm version or on write access to a global npm prefix:

# macOS / Linux
curl -fsSL https://rayucode.com/install | bash

# Windows (PowerShell)
irm https://rayucode.com/install.ps1 | iex

Then start:

rayu

Read the script first if you prefer: https://rayucode.com/install.sh. Full details, flags and uninstall instructions: https://rayucode.com/docs/01-installation.

Via npm (needs Node >= 18)

npm install -g @rayu-dev/rayu-cli

Or run instantly without installing:

npx @rayu-dev/rayu-cli

Package managers

bun install -g @rayu-dev/rayu-cli
pnpm add -g @rayu-dev/rayu-cli
yarn global add @rayu-dev/rayu-cli

Studio Remote

Control a running CLI session from Rayu Studio. There are two connection options:

• QR code: run /web-bridge pair in the CLI, scan the QR code with your phone camera (or open its link), sign in to Studio, and choose Approve machine. This also works when the CLI is signed in. The QR code expires after five minutes.
• Rayu account: sign in to the same Rayu account in the CLI and Studio, then run /web-bridge to connect directly.

Select the machine on Studio's Remote page to send prompts, approve tool calls, and interrupt turns. QR pairing grants control of that running worker; it does not sign the worker into Rayu or provide credentials for hosted models.

Use /web-bridge status to check the connection and /web-bridge off to cancel pairing or disconnect. If already connected, disconnect before starting QR pairing. Closing the CLI also ends remote control for that session.

Update

rayu update

This works for both install methods: an installer-managed install re-runs the installer, an npm install reinstalls from npm.

Or reinstall the latest directly:

curl -fsSL https://rayucode.com/install | bash    # installer-managed
npm install -g @rayu-dev/rayu-cli                 # npm-managed

Prefer rayu update: it resolves the latest version once, installs that exact version, and then verifies what actually landed on disk. A plain npm install -g @rayu-dev/rayu-cli@latest resolves the mutable latest tag a second time and can silently reinstall the version you already have when npm serves cached registry metadata (packuments are cached for 5 minutes), which looks like a successful update that changed nothing.

When a newer version is published, Rayu shows a one-line notice above the prompt and in the welcome box at launch, with a link to the changelog. Nothing is installed until you run rayu update yourself.

Automatic updates (opt-in)

Auto-updates are off by default. Rayu tells you an update exists but never replaces your install behind your back. To turn them on, set autoUpdates in ~/.rayu/config.json:

{
  "autoUpdates": true
}

To silence update checks and notices entirely:

export DISABLE_AUTOUPDATER=1

Two things to know before enabling automatic updates:

• Node version. Rayu requires Node.js 18 or newer. npm only warns when a package's engines requirement isn't met, so if a future release raises that floor, an automatic update could replace a working install with one that refuses to start until you upgrade Node. rayu update has the same constraint, but you choose when it happens.
• Duplicate installs. If Rayu is installed under two different npm prefixes (for example once with sudo, landing in /usr/local, and once without, landing in ~/.npm-global), an update writes to whichever prefix npm is configured for — which may not be the copy your shell actually runs. The result is a "successful" update where rayu --version never changes. rayu update detects this and tells you which copy is shadowing which; the automatic updater does not. Run which -a rayu to check, and remove the copy you don't want.

Uninstall

rayu uninstall

Quick start

On first launch, Rayu will ask you to connect a provider and enter your API key.

rayu                      # start an interactive TUI session
rayu --print "fix the bug in X"   # one-shot prompt, non-interactive
rayu --help               # all CLI flags, subcommands, and options

Interactive session

Inside a session, type / to see all slash commands:

Headless mode

For automation and CI/CD pipelines:

rayu --print --model meta/llama-3.3-70b-instruct "summarize this repo"

Pass credentials via environment variables (no saved config needed):

RAYU_OPENAI_COMPATIBLE=1 \
RAYU_OPENAI_BASE_URL=https://integrate.api.nvidia.com/v1 \
RAYU_OPENAI_API_KEY=nvapi-xxxxx \
rayu --print "list top-level folders"

JSON output for pipelines:

rayu --print --output-format json "list top-level folders" | jq .result

Providers

Rayu speaks four wire formats, so one provider entry can serve models that use different protocols. Which format a request uses is decided per model, not per provider:

Custom providers need no code change. Run /connect → Custom provider, give it a name, pick the API format its endpoint speaks, enter the base URL, the model ids and your key. Declare whether it supports reasoning and images so Rayu never sends a parameter your endpoint would reject.

Google Gemini is available three ways:

1. Gemini API key (GEMINI_API_KEY) via the OpenAI-compatible endpoint
2. Vertex AI with OAuth/ADC — project + region scoped
3. Login with Gemini — interactive Google sign-in, free, no GCP project

The Vertex/OAuth credentials also power Imagen 4 image generation and Veo 3.1 video generation.

Example — headless run with NVIDIA:

RAYU_OPENAI_COMPATIBLE=1 \
RAYU_OPENAI_BASE_URL=https://integrate.api.nvidia.com/v1 \
RAYU_OPENAI_API_KEY=nvapi-xxxxx \
rayu --print --model meta/llama-3.3-70b-instruct "summarize this repo"

Tools

Rayu ships with a comprehensive built-in tool suite:

MCP (Model Context Protocol)

Rayu supports the Model Context Protocol for connecting to external tools and data sources:

# Configure MCP servers interactively
/mcp

# Or add an MCP server in settings

MCP servers are configured in ~/.rayu/settings.json and can expose tools, resources, and prompts to the AI agent during sessions.

Skills

Rayu has a skill system for packaged, reusable procedures:

/install-skill <source>   # Install a skill from GitHub/URL/path
/skill <name> <args>      # Run an installed skill

Skills can be shared as GitHub repos and installed from URLs.

Autonomous mode

Rayu supports running autonomously with automatic approval of operations:

rayu --print --permission-mode bypassPermissions "Refactor the project"

Permission modes: default, bypassPermissions, acceptEdits, bypassReadonly, bypassReadonlyAndApis, and planMode.

Configuration

Config is stored in ~/.rayu by default. Key files:

All settings are preserved across updates and uninstalls.

Architecture overview

User input → Ink TUI (React renderer)
  → Slash command dispatch (/connect, /model, etc.)
  → Query engine (message history, context, tool dispatch)
  → Provider adapter (Anthropic/Bedrock/OpenAI/Vertex/Rayu-hosted)
  → Streaming response → Tool execution → Response rendered in TUI

The terminal UI uses a custom React renderer (src/ink/) built on react-reconciler with efficient frame diffing — cells are packed as Int32 pairs in an ArrayBuffer for zero-GC rendering of 200×120 terminals.

Documentation

Issues & feedback

https://github.com/Choeng-Rayu/rayu-cli/issues

Development

git clone https://github.com/Choeng-Rayu/rayu-cli.git
cd rayu-cli/rayu
bun install
bun run dev             # run from source
bun run build           # bundle CLI to dist/rayu.js (alias for build:cli)
bun run build:cli       # build standalone CLI bundle (dist/rayu.js)
bun run build:vscode    # build Rayucode VS Code extension (.vsix)
bun test                # run tests
bun run typecheck       # TypeScript type checking

Built with Bun, TypeScript, React/Ink, and a custom terminal renderer.