# 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

```
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](/agente-docs/instalacao#onde-ficam-os-dados).

## Exemplos de provisionamento

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

```sh
#!/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):**

```powershell
$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.