nbpull 0.1.0__py3-none-any.whl

nbpull-0.1.0.dist-info/METADATA

@@ -0,0 +1,250 @@
+Metadata-Version: 2.4
+Name: nbpull
+Version: 0.1.0
+Summary: 🔍 Read-only CLI tool to pull IPAM data from NetBox
+Keywords: netbox,ipam,network,cli,read-only
+Author: Aditya Patel
+Author-email: Aditya Patel <adityapatel0905@gmail.com>
+License-Expression: GPL-3.0-only
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: System Administrators
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: GNU General Public License v3 (GPLv3)
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: System :: Networking
+Classifier: Topic :: Utilities
+Classifier: Typing :: Typed
+Requires-Dist: httpx>=0.28
+Requires-Dist: pydantic>=2.10
+Requires-Dist: pydantic-settings>=2.7
+Requires-Dist: typer>=0.15
+Requires-Dist: rich>=13.9
+Requires-Python: >=3.13
+Project-URL: Homepage, https://github.com/Champion2005/nbpull
+Project-URL: Documentation, https://github.com/Champion2005/nbpull/tree/main/docs
+Project-URL: Repository, https://github.com/Champion2005/nbpull
+Project-URL: Issues, https://github.com/Champion2005/nbpull/issues
+Project-URL: Changelog, https://github.com/Champion2005/nbpull/blob/main/CHANGELOG.md
+Description-Content-Type: text/markdown
+
+# 🔍 nbpull
+
+[![CI](https://github.com/Champion2005/nbpull/actions/workflows/ci.yml/badge.svg)](https://github.com/Champion2005/nbpull/actions/workflows/ci.yml)
+[![Python 3.13+](https://img.shields.io/badge/python-3.13%2B-blue.svg)](https://www.python.org/downloads/)
+[![License: GPL v3](https://img.shields.io/badge/License-GPLv3-blue.svg)](https://www.gnu.org/licenses/gpl-3.0)
+[![Typed](https://img.shields.io/badge/typing-strict-brightgreen.svg)](https://mypy-lang.org/)
+
+**Read-only CLI tool to pull IPAM data from
+[NetBox](https://netbox.dev).**
+
+> **🔒 Safety guarantee:** nbpull **only reads** data from NetBox. No
+> POST / PUT / PATCH / DELETE requests are ever made. The HTTP client is
+> hardcoded to GET-only — this invariant is enforced by code structure
+> and verified by tests.
+
+---
+
+## ✨ Features
+
+- 📡 **Prefixes** — list and filter IPAM prefixes
+- 🖥️ **IP Addresses** — query IP address allocations
+- 🏷️ **VLANs** — browse VLAN assignments
+- 🔀 **VRFs** — inspect VRF instances
+- 📦 **Batch queries** — check many prefixes at once from a TOML file
+- 🎨 Rich table output (default) or JSON (`--format json`)
+- 🔎 Filter by status, VRF, tenant, site, tag, or free-text search
+- ⚡ Async HTTP with automatic pagination
+- 🔒 Strict typing (mypy strict mode + Pydantic v2)
+
+## 📦 Installation
+
+### With [uv](https://docs.astral.sh/uv/) (recommended)
+
+```bash
+uv tool install nbpull
+```
+
+### With [pipx](https://pipx.pypa.io/)
+
+```bash
+pipx install nbpull
+```
+
+### With pip
+
+```bash
+pip install nbpull
+```
+
+### From source
+
+```bash
+git clone https://github.com/Champion2005/nbpull.git
+cd nbpull
+make install   # uses uv sync
+```
+
+## 🚀 Quick Start
+
+```bash
+# 1. Configure your NetBox connection
+export NETBOX_URL=https://netbox.example.com
+export NETBOX_TOKEN=your_read_only_token
+
+# Or use a .env file:
+cp .env.example .env
+# Edit .env with your values
+
+# 2. Pull data
+nbpull prefixes
+nbpull prefixes --status active --vrf Production
+nbpull ip-addresses --prefix 10.0.0.0/24
+nbpull vlans --site DC1
+nbpull vrfs --tenant Ops
+nbpull batch-prefixes --file my_prefixes.toml --status-only
+```
+
+## 📋 Commands
+
+| Command | Description |
+|---|---|
+| `nbpull prefixes` | List IPAM prefixes |
+| `nbpull ip-addresses` | List IP addresses |
+| `nbpull vlans` | List VLANs |
+| `nbpull vrfs` | List VRFs |
+| `nbpull batch-prefixes` | Query multiple prefixes from a TOML file |
+
+### Common Flags
+
+| Flag | Description |
+|---|---|
+| `--status` | Filter by status (active, reserved, deprecated, container) |
+| `--vrf` | Filter by VRF name |
+| `--tenant` | Filter by tenant name |
+| `--site` | Filter by site name |
+| `--tag` | Filter by tag slug |
+| `--search` / `-s` | Free-text search |
+| `--limit` / `-l` | Max results (default: 50) |
+| `--format` / `-f` | Output format: `table` (default) or `json` |
+| `--verbose` / `-v` | Enable debug logging |
+
+See the full [command reference](docs/commands.md) for all options.
+
+## ⚙️ Configuration
+
+Set these in `.env` or as environment variables:
+
+| Variable | Required | Default | Description |
+|---|---|---|---|
+| `NETBOX_URL` | ✅ | — | NetBox instance URL |
+| `NETBOX_TOKEN` | ✅ | — | API token (read-only recommended) |
+| `NETBOX_PAGE_SIZE` | ❌ | `100` | Results per API page |
+| `NETBOX_TIMEOUT` | ❌ | `30` | Request timeout (seconds) |
+| `NETBOX_VERIFY_SSL` | ❌ | `true` | Verify SSL certificates |
+
+See [docs/configuration.md](docs/configuration.md) for details on
+token setup and SSL options.
+
+## 📦 Batch Queries
+
+Create a TOML file to query multiple prefixes in one run:
+
+```toml
+prefixes = [
+    "10.0.0.0/8",
+    "172.16.0.0/12",
+    "192.168.0.0/16",
+]
+
+[filters]
+# status = "active"
+# vrf = "Production"
+```
+
+```bash
+nbpull batch-prefixes --file prefixes.toml --status-only
+```
+
+## 📐 Architecture
+
+```
+src/netbox_data_puller/
+├── cli.py          # Typer commands + filtering
+├── client.py       # Async GET-only NetBox API client
+├── config.py       # Pydantic Settings (.env)
+├── formatters.py   # Rich table renderers
+└── models/         # Pydantic models per resource
+    ├── prefix.py
+    ├── ip_address.py
+    ├── vlan.py
+    └── vrf.py
+```
+
+See [docs/architecture.md](docs/architecture.md) for a full breakdown.
+
+## 🛠️ Development
+
+### Prerequisites
+
+- **Python 3.13+**
+- **[uv](https://docs.astral.sh/uv/)** — fast Python package manager
+
+### Setup
+
+```bash
+git clone https://github.com/Champion2005/nbpull.git
+cd nbpull
+make install    # Install dependencies
+```
+
+### Commands
+
+```bash
+make all        # format → lint → typecheck → test
+make test       # unit tests (no network)
+make lint       # ruff linter
+make format     # auto-format with ruff
+make typecheck  # mypy strict mode
+make test-integration  # hits real NetBox API
+```
+
+### Running Tests
+
+Unit tests use mocked HTTP responses and require no network access:
+
+```bash
+make test
+```
+
+Integration tests require `NETBOX_URL` and `NETBOX_TOKEN`:
+
+```bash
+make test-integration
+```
+
+## 🤝 Contributing
+
+Contributions are welcome! Please read
+[CONTRIBUTING.md](CONTRIBUTING.md) before opening a PR.
+
+## 📝 Changelog
+
+See [CHANGELOG.md](CHANGELOG.md) for a history of changes.
+
+## 📄 License
+
+This project is licensed under the
+**GNU General Public License v3.0** — see the [LICENSE](LICENSE) file
+for details.
+
+## 🙏 Acknowledgements
+
+- [NetBox](https://netbox.dev) — the leading open-source IPAM/DCIM
+  platform
+- [Typer](https://typer.tiangolo.com/) — CLI framework
+- [Rich](https://rich.readthedocs.io/) — beautiful terminal formatting
+- [httpx](https://www.python-httpx.org/) — async HTTP client
+- [Pydantic](https://docs.pydantic.dev/) — data validation

nbpull-0.1.0.dist-info/RECORD

@@ -0,0 +1,15 @@
+netbox_data_puller/__init__.py,sha256=7iXthOLjrLHdTZMyYOLcnptqfZ_eJ09QI-B0IdDElc8,102
+netbox_data_puller/cli.py,sha256=25ZgUYkj7nL-1qMqHT8n-1198VUhPcfHzeNgL0KWvO8,12659
+netbox_data_puller/client.py,sha256=jsLGQ8D00e8H_IotmvsTaI72Mh_nWw96hYwF248GGWY,3525
+netbox_data_puller/config.py,sha256=x3OstA8HLeUInL_xkknOneAehdhT5V6Sf_Qh0Z7O92w,582
+netbox_data_puller/formatters.py,sha256=8RNt6Onp4hs3lQX8StNhR5c2mYppXbnTvZUQAq20-2o,9586
+netbox_data_puller/models/__init__.py,sha256=Or2eAaquny9YSpq8PcqbikNyMdI92XqLe69ac1_D9Oc,54
+netbox_data_puller/models/ip_address.py,sha256=_PnieCUhjtSEbjjA1D6akNVl0XLZlGc_Cm07MWqbOMM,593
+netbox_data_puller/models/prefix.py,sha256=d2QEUBTONMCwAtKM5lwMG0J4mPCiM8jsFMI_N02pBFI,1060
+netbox_data_puller/models/vlan.py,sha256=ttKGxAlO3T-g51f3FGBVl80_VV4IZkm9e5ycM1fU7W4,513
+netbox_data_puller/models/vrf.py,sha256=eVE9xPYfDkTpQtN5OcY3Rc104tI30-cuOCQiShrkEx0,405
+netbox_data_puller/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+nbpull-0.1.0.dist-info/WHEEL,sha256=iHtWm8nRfs0VRdCYVXocAWFW8ppjHL-uTJkAdZJKOBM,80
+nbpull-0.1.0.dist-info/entry_points.txt,sha256=l4XI8XvxYl7G1dlhoqbeB9NdPVElzpia0TRIh5VdC50,55
+nbpull-0.1.0.dist-info/METADATA,sha256=6n4C5O52m1t2S1DKR9w9qfbjJ1d4F8NDqz33-FXZ2b8,7075
+nbpull-0.1.0.dist-info/RECORD,,

nbpull-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: uv 0.9.30
+Root-Is-Purelib: true
+Tag: py3-none-any

nbpull-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,3 @@
+[console_scripts]
+nbpull = netbox_data_puller.cli:app
+

netbox_data_puller/__init__.py

@@ -0,0 +1,3 @@
+"""🔍 NetBox Data Puller — Read-only CLI for querying NetBox IPAM data."""
+
+__version__ = "0.1.0"

netbox_data_puller/cli.py

@@ -0,0 +1,467 @@
+"""🖥️ CLI commands for querying NetBox IPAM data.
+
+All commands are READ-ONLY — no data is ever written to NetBox.
+"""
+
+import asyncio
+import logging
+import sys
+from enum import StrEnum
+from pathlib import Path
+from typing import Annotated, Any
+
+import typer
+from rich.console import Console
+from rich.panel import Panel
+from rich.progress import (
+    BarColumn,
+    MofNCompleteColumn,
+    Progress,
+    SpinnerColumn,
+    TextColumn,
+    TimeElapsedColumn,
+)
+from rich.text import Text
+
+from netbox_data_puller.client import NetBoxClient
+from netbox_data_puller.config import Settings
+from netbox_data_puller.formatters import (
+    print_batch_summary,
+    print_ip_addresses,
+    print_json,
+    print_prefixes,
+    print_prefixes_status,
+    print_vlans,
+    print_vrfs,
+)
+from netbox_data_puller.models.ip_address import IPAddress
+from netbox_data_puller.models.prefix import Prefix
+from netbox_data_puller.models.vlan import VLAN
+from netbox_data_puller.models.vrf import VRF
+
+logger = logging.getLogger(__name__)
+console = Console(stderr=True)
+
+app = typer.Typer(
+    name="nbpull",
+    help="🔍 Read-only CLI to pull IPAM data from NetBox.",
+    no_args_is_help=True,
+    rich_markup_mode="rich",
+)
+
+
+# ------------------------------------------------------------------
+# Shared types
+# ------------------------------------------------------------------
+
+
+class OutputFormat(StrEnum):
+    """Output format selector."""
+
+    table = "table"
+    json = "json"
+
+
+# Common option type aliases
+FormatOpt = Annotated[
+    OutputFormat,
+    typer.Option("--format", "-f", help="Output format."),
+]
+StatusOpt = Annotated[
+    str | None,
+    typer.Option(help="Filter by status (e.g. active, reserved)."),
+]
+VRFOpt = Annotated[
+    str | None,
+    typer.Option("--vrf", help="Filter by VRF name."),
+]
+TenantOpt = Annotated[
+    str | None,
+    typer.Option("--tenant", help="Filter by tenant name."),
+]
+SiteOpt = Annotated[
+    str | None,
+    typer.Option("--site", help="Filter by site name."),
+]
+TagOpt = Annotated[
+    str | None,
+    typer.Option("--tag", help="Filter by tag slug."),
+]
+SearchOpt = Annotated[
+    str | None,
+    typer.Option("--search", "-s", help="Free-text search."),
+]
+LimitOpt = Annotated[
+    int,
+    typer.Option("--limit", "-l", help="Maximum results to return."),
+]
+VerboseOpt = Annotated[
+    bool,
+    typer.Option("--verbose", "-v", help="Enable debug logging."),
+]
+StatusOnlyOpt = Annotated[
+    bool,
+    typer.Option(
+        "--status-only",
+        help="Show only prefix and status columns.",
+    ),
+]
+
+
+# ------------------------------------------------------------------
+# Helpers
+# ------------------------------------------------------------------
+
+
+def _build_params(**kwargs: Any) -> dict[str, Any]:
+    """Build API query params, dropping None values."""
+    return {k: v for k, v in kwargs.items() if v is not None}
+
+
+def _get_settings() -> Settings:
+    """Load settings, with a friendly error on misconfiguration."""
+    try:
+        return Settings()
+    except Exception as exc:
+        console.print(
+            f"[bold red]❌ Configuration error:[/bold red] {exc}\n\n"
+            "Make sure NETBOX_URL and NETBOX_TOKEN are set in your "
+            ".env file or environment variables.\n"
+            "See .env.example for reference.",
+        )
+        raise typer.Exit(code=1) from exc
+
+
+def _configure_logging(verbose: bool) -> None:
+    """Set up logging level based on verbosity flag."""
+    level = logging.DEBUG if verbose else logging.WARNING
+    logging.basicConfig(
+        level=level,
+        format="%(asctime)s [%(levelname)s] %(name)s: %(message)s",
+        stream=sys.stderr,
+    )
+
+
+async def _fetch(
+    endpoint: str,
+    params: dict[str, Any],
+) -> list[dict[str, Any]]:
+    """Execute a read-only fetch against NetBox."""
+    settings = _get_settings()
+    async with NetBoxClient(settings) as client:
+        return await client.get(endpoint, params)
+
+
+def _fetch_with_spinner(
+    endpoint: str,
+    params: dict[str, Any],
+    label: str = "Querying NetBox",
+) -> list[dict[str, Any]]:
+    """Fetch with a live spinner shown on stderr."""
+    with Progress(
+        SpinnerColumn("dots"),
+        TextColumn("[bold cyan]{task.description}"),
+        TimeElapsedColumn(),
+        console=console,
+        transient=True,
+    ) as progress:
+        progress.add_task(label, total=None)
+        return asyncio.run(_fetch(endpoint, params))
+
+
+# ------------------------------------------------------------------
+# Commands
+# ------------------------------------------------------------------
+
+
+@app.command()
+def prefixes(
+    status: StatusOpt = None,
+    vrf: VRFOpt = None,
+    tenant: TenantOpt = None,
+    site: SiteOpt = None,
+    tag: TagOpt = None,
+    search: SearchOpt = None,
+    limit: LimitOpt = 50,
+    fmt: FormatOpt = OutputFormat.table,
+    status_only: StatusOnlyOpt = False,
+    verbose: VerboseOpt = False,
+) -> None:
+    """📡 List IPAM prefixes from NetBox."""
+    _configure_logging(verbose)
+    params = _build_params(
+        status=status,
+        vrf=vrf,
+        tenant=tenant,
+        site=site,
+        tag=tag,
+        q=search,
+        limit=limit,
+    )
+    raw = _fetch_with_spinner("ipam/prefixes/", params, "Fetching prefixes")
+    records = [Prefix.model_validate(r) for r in raw]
+
+    if fmt == OutputFormat.json:
+        print_json(records)
+    elif status_only:
+        print_prefixes_status(records)
+    else:
+        print_prefixes(records)
+
+
+@app.command(name="ip-addresses")
+def ip_addresses(
+    status: StatusOpt = None,
+    vrf: VRFOpt = None,
+    tenant: TenantOpt = None,
+    tag: TagOpt = None,
+    search: SearchOpt = None,
+    prefix: Annotated[
+        str | None,
+        typer.Option(
+            "--prefix",
+            help="Filter by parent prefix (e.g. 10.0.0.0/24).",
+        ),
+    ] = None,
+    limit: LimitOpt = 50,
+    fmt: FormatOpt = OutputFormat.table,
+    verbose: VerboseOpt = False,
+) -> None:
+    """🖥️  List IPAM IP addresses from NetBox."""
+    _configure_logging(verbose)
+    params = _build_params(
+        status=status,
+        vrf=vrf,
+        tenant=tenant,
+        tag=tag,
+        q=search,
+        parent=prefix,
+        limit=limit,
+    )
+    raw = _fetch_with_spinner(
+        "ipam/ip-addresses/",
+        params,
+        "Fetching IP addresses",
+    )
+    records = [IPAddress.model_validate(r) for r in raw]
+
+    if fmt == OutputFormat.json:
+        print_json(records)
+    else:
+        print_ip_addresses(records)
+
+
+@app.command()
+def vlans(
+    status: StatusOpt = None,
+    tenant: TenantOpt = None,
+    site: SiteOpt = None,
+    tag: TagOpt = None,
+    search: SearchOpt = None,
+    limit: LimitOpt = 50,
+    fmt: FormatOpt = OutputFormat.table,
+    verbose: VerboseOpt = False,
+) -> None:
+    """🏷️  List IPAM VLANs from NetBox."""
+    _configure_logging(verbose)
+    params = _build_params(
+        status=status,
+        tenant=tenant,
+        site=site,
+        tag=tag,
+        q=search,
+        limit=limit,
+    )
+    raw = _fetch_with_spinner("ipam/vlans/", params, "Fetching VLANs")
+    records = [VLAN.model_validate(r) for r in raw]
+
+    if fmt == OutputFormat.json:
+        print_json(records)
+    else:
+        print_vlans(records)
+
+
+@app.command()
+def vrfs(
+    tenant: TenantOpt = None,
+    tag: TagOpt = None,
+    search: SearchOpt = None,
+    limit: LimitOpt = 50,
+    fmt: FormatOpt = OutputFormat.table,
+    verbose: VerboseOpt = False,
+) -> None:
+    """🔀 List IPAM VRFs from NetBox."""
+    _configure_logging(verbose)
+    params = _build_params(
+        tenant=tenant,
+        tag=tag,
+        q=search,
+        limit=limit,
+    )
+    raw = _fetch_with_spinner("ipam/vrfs/", params, "Fetching VRFs")
+    records = [VRF.model_validate(r) for r in raw]
+
+    if fmt == OutputFormat.json:
+        print_json(records)
+    else:
+        print_vrfs(records)
+
+
+# ------------------------------------------------------------------
+# Batch commands
+# ------------------------------------------------------------------
+
+_DEFAULT_BATCH_FILE = "batch_prefixes.toml"
+
+
+def _load_batch_toml(path: Path) -> dict[str, Any]:
+    """Load and validate a batch-prefixes TOML file."""
+    if not path.exists():
+        console.print(
+            f"[bold red]❌ File not found:[/bold red] {path}\n\n"
+            f"Create a [bold]{_DEFAULT_BATCH_FILE}[/bold] or pass "
+            "--file /path/to/file.toml",
+        )
+        raise typer.Exit(code=1)
+
+    import tomllib
+
+    with path.open("rb") as fh:
+        data = tomllib.load(fh)
+
+    if "prefixes" not in data or not data["prefixes"]:
+        console.print(
+            "[bold red]❌ TOML file must contain a non-empty "
+            "'prefixes' list.[/bold red]",
+        )
+        raise typer.Exit(code=1)
+
+    return data
+
+
+@app.command(name="batch-prefixes")
+def batch_prefixes(
+    file: Annotated[
+        Path,
+        typer.Option(
+            "--file",
+            help=(
+                f"Path to TOML file with prefix list (default: {_DEFAULT_BATCH_FILE})."
+            ),
+        ),
+    ] = Path(_DEFAULT_BATCH_FILE),
+    fmt: FormatOpt = OutputFormat.table,
+    status_only: StatusOnlyOpt = False,
+    verbose: VerboseOpt = False,
+) -> None:
+    """📦 Query NetBox for multiple prefixes defined in a TOML file.
+
+    Reads a list of CIDR prefixes and optional global filters from
+    a TOML file, then queries NetBox for each one.
+
+    Example TOML:
+
+        prefixes = ["10.32.16.0/20", "172.16.0.0/12"]
+
+        [filters]
+
+        status = "active"
+    """
+    _configure_logging(verbose)
+    data = _load_batch_toml(file)
+
+    prefix_list: list[str] = data["prefixes"]
+    global_filters: dict[str, Any] = data.get("filters", {})
+
+    # Header panel
+    header_lines = [
+        f"[bold]Source:[/bold]  [cyan]{file}[/cyan]",
+        f"[bold]Prefixes:[/bold] {len(prefix_list)}",
+    ]
+    if global_filters:
+        header_lines.append(
+            f"[bold]Filters:[/bold] [dim]{global_filters}[/dim]",
+        )
+    console.print()
+    console.print(
+        Panel(
+            "\n".join(header_lines),
+            title="📦 Batch Prefix Query",
+            border_style="cyan",
+            expand=False,
+        ),
+    )
+    console.print()
+
+    # Fetch all prefixes with a progress bar
+    batch_results: list[tuple[str, list[Prefix]]] = []
+    not_found: list[str] = []
+
+    with Progress(
+        SpinnerColumn("dots"),
+        TextColumn("[bold cyan]{task.description}"),
+        BarColumn(bar_width=30),
+        MofNCompleteColumn(),
+        TimeElapsedColumn(),
+        console=console,
+        transient=True,
+    ) as progress:
+        task = progress.add_task(
+            "Querying NetBox",
+            total=len(prefix_list),
+        )
+        for cidr in prefix_list:
+            progress.update(task, description=f"Querying [green]{cidr}[/green]")
+            params = _build_params(q=cidr, **global_filters)
+            raw = asyncio.run(_fetch("ipam/prefixes/", params))
+            records = [Prefix.model_validate(r) for r in raw]
+            if records:
+                batch_results.append((cidr, records))
+            else:
+                not_found.append(cidr)
+            progress.advance(task)
+
+    # Render results
+    if fmt == OutputFormat.json:
+        for cidr, records in batch_results:
+            console.print(
+                f"\n[bold cyan]── {cidr} ──[/bold cyan]",
+                highlight=False,
+            )
+            print_json(records)
+        for cidr in not_found:
+            console.print(
+                f"\n[bold cyan]── {cidr} ──[/bold cyan]",
+                highlight=False,
+            )
+            console.print("[yellow]  ⚠️  No results found.[/yellow]")
+    elif status_only:
+        print_batch_summary(batch_results, not_found)
+    else:
+        for cidr, records in batch_results:
+            console.print(
+                f"\n[bold cyan]── {cidr} ──[/bold cyan]",
+                highlight=False,
+            )
+            print_prefixes(records)
+        for cidr in not_found:
+            console.print(
+                f"\n[bold cyan]── {cidr} ──[/bold cyan]",
+                highlight=False,
+            )
+            console.print("[yellow]  ⚠️  No results found.[/yellow]")
+
+    # Final summary line
+    done = Text()
+    done.append("\n✅ ", style="bold green")
+    done.append(f"{len(batch_results)}", style="bold")
+    done.append(" found")
+    if not_found:
+        done.append("  ·  ", style="dim")
+        done.append(f"⚠️  {len(not_found)}", style="bold yellow")
+        done.append(" not found")
+    console.print(done)
+
+
+if __name__ == "__main__":
+    app()

netbox_data_puller/client.py

@@ -0,0 +1,116 @@
+"""🔒 Read-only async HTTP client for the NetBox REST API.
+
+SAFETY: This client ONLY performs GET requests. No data is ever
+written, modified, or deleted in NetBox. The HTTP method is
+hardcoded — there are no POST/PUT/PATCH/DELETE methods.
+"""
+
+import logging
+from typing import Any
+
+import httpx
+
+from netbox_data_puller.config import Settings
+
+logger = logging.getLogger(__name__)
+
+
+class NetBoxClient:
+    """Async, read-only NetBox API client.
+
+    All requests use HTTP GET. No write operations are exposed
+    or possible through this client.
+    """
+
+    def __init__(self, settings: Settings) -> None:
+        base_url = str(settings.url).rstrip("/")
+        self._base_url = f"{base_url}/api"
+        self._page_size = settings.page_size
+        self._client = httpx.AsyncClient(
+            base_url=self._base_url,
+            headers={
+                "Authorization": f"Token {settings.token}",
+                "Accept": "application/json",
+            },
+            timeout=httpx.Timeout(settings.timeout),
+            verify=settings.verify_ssl,
+        )
+
+    # ------------------------------------------------------------------
+    # Public interface — READ ONLY
+    # ------------------------------------------------------------------
+
+    async def get(
+        self,
+        endpoint: str,
+        params: dict[str, Any] | None = None,
+    ) -> list[dict[str, Any]]:
+        """Fetch all pages of results from a NetBox API endpoint.
+
+        Uses HTTP GET exclusively. Automatically follows pagination.
+
+        Args:
+            endpoint: API path relative to /api/ (e.g. "ipam/prefixes/").
+            params: Optional query parameters for filtering.
+
+        Returns:
+            Flat list of result dicts across all pages.
+        """
+        results: list[dict[str, Any]] = []
+        query = {**(params or {}), "limit": self._page_size, "offset": 0}
+
+        while True:
+            logger.debug("GET %s params=%s", endpoint, query)
+            response = await self._client.get(endpoint, params=query)
+            response.raise_for_status()
+            data = response.json()
+
+            results.extend(data.get("results", []))
+
+            if data.get("next") is None:
+                break
+
+            query["offset"] = query["offset"] + self._page_size
+
+        logger.info(
+            "Fetched %d records from %s",
+            len(results),
+            endpoint,
+        )
+        return results
+
+    async def get_single(
+        self,
+        endpoint: str,
+        params: dict[str, Any] | None = None,
+    ) -> dict[str, Any]:
+        """Fetch a single object from a NetBox API endpoint.
+
+        Uses HTTP GET exclusively.
+
+        Args:
+            endpoint: API path (e.g. "ipam/prefixes/42/").
+            params: Optional query parameters.
+
+        Returns:
+            Single result dict.
+        """
+        logger.debug("GET %s params=%s", endpoint, params)
+        response = await self._client.get(endpoint, params=params)
+        response.raise_for_status()
+        result: dict[str, Any] = response.json()
+        return result
+
+    # ------------------------------------------------------------------
+    # Lifecycle
+    # ------------------------------------------------------------------
+
+    async def close(self) -> None:
+        """Close the underlying HTTP connection pool."""
+        await self._client.aclose()
+
+    async def __aenter__(self) -> "NetBoxClient":
+        return self
+
+    async def __aexit__(self, *_: Any) -> None:
+        await self.close()

netbox_data_puller/config.py

@@ -0,0 +1,24 @@
+"""⚙️ Configuration via environment variables / .env file."""
+
+from pydantic import HttpUrl
+from pydantic_settings import BaseSettings, SettingsConfigDict
+
+
+class Settings(BaseSettings):
+    """NetBox connection settings.
+
+    Reads from environment variables or a .env file in the project root.
+    """
+
+    model_config = SettingsConfigDict(
+        env_file=".env",
+        env_file_encoding="utf-8",
+        env_prefix="NETBOX_",
+        case_sensitive=False,
+    )
+
+    url: HttpUrl
+    token: str
+    page_size: int = 100
+    timeout: int = 30
+    verify_ssl: bool = True

netbox_data_puller/formatters.py

@@ -0,0 +1,321 @@
+"""🎨 Rich table formatters for NetBox IPAM resources."""
+
+import json
+from typing import Any
+
+from rich.console import Console
+from rich.table import Table
+from rich.text import Text
+
+console = Console()
+
+# ------------------------------------------------------------------
+# Helpers
+# ------------------------------------------------------------------
+
+
+def _display_or_dash(obj: Any) -> str:
+    """Extract display name from a nested ref, or return '—'."""
+    if obj is None:
+        return "—"
+    if hasattr(obj, "display"):
+        return str(obj.display)
+    return str(obj)
+
+
+def _tags_str(tags: list[Any]) -> str:
+    """Format tags as a comma-separated string."""
+    return ", ".join(t.display for t in tags) if tags else "—"
+
+
+def _styled_status(obj: Any) -> Text:
+    """Return a Rich Text object with colour-coded status."""
+    if obj is None:
+        return Text("—", style="dim")
+    label = str(obj.display) if hasattr(obj, "display") else str(obj)
+    value = obj.value if hasattr(obj, "value") else ""
+    style_map = {
+        "active": "bold green",
+        "reserved": "bold yellow",
+        "deprecated": "bold red",
+        "container": "bold blue",
+        "dhcp": "bold magenta",
+        "slaac": "bold magenta",
+    }
+    return Text(label, style=style_map.get(value, ""))
+
+
+# ------------------------------------------------------------------
+# JSON output
+# ------------------------------------------------------------------
+
+
+def print_json(records: list[Any]) -> None:
+    """Print records as formatted JSON to stdout."""
+    data = [
+        r.model_dump(mode="json") if hasattr(r, "model_dump") else r for r in records
+    ]
+    console.print_json(json.dumps(data, indent=2, default=str))
+
+
+# ------------------------------------------------------------------
+# Prefixes
+# ------------------------------------------------------------------
+
+
+def print_prefixes(records: list[Any]) -> None:
+    """Render prefixes as a Rich table."""
+    table = Table(
+        title="📡 IPAM Prefixes",
+        show_lines=True,
+        header_style="bold cyan",
+        title_style="bold",
+    )
+    table.add_column("ID", style="dim", justify="right")
+    table.add_column("Prefix", style="bold green")
+    table.add_column("Status")
+    table.add_column("VRF")
+    table.add_column("Tenant")
+    table.add_column("Site")
+    table.add_column("VLAN")
+    table.add_column("Role")
+    table.add_column("Pool", justify="center")
+    table.add_column("Description", max_width=30)
+    table.add_column("Tags")
+
+    for r in records:
+        table.add_row(
+            str(r.id),
+            r.prefix,
+            _styled_status(r.status),
+            _display_or_dash(r.vrf),
+            _display_or_dash(r.tenant),
+            _display_or_dash(r.site),
+            _display_or_dash(r.vlan),
+            _display_or_dash(r.role),
+            "✅" if r.is_pool else "—",
+            r.description or "—",
+            _tags_str(r.tags),
+        )
+
+    console.print(table)
+    console.print(f"[dim]  {len(records)} prefixes[/dim]\n")
+
+
+def print_prefixes_status(records: list[Any]) -> None:
+    """Render a compact prefix + status table."""
+    table = Table(
+        title="📡 Prefix Status",
+        show_lines=True,
+        header_style="bold cyan",
+        title_style="bold",
+    )
+    table.add_column("Prefix", style="bold green")
+    table.add_column("Status")
+
+    for r in records:
+        table.add_row(r.prefix, _styled_status(r.status))
+
+    console.print(table)
+    console.print(f"[dim]  {len(records)} prefixes[/dim]\n")
+
+
+def print_batch_summary(
+    results: list[tuple[str, list[Any]]],
+    not_found: list[str],
+) -> None:
+    """Render a single consolidated table for batch --status-only.
+
+    Groups results by queried CIDR and shows the direct match status
+    prominently, with parent containers shown underneath in dim text.
+    """
+    table = Table(
+        title="📦 Batch Prefix Status",
+        show_lines=True,
+        header_style="bold cyan",
+        title_style="bold",
+        padding=(0, 1),
+    )
+    table.add_column("Queried Prefix", style="bold white")
+    table.add_column("Matched Prefix", style="green")
+    table.add_column("Status")
+    table.add_column("Site")
+    table.add_column("Tenant")
+    table.add_column("Description", max_width=32)
+
+    for cidr, records in results:
+        # Separate direct match from parent containers
+        direct = [r for r in records if r.prefix == cidr]
+        parents = [r for r in records if r.prefix != cidr]
+
+        if direct:
+            for r in direct:
+                table.add_row(
+                    cidr,
+                    r.prefix,
+                    _styled_status(r.status),
+                    _display_or_dash(r.site),
+                    _display_or_dash(r.tenant),
+                    r.description or "—",
+                )
+        elif parents:
+            # No exact match — show closest parent
+            closest = max(parents, key=lambda p: _prefix_len(p.prefix))
+            table.add_row(
+                cidr,
+                Text(f"≈ {closest.prefix}", style="yellow"),
+                _styled_status(closest.status),
+                _display_or_dash(closest.site),
+                _display_or_dash(closest.tenant),
+                closest.description or "—",
+            )
+
+    for cidr in not_found:
+        table.add_row(
+            cidr,
+            Text("—", style="dim"),
+            Text("Not Found", style="bold red"),
+            "—",
+            "—",
+            "—",
+        )
+
+    console.print()
+    console.print(table)
+
+    # Compact legend
+    legend = (
+        "[dim]Status: "
+        "[bold green]● Active[/bold green]  "
+        "[bold blue]● Container[/bold blue]  "
+        "[bold yellow]● Reserved[/bold yellow]  "
+        "[bold red]● Deprecated[/bold red]"
+        "[/dim]"
+    )
+    console.print(legend)
+
+
+def _prefix_len(prefix: str) -> int:
+    """Extract the CIDR mask length for sorting."""
+    try:
+        return int(prefix.split("/")[1])
+    except (IndexError, ValueError):
+        return 0
+
+
+# ------------------------------------------------------------------
+# IP Addresses
+# ------------------------------------------------------------------
+
+
+def print_ip_addresses(records: list[Any]) -> None:
+    """Render IP addresses as a Rich table."""
+    table = Table(
+        title="🖥️  IPAM IP Addresses",
+        show_lines=True,
+        header_style="bold cyan",
+        title_style="bold",
+    )
+    table.add_column("ID", style="dim", justify="right")
+    table.add_column("Address", style="bold green")
+    table.add_column("Status")
+    table.add_column("VRF")
+    table.add_column("Tenant")
+    table.add_column("DNS Name")
+    table.add_column("Role")
+    table.add_column("Description", max_width=30)
+    table.add_column("Tags")
+
+    for r in records:
+        table.add_row(
+            str(r.id),
+            r.address,
+            _styled_status(r.status),
+            _display_or_dash(r.vrf),
+            _display_or_dash(r.tenant),
+            r.dns_name or "—",
+            _display_or_dash(r.role),
+            r.description or "—",
+            _tags_str(r.tags),
+        )
+
+    console.print(table)
+    console.print(f"[dim]  {len(records)} IP addresses[/dim]\n")
+
+
+# ------------------------------------------------------------------
+# VLANs
+# ------------------------------------------------------------------
+
+
+def print_vlans(records: list[Any]) -> None:
+    """Render VLANs as a Rich table."""
+    table = Table(
+        title="🏷️  IPAM VLANs",
+        show_lines=True,
+        header_style="bold cyan",
+        title_style="bold",
+    )
+    table.add_column("ID", style="dim", justify="right")
+    table.add_column("VID", justify="right", style="bold")
+    table.add_column("Name", style="bold green")
+    table.add_column("Status")
+    table.add_column("Tenant")
+    table.add_column("Site")
+    table.add_column("Group")
+    table.add_column("Role")
+    table.add_column("Description", max_width=30)
+    table.add_column("Tags")
+
+    for r in records:
+        table.add_row(
+            str(r.id),
+            str(r.vid),
+            r.name,
+            _styled_status(r.status),
+            _display_or_dash(r.tenant),
+            _display_or_dash(r.site),
+            _display_or_dash(r.group),
+            _display_or_dash(r.role),
+            r.description or "—",
+            _tags_str(r.tags),
+        )
+
+    console.print(table)
+    console.print(f"[dim]  {len(records)} VLANs[/dim]\n")
+
+
+# ------------------------------------------------------------------
+# VRFs
+# ------------------------------------------------------------------
+
+
+def print_vrfs(records: list[Any]) -> None:
+    """Render VRFs as a Rich table."""
+    table = Table(
+        title="🔀 IPAM VRFs",
+        show_lines=True,
+        header_style="bold cyan",
+        title_style="bold",
+    )
+    table.add_column("ID", style="dim", justify="right")
+    table.add_column("Name", style="bold green")
+    table.add_column("RD")
+    table.add_column("Tenant")
+    table.add_column("Enforce Unique", justify="center")
+    table.add_column("Description", max_width=30)
+    table.add_column("Tags")
+
+    for r in records:
+        table.add_row(
+            str(r.id),
+            r.name,
+            r.rd or "—",
+            _display_or_dash(r.tenant),
+            "✅" if r.enforce_unique else "❌",
+            r.description or "—",
+            _tags_str(r.tags),
+        )
+
+    console.print(table)
+    console.print(f"[dim]  {len(records)} VRFs[/dim]\n")

netbox_data_puller/models/__init__.py

@@ -0,0 +1 @@
+"""📦 Pydantic models for NetBox IPAM resources."""

netbox_data_puller/models/ip_address.py

@@ -0,0 +1,22 @@
+"""📦 Pydantic model for NetBox IPAM IP Address."""
+
+from pydantic import BaseModel
+
+from netbox_data_puller.models.prefix import ChoiceRef, NestedRef
+
+
+class IPAddress(BaseModel, extra="allow"):
+    """NetBox IPAM IP Address resource."""
+
+    id: int
+    display: str
+    address: str
+    status: ChoiceRef | None = None
+    vrf: NestedRef | None = None
+    tenant: NestedRef | None = None
+    role: ChoiceRef | None = None
+    assigned_object_type: str | None = None
+    assigned_object_id: int | None = None
+    dns_name: str = ""
+    description: str = ""
+    tags: list[NestedRef] = []

netbox_data_puller/models/prefix.py

@@ -0,0 +1,45 @@
+"""📦 Pydantic model for NetBox IPAM Prefix."""
+
+from pydantic import BaseModel
+
+
+class NestedRef(BaseModel):
+    """Nested reference to a related object (id + display name)."""
+
+    id: int
+    display: str
+
+
+class ChoiceRef(BaseModel):
+    """NetBox v4 choice/enum field (value + label).
+
+    Used for status, role, and other enumerated fields that
+    return {"value": "active", "label": "Active"} instead of
+    {"id": 1, "display": "Active"}.
+    """
+
+    value: str
+    label: str
+
+    @property
+    def display(self) -> str:
+        """Consistent interface with NestedRef."""
+        return self.label
+
+
+class Prefix(BaseModel, extra="allow"):
+    """NetBox IPAM Prefix resource."""
+
+    id: int
+    display: str
+    prefix: str
+    status: ChoiceRef | None = None
+    vrf: NestedRef | None = None
+    tenant: NestedRef | None = None
+    site: NestedRef | None = None
+    vlan: NestedRef | None = None
+    role: NestedRef | None = None
+    is_pool: bool = False
+    mark_utilized: bool = False
+    description: str = ""
+    tags: list[NestedRef] = []

netbox_data_puller/models/vlan.py

@@ -0,0 +1,21 @@
+"""📦 Pydantic model for NetBox IPAM VLAN."""
+
+from pydantic import BaseModel
+
+from netbox_data_puller.models.prefix import ChoiceRef, NestedRef
+
+
+class VLAN(BaseModel, extra="allow"):
+    """NetBox IPAM VLAN resource."""
+
+    id: int
+    display: str
+    vid: int
+    name: str
+    status: ChoiceRef | None = None
+    tenant: NestedRef | None = None
+    site: NestedRef | None = None
+    group: NestedRef | None = None
+    role: NestedRef | None = None
+    description: str = ""
+    tags: list[NestedRef] = []

netbox_data_puller/models/vrf.py

@@ -0,0 +1,18 @@
+"""📦 Pydantic model for NetBox IPAM VRF."""
+
+from pydantic import BaseModel
+
+from netbox_data_puller.models.prefix import NestedRef
+
+
+class VRF(BaseModel, extra="allow"):
+    """NetBox IPAM VRF resource."""
+
+    id: int
+    display: str
+    name: str
+    rd: str | None = None
+    tenant: NestedRef | None = None
+    enforce_unique: bool = True
+    description: str = ""
+    tags: list[NestedRef] = []