Update README with fine-tuning instructions and npm badge
keypair34 committed
Apr 23, 2026 at 22:44 UTC
a23167053e00722c93a254d5c81b451b9f5c00be
3 files changed
+183
-42
README.md
+90
-35
@@ -5,61 +5,61 @@
5
<h1 align="center">onde</h1>
6
7
<p align="center">
8
- <strong>Command-line interface for <a href="https://ondeinference.com">Onde Inference</a>.</strong>
8
+ Command-line interface for <a href="https://ondeinference.com">Onde Inference</a>.
9
</p>
10
11
<p align="center">
12
<a href="https://ondeinference.com"><img src="https://img.shields.io/badge/ondeinference.com-235843?style=flat-square&labelColor=17211D" alt="Website"></a>
13
<a href="https://apps.apple.com/se/developer/splitfire-ab/id1831430993"><img src="https://img.shields.io/badge/App%20Store-live-235843?style=flat-square&labelColor=17211D" alt="App Store"></a>
14
+ <a href="https://www.npmjs.com/package/@ondeinference/cli"><img src="https://img.shields.io/npm/v/@ondeinference/cli?style=flat-square&labelColor=17211D&color=235843" alt="npm"></a>
15
<a href="https://pypi.org/project/onde-cli/"><img src="https://img.shields.io/pypi/v/onde-cli?style=flat-square&labelColor=17211D&color=235843" alt="PyPI"></a>
16
<a href="https://crates.io/crates/onde-cli"><img src="https://img.shields.io/crates/v/onde-cli?style=flat-square&labelColor=17211D&color=235843" alt="Crates.io"></a>
17
</p>
18
19
<p align="center">
19
- <a href="https://github.com/ondeinference/onde-swift">Swift SDK</a> · <a href="https://pub.dev/packages/onde_inference">Flutter SDK</a> · <a href="https://www.npmjs.com/package/@ondeinference/react-native">React Native SDK</a> · <a href="https://ondeinference.com">Website</a>
20
+ <a href="https://github.com/ondeinference/onde-swift">Swift</a> · <a href="https://pub.dev/packages/onde_inference">Flutter</a> · <a href="https://www.npmjs.com/package/@ondeinference/react-native">React Native</a> · <a href="https://crates.io/crates/onde">Rust</a> · <a href="https://ondeinference.com">Website</a>
21
</p>
22
23
---
24
24
-Manage your Onde Inference account from the terminal. Sign up, sign in, and access the service.
25
+Manage your Onde Inference account, fine-tune local models, and export them to GGUF — all from the terminal.
26
27
## Install
28
28
-### Homebrew (macOS)
29
+### npm
30
31
```sh
31
-brew tap ondeinference/homebrew-tap
32
-brew install onde
32
+npm install -g @ondeinference/cli
33
```
34
35
-### pip
35
+### Homebrew
36
37
```sh
38
-pip install onde-cli
38
+brew tap ondeinference/homebrew-tap
39
+brew install onde
40
```
41
41
-### uv
42
+### pip / uv
43
44
```sh
45
+pip install onde-cli
46
+# or
47
uv tool install onde-cli
48
```
49
47
-### Pre-built binary (macOS, Linux, Windows)
50
+### Pre-built binary
51
49
-Download the latest binary for your platform from the
50
-[GitHub Releases](https://github.com/ondeinference/onde-cli/releases) page,
51
-make it executable, and move it onto your `PATH`:
52
+Download from [GitHub Releases](https://github.com/ondeinference/onde-cli/releases):
53
54
```sh
54
-# macOS arm64 example
55
+# macOS Apple Silicon
56
curl -Lo onde https://github.com/ondeinference/onde-cli/releases/latest/download/onde-macos-arm64
56
-chmod +x onde
57
-mv onde /usr/local/bin/onde
57
+chmod +x onde && mv onde /usr/local/bin/onde
58
```
59
60
| Platform | File |
61
|---|---|
62
-| macOS Apple silicon | `onde-macos-arm64` |
62
+| macOS Apple Silicon | `onde-macos-arm64` |
63
| macOS Intel | `onde-macos-amd64` |
64
| Linux x64 | `onde-linux-amd64` |
65
| Linux arm64 | `onde-linux-arm64` |
@@ -89,33 +89,88 @@ cargo build --release
89
onde
90
```
91
92
-Opens a terminal UI. Create an account or sign in.
92
+Opens a TUI. Sign up or sign in from there.
93
94
-## Keys
94
+| Key | What it does |
95
+|---|---|
96
+| `Tab` | move between fields |
97
+| `Enter` | submit / sign out |
98
+| `Ctrl+L` | sign in screen |
99
+| `Ctrl+N` | new account screen |
100
+| `Ctrl+C` | quit |
101
96
-| Key | What it does |
97
-|--------|---------------------|
98
-| Tab | move between fields |
99
-| Enter | submit / sign out |
100
-| Ctrl+L | go to sign in |
101
-| Ctrl+N | go to new account |
102
-| Ctrl+C | quit |
102
+---
103
104
-## Debug
104
+## Fine-tuning
105
106
-Logs go to `~/.cache/onde/debug.log`. Nothing touches the terminal output.
106
+onde includes a LoRA fine-tuning pipeline for Qwen2, Qwen2.5, and Qwen3 models. Runs on Metal on Apple Silicon, CPU elsewhere. No cloud, no Python.
107
108
----
108
+The full pipeline: download a safetensors base model → fine-tune with LoRA → merge the adapter into the base weights → export to GGUF → load in the Onde SDK.
109
110
-## License
110
+### Training data format
111
+
112
+Each line is a complete conversation in Qwen's chat template:
113
+
114
+```jsonl
115
+{"text": "<|im_start|>system\nYou are a helpful assistant.<|im_end|>\n<|im_start|>user\nWhat is LoRA?<|im_end|>\n<|im_start|>assistant\nLoRA adds small trainable matrices to frozen layers, letting you fine-tune large models without updating all the weights.<|im_end|>"}
116
+```
117
+
118
+Save it anywhere — the TUI lets you point to the file path.
119
+
120
+### Running it
121
+
122
+```
123
+onde
124
+ → Models tab (Tab from Apps)
125
+ → Select a safetensors model (↑↓, Enter)
126
+ → Press f
127
+```
128
+
129
+Only safetensors models can be fine-tuned. GGUF models can't — they're quantized and the weights aren't differentiable.
130
+
131
+Configure the run:
132
+
133
+| Field | Default | Notes |
134
+|---|---|---|
135
+| Training data | `~/.onde/finetune/train.jsonl` | Path to your JSONL file |
136
+| LoRA rank | `8` | Higher = more capacity, more memory |
137
+| Epochs | `3` | Full passes over the dataset |
138
+| Learning rate | `0.0001` | AdamW default |
139
+
140
+Press `Enter` to start. Loss should drop by epoch 2. If it doesn't, try bumping the learning rate to `0.0003`.
141
+
142
+### After training
143
+
144
+The adapter is ~1.5 MB for rank 8 on a 0.6B model. From the fine-tune done screen:
145
+
146
+- `m` — merge adapter into the base model
147
+- `g` — export merged model to GGUF
148
+
149
+The resulting GGUF loads directly in the Onde SDK for on-device inference.
150
+
151
+### Supported base models
152
112
-Dual-licensed under **MIT** and **Apache 2.0**.
153
+| Model | Size | Notes |
154
+|---|---|---|
155
+| `Qwen/Qwen3-0.6B` | ~1.2 GB | Smallest, fastest to train |
156
+| `Qwen/Qwen2.5-1.5B-Instruct` | ~3.0 GB | Good for instruction tuning |
157
+| `Qwen/Qwen3-1.7B` | ~3.4 GB | Latest small Qwen3 |
158
+| `Qwen/Qwen3-4B` | ~8.0 GB | Best quality, macOS recommended |
159
114
-- [MIT License](https://github.com/ondeinference/onde/blob/main/LICENSE-MIT)
115
-- [Apache License 2.0](https://github.com/ondeinference/onde/blob/main/LICENSE-APACHE)
160
+Search for any of these by pressing `/` on the Models tab.
161
162
---
163
164
+## Debug
165
+
166
+Logs go to `~/.cache/onde/debug.log`.
167
+
168
+---
169
+
170
+## License
171
+
172
+Dual-licensed under [MIT](https://github.com/ondeinference/onde-cli/blob/main/LICENSE-MIT) and [Apache 2.0](https://github.com/ondeinference/onde-cli/blob/main/LICENSE-APACHE).
173
+
174
<p align="center">
120
- <sub>© 2026 <a href="https://ondeinference.com">Onde Inference</a></sub>
121
-</p>
175
+ <sub>© 2026 <a href="https://ondeinference.com">Onde Inference</a> · <a href="https://apps.apple.com/se/developer/splitfire-ab/id1831430993">Splitfire AB</a></sub>
176
+</p>
\ No newline at end of file
npm/onde-cli/README.md
+42
-3
@@ -5,7 +5,7 @@
5
<h1 align="center">@ondeinference/cli</h1>
6
7
<p align="center">
8
- Manage your Onde Inference account from the terminal.
8
+ Manage your Onde Inference account and fine-tune models from the terminal.
9
</p>
10
11
<p align="center">
@@ -47,13 +47,52 @@ Opens a TUI. Sign up or sign in from there, no browser needed.
47
| Key | What it does |
48
|---|---|
49
| `Tab` | Move between fields |
50
-| `Enter` | Submit / sign out |
50
+| `Enter` | Submit / confirm |
51
| `Ctrl+L` | Sign in screen |
52
| `Ctrl+N` | New account screen |
53
| `Ctrl+C` | Quit |
54
55
---
56
57
+## Fine-tuning
58
+
59
+`onde` includes LoRA fine-tuning for Qwen2, Qwen2.5, and Qwen3 safetensors models. It runs on Metal (Apple Silicon) or CPU — no cloud, no Python.
60
+
61
+### Supported base models
62
+
63
+| Model | Size |
64
+|---|---|
65
+| `Qwen/Qwen3-0.6B` | ~1.2 GB |
66
+| `Qwen/Qwen2.5-1.5B-Instruct` | ~3.0 GB |
67
+| `Qwen/Qwen3-1.7B` | ~3.4 GB |
68
+| `Qwen/Qwen3-4B` | ~8.0 GB |
69
+
70
+Only safetensors models can be fine-tuned. GGUF models are quantized — their weights aren't differentiable.
71
+
72
+### Training data
73
+
74
+One JSON object per line, each with a `text` field containing the full conversation in the Qwen chat template:
75
+
76
+```jsonl
77
+{"text": "<|im_start|>user\nWhat is the boiling point of water?<|im_end|>\n<|im_start|>assistant\n100°C at sea level.<|im_end|>"}
78
+```
79
+
80
+### Running a fine-tune
81
+
82
+1. Go to the Models tab.
83
+2. Select a safetensors model with `↑` / `↓`.
84
+3. Press `f` to open the fine-tune config.
85
+4. Set your data path, LoRA rank (default 8), epochs (default 3), and learning rate (default 0.0001).
86
+5. Start training.
87
+
88
+The adapter for a rank-8 run on the 0.6B model is about 1.5 MB.
89
+
90
+### After training
91
+
92
+Press `m` to merge the adapter into the base weights. Press `g` to export to GGUF. The output file loads directly in the [Onde SDK](https://ondeinference.com) for on-device inference.
93
+
94
+---
95
+
96
## What's Onde?
97
98
[Onde Inference](https://ondeinference.com) runs LLMs on the user's device. No server round-trips, no data leaving the hardware. It ships as a native SDK for each platform:
@@ -62,7 +101,7 @@ Opens a TUI. Sign up or sign in from there, no browser needed.
101
<a href="https://github.com/ondeinference/onde-swift">Swift</a> · <a href="https://pub.dev/packages/onde_inference">Flutter</a> · <a href="https://www.npmjs.com/package/@ondeinference/react-native">React Native</a> · <a href="https://crates.io/crates/onde">Rust</a>
102
</p>
103
65
-This CLI handles the account side of things. The SDKs handle inference.
104
+This CLI handles account management and local fine-tuning. The SDKs handle inference.
105
106
---
107
pypi/README.md
+51
-4
@@ -12,6 +12,7 @@
12
<p align="center">
13
<a href="https://ondeinference.com"><img src="https://img.shields.io/badge/ondeinference.com-235843?style=flat-square&labelColor=17211D" alt="Website"></a>
14
<a href="https://pypi.org/project/onde-cli/"><img src="https://img.shields.io/pypi/v/onde-cli?style=flat-square&labelColor=17211D&color=235843" alt="PyPI"></a>
15
+ <a href="https://www.npmjs.com/package/@ondeinference/cli"><img src="https://img.shields.io/npm/v/@ondeinference/cli?style=flat-square&labelColor=17211D&color=235843" alt="npm"></a>
16
<a href="https://crates.io/crates/onde-cli"><img src="https://img.shields.io/crates/v/onde-cli?style=flat-square&labelColor=17211D&color=235843" alt="Crates.io"></a>
17
<a href="https://github.com/ondeinference/onde-cli/blob/main/LICENSE"><img src="https://img.shields.io/badge/license-MIT%20%2F%20Apache--2.0-235843?style=flat-square&labelColor=17211D" alt="License"></a>
18
</p>
@@ -81,14 +82,60 @@ A full terminal UI opens. Create an account or sign in, then manage your apps an
82
| `Enter` | Assign selected model |
83
| `Esc` | Cancel |
84
84
-## Other installation methods
85
+### Fine-tuning
86
86
-### Cargo
87
+| Key | Action |
88
+|-----------|-----------------------------------------|
89
+| `↑` `↓` | Navigate models |
90
+| `f` | Open fine-tune config for selected model |
91
+| `m` | Merge adapter into base model |
92
+| `g` | Export merged model to GGUF |
93
88
-```sh
89
-cargo install onde-cli
94
+## Fine-tuning
95
+
96
+`onde` includes LoRA fine-tuning for Qwen2, Qwen2.5, and Qwen3 safetensors models. Training runs locally on Metal (Apple Silicon) or CPU — no cloud account, no Python environment.
97
+
98
+### Supported base models
99
+
100
+| Model | Size |
101
+|-------|------|
102
+| `Qwen/Qwen3-0.6B` | ~1.2 GB |
103
+| `Qwen/Qwen2.5-1.5B-Instruct` | ~3.0 GB |
104
+| `Qwen/Qwen3-1.7B` | ~3.4 GB |
105
+| `Qwen/Qwen3-4B` | ~8.0 GB |
106
+
107
+Only safetensors models can be fine-tuned. GGUF models are quantized and their weights aren't differentiable, so they don't work here.
108
+
109
+### Training data format
110
+
111
+One JSON object per line, each with a `text` field containing the full conversation formatted in the Qwen chat template:
112
+
113
+```jsonl
114
+{"text": "<|im_start|>user\nWhat is the boiling point of water?<|im_end|>\n<|im_start|>assistant\n100°C at sea level.<|im_end|>"}
115
+{"text": "<|im_start|>user\nWhat about at high altitude?<|im_end|>\n<|im_start|>assistant\nLower — around 90°C at 3000 m.<|im_end|>"}
116
```
117
118
+### Running a fine-tune
119
+
120
+1. Go to the Models tab.
121
+2. Select a safetensors model with `↑` / `↓`.
122
+3. Press `f` to open the fine-tune config.
123
+4. Set your data path, LoRA rank (default 8), epochs (default 3), and learning rate (default 0.0001).
124
+5. Start training. The adapter for a rank-8 run on the 0.6B model is about 1.5 MB.
125
+
126
+### After training
127
+
128
+Press `m` to merge the LoRA adapter into the base weights, then `g` to export the result to GGUF. The output file loads directly in the [Onde SDK](https://ondeinference.com) for on-device inference.
129
+
130
+## Other installation methods
131
+
132
+| Method | Command |
133
+|--------|---------|
134
+| npm | `npm install -g @ondeinference/cli` |
135
+| Homebrew | `brew install ondeinference/homebrew-tap/onde` |
136
+| uv | `uv tool install onde-cli` |
137
+| Cargo | `cargo install onde-cli` |
138
+
139
### From source
140
141
```sh