Visualizador JSON Bash — jless & JQ_COLORS

Quando você precisa de um visualizador JSON em bash para exploração interativa em vez de scripting, o pipe padrão jq . fica aquém — a saída rola além do topo do terminal e você não tem como navegar de volta em uma resposta de API de 300 linhas. Este guia cobre ferramentas criadas especificamente para visualizar JSON de forma interativa no terminal: jless (árvore recolhível com navegação estilo vim), JQ_COLORS para temas de cor personalizados, jq -C | less -R para paginação colorida, aliases de shell para uso diário, e fx como alternativa baseada em Node.js. Para scripting, CI/CD e fluxos de validação, consulte o guia complementar Formatar JSON em Bash. Para um visualizador no navegador sem instalação, a ferramenta Embelezador JSON funciona instantaneamente. Os exemplos foram testados no Bash 5.x (macOS via Homebrew, Ubuntu 22.04+) e são compatíveis com Bash 3.2+ (shell do sistema macOS).

Visualização JSON Interativa vs. Scripted

Redirecionar JSON para jq . é a escolha certa quando você quer saída formatada para um payload pequeno, ou quando o resultado alimenta outro comando. É a escolha errada quando você precisa explorar uma resposta de API com 200 campos — a saída passa voando pela janela do terminal e não deixa nenhuma forma de navegar, recolher seções ou buscar um campo específico sem executar o comando novamente com um filtro. Visualizadores JSON interativos renderizam a mesma saída formatada e colorida dentro de um paginador persistente onde você controla a navegação. Os dados são idênticos; a diferença é a interface.

# jq . — a saída rola para fora da tela em respostas grandes
curl -s https://api.github.com/users/torvalds | jq .
# Mais de 300 linhas rolam — você perde o contexto imediatamente

# jless — abre um paginador interativo, nada rola para fora da tela
curl -s https://api.github.com/users/torvalds | jless
# Documento completo visível, recolhível, com busca usando j/k/h/l

jless — Visualizador JSON Interativo

jless é um visualizador JSON em terminal criado especificamente para isso. Diferente de um pipe simples de jq, ele renderiza o documento como uma árvore recolhível persistente: cada objeto e array pode ser expandido ou recolhido de forma independente com l e h, a navegação usa teclas estilo vim, e a busca incremental encontra qualquer chave ou valor instantaneamente. Ele transmite a entrada de forma incremental, então abre arquivos grandes e respostas de API em menos de um segundo independentemente do tamanho — enquanto o jq armazena em buffer o documento inteiro antes de exibir qualquer coisa. Recorro ao jless como a primeira ferramenta sempre que uma resposta de API é grande demais para examinar de relance.

Instalação

# macOS
brew install jless

# Linux — binário pré-compilado do GitHub Releases
curl -sL https://github.com/PaulJuliusMartinez/jless/releases/latest/download/jless-x86_64-unknown-linux-gnu.tar.gz \
  | tar xz
sudo mv jless /usr/local/bin/

# Verificar
jless --version

Uso básico

# Abrir um arquivo local — o visualizador de árvore interativo é iniciado imediatamente
jless api-response.json

# Redirecionar qualquer stream JSON diretamente para o jless
curl -s https://api.github.com/users/torvalds | jless

# Abrir com todos os nós recolhidos ao nível superior (ponto de partida útil para documentos grandes)
jless --mode line api-response.json

# Carregar um elemento específico de array e visualizá-lo isoladamente
jq '.[0]' deployments.json | jless

Navegação e busca na prática

# Dentro do jless:
#
#   j / ↓        descer
#   k / ↑        subir
#   l / →        expandir nó (ou Enter)
#   h / ←        recolher nó
#   H            recolher atual + todos os irmãos → visão geral de alto nível
#   L            expandir tudo recursivamente
#
#   /            iniciar busca para frente — digite nome da chave e pressione Enter
#   n / N        próximo / resultado de busca anterior
#
#   g / gg       pular para o início
#   G            pular para o final
#   q            sair

Referência de Atalhos de Teclado do jless

Todos os atalhos estão disponíveis imediatamente após abrir o jless — nenhuma configuração é necessária. O modelo de navegação é intencionalmente idêntico ao do vim para que a memória muscular existente seja transferida.

jq -C | less -R — Paginação Colorida Sem Ferramentas Extras

Se o jless não estiver instalado e você precisar de uma visualização rolável e colorida de uma resposta JSON, jq -C . | less -R é uma alternativa capaz. A flag -C força os códigos de cor ANSI mesmo quando stdout é um pipe (normalmente o jq os remove), e -R instrui o less a renderizar esses códigos em vez de imprimi-los como texto literal. O resultado é um documento completamente colorido e rolável — sem a estrutura de árvore interativa do jless. A navegação dentro do less usa as teclas de seta ou as teclas estilo vim j/k, e / aciona a busca de texto integrada do less.

# Paginador básico colorido
jq -C . response.json | less -R

# De uma resposta curl — -s evita que a barra de progresso corrompa o stream JSON
curl -s https://api.github.com/repos/jqlang/jq | jq -C . | less -R

# Ordenar chaves para facilitar a varredura visual, depois paginar
jq -CS . config.json | less -R
# -C = forçar cor, -S = ordenar chaves (ambas as flags combinadas)

# Adicionar um alias para nunca precisar digitar o pipe completo novamente
alias jqv='jq -C . | less -R'
# Uso: cat response.json | jqv
#   ou: curl -s https://api.example.com/status | jqv

JQ_COLORS — Temas de Cor Personalizados

JQ_COLORS é uma variável de ambiente que substitui o esquema de cor ANSI padrão do jq. Ela aceita uma string de sete códigos de atributo ANSI;cor separados por dois-pontos, um por tipo JSON nesta ordem fixa: null : false : true : números : strings : arrays : objetos. Cada código está no formato atributo;cor onde o atributo é 0 (normal), 1 (negrito), 2 (tênue) ou 4 (sublinhado), e a cor é um número de cor ANSI padrão (30–37 = padrão, 90–97 = brilhante).

# Referência de cores ANSI para construir JQ_COLORS:
#   Atributos:  0=normal  1=negrito  2=tênue  4=sublinhado
#   Cores:      30=preto  31=vermelho  32=verde  33=amarelo
#               34=azul   35=magenta  36=ciano  37=branco
#   Brilhantes: 90=preto-brilhante  91=vermelho-brilhante  92=verde-brilhante  93=amarelo-brilhante
#               94=azul-brilhante  95=magenta-brilhante  96=ciano-brilhante  97=branco-brilhante
#
# Ordem: null : false : true : números : strings : arrays : objetos

# Tema de alto contraste para terminais escuros (recomendado)
export JQ_COLORS="1;30:0;91:0;92:0;93:0;32:1;96:1;96"
# null=cinza-tênue, false=vermelho-brilhante, true=verde-brilhante,
# números=amarelo-brilhante, strings=verde, arrays=ciano-negrito, objetos=ciano-negrito

# Tema estilo Solarized
export JQ_COLORS="2;37:0;35:0;35:0;36:0;33:1;34:1;34"
# null=branco-tênue, false=magenta, true=magenta,
# números=ciano, strings=amarelo, arrays=azul-negrito, objetos=azul-negrito

# Mínimo (apenas chaves em negrito, tudo mais simples)
export JQ_COLORS="0;90:0;39:0;39:0;39:0;39:1;39:1;39"

# Adicionar o tema escolhido a ~/.bashrc ou ~/.zshrc para que se aplique a cada chamada do jq
echo 'export JQ_COLORS="1;30:0;91:0;92:0;93:0;32:1;96:1;96"' >> ~/.bashrc
source ~/.bashrc

# Testar o tema
echo '{"active":true,"errors":null,"count":42,"tags":["api","v2"],"meta":{"version":"1.0"}}' | jq .

Aliases de Shell para Visualização Diária de JSON

Os comandos para visualização interativa de JSON são verbosos por padrão. Um pequeno conjunto de aliases em ~/.bashrc ou ~/.zshrc transforma o jless e a paginação colorida em comandos de uma única palavra que se integram naturalmente a qualquer fluxo de trabalho. Os aliases abaixo se compõem — jv e jvp ambos aceitam entrada redirecionada ou um nome de arquivo como primeiro argumento.

# Adicionar a ~/.bashrc ou ~/.zshrc

# jv — visualizador interativo (jless se disponível, paginador colorido como alternativa)
jv() {
  if command -v jless &>/dev/null; then
    jless "$@"
  else
    jq -C . "$@" | less -R
  fi
}

# jvp — visualizar com chaves ordenadas alfabeticamente (útil para comparar respostas)
alias jvp='jq -CS . | less -R'

# jvc — visualizar da área de transferência (macOS)
alias jvc='pbpaste | jless'

# jvf — visualizar e filtrar: jvf '.users[0]' response.json
jvf() {
  local filter="$1"; shift
  jq -C "$filter" "$@" | less -R
}

# Recarregar sem reiniciar o terminal
source ~/.bashrc

# Exemplos de uso após adicionar os aliases acima

# Visualizar qualquer arquivo ou resposta redirecionada
jv deployment-config.json
curl -s https://api.github.com/users/torvalds | jv

# Visualizar ordenado (fácil de examinar alfabeticamente)
cat feature-flags.json | jvp

# Explorar um subdocumento interativamente
jvf '.database' infra/app-config.json
jvf '.users[] | select(.role == "admin")' users.json

bat — Visualização de Arquivos JSON com Destaque de Sintaxe

bat é um substituto do cat com destaque de sintaxe, números de linha e um paginador integrado. Para arquivos JSON em disco, oferece uma experiência de leitura limpa, similar a um editor, sem abrir um editor de texto completo. Diferente do jless, o bat renderiza o arquivo como texto estático — sem recolhimento, sem busca, sem navegação além da rolagem. Seu ponto forte é a clareza visual para arquivos estáticos de tamanho médio (configs, fixtures, payloads de teste) onde você quer cor de sintaxe e números de linha, mas não precisa de navegação de árvore interativa.

# macOS
brew install bat

# Debian / Ubuntu (o binário pode se chamar batcat)
apt-get install -y bat
# alias bat=batcat   # adicionar a ~/.bashrc se necessário no Ubuntu

# Visualizar um arquivo JSON com destaque de sintaxe e números de linha
bat config/feature-flags.json

# Desativar o paginador — imprimir diretamente no terminal (útil em scripts)
bat --paging=never api-response.json

# Combinar com jq: formatar com jq, visualizar com bat (preserva o destaque JSON do bat)
jq '.' response.json | bat --language=json --paging=never

fx — Explorador JSON Interativo em Node.js

fx é um visualizador JSON interativo construído em Node.js. Sua interface é similar ao jless — árvore recolhível, navegação por teclado, busca — mas adiciona dois recursos que o jless não tem: suporte a mouse (clique para expandir/recolher nós) e a capacidade de digitar uma expressão JavaScript na barra inferior para filtrar o documento em tempo real. Para equipes que já usam Node.js, o fx é uma escolha natural e não requer um binário separado. Para ambientes de terminal puro sem Node, o jless é a opção mais leve.

# Instalar globalmente via npm
npm install -g fx

# Ou executar sem instalar (npx armazena o pacote em cache)
curl -s https://api.github.com/users/torvalds | npx fx

# Uso interativo básico
fx api-response.json
curl -s https://api.github.com/repos/jqlang/jq | fx

# No fx: teclas de seta navegam, Enter expande/recolhe, / busca
# A barra inferior aceita expressões JavaScript para filtragem ao vivo:
#   .name           → mostrar apenas o campo "name"
#   .repos.slice(0,5) → primeiros 5 repos

# fx também funciona como formatador não interativo (como jq . mas com sintaxe JS)
# Passe uma expressão JavaScript como argumento — sem modo interativo
echo '{"users":[{"id":1,"name":"João Silva"},{"id":2,"name":"Camila Rocha"}]}' \
  | fx '.users[0].name'
# João Silva

# Encadear com map para transformações de array
cat deployments.json | fx '.items.map(d => ({id: d.deploy_id, status: d.state}))'

Erros Comuns

Estes quatro erros aparecem repetidamente quando os desenvolvedores começam a usar visualizadores JSON no terminal — cada um tem uma correção clara assim que você entende por que acontece.

# Resposta de API de 300 linhas — as 280 linhas superiores rolam imediatamente
curl -s https://api.github.com/users/torvalds | jq .
# Apenas a parte inferior da saída está visível — não é possível navegar de volta

# O documento completo permanece acessível no jless — nada é perdido
curl -s https://api.github.com/users/torvalds | jless
# j/k para rolar, h/l para recolher/expandir, / para buscar

# Apenas 6 valores — jq usa os padrões silenciosamente, sem indicação de por quê
export JQ_COLORS="1;30:0;91:0;92:0;93:0;32:1;96"
echo '{"ok":true}' | jq .  # cores inalteradas — nenhum erro exibido

# Exatamente 7 valores — 6 dois-pontos
export JQ_COLORS="1;30:0;91:0;92:0;93:0;32:1;96:1;96"

# Verificar a contagem antes de adicionar ao perfil do shell
echo "$JQ_COLORS" | tr -cd ':' | wc -c   # deve exibir 6

# A saída do jless é para olhos humanos — redirecioná-la produz lixo
jless response.json | grep "request_id"
# Saída: códigos de escape ANSI e sequências de cursor, não texto limpo

# Use jq para extração programática — limpo e componível
jq -r '.request_id' response.json | grep "req_"

# Use jless apenas como ponto final do terminal — nada depois dele
jless response.json

# -C sem -R: sequências de escape são impressas como texto bruto
jq -C . response.json | less
# Saída: ^[[1;34m"status"^[[0m: ^[[0;32m"ok"^[[0m ...

# -C com -R: códigos ANSI são renderizados como cores reais
jq -C . response.json | less -R
# Saída: JSON colorido, limpo e legível

jless vs jq vs bat vs fx — Comparação de Visualizadores Interativos

Todas as quatro ferramentas renderizam JSON colorido, mas suas capacidades interativas diferem significativamente. Escolha com base em se você precisa de navegação recolhível, busca ou suporte a mouse — e se o Node.js já está em seu ambiente.

Para a maioria das situações: instale o jless uma vez e use-o como o visualizador interativo padrão. Mantenha jq -C . | less -R como alternativa para ambientes onde você não pode instalar binários adicionais. Adicione fx se sua equipe é principalmente Node.js e valoriza a navegação com mouse ou filtragem JavaScript ao vivo.

Perguntas Frequentes

# Abrir arquivo no jless, depois pressionar / para buscar
jless api-response.json
# No jless: digite /  →  "request_id"  →  Enter  →  n para próxima correspondência

# Alternativa com jq: extrair e imprimir todas as chaves correspondentes no stdout
jq '.. | objects | with_entries(select(.key == "request_id"))' api-response.json

# Abrir a resposta no jless
curl -s https://api.github.com/repos/jqlang/jq | jless
# No jless:
#   H            → recolher todas as chaves do nível superior
#   j/k          → navegar até a chave desejada
#   l            → expandir apenas essa ramificação
#   gg           → retornar à raiz
#   G            → pular para o último elemento

# Tema de alto contraste para terminais escuros — adicionar a ~/.bashrc ou ~/.zshrc
export JQ_COLORS="1;30:0;91:0;92:0;93:0;32:1;96:1;96"
# null=cinza, false=vermelho-brilhante, true=verde-brilhante,
# números=amarelo-brilhante, strings=verde, arrays/objetos=ciano-brilhante

# Testar imediatamente sem recarregar o shell
echo '{"active":true,"errors":0,"tags":["api","v2"]}' | jq .

# Payload pequeno — jq . funciona bem
echo '{"status":"ok","version":"2.4.1"}' | jq .

# Resposta grande ou aninhada — jless é melhor
curl -s https://api.github.com/repos/jqlang/jq | jless
# → árvore interativa, sem saída rolando para fora da tela

# Exploração interativa com jless
curl -s https://api.github.com/users/torvalds | jless

# Paginador colorido como alternativa (sem recolhimento, mas com rolagem e cor)
curl -s https://api.github.com/users/torvalds | jq -C . | less -R

# tmux lado a lado: dividir horizontalmente, depois executar jless em cada painel
tmux split-window -h
# Painel esquerdo:  jless response-v1.json
# Painel direito: jless response-v2.json

# Ou use diff na saída normalizada pelo jq para um diff de texto
diff <(jq -S . response-v1.json) <(jq -S . response-v2.json)

Ferramentas Relacionadas

A ferramenta Embelezador JSON oferece a mesma visualização recolhível e colorida que o jless — diretamente no navegador, sem instalação e sem necessidade de terminal.