NetBox CLI and TUI

Contents

• Quick Test with NetBox Demo Instance
• Install
  • Install nbx Globally (bash + zsh)
• Configure
• Command Modes
  • 1) Dynamic mode (OpenAPI app/resource/action)
  • 2) Explicit HTTP mode
  • 3) Discovery helpers
  • 4) TUI mode
  • Custom Themes (JSON)
• Project Layout
• Notes

---

netbox-cli is an API-first NetBox client that supports both:

• direct command execution (nbx dcim devices get --id 1)
• interactive Textual TUI (nbx tui)

The project is bootstrapped from CLAUDE.md requirements:

• API-only integration with NetBox (no model access)
• async HTTP via aiohttp
• shared backend logic for CLI and TUI
• OpenAPI-driven command/resource discovery
• automatic TUI discovery for plugin REST resources under /api/plugins/

Quick Test with NetBox Demo Instance

The fastest way to try netbox-cli — one command installs everything and connects to the public demo.netbox.dev instance.

Install:

# Debian/Ubuntu — install curl if not present
sudo apt-get update && sudo apt-get install -y curl

curl -fsSL https://raw.githubusercontent.com/emersonfelipesp/netbox-cli/main/install.sh | bash

The script installs uv if not present, fetches netbox-cli directly from this GitHub repository, and sets up Playwright Chromium for the demo login flow.

Reload your shell after install (the installer runs in a subshell, so PATH changes need to be applied):

source ~/.bashrc   # bash
source ~/.zshrc    # zsh

If nbx is still not found, run it directly by full path as a fallback:

~/.local/bin/nbx --help

Authenticate with the demo instance:

nbx demo init
# enter your demo.netbox.dev username and password when prompted

Or non-interactively (CI / scripted):

nbx demo init --username <your-demo-user> --password <your-demo-password>

Run CLI commands against demo.netbox.dev:

nbx demo dcim devices list
nbx demo dcim sites list
nbx demo ipam prefixes list
nbx demo circuits circuit-terminations get --id 15 --trace-only

Launch the interactive TUI:

nbx demo tui

Use / to search, g to focus the nav tree, q to quit. All commands that work under nbx demo … are available inside the TUI with the same demo profile.

If your NetBox instance has plugins with a full REST API implementation, the TUI can discover their /api/plugins/... resources automatically and render them in navigation without extra configuration.

---

Install

cd <path-to-netbox-cli>
uv tool install --force .

Install nbx Globally (bash + zsh)

Preferred (uv tool):

uv tool install --force <path-to-netbox-cli>
nbx --help

If nbx is not found, ensure your shell PATH includes ~/.local/bin.

For bash:

echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc
nbx --help

For zsh:

echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc
nbx --help

Alternative (repo-local maintenance environment):

cd <path-to-netbox-cli>
uv sync --dev
uv run nbx --help

This keeps a project-managed environment for development tasks. The main end-user install path remains uv tool install.

Contributor standard:

cd <path-to-netbox-cli>
uv sync --dev
uv run pre-commit install --hook-type pre-commit --hook-type pre-push
uv run pre-commit run --all-files

Commits and pushes should go through pre-commit, which runs Ruff linting and formatting locally and in GitHub Actions.

Configure

nbx init
# prompts for base URL, token key, token secret, timeout

If configuration is missing, nbx will prompt for host/token credentials automatically before executing commands (including nbx tui).

Demo profile bootstrap:

nbx demo init

This always targets https://demo.netbox.dev/, opens the NetBox login flow in Playwright, prompts for demo username/password in the terminal, creates a fresh API token, and stores that token in the separate demo profile.

Install the Playwright browser first if you want browser-based demo bootstrap:

uv tool run --from playwright playwright install chromium --with-deps

If you already have a demo API token, you can skip Playwright entirely:

nbx demo --token-key <key> --token-secret <secret>

The normal nbx profile and the nbx demo profile are stored separately in the same config file.

Stored config path:

• $XDG_CONFIG_HOME/netbox-cli/config.json
• or ~/.config/netbox-cli/config.json

Environment overrides:

• NETBOX_URL
• NETBOX_TOKEN_KEY
• NETBOX_TOKEN_SECRET

Authentication is v2-token only and sent as:

• Authorization: Bearer nbt_<KEY>.<TOKEN>

Command Modes

1) Dynamic mode (OpenAPI app/resource/action)

nbx dcim devices list
nbx dcim devices get --id 1
nbx ipam ip-addresses create --body-json '{"address":"192.0.2.10/24","status":"active"}'
nbx dcim devices list -q name=switch01

This path is now fully registered as real Typer subcommands generated from OpenAPI, so --help works at each level:

nbx dcim --help
nbx dcim devices --help
nbx dcim devices get --help

Demo mode uses the same command tree against https://demo.netbox.dev/:

nbx demo dcim devices list
nbx demo ipam prefixes list
nbx demo tui

Supported action aliases:

• list -> GET
• get -> GET (requires --id)
• create -> POST
• update -> PUT (requires --id)
• patch -> PATCH (requires --id)
• delete -> DELETE (requires --id)

2) Explicit HTTP mode

nbx call GET /api/status/
nbx call POST /api/ipam/ip-addresses/ --body-file ./payload.json

3) Discovery helpers

nbx groups
nbx resources dcim
nbx ops dcim devices

4) TUI mode

nbx tui

Theme options:

nbx tui --theme          # list available themes
nbx tui --theme dracula  # start with Dracula
nbx tui --theme netbox-light

You can also switch theme live from the top-left Theme dropdown in the TUI.

Theme contract:

• every Textual widget and subcomponent must inherit its visual styling from the active theme
• never hardcode runtime colors in Python or TCSS outside netbox_cli/themes/*.json
• do not opt into builtin Textual widget palettes when they override the repo theme tokens
• if a widget needs a custom state, express it with semantic variables and theme-backed component classes

Textual composition contract:

• use React-style composition for Textual UI work: small reusable widgets, explicit constructor props, nested compose() trees
• prefer composition over inheritance for layout reuse
• extract shared primitives into netbox_cli/ui/widgets.py
• standard reusable controls should expose semantic arguments instead of ad-hoc class combinations
• pass theme-aware styling intent through semantic props such as tone, surface, and size

Custom Themes (JSON)

Themes are loaded dynamically from:

• netbox_cli/themes/

Built-ins:

• netbox_cli/themes/netbox-dark.json
• netbox_cli/themes/dracula.json
• netbox_cli/themes/netbox-light.json

To add a custom theme, place <theme>.json in that folder. It will be auto-discovered.

Strict validation rules:

• required top-level keys: name, label, dark, colors
• optional keys: variables, aliases
• colors must define: primary, secondary, warning, error, success, accent, background, surface, panel, boost
• all color values must be #RRGGBB
• unknown keys, malformed colors, duplicate names, and alias conflicts fail fast with clear errors

TUI behavior (initial bootstrap):

• shell layout inspired by NetBox web UI:
  • top quick-search bar
  • left navigation tree (group -> resource)
  • main tabbed workspace (Results, Details) plus filter dialogs
  • footer status/help
• results view with incremental async refresh and row selection tracking
• details view rendered as panelized object attributes
• filters view with field picker + filter modal
• persisted last context/filter in local TUI state

Useful TUI keys:

• /: focus search
• g: focus navigation
• s: focus results table
• r: refresh current resource
• f: open filter modal
• space: toggle row selection
• a: toggle select all visible rows
• d: jump to details tab
• q: quit

Project Layout

• netbox_cli/config.py: config storage + env overrides
• netbox_cli/schema.py: OpenAPI loading and indexing
• netbox_cli/api.py: async aiohttp client
• netbox_cli/services.py: shared request resolution and action mapping
• netbox_cli/cli.py: Typer entrypoint (CLI + dynamic parser)
• netbox_cli/ui_common.tcss: shared visual design layer for both Textual apps
• netbox_cli/ui/dev_app.py: request-workbench Textual app
• netbox_cli/ui/app.py: shell-style Textual app
• netbox_cli/ui/panels.py: panel widgets for detail rendering
• netbox_cli/ui/widgets.py: shared composition primitives for Textual widgets
• netbox_cli/ui/state.py: persisted TUI view state
• netbox_cli/tui.py: compatibility wrapper
• netbox_cli/dev_tui.py: compatibility wrapper for the dev TUI

Notes

This is the initial bootstrap version. It establishes the architecture needed to mirror NetBox UI workflows over time while keeping CLI and TUI parity on top of the same API execution layer.