ripl-tui 0.3.3

ripl — a living, breathing TUI framework for AI chat in the shell.
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106

# ripl

A shell-based agent chat client and TUI framework.

ripl provides a full-featured ratatui event loop wired to any LLM provider — Anthropic, OpenAI, Ollama, OpenRouter — with Fish Audio TTS/STT, ambient audio, hue-shifting themes, and a session cache. It ships as both a standalone binary (`ripl`) and a library for building your own AI shell experiences on top of it.

Audio features require platform tools: `afplay`/`afinfo` on macOS, or `paplay`/`aplay`/`mpv`/`ffplay` on Linux. TTS uses `say` (macOS) or `espeak`/`espeak-ng` (Linux). STT recording uses `sox`.

---

## Install

```sh
cargo install ripl-tui
```

Requires a provider API key in your environment or `~/.ripl/config.toml`.

---

## Configure

```sh
ripl config          # open ~/.ripl/config.toml in $EDITOR
ripl pair anthropic
ripl pair openai
ripl pair openrouter
```

```toml
# ~/.ripl/config.toml
[provider]
name = "anthropic"
model = "claude-sonnet-4-5"

[speech]
tts = "fish"    # or "say"
stt = "fish"    # or "whisper"

[theme]
root_hue = 217
```

---

## Environment variables

ripl reads these from your shell — no config file needed to get started.

| Variable | Purpose |
|---|---|
| `ANTHROPIC_API_KEY` | Anthropic / Claude provider key |
| `OPENAI_API_KEY` | OpenAI provider key |
| `OPENROUTER_API_KEY` | OpenRouter provider key |
| `FISH_AUDIO_API_KEY` | Fish Audio TTS/STT key (alias: `FISH_API_KEY`) |
| `FISH_AUDIO_VOICE_ID` | Fish Audio voice ID (alias: `FISH_VOICE_ID`) |
| `FISH_AUDIO_MODEL` | Fish TTS model override (alias: `FISH_TTS_MODEL`) |
| `FISH_STT_LANG` | Fish STT language code (e.g. `en`) |
| `RIPL_ROOT_HUE` | Theme hue 0–360 (overrides config) |
| `RIPL_DEV` | Enable dev mode (any value) |
| `RIPL_WHISPER_CMD` | Path to `whisper` binary |
| `RIPL_WHISPER_MODEL` | Path to Whisper model file |
| `RIPL_WHISPER_LANG` | Whisper language code |
| `RIPL_STT_RECORDER` | Audio recorder command (default: `sox`) |
| `RIPL_TTS_CACHE_DIR` | TTS audio cache directory |
| `BUN_PATH` | Path to `bun` for ambient scripts |

---

## Use as a library

```toml
# Cargo.toml
[dependencies]
ripl-tui = "0.3"
```

```rust
use std::sync::Arc;
use ripl::{RunOptions, with_terminal, run_in_terminal}; // "terminal" is the ratatui type
use ripl::providers::Provider;

fn main() -> color_eyre::eyre::Result<()> {
    let provider: Arc<dyn Provider> = // your provider
    with_terminal(|terminal| {
        run_in_terminal(terminal, RunOptions {
            provider: Some(provider),
            label: Some("My App".to_string()),
            scaffold: false,
            ..Default::default()
        })
    })
}
```

---

## Built with ripl

- [clea](https://clea.kerry.ink) — Chief Priestess of Ouracle

---

## License

MIT