aranet-cli 0.1.10

Command-line interface for Aranet environmental sensors
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
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282

<p align="center">
  <picture>
    <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/cameronrye/aranet/main/assets/aranet-logo-dark.svg">
    <source media="(prefers-color-scheme: light)" srcset="https://raw.githubusercontent.com/cameronrye/aranet/main/assets/aranet-logo-light.svg">
    <img alt="Aranet" src="https://raw.githubusercontent.com/cameronrye/aranet/main/assets/aranet-logo-light.svg" height="60">
  </picture>
</p>

# aranet-cli

Command-line interface for Aranet environmental sensors.

A fast, scriptable CLI for reading sensor data, downloading history, and configuring Aranet devices (Aranet4, Aranet2, AranetRn+, Aranet Radiation).

## Installation

```bash
cargo install aranet-cli
```

Or build from source:

```bash
git clone https://github.com/cameronrye/aranet.git
cd aranet
cargo build --release --package aranet-cli
```

## Demo

![Aranet CLI Scan Demo](https://raw.githubusercontent.com/cameronrye/aranet/main/assets/screenshots/cli-scan.gif)

## Usage

### Scan for devices

```bash
aranet scan
```

### Read current measurements

```bash
aranet read --device <DEVICE_ADDRESS>
```

### Download measurement history

```bash
aranet history --device <DEVICE_ADDRESS>
aranet history --device <DEVICE_ADDRESS> --count 100 --format csv --output history.csv

# Filter by date range
aranet history --device <DEVICE_ADDRESS> --since 2026-01-15 --until 2026-01-16
```

### Read from multiple devices

```bash
# Specify multiple devices
aranet read -d device1 -d device2

# Or comma-separated
aranet read -d living-room,bedroom,office
```

### Passive read mode

```bash
# Read from BLE advertisements without connecting (requires Smart Home enabled)
aranet read --device <DEVICE_ADDRESS> --passive
```

### Watch real-time data

```bash
# Watch a specific device
aranet watch --device <DEVICE_ADDRESS> --interval 60

# Watch all devices passively (requires Smart Home enabled)
aranet watch --passive

# Watch a specific device passively
aranet watch --passive --device <DEVICE_ADDRESS>
```

### View device information

```bash
aranet info --device <DEVICE_ADDRESS>
```

### Configure device settings

```bash
aranet set --device <DEVICE_ADDRESS> interval 5
aranet set --device <DEVICE_ADDRESS> range extended
```

### Manage device aliases

```bash
# Create an alias for a device
aranet alias set living-room AA:BB:CC:DD:EE:FF

# List all aliases
aranet alias list

# Use aliases instead of addresses
aranet read -d living-room

# Remove an alias
aranet alias remove living-room
```

### Diagnose BLE issues

```bash
aranet doctor
```

### Sync history to local database

```bash
# Sync device history (incremental - only new records)
aranet sync --device <DEVICE_ADDRESS>

# Full sync (re-download all history)
aranet sync --device <DEVICE_ADDRESS> --full
```

### Query cached data

```bash
# List cached devices
aranet cache devices

# Show cache statistics
aranet cache stats

# Query cached history
aranet cache history --device <DEVICE_ADDRESS> --count 100

# Show database info
aranet cache info
```

### Pressure units

```bash
# Display pressure in inches of mercury
aranet read --device <DEVICE_ADDRESS> --inhg

# Explicitly use hPa (default)
aranet read --device <DEVICE_ADDRESS> --hpa
```

## Configuration

The CLI supports persistent configuration via a TOML file:

```bash
# Initialize config file
aranet config init

# Set a default device
aranet config set device <DEVICE_ADDRESS>

# Set default output format
aranet config set format json

# Show current config
aranet config show
```

Configuration options:

- `device` — Default device address
- `format` — Default output format (`text`, `json`, `csv`)
- `timeout` — Connection timeout in seconds
- `no_color` — Disable colored output
- `fahrenheit` — Use Fahrenheit for temperature display
- `inhg` — Use inHg for pressure display
- `bq` — Use Bq/m3 for radon (instead of pCi/L)

## Output Formats

| Format | Description |
|--------|-------------|
| `text` | Human-readable colored output (default) |
| `json` | JSON for scripting and APIs |
| `csv` | CSV for spreadsheets and data analysis |

```bash
aranet read --device <DEVICE> --format json
aranet read --device <DEVICE> --json    # shorthand
```

## Visual Styling

The CLI uses rich styling by default with color-coded values, spinners, and table formatting.

### Style Modes

| Mode | Description |
|------|-------------|
| `rich` | Full styling with tables, spinners, colored values (default) |
| `minimal` | Colors only, no tables or spinners |
| `plain` | No styling, suitable for scripting |

```bash
# Use minimal styling
aranet read --device <DEVICE> --style minimal

# Plain output for scripts
aranet history --device <DEVICE> --style plain

# Set via environment variable
export ARANET_STYLE=minimal
```

### Color-Coded Values

Sensor readings are color-coded based on thresholds:

| Metric | Green | Yellow | Red |
|--------|-------|--------|-----|
| CO2 | < 800 ppm | 800-1000 ppm | > 1000 ppm |
| Radon | < 100 Bq/m3 | 100-150 Bq/m3 | > 150 Bq/m3 |
| Battery | > 50% | 20-50% | < 20% |
| Humidity | 30-60% | Outside range | - |

### Brief Mode

Get a compact one-line status:

```bash
aranet status --device <DEVICE> --brief
# Output: Aranet4 17C3C: 800 ppm [GREEN] | 22.5C | 45% | 85%
```

## Shell Completions

Generate shell completions for your preferred shell:

```bash
aranet completions bash > ~/.local/share/bash-completion/completions/aranet
aranet completions zsh > ~/.zfunc/_aranet
aranet completions fish > ~/.config/fish/completions/aranet.fish
```

## TUI Dashboard

Launch the interactive terminal dashboard:

```bash
aranet tui
```

The TUI provides real-time monitoring with sparkline charts, threshold alerts, multi-device support, and more. See [aranet-tui](../aranet-tui/) for the complete feature list and keybindings.

## Related Crates

This CLI is part of the [aranet](https://github.com/cameronrye/aranet) workspace:

| Crate | crates.io | Description |
|-------|-----------|-------------|
| [aranet-core](../aranet-core/) | [![crates.io](https://img.shields.io/crates/v/aranet-core.svg)](https://crates.io/crates/aranet-core) | Core BLE library for device communication |
| [aranet-types](../aranet-types/) | [![crates.io](https://img.shields.io/crates/v/aranet-types.svg)](https://crates.io/crates/aranet-types) | Shared types for sensor data |
| [aranet-store](../aranet-store/) | [![crates.io](https://img.shields.io/crates/v/aranet-store.svg)](https://crates.io/crates/aranet-store) | Local data persistence |
| [aranet-tui](../aranet-tui/) | [![crates.io](https://img.shields.io/crates/v/aranet-tui.svg)](https://crates.io/crates/aranet-tui) | Terminal UI dashboard |
| [aranet-service](../aranet-service/) | - | Background collector and REST API |
| [aranet-gui](../aranet-gui/) | - | Desktop GUI application |
| [aranet-wasm](../aranet-wasm/) | - | WebAssembly module |

## License

MIT

---

Made with ❤️ by [Cameron Rye](https://rye.dev/)