Skip to content

Proxbox CLI

proxbox_cli is the command-line client for the proxbox-api backend that powers the Proxbox NetBox plugin workflows.

It is a Typer application with top-level operational commands plus grouped command trees for:

  • sync — operator-friendly trigger for a full Proxmox→NetBox sync job via the proxbox_sync Django management command
  • netbox — remote NetBox endpoint management
  • proxmox — Proxmox session inspection, cluster/node queries, and Proxmox endpoint CRUD
  • proxbox — plugin configuration and backend info
  • dcim — device and interface sync from Proxmox nodes to NetBox
  • virtualization — VM, storage, snapshot, and backup sync operations
  • extras — custom fields initialization in NetBox
  • docs — documentation generation utilities

Installation

Install the CLI dependencies from this repository checkout:

pip install "netbox-proxbox[cli]"

After installation, the console entrypoint is:

pxb --help

Configuration

Initialize the CLI once so it knows where proxbox-api is running:

pxb init
pxb config
pxb test

The CLI stores its config under ~/.config/proxbox-cli/config.json unless XDG_CONFIG_HOME overrides that path.

Quick Reference

Sync commands

The pxb sync group wraps the proxbox_sync Django management command as a subprocess. See Sync Command for full documentation.

Command Description
pxb sync run Enqueue a full Proxmox→NetBox sync job and exit
pxb sync run --wait Block until the job reaches a terminal state
pxb sync run --wait --timeout 600 Wait up to 600 s for completion
pxb sync run --json Emit a single JSON document at exit (CI-friendly)
pxb sync run --netbox-path PATH Override the manage.py resolution chain

Root-level commands

Command Description
pxb init Interactively configure the backend URL and timeout
pxb config Show the current CLI configuration
pxb test Test connectivity to the backend
pxb version Show the backend version
pxb info Show backend project info
pxb cache Show in-memory cache contents
pxb clear-cache Clear the backend cache
pxb full-update Run a full multi-stage sync

Endpoint management

# NetBox remote endpoints
pxb netbox endpoint list|get|create|update|delete

# Proxmox endpoint records (local DB)
pxb proxmox endpoints list|get|create|update|delete

# Backend plugin settings
pxb proxbox settings
pxb proxbox plugins-config
pxb proxbox default-settings

Sync operations

# Device and interface sync
pxb dcim devices
pxb dcim devices-create
pxb dcim interfaces-create <node>
pxb dcim interfaces-create-all

# Virtual machine sync
pxb virtualization vms list
pxb virtualization vms create
pxb virtualization vms interfaces-create
pxb virtualization vms disks-create
pxb virtualization vms backups-sync-all
pxb virtualization vms snapshots-sync-all

# Storage sync
pxb virtualization storage-create

# Cluster and node inspection
pxb proxmox cluster status
pxb proxmox cluster resources
pxb proxmox nodes list
pxb proxmox nodes network <node>
pxb proxmox nodes qemu <node>
pxb proxmox nodes lxc <node>

Output Formats

All commands that fetch data support --json and --yaml output flags:

pxb virtualization vms list --json
pxb proxmox cluster status --yaml

Generated Reference

The MkDocs site includes two machine-generated CLI sections:

  • Command Reference lists every discovered command and an autogenerated example invocation.
  • Command Examples captures representative help output for major command groups and leaf commands.

Regeneration

To refresh the generated CLI docs from the current checkout:

python docs/generate_proxbox_cli_docs.py

The CLI exposes the same generator directly:

pxb docs generate-capture