CLI Commands

scan

Discover nearby Aranet devices via Bluetooth.

aranet scan [OPTIONS]

Options

Option	Default	Description
`-t, --timeout <SECONDS>`	`10`	Scan duration in seconds

Example

$ aranet scan --timeout 15

Scanning for Aranet devices (timeout: 15s)...

Found 2 devices:
  Aranet4 17C3C    AA:BB:CC:DD:EE:FF    RSSI: -45 dBm
  AranetRn+ 306B8  11:22:33:44:55:66    RSSI: -52 dBm

read

Read current sensor measurements from one or more devices.

aranet read [OPTIONS]

Options

Option	Default	Description
`-d, --device <ADDRESS>`	interactive	Device address(es), can be specified multiple times or comma-separated
`-f, --format <FORMAT>`	`text`	Output format: `text`, `json`, `csv`
`--passive`	-	Read from BLE advertisements without connecting
`--inhg`	-	Display pressure in inches of mercury
`--hpa`	-	Display pressure in hPa (default)
`--fahrenheit`	-	Display temperature in Fahrenheit

Example

$ aranet read --device AA:BB:CC:DD:EE:FF

CO₂:         847 ppm   [GREEN]
Temperature: 22.4°C
Humidity:    45%
Pressure:    1013.2 hPa
Battery:     87%

$ aranet read -d living-room -d bedroom

-- living-room --
CO₂:         847 ppm   [GREEN]
Temperature: 22.4°C
...

-- bedroom --
CO₂:         523 ppm   [GREEN]
Temperature: 20.1°C
...

# Read from advertisements without connecting
$ aranet read --device AA:BB:CC:DD:EE:FF --passive

$ aranet read --device AA:BB:CC:DD:EE:FF --format json

{
  "co2": 847,
  "temperature": 22.4,
  "humidity": 45,
  "pressure": 1013.2,
  "battery": 87,
  "status": "green",
  "interval": 300,
  "age": 135
}

history

Download historical measurements from a device.

aranet history [OPTIONS]

Options

Option	Default	Description
`-d, --device <ADDRESS>`	interactive	Device address
`-c, --count <N>`	`0` (all)	Number of records to retrieve
`-f, --format <FORMAT>`	`text`	Output format: `text`, `json`, `csv`
`--since <DATE>`	-	Filter records since this date (RFC3339 or YYYY-MM-DD)
`--until <DATE>`	-	Filter records until this date
`-o, --output <FILE>`	-	Write output to file

$ aranet history --device AA:BB:CC:DD:EE:FF --output history.csv --format csv

Downloading history...
[==========] 100% Download complete
Downloaded 1440 records to history.csv

# Download only records from a specific date range
$ aranet history --device AA:BB:CC:DD:EE:FF --since 2026-01-15 --until 2026-01-16

info

Display device information.

aranet info [OPTIONS]

Options

Option	Default	Description
`-d, --device <ADDRESS>`	auto-detect	Device address

Example

$ aranet info --device AA:BB:CC:DD:EE:FF

Device Information
╭──────────────┬─────────────────╮
│ Property     │ Value           │
├──────────────┼─────────────────┤
│ Name         │ Aranet4 17C3C   │
│ Model        │ Aranet4         │
│ Serial       │ 12345678        │
│ Firmware     │ v1.4.19         │
│ Hardware     │ v1.0            │
│ Software     │ v1.0            │
│ Manufacturer │ SAF Tehnika     │
╰──────────────┴─────────────────╯

status

Quick one-line reading with colored CO2 status indicator.

aranet status [OPTIONS]

Options

Option	Default	Description
`-d, --device <ADDRESS>`	auto-detect	Device address (MAC or UUID)
`--brief`	-	Super-compact single-line output

Example

$ aranet status --device AA:BB:CC:DD:EE:FF

Aranet4 17C3C: 847 ppm [GREEN] 22.4C 45% 1013 hPa

# Brief mode for scripts
$ aranet status --device AA:BB:CC:DD:EE:FF --brief

Aranet4 17C3C: 800 ppm [GREEN] | 22.5C | 45% | 85%

set

Modify device settings.

aranet set [OPTIONS] <SETTING> <VALUE>

Settings

Setting	Values	Description
`interval`	`1`, `2`, `5`, `10`	Measurement interval in minutes
`range`	`standard`, `extended`	Bluetooth range
`smart_home`	`on`, `off`	Smart Home integration

Example

# Set measurement interval to 2 minutes
aranet set --device AA:BB:CC:DD:EE:FF interval 2

# Enable extended Bluetooth range
aranet set --device AA:BB:CC:DD:EE:FF range extended

# Enable Smart Home integration
aranet set --device AA:BB:CC:DD:EE:FF smart_home on

watch

Continuously monitor sensor readings with auto-reconnect.

aranet watch [OPTIONS]

Options

Option	Default	Description
`-d, --device <ADDRESS>`	all devices	Device address (MAC or UUID)
`-i, --interval <SECONDS>`	60	Polling interval in seconds
`-n, --count <N>`	unlimited	Number of readings before exiting
`--passive`	false	Read from BLE advertisements (requires Smart Home enabled)

Examples

Watch a specific device (active connection):

$ aranet watch --device AA:BB:CC:DD:EE:FF

Watching: AA:BB:CC:DD:EE:FF
Interval: 60s | Press Ctrl+C to stop
--------------------------------------------------
[10:00:00] 847 ppm | 22.4 C | 45% | 95%
[10:05:00] 823 ppm | 22.5 C | 44% | 95%

Watch all devices passively (no connection required):

$ aranet watch --passive

Watching: all devices (passive)
Interval: 60s | Press Ctrl+C to stop
------------------------------------------------------------
[10:00:00]  [Aranet4 17C3C]   [GREEN]  523 ppm   22.1C  45%  1013.2 hPa  BAT 87%
[10:00:00]  [AranetRn+ 306B8] [AMBER]  101 pCi/L 14.6C  32%  981.4 hPa   BAT 95%
[10:01:30]  [Aranet4 17C3C]   [GREEN]  518 ppm   22.2C  44%  1013.1 hPa  BAT 87%

Watch a specific device passively:

$ aranet watch --passive --device "AranetRn+ 306B8"

config

Manage the configuration file (~/.config/aranet/config.toml).

aranet config <SUBCOMMAND>

Subcommands

Subcommand	Description
`show`	Display current configuration
`get <KEY>`	Get a configuration value
`set <KEY> <VALUE>`	Set a configuration value
`unset <KEY>`	Remove a configuration value
`path`	Print the config file path
`init`	Initialize default configuration

Example

# Show current configuration
$ aranet config show

device = "AA:BB:CC:DD:EE:FF"
format = "text"
no_color = false
fahrenheit = false

# Print config file path
$ aranet config path

/Users/you/.config/aranet/config.toml

Configuration Options

# Default device address
device = "AA:BB:CC:DD:EE:FF"

# Default output format: text, json, csv
format = "text"

# Disable colored output
no_color = false

# Use Fahrenheit for temperature
fahrenheit = false

# Use inHg for pressure
inhg = false

# Use Bq/m³ for radon (instead of pCi/L)
bq = false

# Device aliases
[aliases]
living-room = "AA:BB:CC:DD:EE:FF"
bedroom = "11:22:33:44:55:66"

completions

Generate shell completion scripts.

aranet completions <SHELL>

Shells

bash, zsh, fish, powershell, elvish

Example

# Generate and install zsh completions
aranet completions zsh > ~/.zfunc/_aranet

alias

Manage device aliases (friendly names for device addresses).

aranet alias <SUBCOMMAND>

Subcommands

Subcommand	Description
`list`	Show all saved device aliases
`set <name> <address>`	Create or update an alias
`remove <name>`	Delete an alias

Example

# Create an alias
$ aranet alias set living-room AA:BB:CC:DD:EE:FF
Added alias 'living-room' -> AA:BB:CC:DD:EE:FF

# List all aliases
$ aranet alias list
╭─────────────┬───────────────────╮
│ Alias       │ Device Address    │
├─────────────┼───────────────────┤
│ bedroom     │ 11:22:33:44:55:66 │
│ living-room │ AA:BB:CC:DD:EE:FF │
╰─────────────┴───────────────────╯

# Use alias instead of address
$ aranet read -d living-room

# Remove an alias
$ aranet alias remove bedroom
Removed alias 'bedroom'

sync

Download device history to the local database for offline access.

aranet sync [OPTIONS]

Options

Option	Default	Description
`-d, --device <ADDRESS>`	required	Device address or alias
`--full`	false	Re-download all history (instead of incremental)

Example

# Incremental sync (only new records since last sync)
$ aranet sync --device AA:BB:CC:DD:EE:FF

Syncing history from Aranet4 17C3C...
[==========] 100% Downloaded 42 new records
Sync complete. Total cached: 1482 records

# Full sync (re-download everything)
$ aranet sync --device living-room --full

Syncing history from Aranet4 17C3C (full)...
[==========] 100% Downloaded 1482 records
Sync complete.

cache

Query cached data from the local database without connecting to a device.

aranet cache <SUBCOMMAND>

Subcommands

Subcommand	Description
`devices`	List all cached devices
`stats`	Show cache statistics
`history`	Query cached history records
`info`	Show database path and size

Examples

List cached devices:

$ aranet cache devices

Cached Devices:
╭─────────────────┬───────────────────┬──────────────┬─────────────╮
│ Name            │ Address           │ Last Sync    │ Records     │
├─────────────────┼───────────────────┼──────────────┼─────────────┤
│ Aranet4 17C3C   │ AA:BB:CC:DD:EE:FF │ 2 hours ago  │ 1482        │
│ AranetRn+ 306B8 │ 11:22:33:44:55:66 │ 1 day ago    │ 720         │
╰─────────────────┴───────────────────┴──────────────┴─────────────╯

Show cache statistics:

$ aranet cache stats

Cache Statistics:
  Devices:  2
  Readings: 156
  History:  2202
  Database: 1.2 MB

Query cached history:

$ aranet cache history --device AA:BB:CC:DD:EE:FF --count 10

# With date filters
$ aranet cache history --device living-room --since 2026-01-15 --until 2026-01-16

Show database info:

$ aranet cache info

Database Path: /Users/you/Library/Application Support/aranet/data.db
Database Size: 1.2 MB

tui

Launch the interactive terminal dashboard for real-time monitoring.

aranet tui

Features

The TUI dashboard provides a full-featured monitoring interface with:

Multi-device monitoring with auto-refresh
Sparkline charts with min/max labels and time axis
Threshold alerts with severity levels and terminal bell
Light/dark theme toggle
Mouse support for device and tab selection
Export history to CSV
Comparison view for side-by-side readings

Key Bindings

Key	Action
`Tab` / `Shift+Tab`	Next/Previous tab
`j` / `k` / `↑` / `↓`	Navigate devices
`Enter`	Connect/Disconnect or edit setting
`s`	Scan for devices
`r`	Refresh reading
`g`	Full-screen chart
`v`	Comparison view
`e`	Export history to CSV
`t`	Toggle theme
`?`	Show help
`q`	Quit

Example

$ aranet tui

┌─ Aranet Monitor ─────────────── *2/3 CO2:847 !1 ─┐
│ ┌─ Devices ───────┐ ┌─ Readings ─────────────────┤
│ │ * Aranet4 17C3C │ │ CO2         847 ppm  ->    │
│ │   AranetRn+ 306 │ │ Temperature  22.4 C        │
│ └─────────────────┘ └────────────────────────────┤
└──────────────────────────────────────────────────┘

See the aranet-tui README for the complete keyboard reference.

doctor

Run BLE diagnostics and permission checks to troubleshoot connectivity issues.

aranet doctor

Example

$ aranet doctor

Aranet Doctor - BLE Diagnostics

Running diagnostics...

Results:
------------------------------------
[PASS] Bluetooth Adapter: Found and accessible
[PASS] BLE Scanning: Found 2 device(s): Aranet4 17C3C, AranetRn+ 306B8

All checks passed! Your system is ready to use Aranet devices.

If there are issues, the doctor will provide platform-specific troubleshooting tips:

macOS: Bluetooth permissions in System Settings
Linux: BlueZ installation, bluetooth group membership
Windows: Bluetooth drivers and settings

Made with ❤️ by Cameron Rye