Metadata-Version: 2.4
Name: netbox-explorer
Version: 0.2.0
Summary: Read-only NetBox CLI with a classic command surface and an interactive shell.
License: MIT License
        
        Copyright (c) 2026 netbox-cli contributors
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
        
Project-URL: Homepage, https://github.com/fciarfella/netbox-cli
Project-URL: Issues, https://github.com/fciarfella/netbox-cli/issues
Project-URL: Repository, https://github.com/fciarfella/netbox-cli
Keywords: netbox,cli,network-automation,inventory
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: System Administrators
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: System :: Networking
Classifier: Topic :: Utilities
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: httpx<1.0,>=0.27
Requires-Dist: prompt-toolkit<4.0,>=3.0
Requires-Dist: rich<14.0,>=13.7
Requires-Dist: typer<1.0,>=0.12
Provides-Extra: dev
Requires-Dist: pytest<9.0,>=8.0; extra == "dev"
Requires-Dist: respx<1.0,>=0.21; extra == "dev"
Dynamic: license-file

# NetBox CLI

[![PyPI](https://img.shields.io/pypi/v/netbox-explorer.svg)](https://pypi.org/project/netbox-explorer/)
[![License](https://img.shields.io/github/license/fciarfella/netbox-cli.svg)](https://github.com/fciarfella/netbox-cli/blob/main/LICENSE)

## What It Is

`netbox-cli` is a read-only Python CLI for NetBox.

Published on PyPI as `netbox-explorer`. Installed command: `netbox`.

It provides two aligned interfaces:

- a standard command line for automation, documentation, and copy/paste use
- an interactive shell for faster exploration, using the same service layer and command semantics

The CLI is the primary interface. 

![CLI demo](docs/demo-cli.gif)

The shell is a convenience layer on top of it.

![Shell demo](docs/demo-shell.gif)


## Features

- explicit configuration with `netbox init`
- config validation and connectivity checks with `netbox config test`
- discovery of apps, endpoints, filters, and known choices from the NetBox API
- read-only `list`, `get`, and grouped global `search`
- Rich tables for interactive terminal output
- JSON and CSV output for automation and piping
- interactive shell with history, contextual navigation, and autocomplete
- local metadata caching for API root, schema, and endpoint `OPTIONS`

## Install

Using a virtual environment is the recommended install path.

### Install from PyPI

Use this for the normal published package install.

```bash
python3 -m venv .venv
source .venv/bin/activate
python3 -m pip install --upgrade pip
python3 -m pip install netbox-explorer
```

### Install from GitHub

Use this when you want to try the tool quickly without cloning the repository.

```bash
python3 -m venv .venv
source .venv/bin/activate
python3 -m pip install --upgrade pip
python3 -m pip install "git+https://github.com/fciarfella/netbox-cli.git"
```

### Install a tagged release from GitHub

Use a tagged release when you want a specific published GitHub version, such as `v0.2.0`.

```bash
python3 -m pip install "git+https://github.com/fciarfella/netbox-cli.git@v0.2.0"
```

### Install from a local clone

Use a local clone when you want to develop the project or make local changes.

```bash
git clone https://github.com/fciarfella/netbox-cli.git
cd netbox-cli
python3 -m venv .venv
source .venv/bin/activate
python3 -m pip install --upgrade pip
python3 -m pip install -e .
```

### Install development dependencies

```bash
python3 -m pip install -e ".[dev]"
```

### Verify the install

```bash
netbox --help
netbox --version
```

### Reactivate the environment

If you open a new shell later, reactivate the environment first:

```bash
source .venv/bin/activate
```

## Configuration

`config.toml` is the primary configuration source for the tool. Environment variables are supported as optional overrides, but normal usage should start with an explicit config file.

Examples in this README assume you have access to a reachable NetBox instance and a valid API token. DNS plugin examples apply only when that plugin is installed and exposed by your NetBox API.

Create config:

```bash
netbox init
```

Example:

```bash
netbox init \
  --url https://netbox.example.com \
  --token YOUR_TOKEN \
  --default-format table \
  --default-limit 25
```

Validate config, token, and connectivity:

```bash
netbox config test
```

Show config, cache, and history paths:

```bash
netbox config paths
```

Clear cached metadata:

```bash
netbox cache clear
```

Typical paths:

```text
~/.config/netbox-cli/config.toml
~/.cache/netbox-cli/
~/.local/state/netbox-cli/shell-history
```

Optional environment variable overrides:

```text
NETBOX_URL
NETBOX_TOKEN
NETBOX_CLI_DEFAULT_FORMAT
NETBOX_CLI_DEFAULT_LIMIT
NETBOX_CLI_TIMEOUT
NETBOX_CLI_VERIFY_TLS
NETBOX_CLI_CONFIG
NETBOX_CLI_CONFIG_DIR
NETBOX_CLI_CACHE_DIR
NETBOX_CLI_HISTORY_DIR
NETBOX_CLI_HISTORY_PATH
```

## CLI Quick Start

Common first commands:

```bash
netbox config test
netbox list
netbox list dcim
netbox list dcim/devices
netbox filters dcim/devices
netbox list dcim/devices status=active
netbox list dcim/devices q=router01 --cols name,site,status
netbox get dcim/devices id=1490
netbox search router01 --cols id,name,site,status
```

## CLI Examples

Explore progressively with `list`:

```bash
netbox list
netbox list dcim
netbox list dcim/devices
```

Inspect endpoint filters and known choices:

```bash
netbox filters dcim/devices
```

List rows from an endpoint:

```bash
netbox list
netbox list dcim
netbox list dcim/devices
netbox list dcim/devices status=active
netbox list dcim/devices router01
netbox list dcim/devices router 01
netbox list dcim/devices router01 status=active
netbox list dcim/devices site=dc1 site=lab
netbox list dcim/devices status=active status=offline
netbox list dcim/devices q=router01
netbox list dcim/devices name__ic=router
netbox list dcim/devices q=router01 --cols name,site,status
netbox list plugins/netbox_dns/records q=198.51.100.10 --cols zone,name,type,value,status
```

The CLI `list` command is the canonical exploration flow and follows the same shorthand as the shell:

```bash
netbox list
netbox list dcim
netbox list dcim/devices
```

Inside an endpoint path, bare terms are treated as `q=...`:

```bash
netbox list dcim/devices router01
```

This behaves like:

```bash
netbox list dcim/devices q=router01
```

Fetch exactly one object:

```bash
netbox get dcim/devices id=1490
```

Run global search across curated endpoints:

```bash
netbox search router01
netbox search router01 --cols id,name,site,status
```

`--cols` takes a comma-separated list of fields and overrides the default profile columns for `list` and `search`.

Use `netbox search <term>` when you want a broad search across multiple object types.

Use `netbox list` as the single exploration command:

- `netbox list` shows top-level apps
- `netbox list <app>` shows endpoints for that app
- `netbox list <app>/<endpoint>` lists records from that endpoint

Use `netbox list <app>/<endpoint> q=<term>` when you already know the endpoint you want to search inside.

Examples:

```bash
netbox search router01
netbox list dcim/devices q=router01
```

Actual supported filters depend on the target endpoint and the schema exposed by your NetBox instance. For endpoint-specific lookups, `netbox filters <app>/<endpoint>` shows what the tool has discovered.

For multi-value filters, repeat the parameter instead of using a comma-separated value:

```bash
netbox list dcim/devices site=dc1 site=lab
```

This is separate from NetBox options like `ordering`, where comma-separated values are still the normal form:

```bash
netbox list dcim/devices ordering=name,-serial
```

## Search Behavior

`netbox search <term>` searches a curated set of endpoints and groups results by object type.

The v1 search set includes:

- `dcim/devices`
- `virtualization/virtual-machines`
- `ipam/ip-addresses`
- `ipam/prefixes`
- `ipam/vlans`
- `dcim/sites`
- `dcim/racks`
- `plugins/netbox_dns/records` when available

Ranking prefers:

1. exact matches
2. prefix matches
3. substring matches

Search output is grouped by endpoint and shows the endpoint path, match count, and a useful default column set for each group.

## Interactive Shell

Launch the shell:

```bash
netbox shell
```

The prompt always shows the current path, output format, and row limit:

```text
netbox:/ [table|15]>
```

Typical session:

```text
netbox:/ [table|15]> list
netbox:/ [table|15]> cd dcim
netbox:/dcim [table|15]> list
netbox:/dcim [table|15]> cd devices
netbox:/dcim/devices [table|15]> filters
netbox:/dcim/devices [table|15]> list status=active
netbox:/dcim/devices [table|15]> open 1
```

Change output format and row limit:

```text
netbox:/dcim/devices [table|15]> format json
netbox:/dcim/devices [json|15]> limit 5
netbox:/dcim/devices [json|5]> get name=router01
```

Search and open:

```text
netbox:/ [table|15]> search router01
netbox:/ [table|15]> open 2
```

Inside an endpoint context, `list` supports a shorthand search term:

```text
netbox:/dcim/devices [table|15]> list web01
```

This behaves like:

```text
netbox:/dcim/devices [table|15]> list q=web01
```

Quoted values work the same way:

```text
netbox:/dcim/devices [table|15]> list "router 01"
```

This behaves like:

```text
netbox:/dcim/devices [table|15]> list q="router 01"
```

Mixed shorthand and explicit filters also work:

```text
netbox:/dcim/devices [table|15]> list web01 status=active
```

This behaves like:

```text
netbox:/dcim/devices [table|15]> list q=web01 status=active
```

If `q=...` is already present explicitly, the shell does not add a second `q`.

Repeated filters are supported in the shell the same way they are in the CLI:

```text
netbox:/dcim/devices [table|15]> list site=dc1 site=lab
netbox:/dcim/devices [table|15]> list web01 site=dc1 site=lab
```

Shell commands:

Navigation:

```text
cd [path]
```

Inspection:

```text
filters
list [term] [k=v ...]
get k=v [...]
search <term>
open <index>
```

Session controls:

```text
cols
cols a,b,c
cols reset
format <table|json|csv>
limit <n>
exit
help
```

## Autocomplete

Shell completion is contextual.

It uses the current shell state plus cached metadata to suggest:

- shell commands
- app names
- endpoint path segments
- filter names for the current endpoint
- known choice values for filters
- known and default columns
- simple enum values such as output formats

Examples:

```text
cd d<TAB>                  -> dcim
cd /plugins/ne<TAB>        -> /plugins/netbox_dns
cd net<TAB>                -> netbox_dns
list st<TAB>               -> status=
list status=<TAB>          -> active offline planned
cols na<TAB>               -> name
format j<TAB>              -> json
```

Completion is driven by shell state and cached metadata. If metadata for the current context is missing, the shell may fetch it lazily once and then reuse it for later completions.

## Output Formats

CLI and shell share the same renderers.

Available formats:

- `table`
- `json`
- `csv`

Use table output for interactive work:

```bash
netbox list dcim/devices status=active
```

Use JSON when you want machine-readable output:

```bash
netbox get dcim/devices id=1490 --format json
netbox list dcim/devices q=router01 --cols name,site,status --format json
```

Use CSV when you want simple pipe-friendly rows:

```bash
netbox list dcim/devices status=active --format csv
netbox search router01 --cols id,name,site,status --format csv
```

In the shell, numbered results are mainly meant for table-mode exploration with `open <index>`. JSON and CSV still include the index for consistency, but the primary workflow is interactive table output plus `open`.

## Cache

The tool caches a small amount of discovery metadata locally:

- API root
- schema
- endpoint `OPTIONS` metadata

This cache improves discovery, filter help, choice lookups, and autocomplete responsiveness.

Use this command to clear it:

```bash
netbox cache clear
```

`netbox cache clear` is the supported reset path. There is no `--no-cache` flag.

## Project Layout

The codebase is split by responsibility:

```text
netbox_cli/
  app.py
  client.py
  config.py
  discovery.py
  query.py
  search.py
  render.py
  cache.py
  profiles.py
  repl/
    shell.py
    state.py
    commands.py
    completer.py
    metadata.py
tests/
  ...
```

## Known Limitations

- v1 is read-only
- the shell is line-oriented, not a full-screen TUI
- autocomplete is best-effort when metadata is incomplete or unavailable
- plugin endpoints are handled gracefully, but depend on what your NetBox instance exposes
- endpoint-specific filter support depends on the schema and metadata provided by your NetBox instance
