CLI Commands

Global Options

These options apply to most commands:

Option	Description
-v, --verbose	Enable verbose logging
-q, --quiet	Suppress non-essential output
--json	Shorthand for JSON output where supported
--compact	Emit compact JSON instead of pretty-printed JSON
--no-color	Disable colored output
--style <MODE>	Visual style: rich, minimal, plain
-o, --output <FILE>	Write output to a file instead of stdout

Common unit flags:

Option	Description
--fahrenheit / --celsius	Override temperature units
--inhg / --hpa	Override pressure units
--bq / --pci	Override radon units

scan

Discover nearby Aranet devices via Bluetooth.

aranet scan [OPTIONS]

Option	Description
-t, --timeout <SECONDS>	Scan duration in seconds
-f, --format <FORMAT>	Output format: text, json, csv
--no-header	Omit the CSV header row
-a, --alias	Interactively save aliases for discovered devices

aranet scan --timeout 15
aranet scan --alias

read

Read current sensor measurements from one or more devices.

aranet read [OPTIONS]

Option	Description
-d, --device <ADDRESS>	Device address or alias; can be repeated or comma-separated
-T, --timeout <SECONDS>	Connection timeout per device
-f, --format <FORMAT>	Output format: text, json, csv
--passive	Read from BLE advertisements without connecting
--no-header	Omit the CSV header row

aranet read --device AA:BB:CC:DD:EE:FF
aranet read -d living-room -d bedroom
aranet read --device living-room --passive --json

Note

If you omit --device, the CLI uses the configured or last-used device when available. Otherwise it falls back to the interactive picker.

status

Show a one-line summary for a device.

aranet status [OPTIONS]

Option	Description
-d, --device <ADDRESS>	Device address or alias
-T, --timeout <SECONDS>	Connection timeout
-f, --format <FORMAT>	Output format: text, json, csv
--brief	Emit a compact single-line summary
--no-header	Omit the CSV header row

aranet status --device living-room
aranet status --device living-room --brief

history

Download historical measurements from a device, or read them from the local cache.

aranet history [OPTIONS]

Option	Description
-d, --device <ADDRESS>	Device address or alias
-T, --timeout <SECONDS>	Connection timeout
-c, --count <N>	Number of records to retrieve (0 means all)
-f, --format <FORMAT>	Output format: text, json, csv
--since <DATE>	Filter records after this RFC3339 or YYYY-MM-DD timestamp
--until <DATE>	Filter records before this RFC3339 or YYYY-MM-DD timestamp
--cache	Read from the local cache instead of connecting to the device
--no-header	Omit the CSV header row

aranet history --device living-room --output history.csv --format csv
aranet history --device living-room --since 2026-03-01 --until 2026-03-07
aranet history --device living-room --cache --count 100 --format json

info

Display device metadata such as model, firmware, and serial number.

aranet info [OPTIONS]

Option	Description
-d, --device <ADDRESS>	Device address or alias
-T, --timeout <SECONDS>	Connection timeout
-f, --format <FORMAT>	Output format: text, json, csv
--no-header	Omit the CSV header row

aranet info --device living-room

set

Modify supported device settings.

aranet set [OPTIONS] <SUBCOMMAND>

Subcommand	Description
interval <MINUTES>	Set the measurement interval in minutes; valid values are 1, 2, 5, 10
range <MODE>	Set Bluetooth range mode; valid values are standard, extended
smart-home <BOOL>	Enable or disable Smart Home BLE advertisements

Option	Description
-d, --device <ADDRESS>	Device address or alias
-T, --timeout <SECONDS>	Connection timeout
-f, --force	Skip the confirmation prompt

aranet set --device living-room interval 5
aranet set --device living-room range extended
aranet set --device living-room smart-home on

watch

Continuously monitor a device, or all devices passively.

aranet watch [OPTIONS]

Option	Description
-d, --device <ADDRESS>	Device address or alias
-T, --timeout <SECONDS>	Connection timeout
-i, --interval <SECONDS>	Poll interval
-n, --count <N>	Stop after N samples (0 means unlimited)
-f, --format <FORMAT>	Output format: text, json, csv
--passive	Watch BLE advertisements instead of opening a connection
--no-header	Omit the CSV header row

aranet watch --device living-room --interval 30
aranet watch --passive
aranet watch --device basement --passive --count 10

Note

Passive mode requires Smart Home broadcasting to be enabled on the device.

alias

Manage friendly names for device addresses.

aranet alias <SUBCOMMAND>

Subcommand	Description
list	List configured aliases
set <NAME> <ADDRESS>	Create or update an alias
remove <NAME>	Delete an alias

aranet alias set living-room AA:BB:CC:DD:EE:FF
aranet alias list
aranet alias remove living-room

config

Manage the CLI configuration file.

aranet config <SUBCOMMAND>

Subcommand	Description
show	Print the full config
get <KEY>	Print a single config value
set <KEY> <VALUE>	Update a config value
unset <KEY>	Remove a config value
path	Print the config file path
init	Create a default config file

Supported keys: device, format, timeout, no-color, fahrenheit, inhg, bq.

aranet config init
aranet config set device living-room
aranet config set format json
aranet config show

sync

Sync device history into the local SQLite cache.

aranet sync [OPTIONS]

Option	Description
-d, --device <ADDRESS>	Device address or alias
-T, --timeout <SECONDS>	Connection timeout
-f, --format <FORMAT>	Output format: text, json, csv
--full	Re-download all history instead of syncing incrementally
--all	Sync all known devices from the database

aranet sync --device living-room
aranet sync --device living-room --full
aranet sync --all --format json

report

Generate summary reports from cached history.

aranet report [OPTIONS]

Option	Description
-d, --device <ADDRESS>	Device address or alias
--all	Report on every cached device
-p, --period <PERIOD>	daily, weekly, or monthly
-f, --format <FORMAT>	Output format: text or json

aranet report --device living-room
aranet report --device living-room --period weekly --format json
aranet report --all --period monthly

Note

report works entirely from the local cache populated by aranet sync.

cache

Query and maintain the local SQLite cache directly.

aranet cache <SUBCOMMAND>

Subcommand	Description
devices	List cached devices
stats [--device <ADDRESS>]	Show cache statistics
history --device <ADDRESS>	Query cached history records
aggregate --device <ADDRESS>	Show min/max/avg aggregates
export --device <ADDRESS>	Export cached history to CSV or JSON
prune --older-than <DURATION>	Delete older cache records
info	Show database path and size
import	Import history from CSV or JSON

aranet cache devices
aranet cache stats --device living-room
aranet cache history --device living-room --count 50 --format json
aranet cache aggregate --device living-room --since 2026-03-01
aranet cache export --device living-room --format csv --output living-room.csv
aranet cache prune --older-than 90d --history-only --vacuum
aranet cache import --format json --input export.json

server

Launch the bundled HTTP API server and dashboard from the CLI.

aranet server [OPTIONS]

Option	Description
-c, --config <PATH>	Path to the aranet-service configuration file
-b, --bind <ADDR>	Bind address override
--database <PATH>	Database path override
--no-collector	Start the API without background polling
--daemon	Detach and run in the background

aranet server --bind 127.0.0.1:8080
aranet server --config ~/.config/aranet/server.toml --no-collector

completions

Generate shell completions.

aranet completions <SHELL>

Supported shells: bash, zsh, fish, powershell, elvish.

aranet completions zsh > ~/.zfunc/_aranet

doctor

Run BLE diagnostics and permission checks.

aranet doctor

aranet doctor

examples

Print a curated set of common command examples.

aranet examples

tui

Launch the interactive terminal dashboard.

aranet tui

The default aranet-cli release includes the tui subcommand. If you install the standalone TUI package instead, use aranet-tui.