npm package: @janwirth/ifconfig-reader
Description: Parse ifconfig output and identify network interfaces, especially iPhone USB tethering and local network interfaces
Author: Jan Wirth
Latest version: 1.1.0

# @janwirth/ifconfig-reader

Parse `ifconfig` output and identify the interface that an iPhone can reach this computer on (iPhone USB first, then local network fallback).

## Installation

```bash
bun add @janwirth/ifconfig-reader
```

or with npm:

```bash
npm install @janwirth/ifconfig-reader
```

## Usage

```typescript
import { getNetworkInterfaces } from "@janwirth/ifconfig-reader";

const interfaces = await getNetworkInterfaces();
// Returns:
// {
//   all: NetworkInterface[],              // All network interfaces
//   active: NetworkInterface[],           // Only active interfaces
//   constrained: NetworkInterface[],      // Constrained interfaces (iPhone USB)
//   withInet: NetworkInterface[],         // Interfaces with non-local IPs
//   iPhoneInterface?: NetworkInterface,   // Interface iPhone can reach (USB → local network)
//   localNetworkInterface?: NetworkInterface  // Local network interface
// }
```

### Example Output

```json
{
  "all": [
    {
      "name": "en0",
      "flags": ["UP", "BROADCAST", "SMART", "RUNNING"],
      "mtu": 1500,
      "ether": "ee:ad:59:84:82:eb",
      "inet": "192.168.192.248",
      "netmask": "0xffffff00",
      "broadcast": "192.168.192.255",
      "status": "active"
    },
    {
      "name": "en5",
      "flags": ["UP", "BROADCAST", "RUNNING"],
      "mtu": 1500,
      "isConstrained": true, // iPhone USB tethering
      "inet": "169.254.57.70",
      "status": "active"
    }
  ],
  "active": [
    /* active interfaces */
  ],
  "constrained": [
    /* constrained interfaces (iPhone USB) */
  ],
  "withInet": [
    /* interfaces with non-local IPs */
  ],
  "iPhoneInterface": {
    "name": "en5", // iPhone USB interface (or local network if no USB)
    "inet": "169.254.57.70"
  },
  "localNetworkInterface": {
    "name": "en0",
    "inet": "192.168.192.248"
  }
}
```

## CLI

Run the CLI tool using `bun x` (no installation required):

```bash
bun x @janwirth/ifconfig-reader src/cli.ts all      # Show all interfaces
bun x @janwirth/ifconfig-reader src/cli.ts iphone   # Get iPhone-reachable IP
bun x @janwirth/ifconfig-reader src/cli.ts local    # Get local network IP
bun x @janwirth/ifconfig-reader src/cli.ts summary  # Human-readable summary
```

For local development (when working in the package directory):

```bash
bun run src/cli.ts all      # Show all interfaces
bun run src/cli.ts iphone   # Get iPhone-reachable IP
bun run src/cli.ts local    # Get local network IP
bun run src/cli.ts summary  # Human-readable summary
```

## API

### `getNetworkInterfaces(): Promise<ParsedInterfaces>`

Get all parsed network interfaces by running `ifconfig` command.

### `getIPhoneReachableIP(): Promise<string | null>`

Get IP address that an iPhone can reach (USB tethering → local network fallback).

### `getLocalNetworkIP(): Promise<string | null>`

Get IP address visible on the local network.

### `parseIfconfig(output: string): ParsedInterfaces`

Parse raw ifconfig output string into structured data.

## Requirements

- Bun >= 1.0.0
- macOS (uses `ifconfig` command)
- TypeScript >= 5.0.0 (peer dependency)

## License

MIT