Ryvos is a single binary with a rich CLI built on clap v4. Run ryvos --help for the full list, or see each command below.

Global Flags

These flags work with any command:

--config <path>       Override config file path (default: ~/.ryvos/config.toml)
--workspace <path>    Override workspace directory
--verbose             Enable verbose logging (RUST_LOG=debug)
--quiet               Suppress non-essential output
--json                Output in JSON format (where supported)
--version             Print version and exit
--help                Print help and exit

Commands

ryvos (default: REPL)

ryvos

Starts the interactive REPL (Read-Eval-Print Loop). This is the default when no subcommand is given.

╭──────────────────────────────╮
│  ryvos v0.6.5                │
│  Model: claude-sonnet-4-20250514   │
│  Session: a1b2c3d4           │
╰──────────────────────────────╯

You > _

REPL-specific features:

• Session persists across messages
• Type exit or press Ctrl+C to quit
• Type /help for in-REPL commands
• Automatic context management and compaction

ryvos run

Execute a single prompt and exit:

ryvos run "your prompt here"

Flags:

Examples:

# Single task
ryvos run "list all TODO comments in this codebase"
 
# With Director orchestration
ryvos run --director "refactor the authentication module to use OAuth2"
 
# Resume a session
ryvos run --resume abc123 "what about the edge case we discussed?"
 
# CI/CD usage with JSON output
ryvos run --json "check if all tests pass" | jq '.success'

ryvos serve

Start the HTTP/WebSocket gateway server:

ryvos serve

Starts the Axum server at http://localhost:18789 (or your configured bind address) with:

• REST API (/api/chat, /api/sessions, /api/config)
• WebSocket endpoint (/ws) for real-time streaming
• Embedded Web UI dashboard
• Role-based authentication

Flags:

ryvos daemon

Start always-on daemon mode:

ryvos daemon
ryvos daemon --gateway

Runs Ryvos as a long-running process with:

• All configured channel adapters (Telegram, Discord, Slack, WhatsApp)
• Heartbeat monitoring
• Cron scheduled tasks
• Auto-restart on failure

Flags:

ryvos init

Interactive setup wizard:

ryvos init
ryvos init -y    # Accept all defaults

Runs the 10-phase onboarding flow:

1. LLM Provider — Choose and configure your model
2. Security — Set safety preferences
3. Channels — Configure Telegram, Discord, Slack, WhatsApp
4. Gateway — Set up Web UI and API
5. MCP Servers — Add external tool servers
6. Cron — Schedule recurring tasks
7. Heartbeat — Configure health monitoring
8. Web Search — Set up web search provider
9. Embeddings — Configure semantic search
10. Budget — Set spending limits

The wizard writes ~/.ryvos/config.toml and optionally creates a systemd user service.

ryvos config

Print the resolved configuration:

ryvos config

Shows the fully resolved config with environment variables expanded. Useful for debugging.

:::caution This command prints API keys in plaintext. Use only in secure environments. :::

ryvos doctor

Run system health checks:

ryvos doctor
ryvos doctor --json

Checks:

• Config file validity
• API key connectivity for primary and fallback models
• Workspace directory access
• Database integrity (SQLite)
• Channel adapter configuration
• MCP server connectivity
• Cron expression validity
• Security policy consistency

✓ Config loaded from ~/.ryvos/config.toml
✓ Anthropic API (claude-sonnet-4-20250514) — connected, 247ms
✓ Ollama (llama3.1:70b) — connected, 12ms
✓ Workspace ~/.ryvos — readable, writable
✓ Database — SQLite WAL mode, 1,247 sessions
✓ Telegram — bot token valid, webhook active
✗ Discord — bot token expired (update in config)
✓ MCP filesystem — 3 tools available
✓ Cron — 2 jobs, next fire in 47 minutes

ryvos health

Show tool health statistics:

ryvos health

Displays success/failure rates for each tool based on the failure journal:

Tool              Success   Failures   Health
bash              234       3          98.7%
read              1,024     0          100.0%
web_fetch         89        12         88.1%
browser_navigate  45        8          84.9%

ryvos tui

Launch the terminal UI:

ryvos tui

Full-screen terminal interface built with ratatui and crossterm:

• Split-pane layout (chat + tool output)
• Real-time streaming display
• Session info banner
• Arrow key navigation, Enter to send, Ctrl+C to quit

ryvos mcp

Manage MCP (Model Context Protocol) servers:

List

ryvos mcp list

Shows all configured MCP servers and their available tools:

Server: filesystem (stdio)
  Tools: read_file, write_file, list_directory
Server: github (stdio)
  Tools: create_issue, list_repos, search_code

Add

ryvos mcp add <name> --command <cmd> --args <args...>
ryvos mcp add <name> --url <sse-url>

Examples:

# Add a stdio MCP server
ryvos mcp add filesystem --command npx --args "-y" "@modelcontextprotocol/server-filesystem" "/home/user"
 
# Add an SSE MCP server
ryvos mcp add remote-tools --url "http://localhost:3001/sse"

ryvos skill

Manage skills (Lua/Rhai scripts):

ryvos skill list                  # List installed skills
ryvos skill install <name>        # Install from registry
ryvos skill search <query>        # Search the skill registry
ryvos skill remove <name>         # Uninstall a skill

ryvos soul

Run the personality interview:

ryvos soul

A 5-question interactive interview that generates SOUL.md in your workspace. This defines the agent's personality, communication style, and behavioral preferences.

ryvos update

Self-update to the latest version:

ryvos update

Downloads and replaces the current binary with the latest release from GitHub.

ryvos viking-server

Start the Viking memory server:

ryvos viking-server

Starts the hierarchical memory server on port 1933. Normally started automatically in daemon mode when [openviking] is configured.

ryvos migrate-memory

Migrate memory between backends:

ryvos migrate-memory --from sqlite --to viking
ryvos migrate-memory --from viking --to sqlite

Transfers memory data between the SQLite store and Viking hierarchical memory.

ryvos completions

Generate shell completion scripts:

Bash

ryvos completions bash > ~/.local/share/bash-completion/completions/ryvos

Zsh

ryvos completions zsh > ~/.zfunc/_ryvos

Fish

ryvos completions fish > ~/.config/fish/completions/ryvos.fish

PowerShell

ryvos completions powershell > $HOME\Documents\PowerShell\Completions\ryvos.ps1

Exit Codes

Environment Variables

Beyond $\{VAR\} expansion in config, these environment variables affect behavior:

Next Steps

• Quick Start — Walkthrough of first usage
• Configuration — Full config.toml reference
• Systemd Service — Run as a system service