HubSaúde CLI
Um único programa instala e comanda tudo o que você precisa para testar a integração antes de ir ao ar: validação de recursos, simulador e servidor FHIR local. Ele não exige Java instalado nem permissão de administrador.
Demonstração de instalação e validação
Demonstração estática de terminal: instalação via curl com verificação de checksum, consulta de versão e validação de uma instância FHIR em JSON. As versões e saídas abaixo são ilustrativas, não resultados executados nesta página.
# 1) Instalar o HubSaúde CLI (sem Java · verifica SHA-256)
$ curl -fsSL raw.githubusercontent.com/sesgo-ti/hubsaude/main/install.sh | bash
✓ checksum verificado (SHA-256)
✓ hubsaude instalado em ~/.local/bin/hubsaude
# 2) Conferir a versão do CLI e dos componentes
$ hubsaude version
hubsaude 0.3.16 · validador 0.1.43 · simulador 0.1.40
# 3) Validar uma instância FHIR (JSON) contra os IGs
$ hubsaude validate paciente.json
✓ Patient válido (0 erros · 0 avisos)
Instalar com um comando
Baixa o hubsaude, confere a integridade por SHA-256 e instala sem exigir administrador nem sudo.
Selecione manualmente o sistema operacional. No Windows, use PowerShell; em macOS e Linux, é preciso ter curl e bash.
- macOS e Linux
- Windows
curl -fsSL https://raw.githubusercontent.com/sesgo-ti/hubsaude/main/install.sh | bash
irm https://raw.githubusercontent.com/sesgo-ti/hubsaude/main/install.ps1 | iex
Comandos
Todos os comandos partem do programa hubsaude instalado acima e são digitados no terminal do seu computador: no Windows, o PowerShell; no macOS e no Linux, o aplicativo Terminal. Para ver as opções de qualquer comando, acrescente --help, como em hubsaude validate --help.
Conferir registros
| Comando | O que faz |
|---|---|
hubsaude validate <arquivo> | Valida um ou mais arquivos com recursos FHIR |
hubsaude validate --dir <pasta> --recursive | Valida todos os recursos de uma pasta, incluindo subpastas |
hubsaude validate - | Lê o recurso da entrada padrão (stdin) |
hubsaude validate <arquivo> -o json | Apresenta o resultado em JSON, adequado a automações |
hubsaude validate <arquivo> --report | Gera um relatório em HTML e o abre no navegador |
hubsaude validate <arquivo> --profile <url> | Valida contra um perfil específico |
hubsaude fhirpath '<expressão>' <arquivo> | Extrai informações de um recurso com uma expressão FHIRPath |
Controlar as ferramentas locais
Validador, Simulador e servidor FHIR local aceitam os mesmos quatro subcomandos.
| Comando | O que faz |
|---|---|
hubsaude validador start|stop|status|logs | Controla o Validador, que também é iniciado automaticamente pelo validate |
hubsaude simulador start|stop|status|logs | Controla o Simulador; também aceita a forma abreviada hubsaude sim |
hubsaude server start|stop|status|logs | Controla o servidor FHIR local; start --reset apaga os dados antes de iniciar |
hubsaude status | Mostra, de uma só vez, a situação das três ferramentas |
Use logs -f para acompanhar os registros de funcionamento em tempo real, como em hubsaude simulador logs -f.
Credencial, atualização e remoção
| Comando | O que faz |
|---|---|
hubsaude auth verify | Confirma se a credencial do credenciamento funciona, conforme detalhado abaixo |
hubsaude update | Atualiza o Validador, o Simulador, o servidor FHIR local e o Java utilizado por eles |
hubsaude self-update | Atualiza o próprio programa hubsaude |
hubsaude version | Exibe a versão do programa e das ferramentas instaladas |
hubsaude uninstall | Remove o programa e todos os dados locais |
O Validador e o Simulador têm páginas próprias, com exemplos de uso de cada um: Validador e Simulador.
Extrair informações com FHIRPath
FHIRPath é uma linguagem de consulta para recursos FHIR. Com ela, você confere rapidamente o valor de um campo sem abrir o arquivo inteiro.
# nome de um paciente
hubsaude fhirpath 'Patient.name.given' paciente.json
# o mesmo campo em vários arquivos
hubsaude fhirpath 'name.family' a.json b.json
# todos os arquivos de uma pasta
hubsaude fhirpath 'Patient.id' --dir ./recursos --recursive
# resultado em JSON
hubsaude fhirpath 'Patient.name' paciente.json -o json
Escreva a expressão entre aspas simples, para que o terminal não interprete caracteres como $ e *. Quando o resultado é vazio, nada é impresso; para que esse caso seja tratado como falha em uma automação, acrescente --fail-empty. A consulta usa o Validador local; se ele estiver desatualizado, o programa orienta a executar hubsaude update.
Servidor FHIR local
O hubsaude server sobe um servidor FHIR completo no endereço http://127.0.0.1:8100/fhir, útil para experimentar o formato dos registros antes de usar o Simulador.
hubsaude server start # baixa na primeira vez e inicia o servidor
hubsaude server status
hubsaude server logs -f
hubsaude server stop
hubsaude server start --reset # apaga os dados locais antes de iniciar
Diferenças em relação às demais ferramentas:
- Os dados são mantidos entre um uso e outro. Para recomeçar do zero, pare o servidor e use
start --reset. - Não encerra sozinho por inatividade: permanece ativo até
hubsaude server stop. - Recusa registros inválidos, devolvendo a explicação do problema.
- É baixado apenas no primeiro uso, pois tem cerca de 150 MB.
O servidor FHIR local não tem autenticação nem criptografia e só aceita conexões do próprio computador. Não o exponha na rede e use apenas dados fictícios. O comando hubsaude uninstall apaga também os dados armazenados nele.
hubsaude auth verify
Assim que o credenciamento é aprovado, este comando confirma em segundos que a sua chave e o seu certificado realmente funcionam, sem precisar escrever uma linha de código. Ele existe para conferência: para obter tokens no funcionamento normal da aplicação, use um dos SDKs.
hubsaude auth verify \
--client-id hs-12345678 \
--key minha-chave.pem \
--cert meu-certificado.pem \
--ig hemograma --ig-versao 0.0.1
No Windows, o PowerShell não reconhece a barra invertida (\) como continuação de linha. Digite o comando em uma única linha ou troque cada \ no fim da linha pelo acento grave (`).
| Exit | Significado | Ação recomendada |
|---|---|---|
0 | Sucesso: token obtido, credencial apta | Nenhuma |
3 | Erro de uso: argumentos, arquivos ou configuração inválidos | Corrigir a invocação |
4 | Falha de rede: teste inconclusivo (descoberta, timeout, 429, 5xx) | Repetir mais tarde (retry/backoff) |
6 | Credencial não apta: rejeição definitiva (HTTP 400/401 invalid_client ou handshake mTLS) | Acionar o processo de credenciamento |
Na dúvida, o comando erra para o lado seguro. Se a falha não puder ser atribuída com certeza à credencial, ela é classificada como 4, ou seja, inconclusiva. Uma credencial nunca é declarada inapta sem evidência clara. Os mesmos códigos de saída valem para a ferramenta Java autônoma hubsaude-cliente-cli.
O comando aceita a chave em arquivo PEM, cifrado ou não, e também arquivos .p12 ou .pfx. Se a chave tiver senha, prefira informá-la com --password-stdin ou pela variável HUBSAUDE_KEY_PASSWORD: a opção --password deixa a senha visível no histórico do terminal. O token completo só é exibido com --show-token; evite essa opção em automações, para que o token não fique registrado em logs.
Atualizar e desinstalar
Há duas atualizações independentes:
hubsaude update # atualiza as ferramentas: Validador, Simulador, servidor FHIR local e Java
hubsaude self-update # atualiza o próprio programa hubsaude
As ferramentas só mudam de versão com hubsaude update. Os demais comandos reutilizam a versão já instalada, sem consultar a internet.
hubsaude self-update --check # apenas verifica se há versão nova
hubsaude self-update --to 0.3.16 # instala uma versão específica
Para remover o programa e todos os dados locais, inclusive os do servidor FHIR local:
hubsaude uninstall --dry-run # mostra o que seria removido, sem remover
hubsaude uninstall # remove após confirmação
Use --keep-cache para preservar os arquivos já baixados e --yes para dispensar a confirmação.
Códigos de saída
Os códigos de saída permitem usar o programa em scripts e pipelines de integração contínua.
| Código | Significado |
|---|---|
0 | Sucesso |
1 | A validação encontrou erros |
2 | A validação encontrou apenas avisos |
3 | Erro de uso: argumentos ou opções inválidos |
4 | Falha de rede ou de instalação das ferramentas |
5 | Há atualização disponível (--check) |
6 | Credencial não apta (auth verify) |
Para investigar um problema, acrescente -v a qualquer comando. O detalhamento omite o conteúdo dos registros enviados, para não expor dados de saúde no terminal ou em logs.
Variáveis de ambiente
| Variável | Efeito | Padrão |
|---|---|---|
HUBSAUDE_VALIDADOR_PORT | Porta local do Validador | 8090 |
HUBSAUDE_SIMULADOR_PORT | Porta local do Simulador | 8443 |
HUBSAUDE_SERVER_PORT | Porta local do servidor FHIR | 8100 |
HUBSAUDE_IDLE_TIMEOUT | Tempo de ociosidade antes de encerrar um componente local | 30m |
HUBSAUDE_HTTP_TIMEOUT | Timeout das requisições HTTP feitas pelo CLI | 120s |
HUBSAUDE_RELEASE_CHANNEL | Canal de release usado para baixar os componentes | stable |
As variáveis que controlam a instalação, como a versão e a pasta de destino do programa, estão documentadas no README do repositório de distribuição.
Outros recursos
Materiais que acompanham a integração e não fazem parte do CLI.
Safira
Assina e valida documentos FHIR conforme a política de assinatura
Contrato FHIR
CapabilityStatements (normativo) e OpenAPI derivado
Coleção do produtor
Requisições prontas para executar o fluxo de escrita (Bruno e .http)