### Install Whosthere with Go

Source: https://github.com/ramonvermeulen/whosthere/blob/main/README.md

Installs the Whosthere tool using the Go build tool. This method is suitable if you have Go installed and prefer to manage the installation directly.

```bash
go install github.com/ramonvermeulen/whosthere@latest
```

--------------------------------

### Install Whosthere with Nix

Source: https://github.com/ramonvermeulen/whosthere/blob/main/README.md

Installs the Whosthere tool on NixOS using the `nix profile install` command. This ensures a declarative and reproducible installation.

```bash
nix profile install nixpkgs#whosthere
```

--------------------------------

### Example Whosthere Configuration (YAML)

Source: https://github.com/ramonvermeulen/whosthere/blob/main/README.md

This snippet shows an example configuration file for Whosthere, demonstrating settings for network interfaces, scan intervals, enabled scanners (mDNS, SSDP, ARP), sweeper, port scanner, splash screen, and theme customization. It highlights how to enable/disable features and specify scan parameters.

```yaml
# Uncomment the next line to configure a specific network interface - uses OS default if not set
# network_interface: eth0

# How often to run discovery scans
scan_interval: 20s

# Maximum timeout for each scan, recommended to be less than the scan interval
scan_timeout: 10s

scanners:
  mdns:
    enabled: true
  ssdp:
    enabled: true
  arp:
    enabled: true

sweeper:
  enabled: true
  interval: 5m
  timeout: 20s

port_scanner:
  timeout: 5s
  # List of TCP ports to scan on discovered devices
  tcp: [21, 22, 23, 25, 80, 110, 135, 139, 143, 389, 443, 445, 993, 995, 1433, 1521, 3306, 3389, 5432, 5900, 8080, 8443, 9000, 9090, 9200, 9300, 10000, 27017]

splash:
  enabled: true
  delay: 1s

theme:
  # When disabled, the TUI will use the terminal it's default ANSI colors
  # Also see the NO_COLOR environment variable to completely disable ANSI colors
  enabled: true

  # See the complete list of available themes at https://github.com/ramonvermeulen/whosthere/tree/main/internal/ui/theme/theme.go
  # Set name to "custom" to use the custom colors below
  # For any color that is not configured it will take the default theme value as fallback
  name: default

  # Disable ANSI colors completely, overrides theme.enabled
  # Can also be set via NO_COLOR or WHOSTHERE__THEME__NO_COLOR environment variables
  # no_color: false

  # Custom theme colors (uncomment and set name: custom to use)
  # primitive_background_color: "#000a1a"
  # contrast_background_color: "#001a33"
  # more_contrast_background_color: "#003366"
  # border_color: "#0088ff"
  # title_color: "#00ffff"
  # graphics_color: "#00ffaa"
  # primary_text_color: "#cceeff"
  # secondary_text_color: "#6699ff"
  # tertiary_text_color: "#ffaa00"
  # inverse_text_color: "#000a1a"
  # contrast_secondary_text_color: "#88ddff"

```

--------------------------------

### Install Whosthere via Homebrew, Go, or Source

Source: https://context7.com/ramonvermeulen/whosthere/llms.txt

Instructions for installing Whosthere using different package managers or by building from source. This ensures the tool is available for use on your system.

```bash
# Via Homebrew
brew install whosthere

# Via Go
go install github.com/ramonvermeulen/whosthere@latest

# Build from source
git clone https://github.com/ramonvermeulen/whosthere.git
cd whosthere
make build
```

--------------------------------

### Install Whosthere with Homebrew

Source: https://github.com/ramonvermeulen/whosthere/blob/main/README.md

Installs the Whosthere tool using the Homebrew package manager. This is a convenient method for macOS and Linux users who have Homebrew set up.

```bash
brew install whosthere
```

--------------------------------

### Example Theme Configuration (YAML)

Source: https://github.com/ramonvermeulen/whosthere/blob/main/README.md

This YAML snippet demonstrates how to configure the theme for Whosthere. It shows how to enable the theme, set a specific theme name (e.g., 'cyberpunk'), and provides commented-out options for custom color definitions and disabling ANSI colors.

```yaml
theme:
  enabled: true
  name: cyberpunk
```

--------------------------------

### Configure Whosthere with YAML

Source: https://context7.com/ramonvermeulen/whosthere/llms.txt

Shows an example YAML configuration file for whosthere. This file allows customization of network interfaces, scan intervals, enabled scanners, sweeper settings, port scanner configurations, and UI themes.

```yaml
# Network interface (auto-detect if not set)
# network_interface: eth0

# Scan timing
scan_interval: 20s
scan_timeout: 10s

# Scanner settings
scanners:
  mdns:
    enabled: true
  ssdp:
    enabled: true
  arp:
    enabled: true

# Sweeper for ARP cache population
sweeper:
  enabled: true
  interval: 5m
  timeout: 20s

# Port scanner settings
port_scanner:
  timeout: 5s
  tcp: [21, 22, 23, 25, 80, 110, 135, 139, 143, 389, 443, 445, 993, 995, 1433, 1521, 3306, 3389, 5432, 5900, 8080, 8443, 9000, 9090, 9200, 9300, 10000, 27017]

# TUI splash screen
splash:
  enabled: true
  delay: 1s

# Theme settings
theme:
  enabled: true
  name: default  # Options: default, cyberpunk, dracula, gruvbox, nord, solarized, custom

  # Custom theme colors (set name: custom to use)
  # primitive_background_color: "#000a1a"
  # contrast_background_color: "#001a33"
  # border_color: "#0088ff"
  # title_color: "#00ffff"
  # primary_text_color: "#cceeff"

```

--------------------------------

### Install Whosthere with Yay (Arch Linux)

Source: https://github.com/ramonvermeulen/whosthere/blob/main/README.md

Installs the Whosthere tool on Arch Linux using the `yay` AUR helper. This command fetches and builds the package from the Arch User Repository.

```bash
yay -S whosthere-bin
```

--------------------------------

### Start Continuous Discovery with Go

Source: https://context7.com/ramonvermeulen/whosthere/llms.txt

Starts continuous network discovery in the background and returns a channel for events. It handles graceful shutdown by listening for interrupt signals. The function processes various discovery events, such as engine start/stop, scan start/completion, discovered devices, and errors. Requires a pre-configured discovery engine.

```go
package main

import (
    "context"
    "fmt"
    "os"
    "os/signal"
    "syscall"

    "github.com/ramonvermeulen/whosthere/pkg/discovery"
)

func main() {
    // Assume engine is already created (see NewEngine example)
    engine, _ := createEngine() // Your engine creation function

    ctx, cancel := context.WithCancel(context.Background())
    defer cancel()

    // Start discovery - returns event channel
    events := engine.Start(ctx)

    // Handle graceful shutdown
    sigChan := make(chan os.Signal, 1)
    signal.Notify(sigChan, syscall.SIGINT, syscall.SIGTERM)

    go func() {
        <-sigChan
        fmt.Println("\nShutting down...")
        engine.Stop()
    }()

    // Process events
    for event := range events {
        switch event.Type {
        case discovery.EventEngineStarted:
            fmt.Println("Discovery engine started")

        case discovery.EventScanStarted:
            fmt.Println("Scan started...")

        case discovery.EventDeviceDiscovered:
            dev := event.Device
            fmt.Printf("Found: %-15s %-17s %-20s %s\n",
                dev.IP(), dev.MAC(), dev.Manufacturer(), dev.DisplayName())

        case discovery.EventScanCompleted:
            fmt.Printf("Scan complete: %d devices in %v\n",
                event.Stats.Count, event.Stats.Duration)

        case discovery.EventError:
            fmt.Printf("Error: %v\n", event.Error)

        case discovery.EventEngineStopped:
            fmt.Println("Discovery engine stopped")
            return
        }
    }
}
```

--------------------------------

### Implement Custom Scanner in Go for Whosthere

Source: https://context7.com/ramonvermeulen/whosthere/llms.txt

Provides a Go code example for creating a custom scanner that integrates with the whosthere discovery engine. It demonstrates implementing the `discovery.Scanner` interface, defining a `Scan` method to discover devices, and registering the custom scanner with the discovery engine.

```go
package main

import (
    "context"
    "net"
    "time"

    "github.com/ramonvermeulen/whosthere/pkg/discovery"
)

// CustomScanner implements discovery.Scanner interface
type CustomScanner struct {
    iface *discovery.InterfaceInfo
}

func (s *CustomScanner) Name() string {
    return "custom-scanner"
}

func (s *CustomScanner) Scan(ctx context.Context, out chan<- *discovery.Device) error {
    // Your custom discovery logic here
    // Example: read from a database, query an API, etc.

    devices := []struct {
        ip   string
        mac  string
        name string
    }{
        {"192.168.1.10", "aa:bb:cc:dd:ee:01", "Server 1"},
        {"192.168.1.11", "aa:bb:cc:dd:ee:02", "Server 2"},
    }

    for _, d := range devices {
        select {
        case <-ctx.Done():
            return ctx.Err()
        default:
            device := discovery.NewDevice(net.ParseIP(d.ip))
            device.SetMAC(d.mac)
            device.SetDisplayName(d.name)
            device.AddSource(s.Name())

            select {
            case out <- device:
            case <-ctx.Done():
                return ctx.Err()
            }
        }
    }

    return nil
}

func main() {
    iface, _ := discovery.NewInterfaceInfo("")
    customScanner := &CustomScanner{iface: iface}

    engine, _ := discovery.NewEngine(
        discovery.WithInterface(iface),
        discovery.WithScanners(customScanner),
        discovery.WithScanInterval(0), // Single scan
    )

    results, _ := engine.Scan(context.Background())
    for _, dev := range results.Devices {
        println(dev.IP().String(), dev.DisplayName())
    }
}
```

--------------------------------

### Configure Whosthere with Environment Variables

Source: https://context7.com/ramonvermeulen/whosthere/llms.txt

Illustrates how to configure whosthere using environment variables. Settings are prefixed with `WHOSTHERE__` and follow a hierarchical structure mirroring the YAML configuration. This example shows disabling the splash screen, setting scan intervals, disabling scanners, and customizing the port list and theme.

```bash
# Disable splash screen
export WHOSTHERE__SPLASH__ENABLED=false

# Set scan interval
export WHOSTHERE__SCAN_INTERVAL=30s

# Disable specific scanners
export WHOSTHERE__SCANNERS__MDNS__ENABLED=false
export WHOSTHERE__SCANNERS__SSDP__ENABLED=false

# Custom port list
export WHOSTHERE__PORT_SCANNER__TCP=80,443,8080,9000

# Set theme
export WHOSTHERE__THEME__NAME=cyberpunk

# Disable colors
export NO_COLOR=1

# Set log level
export WHOSTHERE_LOG=debug
```

--------------------------------

### GET /devices - List All Discovered Devices

Source: https://context7.com/ramonvermeulen/whosthere/llms.txt

Retrieves a JSON array of all devices currently discovered on the network. This endpoint is useful for getting an overview of all active devices.

```APIDOC
## GET /devices

### Description
Returns a JSON array of all devices currently discovered on the network.

### Method
GET

### Endpoint
/devices

### Parameters
#### Query Parameters
None

#### Request Body
None

### Response
#### Success Response (200)
- **devices** (array) - An array of device objects.
  - **ip** (string) - The IP address of the device.
  - **mac** (string) - The MAC address of the device.
  - **displayName** (string) - A human-readable name for the device.
  - **manufacturer** (string) - The manufacturer of the device.
  - **sources** (array of strings) - The discovery methods used for this device (e.g., "arp-cache", "ssdp").
  - **firstSeen** (string) - The timestamp when the device was first discovered (ISO 8601 format).
  - **lastSeen** (string) - The timestamp when the device was last seen (ISO 8601 format).
  - **extraData** (object) - Additional information specific to the device or discovery method.

#### Response Example
```json
[
  {
    "ip": "192.168.1.1",
    "mac": "aa:bb:cc:dd:ee:ff",
    "displayName": "Router",
    "manufacturer": "Cisco Systems",
    "sources": ["arp-cache", "ssdp"],
    "firstSeen": "2024-01-15T10:30:00Z",
    "lastSeen": "2024-01-15T10:35:00Z",
    "extraData": {"location": "http://192.168.1.1:80/description.xml"}
  }
]
```
```

--------------------------------

### Whosthere Configuration Precedence

Source: https://github.com/ramonvermeulen/whosthere/blob/main/README.md

Illustrates the order of precedence for Whosthere configuration settings, starting from command-line flags (highest priority) down to default values. This helps in understanding how conflicting settings are resolved.

```text
1. Command line flags
2. Environment variables (WHOSTHERE__ prefix)
3. Configuration file (YAML)
4. Default values
```

--------------------------------

### discovery.NewInterfaceInfo - Get Network Interface

Source: https://context7.com/ramonvermeulen/whosthere/llms.txt

Creates interface information for a network interface, auto-detecting the default interface if no name is provided.

```APIDOC
## discovery.NewInterfaceInfo - Get Network Interface

### Description
Creates interface information for a network interface, auto-detecting if no name provided.

### Method
`discovery.NewInterfaceInfo(name string) (*discovery.InterfaceInfo, error)`

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```go
package main

import (
    "fmt"
    "log"

    "github.com/ramonvermeulen/whosthere/pkg/discovery"
)

func main() {
    // Auto-detect default interface
    iface, err := discovery.NewInterfaceInfo("")
    if err != nil {
        log.Fatal(err)
    }
    fmt.Printf("Interface: %s\n", iface.Interface.Name)

    // Or specify a specific interface
    specificIface, err := discovery.NewInterfaceInfo("en0") // macOS
    if err != nil {
        log.Fatalf("Interface not found: %v", err)
    }
    fmt.Printf("Specific Interface: %s\n", specificIface.Interface.Name)
}
```

### Response
#### Success Response (200)
Returns a pointer to a `discovery.InterfaceInfo` object containing network interface details.

#### Response Example
```json
{
  "Interface": {
    "Name": "eth0",
    "HardwareAddr": "00:11:22:33:44:55",
    "Flags": 1024
  },
  "IPv4Addr": "192.168.1.50",
  "IPv4Net": "192.168.1.0/24"
}
```
```

--------------------------------

### GET /devices/{ip} - Get Device Details

Source: https://context7.com/ramonvermeulen/whosthere/llms.txt

Retrieves detailed information for a specific network device identified by its IP address. This is useful for inspecting a single device.

```APIDOC
## GET /devices/{ip}

### Description
Returns details for a specific device by IP address.

### Method
GET

### Endpoint
/devices/{ip}

### Parameters
#### Path Parameters
- **ip** (string) - Required - The IP address of the device to retrieve details for.

#### Query Parameters
None

#### Request Body
None

### Response
#### Success Response (200)
- **ip** (string) - The IP address of the device.
- **mac** (string) - The MAC address of the device.
- **displayName** (string) - A human-readable name for the device.
- **manufacturer** (string) - The manufacturer of the device.
- **sources** (array of strings) - The discovery methods used for this device (e.g., "mdns", "ssdp").
- **firstSeen** (string) - The timestamp when the device was first discovered (ISO 8601 format).
- **lastSeen** (string) - The timestamp when the device was last seen (ISO 8601 format).
- **extraData** (object) - Additional information specific to the device or discovery method.

#### Response Example
```json
{
  "ip": "192.168.1.100",
  "mac": "11:22:33:44:55:66",
  "displayName": "Living Room Speaker",
  "manufacturer": "Google Inc",
  "sources": ["mdns", "ssdp"],
  "firstSeen": "2024-01-15T10:30:00Z",
  "lastSeen": "2024-01-15T10:35:00Z",
  "extraData": {"md": "Google Home Mini"}
}
```
```

--------------------------------

### Run Whosthere Daemon Mode with HTTP API

Source: https://context7.com/ramonvermeulen/whosthere/llms.txt

Starts Whosthere as a background service that continuously scans the network and exposes device data via a REST API. Allows specifying a custom port for the API.

```bash
# Start daemon on default port 8080
whosthere daemon

# Start daemon on custom port
whosthere daemon --port=9000
```

--------------------------------

### Run Whosthere Daemon

Source: https://github.com/ramonvermeulen/whosthere/blob/main/README.md

Starts Whosthere in daemon mode, exposing an HTTP API on port 8080. This allows other applications to interact with Whosthere programmatically in the background.

```bash
whosthere daemon --port=8080
```

--------------------------------

### Get Network Interface Info with discovery.NewInterfaceInfo

Source: https://context7.com/ramonvermeulen/whosthere/llms.txt

Creates interface information for a network interface. If no name is provided, it auto-detects the default interface. It returns details about the interface, including its name, IPv4 address, and subnet. This is useful for network-related operations.

```go
package main

import (
    "fmt"
    "log"

    "github.com/ramonvermeulen/whosthere/pkg/discovery"
)

func main() {
    // Auto-detect default interface
    iface, err := discovery.NewInterfaceInfo("")
    if err != nil {
        log.Fatal(err)
    }

    fmt.Printf("Interface: %s\n", iface.Interface.Name)
    fmt.Printf("IPv4 Address: %s\n", iface.IPv4Addr)
    fmt.Printf("Subnet: %s\n", iface.IPv4Net)

    // Or specify a specific interface
    specificIface, err := discovery.NewInterfaceInfo("en0") // macOS
    // specificIface, err := discovery.NewInterfaceInfo("eth0") // Linux
    if err != nil {
        log.Fatalf("Interface not found: %v", err)
    }

    fmt.Printf("Specific Interface: %s\n", specificIface.Interface.Name)
}
```

--------------------------------

### GET /health - Health Check

Source: https://context7.com/ramonvermeulen/whosthere/llms.txt

Checks the operational status of the Whosthere daemon. Returns 'OK' if the service is running correctly.

```APIDOC
## GET /health

### Description
Returns the service health status.

### Method
GET

### Endpoint
/health

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Response
#### Success Response (200)
- **status** (string) - The health status of the service. Expected value is 'OK'.

#### Response Example
```
OK
```
```

--------------------------------

### Whosthere Daemon Mode HTTP API Endpoints

Source: https://github.com/ramonvermeulen/whosthere/blob/main/README.md

This section outlines the HTTP API endpoints available when Whosthere is running in daemon mode. It includes GET requests for retrieving lists of discovered devices, details of specific devices by IP, and a health check endpoint.

```http
GET /devices
GET /device/{ip}
GET /health
```

--------------------------------

### Build Whosthere from Source

Source: https://github.com/ramonvermeulen/whosthere/blob/main/README.md

Builds the Whosthere tool from its source code. This involves cloning the repository and running the `make build` command, typically used for development or when pre-built binaries are not available.

```bash
git clone https://github.com/ramonvermeulen/whosthere.git
cd whosthere
make build
```

--------------------------------

### Sort IP Addresses Numerically in Go

Source: https://context7.com/ramonvermeulen/whosthere/llms.txt

Demonstrates how to sort a slice of IP addresses numerically using the `discovery.CompareIPs` function from the whosthere library. This ensures correct sorting order for IP addresses, unlike lexicographical sorting.

```go
package main

import (
    "fmt"
    "net"
    "sort"

    "github.com/ramonvermeulen/whosthere/pkg/discovery"
)

func main() {
    ips := []net.IP{
        net.ParseIP("192.168.1.100"),
        net.ParseIP("192.168.1.2"),
        net.ParseIP("192.168.1.50"),
        net.ParseIP("192.168.1.10"),
        net.ParseIP("10.0.0.1"),
    }

    // Sort IPs numerically (not lexicographically)
    sort.Slice(ips, func(i, j int) bool {
        return discovery.CompareIPs(ips[i], ips[j])
    })

    fmt.Println("Sorted IPs:")
    for _, ip := range ips {
        fmt.Printf("  %s\n", ip)
    }
    // Output:
    //   10.0.0.1
    //   192.168.1.2
    //   192.168.1.10
    //   192.168.1.50
    //   192.168.1.100
}
```

--------------------------------

### Create Discovery Engine with Go

Source: https://context7.com/ramonvermeulen/whosthere/llms.txt

Creates and configures a new discovery engine for network scanning. It allows for the inclusion of various scanners (ARP, mDNS, SSDP), a sweeper for ARP cache population, an OUI registry for manufacturer lookups, and configurable scan intervals and timeouts. Dependencies include standard Go libraries and specific whosthere packages.

```go
package main

import (
    "context"
    "fmt"
    "log"
    "time"

    "github.com/ramonvermeulen/whosthere/pkg/discovery"
    "github.com/ramonvermeulen/whosthere/pkg/discovery/oui"
    "github.com/ramonvermeulen/whosthere/pkg/discovery/scanners/arp"
    "github.com/ramonvermeulen/whosthere/pkg/discovery/scanners/mdns"
    "github.com/ramonvermeulen/whosthere/pkg/discovery/scanners/ssdp"
    "github.com/ramonvermeulen/whosthere/pkg/discovery/sweeper"
)

func main() {
    ctx := context.Background()

    // Auto-detect network interface (or specify "en0", "eth0", etc.)
    iface, err := discovery.NewInterfaceInfo("")
    if err != nil {
        log.Fatal(err)
    }
    fmt.Printf("Using interface: %s (%s)\n", iface.Interface.Name, iface.IPv4Addr)

    // Create scanners
    arpScanner, _ := arp.New(iface)
    mdnsScanner, _ := mdns.New(iface)
    ssdpScanner := ssdp.New(iface)

    // Create sweeper to populate ARP cache
    sw, _ := sweeper.New(
        sweeper.WithSweeperInterface(iface),
        sweeper.WithSweeperInterval(5*time.Minute),
        sweeper.WithSweeperTimeout(20*time.Second),
    )

    // Create OUI registry for manufacturer lookups
    ouiRegistry, _ := oui.New(ctx)

    // Build engine with all components
    engine, err := discovery.NewEngine(
        discovery.WithInterface(iface),
        discovery.WithScanners(arpScanner, mdnsScanner, ssdpScanner),
        discovery.WithSweeper(sw),
        discovery.WithOUIRegistry(ouiRegistry),
        discovery.WithScanInterval(20*time.Second),
        discovery.WithScanTimeout(10*time.Second),
    )
    if err != nil {
        log.Fatal(err)
    }

    // Engine is ready to use
    fmt.Println("Discovery engine created successfully")
}
```

--------------------------------

### Run Whosthere TUI

Source: https://github.com/ramonvermeulen/whosthere/blob/main/README.md

Launches the Whosthere tool in its interactive Terminal User Interface (TUI) mode. This allows for real-time network discovery and exploration.

```bash
whosthere
```

--------------------------------

### Display Whosthere Help

Source: https://github.com/ramonvermeulen/whosthere/blob/main/README.md

Displays the help message for the Whosthere command-line tool, listing all available commands, subcommands, and options. This is essential for understanding the full range of functionalities.

```bash
whosthere --help
```

--------------------------------

### SSDP/UPnP Scanner in Go

Source: https://context7.com/ramonvermeulen/whosthere/llms.txt

Scans for devices using the Simple Service Discovery Protocol (SSDP), commonly found in smart home and media devices. It requires a context with a timeout and returns discovered devices with their IP addresses, display names, and optional location and server information.

```go
package main

import (
    "context"
    "fmt"
    "time"

    "github.com/ramonvermeulen/whosthere/pkg/discovery"
    "github.com/ramonvermeulen/whosthere/pkg/discovery/scanners/ssdp"
)

func main() {
    iface, _ := discovery.NewInterfaceInfo("")

    scanner := ssdp.New(iface)

    fmt.Printf("Scanner name: %s\n", scanner.Name()) // "ssdp"

    // SSDP requires a deadline context
    ctx, cancel := context.WithTimeout(context.Background(), 5*time.Second)
    defer cancel()

    devices := make(chan *discovery.Device, 100)
    go func() {
        _ = scanner.Scan(ctx, devices)
        close(devices)
    }()

    // SSDP provides location URLs and server info
    for device := range devices {
        fmt.Printf("SSDP: %s - %s\n", device.IP(), device.DisplayName())
        if loc, ok := device.ExtraData()["location"]; ok {
            fmt.Printf("  Location: %s\n", loc)
        }
        if server, ok := device.ExtraData()["server"]; ok {
            fmt.Printf("  Server: %s\n", server)
        }
    }
}
```

--------------------------------

### Scan and Output JSON

Source: https://github.com/ramonvermeulen/whosthere/blob/main/README.md

Performs a network scan with a 5-second timeout and outputs the discovered devices in a pretty-printed JSON format to a file named 'devices.json'. This is useful for programmatic analysis of network data.

```bash
whosthere scan -t 5 --json --pretty > devices.json
```

--------------------------------

### Configuration File

Source: https://github.com/ramonvermeulen/whosthere/blob/main/README.md

Details on the configuration file structure and options for Whosthere.

```APIDOC
## Configuration File

Whosthere looks for the configuration file in the following order, using the first one found:

1. Path specified via `--config` flag or `WHOSTHERE_CONFIG` environment variable
1. `$XDG_CONFIG_HOME/whosthere/config.yaml` (if `XDG_CONFIG_HOME` is set)
1. `~/.config/whosthere/config.yaml` (default location)

**Example configuration:**

```yaml
# Uncomment the next line to configure a specific network interface - uses OS default if not set
# network_interface: eth0

# How often to run discovery scans
scan_interval: 20s

# Maximum timeout for each scan, recommended to be less than the scan interval
scan_timeout: 10s

scanners:
  mdns:
    enabled: true
  ssdp:
    enabled: true
  arp:
    enabled: true

sweeper:
  enabled: true
  interval: 5m
  timeout: 20s

port_scanner:
  timeout: 5s
  # List of TCP ports to scan on discovered devices
  tcp: [21, 22, 23, 25, 80, 110, 135, 139, 143, 389, 443, 445, 993, 995, 1433, 1521, 3306, 3389, 5432, 5900, 8080, 8443, 9000, 9090, 9200, 9300, 10000, 27017]

splash:
  enabled: true
  delay: 1s

theme:
  # When disabled, the TUI will use the terminal it's default ANSI colors
  # Also see the NO_COLOR environment variable to completely disable ANSI colors
  enabled: true

  # See the complete list of available themes at https://github.com/ramonvermeulen/whosthere/tree/main/internal/ui/theme/theme.go
  # Set name to "custom" to use the custom colors below
  # For any color that is not configured it will take the default theme value as fallback
  name: default

  # Disable ANSI colors completely, overrides theme.enabled
  # Can also be set via NO_COLOR or WHOSTHERE__THEME__NO_COLOR environment variables
  # no_color: false

  # Custom theme colors (uncomment and set name: custom to use)
  # primitive_background_color: "#000a1a"
  # contrast_background_color: "#001a33"
  # more_contrast_background_color: "#003366"
  # border_color: "#0088ff"
  # title_color: "#00ffff"
  # graphics_color: "#00ffaa"
  # primary_text_color: "#cceeff"
  # secondary_text_color: "#6699ff"
  # tertiary_text_color: "#ffaa00"
  # inverse_text_color: "#000a1a"
  # contrast_secondary_text_color: "#88ddff"
```
```

--------------------------------

### Themes

Source: https://github.com/ramonvermeulen/whosthere/blob/main/README.md

Information on configuring and using themes in Whosthere.

```APIDOC
## Themes

Theme can be configured via the configuration file, or at runtime via the `CTRL+t` key binding. A complete list of available themes can be found [**here**](https://github.com/ramonvermeulen/whosthere/blob/main/internal/ui/theme/theme.go), feel free to open a PR to add your own theme!

Example of theme configuration:

```yaml
theme:
  enabled: true
  name: cyberpunk
```

When the `name` is set to `custom`, the other color options can be used to create your own custom theme. When the `enabled` option is set to `false`, the TUI will use the terminal's default ANSI colors. When `NO_COLOR` environment variable is set, all ANSI colors will be disabled.
```

--------------------------------

### Perform Single Synchronous Scan with Go

Source: https://context7.com/ramonvermeulen/whosthere/llms.txt

Executes a single, one-time network scan and returns all discovered devices synchronously. This function allows for setting a timeout for the scan operation. The results include statistics about the scan and a list of discovered devices, which can be printed in a table format or as JSON. Requires a pre-configured discovery engine.

```go
package main

import (
    "context"
    "encoding/json"
    "fmt"
    "log"
    "os"
    "time"

    "github.com/ramonvermeulen/whosthere/pkg/discovery"
)

func main() {
    // Assume engine is already created
    engine, _ := createEngine()

    // Set a timeout for the scan
    ctx, cancel := context.WithTimeout(context.Background(), 15*time.Second)
    defer cancel()

    // Perform synchronous scan
    results, err := engine.Scan(ctx)
    if err != nil {
        log.Fatal(err)
    }

    // Print statistics
    fmt.Printf("Discovered %d devices in %v\n\n",
        results.Stats.Count, results.Stats.Duration)

    // Print devices in table format
    fmt.Printf("%-15s %-17s %-20s %s\n", "IP", "MAC", "Manufacturer", "Name")
    fmt.Println(strings.Repeat("-", 80))

    for _, dev := range results.Devices {
        fmt.Printf("%-15s %-17s %-20s %s\n",
            dev.IP(), dev.MAC(), dev.Manufacturer(), dev.DisplayName())
    }

    // Or output as JSON
    jsonOutput, _ := json.MarshalIndent(results, "", "  ")
    os.Stdout.Write(jsonOutput)
}
```

--------------------------------

### Fetch All Discovered Devices via HTTP API

Source: https://context7.com/ramonvermeulen/whosthere/llms.txt

Retrieves a JSON array of all devices currently discovered on the network from the Whosthere daemon. Includes details like IP, MAC, display name, manufacturer, and timestamps.

```bash
# Fetch all devices
curl http://localhost:8080/devices

# Example response:
# [
#   {
#     "ip": "192.168.1.1",
#     "mac": "aa:bb:cc:dd:ee:ff",
#     "displayName": "Router",
#     "manufacturer": "Cisco Systems",
#     "sources": ["arp-cache", "ssdp"],
#     "firstSeen": "2024-01-15T10:30:00Z",
#     "lastSeen": "2024-01-15T10:35:00Z",
#     "extraData": {"location": "http://192.168.1.1:80/description.xml"}
#   }
# ]
```

--------------------------------

### Create Device Object with discovery.NewDevice

Source: https://context7.com/ramonvermeulen/whosthere/llms.txt

Creates a new device object with an IP address and allows setting various properties like MAC address, display name, manufacturer, and extra data. It also supports merging information from other device objects. This function is intended for custom scanner implementations.

```go
package main

import (
    "fmt"
    "net"
    "time"

    "github.com/ramonvermeulen/whosthere/pkg/discovery"
)

func main() {
    // Create a new device
    device := discovery.NewDevice(net.ParseIP("192.168.1.100"))

    // Set device properties
    device.SetMAC("aa:bb:cc:dd:ee:ff")
    device.SetDisplayName("Smart TV")
    device.SetManufacturer("Samsung Electronics")
    device.AddSource("custom-scanner")
    device.AddExtraData("model", "UN55TU8000")
    device.AddExtraData("firmware", "1.2.3")

    // Access device properties (thread-safe)
    fmt.Printf("IP: %s\n", device.IP())
    fmt.Printf("MAC: %s\n", device.MAC())
    fmt.Printf("Name: %s\n", device.DisplayName())
    fmt.Printf("Manufacturer: %s\n", device.Manufacturer())
    fmt.Printf("First Seen: %v\n", device.FirstSeen())
    fmt.Printf("Last Seen: %v\n", device.LastSeen())
    fmt.Printf("Sources: %v\n", device.Sources())
    fmt.Printf("Extra Data: %v\n", device.ExtraData())

    // Merge information from another discovery
    otherDevice := discovery.NewDevice(net.ParseIP("192.168.1.100"))
    otherDevice.SetDisplayName("Samsung Smart TV")
    otherDevice.AddSource("mdns")
    otherDevice.AddExtraData("serial", "ABC123")

    device.Merge(otherDevice)
    // Now device has combined sources: {"custom-scanner", "mdns"}
    // and combined extraData with both model, firmware, and serial
}
```

--------------------------------

### Environment Variables

Source: https://github.com/ramonvermeulen/whosthere/blob/main/README.md

Environment variables that can be used to configure Whosthere.

```APIDOC
## Environment Variables

### General Environment Variables

| Variable           | Description                                                                     |
| ------------------ | ------------------------------------------------------------------------------- |
| `WHOSTHERE_CONFIG` | Path to the configuration file, to be able to overwrite the default location.   |
| `WHOSTHERE_LOG`    | Set the log level (e.g., `debug`, `info`, `warn`, `error`). Defaults to `info`. |
| `NO_COLOR`         | Disable ANSI colors in the TUI.                                                 |

### Configuration via Environment Variables

Any configuration option that is available in the YAML configuration, can be set via environment variables using the
`WHOSTHERE__` prefix (note the double underscore). Nested configuration keys are separated by double underscores, and
keys are case-insensitive.

Examples:

- `WHOSTHERE__SPLASH__ENABLED=false` - Disable the splash screen, equivalent to `splash.enabled: false` in the YAML config
- `WHOSTHERE__SPLASH__DELAY=2s` - Set splash screen delay to 2 seconds, equivalent to `splash.delay: 2s` in the YAML config
- `WHOSTHERE__SCAN_INTERVAL=30s` - Set scan interval to 30 seconds, equivalent to `scan_interval: 30s` in the YAML config
- `WHOSTHERE__SCANNERS__MDNS__ENABLED=false` - Disable mDNS scanner, equivalent to `scanners.mdns.enabled: false` in the YAML config
- `WHOSTHERE__PORT_SCANNER__TCP=80,443,8080` - Set custom TCP ports to scan, equivalent to `port_scanner.tcp: [80, 443, 8080]` in the YAML config
- `WHOSTHERE__THEME__NAME=cyberpunk` - Set theme to cyberpunk, equivalent to `theme.name: cyberpunk` in the YAML config
```

--------------------------------

### Run Whosthere Scan CLI

Source: https://github.com/ramonvermeulen/whosthere/blob/main/README.md

Executes a single network scan using the Whosthere command-line interface (CLI) with a timeout of 5 seconds. The results are printed to standard output.

```bash
whosthere scan -t 5
```

--------------------------------

### Multicast DNS Scanner with mdns.Scanner

Source: https://context7.com/ramonvermeulen/whosthere/llms.txt

Discovers devices advertising via mDNS (Bonjour/Avahi). This scanner provides device names and service metadata. It's useful for discovering devices on a local network that support mDNS. The results include IP, display name, manufacturer, and extra data.

```go
package main

import (
    "context"
    "fmt"
    "time"

    "github.com/ramonvermeulen/whosthere/pkg/discovery"
    "github.com/ramonvermeulen/whosthere/pkg/discovery/scanners/mdns"
)

func main() {
    iface, _ := discovery.NewInterfaceInfo("")

    scanner, err := mdns.New(iface)
    if err != nil {
        panic(err)
    }

    fmt.Printf("Scanner name: %s\n", scanner.Name()) // "mdns"

    ctx, cancel := context.WithTimeout(context.Background(), 10*time.Second)
    defer cancel()

    devices := make(chan *discovery.Device, 100)
    go func() {
        _ = scanner.Scan(ctx, devices)
        close(devices)
    }()

    // mDNS provides rich device information
    for device := range devices {
        fmt.Printf("mDNS: %s - %s (%s)\n",
            device.IP(),
            device.DisplayName(),
            device.Manufacturer())
        for k, v := range device.ExtraData() {
            fmt.Printf("  %s: %s\n", k, v)
        }
    }
}
```

--------------------------------

### TCP Port Scanner in Go

Source: https://context7.com/ramonvermeulen/whosthere/llms.txt

Scans TCP ports on a specified IP address to identify running services. It allows configuration of the number of concurrent workers, target IP, a list of ports to scan, and a timeout for each port connection. The scanner streams results, indicating which ports are open.

```go
package main

import (
    "context"
    "fmt"
    "sync"
    "time"

    "github.com/ramonvermeulen/whosthere/pkg/discovery"
)

func main() {
    iface, _ := discovery.NewInterfaceInfo("")

    // Create port scanner with 20 concurrent workers
    scanner := discovery.NewPortScanner(20, iface)

    targetIP := "192.168.1.1"
    ports := []int{21, 22, 23, 80, 443, 3389, 8080}
    timeout := 5 * time.Second

    ctx, cancel := context.WithTimeout(context.Background(), 30*time.Second)
    defer cancel()

    fmt.Printf("Scanning %s for open ports...\n", targetIP)

    var openPorts []int
    var mu sync.Mutex

    err := scanner.Stream(ctx, targetIP, ports, timeout, func(port int) {
        mu.Lock()
        openPorts = append(openPorts, port)
        mu.Unlock()
        fmt.Printf("  Port %d is OPEN\n", port)
    })

    if err != nil && err != context.DeadlineExceeded {
        fmt.Printf("Scan error: %v\n", err)
    }

    fmt.Printf("\nOpen ports on %s: %v\n", targetIP, openPorts)
}
```

--------------------------------

### Run Whosthere Single Scan (CLI)

Source: https://context7.com/ramonvermeulen/whosthere/llms.txt

Executes a one-time network scan with various output formats. Supports JSON, pretty-printed JSON, and disabling specific scanning methods like mDNS or SSDP.

```bash
# Basic scan with table output
whosthere scan

# Scan with JSON output
whosthere scan --json

# Scan with pretty-printed JSON and custom timeout
whosthere scan --json --pretty --timeout 5s > devices.json

# Disable specific scanners
whosthere scan --mdns=false --ssdp=false
whosthere scan --sweeper=false
```

--------------------------------

### mdns.Scanner - Multicast DNS Scanner

Source: https://context7.com/ramonvermeulen/whosthere/llms.txt

Discovers devices advertising via mDNS (Bonjour/Avahi), providing device names and service metadata.

```APIDOC
## mdns.Scanner - Multicast DNS Scanner

### Description
Discovers devices advertising via mDNS (Bonjour/Avahi), providing device names and service metadata.

### Method
`mdns.New(iface *discovery.InterfaceInfo) (*mdns.Scanner, error)`

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```go
package main

import (
    "context"
    "fmt"
    "time"

    "github.com/ramonvermeulen/whosthere/pkg/discovery"
    "github.com/ramonvermeulen/whosthere/pkg/discovery/scanners/mdns"
)

func main() {
    iface, _ := discovery.NewInterfaceInfo("")

    scanner, err := mdns.New(iface)
    if err != nil {
        panic(err)
    }

    ctx, cancel := context.WithTimeout(context.Background(), 10*time.Second)
    defer cancel()

    devices := make(chan *discovery.Device, 100)
    go func() {
        _ = scanner.Scan(ctx, devices)
        close(devices)
    }()

    for device := range devices {
        fmt.Printf("mDNS: %s - %s (%s)\n",
            device.IP(),
            device.DisplayName(),
            device.Manufacturer())
        for k, v := range device.ExtraData() {
            fmt.Printf("  %s: %s\n", k, v)
        }
    }
}
```

### Response
#### Success Response (200)
Returns a pointer to an `mdns.Scanner` object. The `Scan` method returns a channel of `discovery.Device` objects with rich mDNS information.

#### Response Example
```json
{
  "devices": [
    {
      "ip": "192.168.1.101",
      "displayName": "Living Room Speaker",
      "manufacturer": "Sonos",
      "extraData": {
        "model": "Sonos One",
        "serial": "XYZ789"
      }
    }
  ]
}
```
```

--------------------------------

### Fetch Specific Device Details via HTTP API

Source: https://context7.com/ramonvermeulen/whosthere/llms.txt

Retrieves detailed information for a specific device identified by its IP address from the Whosthere daemon. Provides comprehensive data about the target device.

```bash
# Fetch specific device
curl http://localhost:8080/devices/192.168.1.100

# Example response:
# {
#   "ip": "192.168.1.100",
#   "mac": "11:22:33:44:55:66",
#   "displayName": "Living Room Speaker",
#   "manufacturer": "Google Inc",
#   "sources": ["mdns", "ssdp"],
#   "firstSeen": "2024-01-15T10:30:00Z",
#   "lastSeen": "2024-01-15T10:35:00Z",
#   "extraData": {"md": "Google Home Mini"}
# }
```

--------------------------------

### discovery.NewDevice - Create Device Object

Source: https://context7.com/ramonvermeulen/whosthere/llms.txt

Creates a new device object with an IP address. This is used by custom scanner implementations to represent discovered network devices.

```APIDOC
## discovery.NewDevice - Create Device Object

### Description
Creates a new device object with an IP address. Used by custom scanner implementations.

### Method
`discovery.NewDevice(ip net.IP) *discovery.Device`

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```go
package main

import (
    "fmt"
    "net"

    "github.com/ramonvermeulen/whosthere/pkg/discovery"
)

func main() {
    device := discovery.NewDevice(net.ParseIP("192.168.1.100"))
    device.SetMAC("aa:bb:cc:dd:ee:ff")
    device.SetDisplayName("Smart TV")
    fmt.Printf("IP: %s\n", device.IP())
}
```

### Response
#### Success Response (200)
Returns a pointer to a `discovery.Device` object.

#### Response Example
```json
{
  "ip": "192.168.1.100",
  "mac": "aa:bb:cc:dd:ee:ff",
  "displayName": "Smart TV"
}
```
```