netbox-cli

CLI em Python para consultar e administrar inventário físico no NetBox. Ela foi projetada para dois modos de uso:

uso humano, com menus, tabelas, painéis e árvores Rich;
automação, CI/CD e agentes de IA, com JSON puro, códigos de saída e operações idempotentes.

A CLI cobre regiões, sites, locais, grupos de racks, racks, fabricantes, tipos de dispositivos e dispositivos. Também oferece busca, inventário, inspeção, capacidade, elevação de racks, rastreamento físico e árvores de infraestrutura.

Sumário

Instalação
Primeiros passos
Configuração e autenticação
Saída, erros e códigos de retorno
Referência rápida
Consultas operacionais
Regiões
Sites
Locais
Grupos de racks
Racks
Fabricantes
Tipos de dispositivos
Dispositivos
Idempotência e dry-run
Receitas de automação
Uso com agentes de IA
Limites atuais

Instalação

Pacote Debian para servidores Ubuntu

O pacote .deb inclui o runtime necessário e instala o comando em /usr/bin/netbox. O servidor não precisa ter Python 3.11, pip ou ambiente virtual.

sudo apt install ./dist/netbox-cli_0.1.1_amd64.deb
netbox --help

Para atualizar, instale o novo arquivo .deb com o mesmo comando. Para remover:

sudo apt remove netbox-cli

A configuração e o token pertencem ao usuário que executa a CLI e continuam em ~/.config/netbox-cli/config.yaml; eles não são incluídos nem removidos pelo pacote.

O artefato amd64 é construído no Ubuntu 20.04 com Python 3.11 e PyInstaller no modo onedir. O mesmo pacote é instalado e executado automaticamente em containers limpos com Ubuntu 20.04, 22.04, 24.04 e 26.04 antes de o build ser considerado concluído.

Gerando o `.deb`

O único requisito da máquina de build é Docker com acesso ao daemon:

./packaging/build-deb.sh

O script:

compila o Python 3.11 no Ubuntu 20.04;
empacota a CLI e suas dependências com PyInstaller onedir;
cria dist/netbox-cli_<versão>_amd64.deb;
instala exatamente esse arquivo nos Ubuntu 20.04, 22.04, 24.04 e 26.04;
valida netbox --help, netbox tree --help e o destino de /usr/bin/netbox.

O número da versão do pacote e do projeto vem de netbox_cli.__version__, que é a fonte única da versão. As dependências do artefato estão fixadas em packaging/deb/constraints.txt para que builds posteriores não incorporem versões novas silenciosamente. Como o pacote contém binários, uma arquitetura diferente, como arm64, deve ser construída nativamente ou com um builder Docker configurado para essa arquitetura.

Instalação para desenvolvimento

Para executar a partir do código-fonte, requer Python 3.11 ou posterior.

python -m venv .venv
. .venv/bin/activate
pip install -e .

Depois da instalação, o comando principal é netbox:

netbox --help

Também é possível executar sem instalar o entry point:

python -m netbox_cli --help

Para instalar ou exibir completion do shell:

netbox --install-completion
netbox --show-completion

Primeiros passos

Fluxo interativo:

netbox

O menu permite fazer login, alterar URL e timeout, verificar o estado da sessão e remover o token local.

Para abrir diretamente o login:

netbox login

Depois do login, valide a conexão:

netbox --version
netbox status
netbox --output json status

Faça uma primeira consulta:

netbox search server-01
netbox --output json search server-01

Configuração e autenticação

Arquivo local

O login solicita usuário e senha. A senha fica oculta e nunca é armazenada. O token provisionado é salvo em:

~/.config/netbox-cli/config.yaml

Conteúdo:

url: http://localhost:8000
token: ''
token_id: null
token_url: ''
timeout: 15

O diretório é protegido com permissão 0700 e o arquivo com 0600. O token é vinculado à URL em que foi provisionado; um token do arquivo não é enviado para outra origem.

O login provisiona token v2, valida o token recém-criado e confirma que a conta é superusuária antes de salvá-lo. Tokens fornecidos externamente continuam sujeitos às permissões aplicadas pelo próprio NetBox.

Variáveis de ambiente

Para containers, pipelines e runners efêmeros:

export NETBOX_URL="https://netbox.example.com"
export NETBOX_TOKEN="nbt_chave.token"
export NETBOX_TIMEOUT="30"

netbox --output json status

Variáveis disponíveis:

Variável	Finalidade
`NETBOX_URL`	URL base do NetBox
`NETBOX_TOKEN`	Token v1 ou v2 da API
`NETBOX_TIMEOUT`	Timeout HTTP em segundos
`NETBOX_CONFIG`	Caminho alternativo para o YAML
`XDG_CONFIG_HOME`	Raiz padrão de configuração quando `NETBOX_CONFIG` não existe

Quando URL, token e timeout vêm de fontes externas, a CLI funciona sem precisar criar um arquivo de configuração.

Opções globais

As opções globais devem aparecer antes do grupo ou comando:

netbox [OPÇÕES GLOBAIS] COMANDO [OPÇÕES DO COMANDO]

Opção	Finalidade
`--version`	Exibe a versão instalada da CLI e encerra
`--url URL`	Sobrescreve a URL
`--token TOKEN`	Sobrescreve o token
`--timeout SEGUNDOS`	Sobrescreve o timeout
`--config CAMINHO`	Seleciona outro YAML
`--output json\|human\|id`	Força o formato global
`--retries N`	Repete leituras após falhas transitórias; padrão 2
`--backoff SEGUNDOS`	Espera inicial exponencial; padrão 0,5 s
`--verbose`, `-v`	Mostra endpoint, tentativa, timeout e resposta
`--debug`	Ativa verbose e inclui tipo da exceção e traceback

Exemplo:

netbox \
  --url https://netbox.example.com \
  --token "$NETBOX_TOKEN" \
  --timeout 20 \
  --output json \
  devices list

Prefira NETBOX_TOKEN a --token, pois argumentos podem aparecer no histórico do shell e na listagem de processos.

Diagnóstico e novas tentativas

Erros de comunicação exibem sempre método, endpoint, timeout por tentativa, quantidade de tentativas realizadas e causa resumida. Para acompanhar cada requisição:

netbox \
  --timeout 5 \
  --retries 3 \
  --backoff 0.5 \
  --verbose \
  devices list

O backoff é exponencial: com --backoff 0.5, as esperas são 0,5 s, 1 s e 2 s. O cabeçalho HTTP Retry-After, quando numérico, tem precedência.

São repetidas somente leituras GET, HEAD e OPTIONS após timeout, falha de conexão, HTTP 429, 500, 502, 503 ou 504. Mutações POST e PATCH não são repetidas automaticamente, evitando duplicação caso o servidor tenha processado a operação antes da conexão cair.

Use --debug quando o resumo não for suficiente. O traceback é enviado para stderr e nunca inclui o token ou o corpo enviado pela requisição.

Precedência

Cada campo é resolvido nesta ordem:

opção global > variável de ambiente > arquivo YAML > valor padrão

Assim, URL e token podem vir do ambiente enquanto o timeout continua vindo do arquivo, por exemplo.

Saída, erros e códigos de retorno

Formatos

Os comandos CRUD usam JSON por padrão e aceitam tabela:

netbox sites list
netbox sites list --output table

Consultas operacionais usam apresentação humana por padrão e aceitam JSON:

netbox inspect server-01
netbox inspect server-01 --output json

Para garantir JSON em qualquer consulta, use a opção global antes do comando:

netbox --output json device tree server-01

Inventário também aceita CSV:

netbox inventory --rack RACK-04 --output csv > rack-04.csv

stdout e stderr

resultados são escritos em stdout;
erros operacionais são escritos em stderr;
no modo global --output json, erros operacionais também são JSON puro;
erros de sintaxe continuam usando a ajuda do Typer.

Exemplo de erro estruturado:

{
  "error": {
    "code": "resource_not_found",
    "message": "Dispositivo 'server-99' não encontrado."
  }
}

Códigos de saída

Código	Significado
`0`	Operação concluída
`1`	Falha operacional, autenticação inválida ou status não autorizado
`2`	Uso incorreto da linha de comando, produzido pelo parser

Em scripts, use set -o pipefail para não perder o código da CLI quando houver pipe para jq.

Referência rápida

Comando	Uso
`netbox`	Menu interativo
`netbox login`	Login direto
`netbox status`	Diagnóstico de URL, token e superusuário
`netbox search QUERY`	Busca geral
`netbox inspect DEVICE`	Inspeção rápida do dispositivo
`netbox inventory`	Exportação de inventário
`netbox trace DEVICE INTERFACE`	Rastreamento físico
`netbox tree`	Hierarquia completa
`netbox regions ...`	Regiões
`netbox sites ...`	Sites
`netbox locations ...`	Locais
`netbox rack-groups ...`	Grupos de racks
`netbox racks ...`	Racks
`netbox manufacturers ...`	Fabricantes
`netbox device-roles ...`	Funções de dispositivos
`netbox device-types ...`	Tipos de dispositivos
`netbox devices ...`	Dispositivos
`netbox interfaces ...`	Interfaces
`netbox front-ports ...`	Portas frontais
`netbox rear-ports ...`	Portas traseiras
`netbox console-ports ...`	Portas de console
`netbox power-ports ...`	Portas de energia
`netbox cables ...`	Cabos e conexões

site, rack e device são aliases singulares de sites, racks e devices.

Aliases ocultos mantidos por compatibilidade:

post continua equivalente a create;
all continua equivalente a list;
view, usado anteriormente por regiões, sites e locais, continua equivalente a get.

Os recursos CRUD usam o mesmo contrato: list, get, create, update e delete. Comandos operacionais como status, tree, move e capacity continuam disponíveis ao lado desse conjunto.

Consultas operacionais

`status`

Exibe a versão da CLI e verifica URL, conectividade, existência e versão do token, autenticação e acesso de superusuário. No JSON, a versão está disponível em cli_version.

netbox status
netbox --output json status

O código de saída é zero somente quando authorized for verdadeiro, permitindo uso como health check:

if netbox --output json status > status.json; then
  echo "NetBox pronto"
else
  jq . status.json
  exit 1
fi

`search`

Busca simultaneamente dispositivos, racks, sites, locais e endereços IP.

netbox search server-01
netbox search 10.10.0.23 --limit 20
netbox --output json search server-01

--limit controla o máximo por tipo de recurso; o padrão é 10.

`inspect`

Inspeção por nome exato, com site opcional para resolver nomes repetidos:

netbox inspect server-01
netbox inspect server-01 --site CPTEC
netbox --output json inspect server-01 --site CPTEC

Mostra localização, montagem, status, interfaces conectadas e IPs. A inspeção detalhada também está disponível em netbox device inspect.

`inventory`

Lista dispositivos por site ou rack. Site e location podem restringir a resolução de um rack cujo nome esteja repetido:

netbox inventory --site CPTEC
netbox inventory --rack RACK-04 --site CPTEC
netbox inventory --rack RACK-04 --site CPTEC --location Datacenter
netbox inventory --rack RACK-04 --output json
netbox inventory --rack RACK-04 --output csv > rack-04.csv
netbox inventory --rack RACK-04 --wide
netbox inventory --rack RACK-04 --no-truncate
netbox inventory --rack RACK-04 --columns id,name,role,rack,status

Na saída humana, as colunas são escolhidas conforme a largura atual do terminal. --wide mostra o conjunto completo, --no-truncate preserva os valores inteiros usando quebras de linha e --columns seleciona e ordena campos específicos. A seleção de colunas também pode ser usada com CSV; JSON não é modificado.

O CSV possui colunas estáveis para ID, nome, função, tipo, site, local, rack, posição, status, IP primário e serial.

É obrigatório informar --site ou --rack. --location só pode ser usado junto com --rack.

`trace`

Rastreia uma interface através dos cabos registrados no NetBox:

netbox trace server-01 eth0
netbox trace server-01 eth0 --site CPTEC
netbox --output json trace server-01 eth0 --site CPTEC

`tree`

Árvore completa de região, site, location, rack e dispositivo:

netbox tree
netbox tree --site CPTEC
netbox --output json tree --site CPTEC

Árvore de um rack e seus dispositivos:

netbox rack tree RACK-04
netbox rack tree RACK-04 --site CPTEC --location Datacenter
netbox --output json rack tree RACK-04 --site CPTEC

Árvore de localização e conexões de um dispositivo:

netbox device tree server-01
netbox device tree server-01 --site CPTEC
netbox --output json device tree server-01 --site CPTEC

Componentes e conexões

Todos os comandos de componentes possuem create, list, update e delete. O dispositivo pode ser informado por ID ou nome exato. Os valores de --type usam os identificadores aceitos pelo NetBox.

Interfaces

netbox interfaces create \
  --device switch-01 \
  --name Gi0/1 \
  --type 1000base-t
netbox interfaces list --device switch-01
netbox interfaces update 10 --description "Uplink principal"
netbox interfaces delete 10 --dry-run

Patch panels

Crie primeiro a porta traseira e depois associe a porta frontal pelo ID ou nome:

netbox rear-ports create \
  --device patch-panel-01 \
  --name Rear-01 \
  --type 8p8c

netbox front-ports create \
  --device patch-panel-01 \
  --name Front-01 \
  --type 8p8c \
  --rear-port Rear-01 \
  --rear-port-position 1

Console e energia

netbox console-ports create \
  --device servidor-01 \
  --name Console \
  --type rj-45 \
  --speed 9600

netbox power-ports create \
  --device servidor-01 \
  --name PSU-1 \
  --type iec-60320-c14 \
  --maximum-draw 500

Cabos

As terminações aceitas são interface, front-port, rear-port, console-port e power-port:

netbox cables create \
  --a-type interface \
  --a-device switch-01 \
  --a-name Gi0/1 \
  --b-type front-port \
  --b-device patch-panel-01 \
  --b-name Front-01 \
  --type cat6 \
  --label CAB-001

netbox cables list
netbox cables update 20 --status planned
netbox cables delete 20 --dry-run

Use --dry-run nas criações e atualizações para conferir os IDs resolvidos e o payload sem alterar o NetBox. Exclusões também aceitam --ignore-not-found.

A árvore do dispositivo inclui caminho de localização, interfaces, IPs, equipamentos conectados e conexões dos demais componentes físicos.

Regiões

Criar ou convergir

netbox regions create --name Sudeste
netbox regions create \
  --name Sudeste \
  --slug sudeste \
  --description "Região Sudeste" \
  --ensure
netbox regions create --name Sudeste --ensure --dry-run

Opções: --name, --slug, --description, --ensure, --dry-run e --output json|table.

Com --ensure, nome identifica a região. Em um recurso existente, apenas opções explicitamente informadas participam do PATCH.

Consultar e listar

netbox regions get 1
netbox regions list
netbox regions list --search sudeste
netbox regions list --limit 0
netbox regions list --output table

--limit 0 percorre todas as páginas.

Atualizar e excluir

netbox regions update 1 --name "Sudeste Brasil"
netbox regions delete 1
netbox regions delete 1 --dry-run
netbox regions delete 1 --ignore-not-found

Sites

Criar ou convergir

netbox sites create --name CPTEC
netbox sites create \
  --name CPTEC \
  --slug cptec \
  --status active \
  --region sudeste \
  --description "Site principal" \
  --ensure
netbox sites create --name CPTEC --region Sudeste --ensure --dry-run

Opções: --name, --slug, --status, --region ID|NOME|SLUG, --description, --ensure, --dry-run e --output json|table.

Consultar e listar

netbox sites get 1
netbox sites list
netbox sites list --search cptec
netbox sites list --limit 0
netbox sites list --output table

Resumo operacional

netbox site status CPTEC
netbox --output json site status CPTEC

O resumo agrega racks, dispositivos, capacidade total, unidades ocupadas/livres, percentual de ocupação e distribuição por fabricante.

Atualizar e excluir

netbox sites update 1 --status active --region Sudeste
netbox sites delete 1
netbox sites delete 1 --dry-run
netbox sites delete 1 --ignore-not-found

Locais

Locations pertencem a um site e podem ter um local pai.

Criar ou convergir

netbox locations create --name Datacenter --site CPTEC
netbox locations create \
  --name Datacenter \
  --site CPTEC \
  --slug datacenter \
  --status active \
  --parent 2 \
  --description "Sala principal" \
  --ensure
netbox locations create --name Datacenter --site cptec --ensure --dry-run

O --ensure identifica o local pela combinação nome e site.

Consultar, listar, atualizar e excluir

netbox locations get 1
netbox locations list
netbox locations list --search data
netbox locations list --limit 0
netbox locations update 1 --description "Sala principal"
netbox locations delete 1 --dry-run
netbox locations delete 1 --ignore-not-found

Grupos de racks

Criar ou convergir

netbox rack-groups create --name "Corredor A"
netbox rack-groups create --name "Corredor A" --ensure
netbox rack-groups create --name "Corredor A" --ensure --dry-run

O slug é gerado automaticamente pelo nome.

Consultar e listar

netbox rack-groups get 1
netbox rack-groups list
netbox rack-groups list --search corredor
netbox rack-groups list --limit 20
netbox rack-groups list --output table

Sem --limit, list percorre todas as páginas. --limit 0 também representa todos os resultados.

Atualizar

netbox rack-groups update 1 --name "Corredor B"
netbox rack-groups update 1 --name "Corredor B" --dry-run

No dry-run, a CLI consulta o grupo e retorna changed: false se o nome já for o desejado.

Excluir

netbox rack-groups delete 1
netbox rack-groups delete 1 --dry-run
netbox rack-groups delete 1 --ignore-not-found

Racks

Criar ou convergir

netbox racks create \
  --site "Site Teste" \
  --name RACK-04 \
  --width 19 \
  --starting-unit 1 \
  --u-height 42

Com vínculos opcionais:

netbox racks create \
  --site site-teste \
  --name RACK-04 \
  --width 19 \
  --starting-unit 1 \
  --u-height 42 \
  --location "Sala Teste" \
  --group 2 \
  --role 3 \
  --type 4 \
  --ensure

Simulação idempotente:

netbox --output json racks create \
  --site "Site Teste" \
  --name RACK-04 \
  --width 19 \
  --starting-unit 1 \
  --u-height 42 \
  --ensure \
  --dry-run

Campos obrigatórios: --site, --name, --width, --starting-unit e --u-height. Larguras aceitas: 10, 19, 21 e 23. O status inicial é active. Site e localização aceitam ID, nome exato ou slug. A localização é resolvida dentro do site. Grupo, função e tipo são IDs opcionais.

O --ensure identifica o rack por nome e site. Defaults de criação, como status, não sobrescrevem um rack existente quando não foram informados.

Consultar e listar

netbox racks get 4
netbox racks list
netbox racks list --search RACK-04
netbox racks list --limit 25
netbox racks list --output table

Atualizar

netbox racks update 4 --name RACK-04A
netbox racks update 4 --location 3
netbox racks update 4 --location "Sala Teste"
netbox racks update 4 --u-height 48 --role 3
netbox racks update 4 --u-height 48 --dry-run

Campos disponíveis: --site, --name, --width, --starting-unit, --u-height, --location, --group, --role|--function e --type|--rack-type.

O update altera somente campos informados. O dry-run consulta o rack e mostra apenas as diferenças reais.

Elevação

netbox rack show 4
netbox rack show RACK-04
netbox rack show RACK-04 --face rear
netbox rack show RACK-04 --site CPTEC --location Datacenter
netbox --output json rack show RACK-04

O primeiro argumento aceita o ID numérico ou o nome exato do rack. O mesmo contrato é usado por rack tree, rack available e rack capacity. Quando informados, --site e --location também restringem buscas por ID.

--face aceita front ou rear.

Posições disponíveis

netbox rack available RACK-04 --height 2
netbox rack available RACK-04 --height 0.5 --face rear
netbox rack available RACK-04 \
  --height 2 \
  --site CPTEC \
  --location Datacenter

A consulta considera ocupação, altura, face e suporte a meia unidade.

Capacidade

netbox rack capacity RACK-04
netbox rack capacity RACK-04 --site CPTEC --location Datacenter
netbox --output json rack capacity RACK-04

Mostra capacidade total, ocupação e visão separada das faces frontal e traseira.

Árvore

netbox rack tree RACK-04
netbox rack tree RACK-04 --site CPTEC --location Datacenter
netbox --output json rack tree RACK-04

Excluir

netbox racks delete 4
netbox racks delete 4 --dry-run
netbox racks delete 4 --ignore-not-found

Fabricantes

Criar ou convergir

netbox manufacturers create --name Dell
netbox manufacturers create \
  --name Dell \
  --comments "Fornecedor principal" \
  --ensure
netbox manufacturers create --name Dell --ensure --dry-run

O nome identifica o fabricante. --comments|--comment é opcional.

Consultar, listar, atualizar e excluir

netbox manufacturers get 10
netbox manufacturers list
netbox manufacturers list --search dell
netbox manufacturers list --limit 20
netbox manufacturers list --output table
netbox manufacturers update 10 --comments "Fornecedor homologado"
netbox manufacturers delete 10 --dry-run
netbox manufacturers delete 10 --ignore-not-found

Funções de dispositivos

netbox device-roles create --name Servidor
netbox device-roles create --name Servidor --color 2196f3 --no-vm-role
netbox device-roles get 2
netbox device-roles list
netbox device-roles list --search servidor --output table
netbox device-roles update 2 --name "Servidor físico" --color 3f51b5
netbox device-roles delete 2 --dry-run
netbox device-roles delete 2 --ignore-not-found

O slug é gerado automaticamente a partir do nome. create também aceita --ensure para criar ou convergir uma função existente.

Tipos de dispositivos

Criar ou convergir

netbox device-types create \
  --manufacturer Dell \
  --model "PowerEdge R650" \
  --u-height 1

netbox device-types create \
  --manufacturer dell \
  --model "PowerEdge R650" \
  --u-height 1 \
  --ensure

Campos obrigatórios: fabricante, modelo e altura. O fabricante aceita ID, nome exato ou slug. O --ensure identifica o tipo pela combinação fabricante e modelo.

Consultar, listar, atualizar e excluir

netbox device-types get 15
netbox device-types list
netbox device-types list --search PowerEdge
netbox device-types list --limit 20
netbox device-types list --output table
netbox device-types update 15 --u-height 2
netbox device-types delete 15 --dry-run
netbox device-types delete 15 --ignore-not-found

Dispositivos

Criar ou convergir

Cadastro mínimo:

netbox devices create \
  --name server-01 \
  --role Servidor \
  --device-type "PowerEdge R650" \
  --site "Site Teste"

Cadastro montado em rack:

netbox devices create \
  --name server-01 \
  --role servidor \
  --device-type poweredge-r650 \
  --site site-teste \
  --serial ABC123 \
  --location "Sala Teste" \
  --rack Rack-01 \
  --position 10

Função, tipo, site, localização e rack aceitam ID, nome/modelo exato ou slug. Localização e rack são resolvidos dentro do site. Quando --position é informado, --rack é obrigatório e a face é front. Posições aceitam incrementos de meia unidade.

Campos personalizados usam um objeto JSON:

netbox devices create \
  --name server-01 \
  --role Servidor \
  --device-type "PowerEdge R650" \
  --site "Site Teste" \
  --custom-fields '{"patrimonio":"PAT-001","monitorado":true}'

A CLI consulta os campos personalizados aplicáveis a dcim.device e recusa a criação quando um campo obrigatório não foi fornecido.

Modo idempotente:

netbox --output json devices create \
  --name server-01 \
  --role Servidor \
  --device-type "PowerEdge R650" \
  --site "Site Teste" \
  --serial ABC123 \
  --ensure

O --ensure identifica o dispositivo por nome e site. Em dispositivos existentes, somente opções explicitamente informadas são atualizadas; custom_fields={} e status=active não são aplicados implicitamente.

Consultar e listar

netbox devices get 30
netbox devices list
netbox devices list --search server
netbox devices list --limit 50
netbox devices list --output table
netbox devices list --output table --wide
netbox devices list --output table --no-truncate
netbox devices list --output table --columns id,name,role,site,rack,status

As tabelas se ajustam à largura do terminal. Use --wide para incluir todas as colunas, --no-truncate para quebrar valores longos sem reticências ou --columns para escolher e ordenar os campos exibidos.

Atualizar

netbox devices update 30 --name server-02 --status offline
netbox devices update 30 --role Servidor --device-type "PowerEdge R650"
netbox devices update 30 --custom-fields '{"patrimonio":"PAT-002"}' --dry-run

Inspecionar

netbox device inspect server-01
netbox device inspect server-01 --site CPTEC
netbox --output json device inspect server-01

Inclui identificação, modelo, fabricante, montagem, IPs, interfaces, componentes, campos personalizados, datas e tags.

Árvore de conexões

netbox device tree server-01
netbox device tree server-01 --site CPTEC
netbox --output json device tree server-01

Mover

move permite reposicionar um dispositivo que já esteja alocado:

netbox device move server-01 --rack RACK-04 --position 10
netbox device move server-01 \
  --device-site CPTEC \
  --rack RACK-04 \
  --rack-site CPTEC \
  --rack-location Datacenter \
  --position 10
netbox --output json device move server-01 \
  --rack RACK-04 \
  --position 10 \
  --dry-run

Se o rack estiver em outro site ou location, esses vínculos também são atualizados. A face de montagem é front.

Alocar

allocate aceita somente dispositivos ainda não instalados em um rack:

netbox device allocate server-01 --rack RACK-04 --position 10
netbox device allocate server-01 \
  --device-site CPTEC \
  --rack RACK-04 \
  --rack-site CPTEC \
  --rack-location Datacenter \
  --position 10 \
  --dry-run

Se o dispositivo já estiver alocado, use move.

Desalocar

netbox device deallocate server-01
netbox device deallocate server-01 --site CPTEC
netbox device deallocate server-01 --site CPTEC --dry-run

Rack, posição e face são limpos; site e location são preservados.

Excluir

netbox devices delete 30
netbox devices delete 30 --dry-run
netbox devices delete 30 --ignore-not-found
netbox devices delete 30 --dry-run --ignore-not-found

Idempotência e dry-run

`post --ensure`

O fluxo de convergência é:

resolver identidade e escopo
        │
        ├── não existe ──> criar
        │
        └── existe ──────> comparar somente opções explícitas
                               │
                               ├── diferente ──> PATCH
                               └── igual ──────> changed: false

Identidades usadas:

Recurso	Identidade
Região	nome
Site	nome
Location	nome + site
Grupo de racks	nome
Rack	nome + site
Fabricante	nome
Tipo de dispositivo	modelo + fabricante
Dispositivo	nome + site

Respostas típicas:

{
  "action": "unchanged",
  "changed": false,
  "resource": {
    "id": 30,
    "name": "server-01"
  }
}

{
  "action": "updated",
  "changed": true,
  "changes": {
    "serial": "ABC123"
  },
  "resource": {
    "id": 30,
    "name": "server-01"
  }
}

Contrato JSON e `--output id`

Uma criação sem --ensure retorna diretamente o objeto da API, portanto o ID fica em .id. Com --ensure, a resposta inclui metadados de convergência e o objeto fica em .resource, portanto o ID fica em .resource.id:

Operação	Caminho JSON do ID
Criação normal	`.id`
`--ensure`: criado, atualizado ou inalterado	`.resource.id`
Update em `--dry-run`	`.resource.id`
Criação em `--dry-run`	Não há ID; o recurso ainda não existe

Para scripts não precisarem conhecer esses envelopes, use --output id:

DEVICE_ID=$(netbox devices create \
  --name server-01 \
  --role Servidor \
  --device-type "PowerEdge R650" \
  --site CPTEC \
  --ensure \
  --output id)

O comando imprime somente o valor, como 30. Também é possível usar a opção global: netbox --output id devices create .... Se a operação não possuir ID, como uma criação com --dry-run, a CLI encerra com código 1 e explica o motivo.

`--dry-run`

O dry-run permite leitura, mas nunca envia mutações POST, PATCH ou DELETE. Ele é útil para aprovação humana, logs de pipeline e agentes de IA.

plan=$(netbox --output json racks update 4 --u-height 48 --dry-run)
echo "$plan" | jq .

if jq -e '.changed == true' <<<"$plan" > /dev/null; then
  netbox --output json racks update 4 --u-height 48
fi

Exclusão repetível

netbox --output json devices delete 30 --ignore-not-found

Se o dispositivo já não existir:

{
  "deleted": false,
  "changed": false,
  "not_found": true,
  "resource": "device",
  "id": 30
}

Receitas de automação

Os exemplos abaixo usam jq. Ative tratamento rigoroso de erros:

set -euo pipefail

Criar a estrutura base

#!/usr/bin/env bash
set -euo pipefail

: "${NETBOX_URL:?defina NETBOX_URL}"
: "${NETBOX_TOKEN:?defina NETBOX_TOKEN}"

REGION_ID=$(
  netbox --output id regions create \
    --name Sudeste \
    --description "Região Sudeste" \
    --ensure
)

SITE_ID=$(
  netbox --output id sites create \
    --name CPTEC \
    --region "$REGION_ID" \
    --ensure
)

LOCATION_ID=$(
  netbox --output id locations create \
    --name Datacenter \
    --site "$SITE_ID" \
    --ensure
)

RACK_ID=$(
  netbox --output id racks create \
    --site "$SITE_ID" \
    --name RACK-04 \
    --width 19 \
    --starting-unit 1 \
    --u-height 42 \
    --location "$LOCATION_ID" \
    --ensure
)

echo "region=$REGION_ID site=$SITE_ID location=$LOCATION_ID rack=$RACK_ID"

O rack é associado à location criada anteriormente. Assim, dispositivos podem usar simultaneamente --rack e --location sem violar o escopo validado pelo NetBox.

Cadastrar fabricante, tipo e dispositivo

Função e site precisam existir. Ambos podem ser informados por nome ou slug, sem consulta prévia do ID.

#!/usr/bin/env bash
set -euo pipefail

MANUFACTURER_ID=$(
  netbox --output id manufacturers create \
    --name Dell \
    --ensure
)

DEVICE_TYPE_ID=$(
  netbox --output id device-types create \
    --manufacturer "$MANUFACTURER_ID" \
    --model "PowerEdge R650" \
    --u-height 1 \
    --ensure
)

netbox --output json devices create \
  --name server-01 \
  --role Servidor \
  --device-type "$DEVICE_TYPE_ID" \
  --site CPTEC \
  --location Datacenter \
  --serial ABC123 \
  --ensure

Encontrar espaço e mover um dispositivo

POSITIONS=$(
  netbox --output json rack available RACK-04 \
    --site CPTEC \
    --height 2
)

POSITION=$(jq -er '.positions[0]' <<<"$POSITIONS")

netbox --output json device move server-01 \
  --device-site CPTEC \
  --rack RACK-04 \
  --rack-site CPTEC \
  --position "$POSITION" \
  --dry-run

netbox --output json device move server-01 \
  --device-site CPTEC \
  --rack RACK-04 \
  --rack-site CPTEC \
  --position "$POSITION"

Exportar inventário periodicamente

#!/usr/bin/env bash
set -euo pipefail

destination="inventario-$(date +%F).csv"
netbox inventory --site CPTEC --output csv > "$destination"
echo "Inventário salvo em $destination"

Health check para pipeline

#!/usr/bin/env bash
set -euo pipefail

status_file=$(mktemp)
error_file=$(mktemp)
trap 'rm -f "$status_file" "$error_file"' EXIT

if netbox --output json status >"$status_file" 2>"$error_file"; then
  jq -e '.authorized == true' "$status_file" > /dev/null
else
  jq . "$status_file" 2>/dev/null || true
  jq . "$error_file" 2>/dev/null || true
  exit 1
fi

Exemplo de CI

Exemplo genérico para GitHub Actions:

name: NetBox automation

on:
  workflow_dispatch:

jobs:
  inventory:
    runs-on: ubuntu-latest
    env:
      NETBOX_URL: ${{ secrets.NETBOX_URL }}
      NETBOX_TOKEN: ${{ secrets.NETBOX_TOKEN }}
      NETBOX_TIMEOUT: '30'
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-python@v5
        with:
          python-version: '3.12'
      - run: pip install -e .
      - run: netbox --output json status
      - run: |
          netbox --output json manufacturers create \
            --name Dell \
            --ensure \
            --dry-run

Guarde o token em secrets do provedor de CI; não o escreva no repositório nem no log do pipeline.

Uso com agentes de IA

Para agentes, prefira sempre:

netbox --output json ...

Fluxo recomendado:

Executar status e interromper se authorized não for verdadeiro.
Usar search, tree ou inspect para descobrir o estado atual.
Informar --site e --location quando nomes puderem ser repetidos.
Para criação declarativa, usar post --ensure.
Antes de uma mutação sensível, executar o mesmo comando com --dry-run.
Examinar changed, action e changes no JSON.
Aplicar sem --dry-run somente quando o plano for esperado.
Em exclusões repetíveis, usar --ignore-not-found.
Nunca interpretar tabelas Rich; consumir somente JSON ou CSV.
Tratar código diferente de zero como falha, mesmo que exista saída parcial.

Exemplo de política para um agente:

Antes de alterar o NetBox:
- obtenha o contexto com search/tree/inspect em JSON;
- não escolha silenciosamente entre nomes ambíguos;
- execute dry-run;
- descreva os campos que mudarão;
- aplique somente após aprovação;
- consulte novamente o recurso e confirme o estado final.

Exemplo de sequência:

netbox --output json search server-01
netbox --output json device tree server-01 --site CPTEC
netbox --output json device move server-01 \
  --device-site CPTEC \
  --rack RACK-04 \
  --rack-site CPTEC \
  --position 10 \
  --dry-run
netbox --output json device move server-01 \
  --device-site CPTEC \
  --rack RACK-04 \
  --rack-site CPTEC \
  --position 10
netbox --output json device tree server-01 --site CPTEC

Limites atuais

A CLI não é uma interface genérica para todos os endpoints do NetBox. Ainda não há CRUD para:

endereços IP, prefixes, VLANs e VRFs;
funções de racks;
tenants;
tipos genéricos/content types;
operações em lote por JSON ou JSONL.

Relacionamentos cobertos pela CLI aceitam ID, nome exato ou slug sempre que o recurso possui esses campos. Buscas contextuais, como rack e localização, são restritas ao site e recusam ambiguidades.

--ensure executa consulta seguida de criação ou atualização. Duas automações concorrentes ainda podem disputar a criação do mesmo recurso; as restrições de unicidade do NetBox continuam sendo a proteção final.

Use a ajuda instalada como fonte definitiva para a versão em execução:

netbox --help
netbox devices --help
netbox devices create --help
netbox rack tree --help

Name		Name	Last commit message	Last commit date
packaging		packaging
src/netbox_cli		src/netbox_cli
tests		tests
.dockerignore		.dockerignore
.gitignore		.gitignore
README.md		README.md
pyproject.toml		pyproject.toml
requirements.txt		requirements.txt

Latest commit

History

Folders and files

Repository files navigation

netbox-cli

Sumário

Instalação

Pacote Debian para servidores Ubuntu

Gerando o .deb

Instalação para desenvolvimento

Primeiros passos

Configuração e autenticação

Arquivo local

Variáveis de ambiente

Opções globais

Diagnóstico e novas tentativas

Precedência

Saída, erros e códigos de retorno

Formatos

stdout e stderr

Códigos de saída

Referência rápida

Consultas operacionais

status

search

inspect

inventory

trace

tree

Componentes e conexões

Interfaces

Patch panels

Console e energia

Cabos

Regiões

Criar ou convergir

Consultar e listar

Atualizar e excluir

Sites

Criar ou convergir

Consultar e listar

Resumo operacional

Atualizar e excluir

Locais

Criar ou convergir

Consultar, listar, atualizar e excluir

Grupos de racks

Criar ou convergir

Consultar e listar

Atualizar

Excluir

Racks

Criar ou convergir

Consultar e listar

Atualizar

Elevação

Posições disponíveis

Capacidade

Árvore

Excluir

Fabricantes

Criar ou convergir

Consultar, listar, atualizar e excluir

Funções de dispositivos

Tipos de dispositivos

Criar ou convergir

Consultar, listar, atualizar e excluir

Dispositivos

Criar ou convergir

Consultar e listar

Atualizar

Inspecionar

Árvore de conexões

Mover

Alocar

Desalocar

Excluir

Idempotência e dry-run

post --ensure

Contrato JSON e --output id

Gerando o `.deb`

`status`

`search`

`inspect`

`inventory`

`trace`

`tree`

`post --ensure`

Contrato JSON e `--output id`

`--dry-run`