tl-cli 0.1.0

A streaming, cached translation CLI using OpenAI-compatible endpoints
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

# tl – streaming, cached translation CLI

[![CI](https://github.com/d2verb/tl/actions/workflows/ci.yml/badge.svg)](https://github.com/d2verb/tl/actions/workflows/ci.yml)

`tl` is a small CLI that streams translations coming from standard input or files through any OpenAI-compatible endpoint (local or remote). Configure multiple providers with their own endpoints, API keys, and models, then switch between them as needed.

## Install

```sh
cargo install tl-cli
```

Or build from source:

```sh
git clone https://github.com/d2verb/tl.git
cd tl
cargo install --path .
```

## Quick Usage

```sh
tl ./notes.md                       # translate a file
cat report.md | tl                   # translate stdin
tl --to ja ./notes.md                # override target language
tl --provider openrouter ./notes.md  # use a specific provider
tl --model gpt-4o ./notes.md         # use a specific model
tl --no-cache ./notes.md             # bypass cache
tl -w ./notes.md                     # overwrite file with translation
```

`tl` caches each translation (keyed on the input, language, model, endpoint, and prompt) so rerunning the same source is fast and cheap. Streaming responses keep your terminal responsive, and a spinner on stderr signals when work is in progress.

## Configuration

Settings live in `~/.config/tl/config.toml`.

```toml
[tl]
provider = "ollama"
model = "gemma3:12b"
to = "ja"

[providers.ollama]
endpoint = "http://localhost:11434"
models = ["gemma3:12b", "llama3.2"]

[providers.openrouter]
endpoint = "https://openrouter.ai/api"
api_key_env = "OPENROUTER_API_KEY"
models = ["anthropic/claude-3.5-sonnet", "openai/gpt-4o"]
```

### Provider Configuration

Each provider has:
- `endpoint` (required) – the OpenAI-compatible API endpoint
- `api_key_env` (optional) – environment variable name containing the API key
- `api_key` (optional) – API key stored directly in config (not recommended)
- `models` (optional) – list of available models for this provider

CLI options always supersede the config file.

### Managing Providers

Use `tl providers` to list configured providers:

```sh
tl providers                        # list all providers
tl providers ollama                 # show details for a specific provider
```

## Chat Mode

For interactive translation sessions, use `tl chat`:

```sh
tl chat                              # start chat mode with config defaults
tl chat --to ja                      # override target language
tl chat --provider openrouter        # use a specific provider
tl chat --model gpt-4o               # use a specific model
```

Type text and press Enter to translate. Translations stream in real-time.

### Slash Commands

- `/config` – show current configuration
- `/help` – list available commands
- `/quit` – exit chat mode

## Troubleshooting

- Use `tl languages` to see the supported ISO 639-1 codes before passing `--to`.
- Streaming is cancel-safe: pressing `Ctrl+C` while streaming aborts without polluting the cache.
- No cache hits? Run with `--no-cache` to force a fresh request.
- API key issues? Set the environment variable specified in `api_key_env` for your provider.