@shumoku/netbox

NetBox API client and converter for Shumoku network diagrams.

Installation

npm install @shumoku/netbox

Usage

As a Library

import { NetBoxClient, convertToShumoku } from '@shumoku/netbox'

// Create client
const client = new NetBoxClient({
  url: 'https://netbox.example.com',
  token: 'your-api-token'
})

// Fetch devices and convert to Shumoku format
const devices = await client.getDevices()
const cables = await client.getCables()

const graph = convertToShumoku({ devices, cables })

As a CLI

# Convert NetBox data to Shumoku YAML
npx netbox-to-shumoku --url https://netbox.example.com --token YOUR_TOKEN

# Output to file
npx netbox-to-shumoku --url https://netbox.example.com --token YOUR_TOKEN -o network.yaml

# Generate SVG with legend
npx netbox-to-shumoku --url https://netbox.example.com --token YOUR_TOKEN --legend -o network.svg

# Export as NetworkGraph JSON (for integration with other tools)
npx netbox-to-shumoku --url https://netbox.example.com --token YOUR_TOKEN -f json -o network.json

CLI Options

| Option | Description | |--------|-------------| | -u, --url <url> | NetBox API URL (or set NETBOX_URL env var) | | -t, --token <token> | API token (or set NETBOX_TOKEN env var) | | -k, --insecure | Skip TLS certificate verification (for self-signed certs) | | -f, --format <type> | Output format: yaml, json, svg, html (default: auto from extension) | | -o, --output <file> | Output file (default: topology.yaml) | | --theme <theme> | Theme: light or dark (default: light) | | -s, --site <slug> | Filter by site slug | | -r, --role <slug> | Filter by device role slug | | --status <status> | Filter by status | | --tag <slug> | Filter by tag slug | | -g, --group-by <type> | Group by: tag, site, location, prefix, none | | --no-ports | Don't include port names in links | | --no-colors | Don't color links by cable type | | --color-by-status | Color devices by their status | | --legend | Show legend in the diagram (SVG only) | | -d, --debug | Show debug output (API requests/responses) |

Integration Workflow

Export NetBox data as JSON, merge with custom data, then render:

# Step 1: Export from NetBox as JSON
npx netbox-to-shumoku -f json -o netbox.json

# Step 2: Merge or modify the JSON with your custom data (via script)
# The JSON follows the NetworkGraph schema

# Step 3: Render the final JSON to SVG or HTML
npx shumoku render merged.json -o diagram.html

API

NetBoxClient

const client = new NetBoxClient({
  url: string,      // NetBox URL
  token: string,    // API token
  debug?: boolean   // Enable debug output (default: false)
})

// Methods
client.getDevices(): Promise<NetBoxDevice[]>
client.getCables(): Promise<NetBoxCable[]>
client.getSites(): Promise<NetBoxSite[]>

convertToShumoku

import { convertToShumoku } from '@shumoku/netbox'

const graph = convertToShumoku({
  devices: NetBoxDevice[],
  cables: NetBoxCable[],
  sites?: NetBoxSite[]
})

Related Packages

• shumoku - Main package
• @shumoku/core - Core library

License

MIT