Dynamic Commands

Every NetBox resource reachable through the API is automatically registered as a Typer subcommand, derived from the bundled OpenAPI schema at import time. This means --help works at every level and shell completion is fully supported.

---

Command structure

nbx <group> <resource> <action> [options]

For example:

nbx dcim devices list
nbx dcim devices get --id 1
nbx ipam prefixes create --body-json '{...}'

---

Discovery

Use the discovery commands to explore what's available:

# All app groups
nbx groups
# → circuits, core, dcim, extras, ipam, plugins, tenancy, users, virtualization, vpn, wireless

# Resources in a group
nbx resources dcim
# → cable-terminations, cables, console-ports, device-bays, device-roles, devices, …

# Help at any level
nbx dcim --help
nbx dcim devices --help
nbx dcim devices list --help

---

Actions

Action	HTTP method	Path	Notes
list	GET	/api/<group>/<resource>/	Returns paginated list
get	GET	/api/<group>/<resource>/{id}/	Requires --id
create	POST	/api/<group>/<resource>/	Requires --body-json or --body-file
update	PUT	/api/<group>/<resource>/{id}/	Requires --id and body
patch	PATCH	/api/<group>/<resource>/{id}/	Requires --id and body
delete	DELETE	/api/<group>/<resource>/{id}/	Requires --id

Not every resource supports all actions — availability depends on the OpenAPI schema.

---

Options (all actions)

Flag	Description
--id INTEGER	Object ID for detail operations (get, update, patch, delete)
-q / --query KEY=VALUE	Query string filter (repeatable)
--body-json TEXT	Inline JSON request body
--body-file PATH	Path to JSON file for request body
--json	Output raw JSON
--yaml	Output YAML
--markdown	Output table-first Markdown
--trace	Fetch and render ASCII cable trace (interfaces only, get only)
--select TEXT	JSON dot-path to extract specific field from response (e.g., results.0.name)
--columns TEXT	Comma-separated list of columns to display in table output
--max-columns INTEGER	Maximum number of columns to display (default: 6)
--dry-run	Preview write operation without executing (create/update/patch/delete only)

--json, --yaml, and --markdown are mutually exclusive.

---

Filtering

The -q / --query flag maps to NetBox API query parameters:

nbx dcim devices list -q site=nyc01
nbx dcim devices list -q status=active -q role=spine
nbx ipam prefixes list -q family=6 -q status=active
nbx dcim interfaces list -q device_id=1

Multiple -q flags are ANDed together.

---

Output formats

Rich table (default)JSONYAMLMarkdown

nbx dcim devices list

Renders a Rich table with prioritized columns: id, name, status, site, role, type, etc.

nbx dcim devices list --json

Prints the raw paginated API response as indented JSON. Useful for piping to jq.

nbx dcim devices list --yaml

Renders the response as YAML.

nbx dcim devices list --markdown

Renders API JSON as table-first Markdown output.

---

Field selection (--select)

Extract specific fields from the JSON response using dot notation:

# Get the first device's name
nbx dcim devices list --select results.0.name

Only numeric list indices are supported in paths (no wildcards such as [*]).

Supported path patterns: - results.0.name — Access nested object at a numeric index - count — Access top-level fields

---

Column control (--columns, --max-columns)

Limit which columns appear in table output:

# Display only specific columns
nbx dcim devices list --columns id,name,status

# Limit total columns to 3
nbx dcim devices list --max-columns 3

# Combine both
nbx dcim devices list --columns id,name,status --max-columns 2

The --columns flag accepts a comma-separated list of field names to display. The --max-columns flag limits the total number of columns shown, defaulting to 6.

---

Dry run (--dry-run)

Preview what a write operation would send without actually executing it:

# Preview a create operation
nbx dcim devices create --dry-run --body-json '{"name":"test-device","site":1}'

# Preview an update operation
nbx dcim devices update --dry-run --id 1 --body-json '{"name":"updated-name"}'

# Preview a delete operation
nbx dcim devices delete --dry-run --id 1

Output shows the HTTP method, path, and request body in a formatted table. The --dry-run flag is only valid for write operations (create, update, patch, delete).

---

Cable trace

For dcim/interfaces, the get action supports --trace to fetch and display the cable path as an ASCII diagram:

nbx dcim interfaces get --id 4 --trace

Output:

Cable Trace:
┌────────────────────────────────────┐
│         dmi01-akron-rtr01          │
│       GigabitEthernet0/1/1         │
└────────────────────────────────────┘
                │
                │  Cable #36
                │  Connected
                │
┌────────────────────────────────────┐
│       GigabitEthernet1/0/2         │
│         dmi01-akron-sw01           │
└────────────────────────────────────┘

Trace Completed - 1 segment(s)

---

Demo profile variant

The same dynamic command tree is registered under nbx demo and targets demo.netbox.dev:

nbx demo dcim devices list
nbx demo ipam prefixes list
nbx demo dcim interfaces get --id 4 --trace

See Demo Profile for setup.

---

How it works

At startup, _register_openapi_subcommands() in cli.py reads reference/openapi/netbox-openapi.json, builds a SchemaIndex, then creates a Typer sub-app for every group, a nested sub-app for every resource, and a command for every supported action. The same registration runs twice — once for the root app and once for demo_app with _get_demo_client as the client factory.

For plugin resources, the bundled schema gives nbx the static command tree it knows about, and the TUI layer can additionally augment that view at runtime by discovering live /api/plugins/ REST endpoints from the connected NetBox instance.