Copy page

Brasil NFe Agente

CLI e console remoto

O Agente é um único executável com três entradas para as mesmas operações: a interface gráfica, a linha de comando (que é também o modo headless para servidores) e o console remoto na aba Agente do painel, que executa os comandos nfce ... e update de longe, na máquina da loja. A implementação é uma só; o que muda é quem chama e como o resultado é mostrado.

O executável

Plataforma	Caminho / nome
Windows (instalador)	%LOCALAPPDATA%\Brasil NFe Agente\brasilnfe-agent.exe (não entra no PATH)
Linux .deb/.rpm	brasil-nfe-agente (no PATH)
Linux AppImage	o próprio arquivo .AppImage
Linux headless	brasilnfe-agent (onde você o colocou; ex.: /usr/local/bin)

Sem argumentos: abre a interface gráfica (no Linux sem DISPLAY, equivale a run; no binário headless, mostra a ajuda). No Windows, o executável se anexa ao console que o chamou quando recebe um subcomando; no cmd.exe use start /wait para esperar a saída. Logs vão para stderr; stdout é o canal de dados (JSON, DANFE, XML), então > arquivo e | funcionam.

Referência de comandos

Code
pair CODIGO --pfx ARQUIVO.pfx          pareia uma empresa com certificado A1
pair CODIGO --module LIB [--slot N]    pareia com token A3 (módulo PKCS#11)
pair CODIGO --thumbprint SHA1          pareia com certificado da loja do Windows
unpair CODIGO                          remove um pareamento (e o segredo do cofre)
list                                   lista os pareamentos salvos
run                                    conecta ao Brasil NFe e fica assinando; sobe a API local
                                       de NFC-e e a sincronização (ctrl-c encerra)
nfce status                            tudo: agente, atualização, API local, servidor,
                                       pacote fiscal, modo, origens, empresas, notas, backup
nfce notas [pendentes|enviadas|transmitidas|rejeitadas|todas] [N]
                                       notas off-line da empresa (padrão: pendentes 50)
nfce nota CHAVE                        detalhes de uma nota (sem os corpos)
nfce nota CHAVE json [--out ARQ]       JSON original da venda
nfce nota CHAVE xml [--out ARQ]        XML assinado
nfce nota CHAVE danfe [--out ARQ]      DANFE em HTML, gerado do XML na hora
nfce nota CHAVE reenviar               marca para reenvio ao servidor
nfce nota CHAVE corrigir --arquivo nota.json|nota.xml   (ou pelo stdin)
                                       nota ainda no caixa: JSON regera e assina
                                       (mesma série/número); XML valida e reassina
nfce config                            mostra a configuração
nfce config [--porta N] [--bind IP] [--origem https://pdv...]...
            [--sem-origens] [--serie N] [--ambiente 1|2] [--numero N]
            [--modo auto|contingencia]
                                       altera (e reinicia a API local, se estiver rodando)
update check                           consulta se há versão nova do agente
update apply                           baixa, verifica a assinatura e aplica (reinicia)
sefaz-test URL --pfx ARQ --body ENVELOPE.xml [--action URN] [--timeout S]
                                       diagnóstico: POST mTLS real na SEFAZ
help                                   ajuda

Opções comuns aos comandos nfce e update

Opção	Efeito
--codigo bna_...	Escolhe a empresa quando há mais de uma pareada (obrigatório nesse caso para status por empresa, notas, nota, --serie, --ambiente, --numero). Com uma só, é inferida.
--out ARQUIVO	Grava a saída no arquivo em vez do stdout (útil para DANFE/XML/JSON).
--arquivo ARQ	Corpo do nota CHAVE corrigir (JSON ou XML). Sem ele, o corpo é lido do stdin.

Saída e códigos de retorno

• Resultado em JSON (pretty) quando é estrutura; texto quando é conteúdo (XML, DANFE, JSON da nota).
• Código de saída 0 sucesso, 1 erro na execução (mensagem em Erro: ... no stderr), 2 uso inválido (mostra a ajuda).
• nfce config com flags responde a configuração resultante mais ok e mensagem (salvo, salvo; API local reiniciada ou salvo; vale a partir do próximo run).

Detalhes do nfce config

• --porta, --bind, --origem, --sem-origens e --modo valem para o Agente inteiro e reiniciam a API local se ela estiver no ar neste processo (run/interface); numa CLI avulsa, valem no próximo run.
• --serie e --ambiente valem para a empresa (--codigo); valores iguais ao padrão (500/produção) removem a entrada do arquivo. Série válida: 1 a 889.
• --numero N define o próximo número da série da empresa e só sobe (nunca abaixo do já consumido).
• --origem normaliza para esquema://host[:porta] em minúsculas e não duplica.

Senhas em scripts

pair e sefaz-test pedem a senha/PIN no prompt sem eco. Para provisionamento automatizado use a variável BRASILNFE_CERT_SECRET (funciona em todos os sistemas; no Windows o prompt lê do console e ignora stdin canalizado). Com stdin canalizado no Linux, uma linha com a senha também é aceita.

Variáveis de ambiente

Variável	Efeito
BRASILNFE_CERT_SECRET	Senha do PFX / PIN para pair e sefaz-test sem prompt.
BRASILNFE_DATA_DIR	Pasta de dados alternativa (segunda instância na mesma máquina, testes).
BRASILNFE_AUTO_UPDATE=0	Desliga a aplicação automática de atualizações (só avisa no log).
HTTPS_PROXY / HTTP_PROXY / NO_PROXY	Proxy HTTP (túnel CONNECT) para a conexão mTLS com a SEFAZ.
RUST_LOG	Nível de log, ex.: brasilnfe_agent_lib=info (padrão) ou brasilnfe_agent_lib=debug.

Console remoto no painel

Em Configurações › aba Agente, com o Agente conectado, o cartão Console do agente oferece um menu com os comandos e um campo de argumentos:

Item do menu	O que roda
status	nfce status
notas pendentes 50	nfce notas pendentes 50 (troque o filtro e o limite)
nota CHAVE / CHAVE danfe / CHAVE xml / CHAVE json / CHAVE reenviar	nfce nota ... (o DANFE abre em nova aba pelo botão "Abrir DANFE")
nota CHAVE corrigir	nfce nota CHAVE corrigir, com o JSON ou XML colado no campo grande que aparece
config	mostra a configuração
config --serie 500 --ambiente 1, --numero 1, --origem https://..., --porta 9155 --bind 127.0.0.1, --modo contingencia, --modo auto	nfce config ...
update check / apply	update check / update apply (o apply pede confirmação: o Agente reinicia)

O comando roda no computador da loja, no escopo da empresa da conexão, e o resultado volta ao painel. É uma lista fechada de comandos do próprio Agente: nunca shell, nunca código arbitrário. Não é possível parear ou remover pareamentos pelo console (isso é feito na máquina, ou revogando o código no painel).

Arquivos e pastas

Ver a tabela completa em Instalação › Onde ficam os dados.

Exemplos de provisionamento

Linux (servidor de loja, um script por loja):

Code
#!/bin/sh
set -e
export BRASILNFE_CERT_SECRET="$SENHA_DO_PFX"
brasilnfe-agent pair "$CODIGO_PAREAMENTO" --pfx /opt/loja/certificado.pfx
brasilnfe-agent nfce config --bind 0.0.0.0 --porta 9155 --origem https://pdv.suaempresa.com.br
brasilnfe-agent nfce config --serie 500 --numero 1
sudo systemctl enable --now brasilnfe-agent
brasilnfe-agent nfce status | head -40

Windows (PowerShell, caixa único com certificado já instalado):

Code
$agent = "$env:LOCALAPPDATA\Brasil NFe Agente\brasilnfe-agent.exe"
$thumb = (Get-ChildItem Cert:\CurrentUser\My | Where-Object Subject -like "*12345678000195*").Thumbprint
$env:BRASILNFE_CERT_SECRET = ""            # A1 importado nao tem PIN
& $agent pair $env:CODIGO_PAREAMENTO --thumbprint $thumb
& $agent nfce config --origem https://pdv.suaempresa.com.br
Start-Process $agent                          # abre a interface; fica na bandeja

Depois do pair, abrir a interface (ou rodar run) é o que sobe a conexão com o hub, a API local e a sincronização.