eeroctl

A command-line tool for managing eero WiFi mesh routers. Built on the unofficial eero API, eeroctl gives you full control over your network from the terminal: view connected devices, manage profiles, configure port forwards, run speed tests, and more.

This project consists of two crates:

• eeroctl — The CLI application (AGPL-3.0)
• eero-api — A standalone async Rust client library for the eero API (MIT) — see eero-api/README.md

Things You Can Do With It

See all the devices on your network at a glance:

$ eeroctl device list
ID           NAME
04421a06d967 islay-49
ae94f29cf6d1 speyside
b0416f0b2f70 town-os
666ce339fe60 66:6c:e3:39:fe:60
72dcf28ae564 Watch

Set up port forwarding with a single command:

$ eeroctl forward create --help
Create a port forward

Usage: eeroctl forward create [OPTIONS] --ip-address <IP_ADDRESS> --port <PORT> [NETWORK]

Arguments:
  [NETWORK]  Network name (SSID) or `id:XXXXX`. Defaults to first network

Options:
      --ip-address <IP_ADDRESS>        Internal IP address
      --port <PORT>                    Internal port
      --external-port <EXTERNAL_PORT>  External port (defaults to same as internal)
      --protocol <PROTOCOL>            Protocol (tcp, udp, or tcp_udp)
  -h, --help                           Print help

Testing and Compatibility

eeroctl is developed and tested against an eero 6 router. The eero API is undocumented and not officially supported by eero, so behavior may vary across hardware generations and firmware versions.

If you have a different eero model and would like to help verify compatibility:

1. Install eeroctl and authenticate (see below)
2. Run through the basic commands (account get, network get, eero list, device list)
3. Report any issues or unexpected output at github.com/erikh/eeroctl/issues

The test suite includes unit tests, integration tests with a mock API server, and optional live tests that run against a real eero device. See Running Tests for details.

Installation

Requires Rust 1.70+.

# From source
cargo install --path eeroctl

# Or build without installing
cargo build --release -p eeroctl

Authentication

eero uses a two-step verification flow. You authenticate once and the session token is stored locally in ~/.config/eero/.

# Step 1: Request a verification code (sent via SMS or email)
eeroctl auth login you@example.com

# Step 2: Enter the code you received
eeroctl auth verify 123456

After verification you're authenticated and can run any command.

To skip the interactive flow, set the EERO_SESSION_TOKEN environment variable or pass --user-token:

export EERO_SESSION_TOKEN="your_token_here"
eeroctl account get

To log out and clear stored credentials:

eeroctl auth logout

Quick Start

# See your account and networks
eeroctl account get

# List devices on your network
eeroctl device list

# Get details for a specific device
eeroctl device get "MacBook Pro"

# Run a speed test
eeroctl network speed-test run

# Check eero node status
eeroctl eero list

Network Resolution

Most commands accept an optional network argument. If omitted, the first network on your account is used automatically:

# Uses your default (first) network
eeroctl device list

# Specify a network by SSID
eeroctl device list "My Home WiFi"

# Use a numeric network ID with the id: prefix
eeroctl network get "id:12345"

Run eeroctl account get to see your available networks and their names.

Name Resolution

eeros, devices, and profiles can be referenced by human-readable names instead of numeric IDs:

# eero by location name
eeroctl eero get "Living Room"

# Device by display name, nickname, or hostname
eeroctl device get "MacBook Pro"

# Profile by name
eeroctl profile get "Kids"

If a name matches multiple objects, an error is returned listing the matches. To use a numeric ID directly, prefix it with id::

eeroctl eero get "id:1001"
eeroctl device get "id:2001"

Commands

Authentication

Account

Network

Network set flags: --name, --password, --sqm, --band-steering, --thread, --upnp, --ipv6, --wpa3

Speed Test

Guest Network

Guest set flags: --name, --password, --enabled

eero Nodes

eero set flags: --location, --led-on, --nightlight-enabled, --nightlight-brightness, --nightlight-on, --nightlight-off

Devices

Device set flags: --nickname, --blocked, --paused, --profile

Profiles

Profile set flags: --name, --paused

Port Forwarding

Forward create flags: --ip-address (required), --port (required), --external-port, --protocol (tcp, udp, or tcp_udp)

Activity

Diagnostics

Output Formats

By default, output is syntax-highlighted YAML. You can change this:

# JSON output
eeroctl --json device list -m

# Disable syntax highlighting (useful for piping)
eeroctl -n device list -m

# Apply a jq filter (output is always JSON, one value per line)
eeroctl --jq '.name' network get
eeroctl --jq '.[].display_name' device list -m

Global Options

Running Tests

# Run linting and all tests (skips live tests)
make test

# Run only eero-api tests
cargo test -p eero-api -- --skip live_

# Run only eeroctl tests
cargo test -p eeroctl

Live Tests

Live tests run against a real eero router on your network. They require authentication and the router's IP address:

# Specify the eero IP address
make test-live EERO_IP=192.168.4.1

# Auto-detect from default gateway
make test-live-default

Live tests perform read-only operations and will not change your network configuration.

License

• eeroctl (CLI) — AGPL-3.0-or-later
• eero-api (library) — MIT