Visor JSON en Bash — jless & JQ_COLORS

Cuando necesitas un visor JSON en bash para exploración interactiva en lugar de scripting, el pipe estándar jq . se queda corto — la salida se desplaza más allá del inicio del terminal y no hay forma de navegar hacia atrás en una respuesta de API de 300 líneas. Esta guía cubre herramientas creadas específicamente para ver JSON de forma interactiva en el terminal: jless (árbol contraíble con navegación estilo vim), JQ_COLORS para temas de color personalizados, jq -C | less -R para paginación con color, alias de shell para uso diario, y fx como alternativa basada en Node.js. Para scripting, CI/CD y flujos de validación, consulta la guía complementaria Formatear JSON en Bash. Para un visor en el navegador sin instalación, la herramienta Embellecedor JSON funciona al instante. Los ejemplos están probados en Bash 5.x (macOS vía Homebrew, Ubuntu 22.04+) y son compatibles con Bash 3.2+ (shell del sistema macOS).

Vista JSON Interactiva vs. Scripted

Canalizar JSON a jq . es la elección correcta cuando quieres salida formateada para un payload pequeño, o cuando el resultado alimenta otro comando. Es la elección equivocada cuando necesitas explorar una respuesta de API con 200 campos — la salida vuela más allá de la ventana del terminal y no te deja ninguna forma de navegar, contraer secciones o buscar un campo específico sin volver a ejecutar el comando con un filtro. Los visores JSON interactivos renderizan la misma salida formateada y con colores dentro de un paginador persistente donde tú controlas la navegación. Los datos son idénticos; la diferencia es la interfaz.

# jq . — la salida se desplaza fuera de pantalla en respuestas grandes
curl -s https://api.github.com/users/torvalds | jq .
# Más de 300 líneas se desplazan — pierdes el contexto de inmediato

# jless — abre un paginador interactivo, nada se desplaza fuera de pantalla
curl -s https://api.github.com/users/torvalds | jless
# Documento completo visible, contraíble, con búsqueda usando j/k/h/l

jless — Visor JSON Interactivo

jless es un visor JSON en terminal diseñado específicamente para ello. A diferencia de un pipe simple de jq, renderiza el documento como un árbol contraíble persistente: cada objeto y array puede expandirse o contraerse de forma independiente con l y h, la navegación usa teclas estilo vim, y la búsqueda incremental encuentra cualquier clave o valor al instante. Transmite la entrada de forma incremental, por lo que abre archivos grandes y respuestas de API en menos de un segundo independientemente del tamaño — donde jq almacena en búfer todo el documento antes de mostrar nada. Recurro a jless como la primera herramienta siempre que una respuesta de API es demasiado grande para escanear de un vistazo.

Instalación

# macOS
brew install jless

# Linux — binario precompilado desde 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 un archivo local — el visor de árbol interactivo se inicia inmediatamente
jless api-response.json

# Canalizar cualquier stream JSON directamente a jless
curl -s https://api.github.com/users/torvalds | jless

# Abrir con todos los nodos contraídos al nivel superior (punto de partida útil para documentos grandes)
jless --mode line api-response.json

# Cargar un elemento específico de array y verlo en aislamiento
jq '.[0]' deployments.json | jless

Navegación y búsqueda en la práctica

# Dentro de jless:
#
#   j / ↓        bajar
#   k / ↑        subir
#   l / →        expandir nodo (o Intro)
#   h / ←        contraer nodo
#   H            contraer actual + todos los hermanos → vista de alto nivel
#   L            expandir todo de forma recursiva
#
#   /            iniciar búsqueda hacia adelante — escribe nombre de clave y pulsa Intro
#   n / N        siguiente / resultado de búsqueda anterior
#
#   g / gg       saltar al inicio
#   G            saltar al final
#   q            salir

Referencia de Atajos de Teclado de jless

Todos los atajos están disponibles de inmediato al abrir jless — no se requiere configuración. El modelo de navegación es intencionalmente idéntico al de vim para que la memoria muscular existente sea transferible.

jq -C | less -R — Paginación con Color Sin Herramientas Adicionales

Si jless no está instalado y necesitas una vista desplazable y con colores de una respuesta JSON, jq -C . | less -R es una alternativa capaz. El flag -C fuerza los códigos de color ANSI incluso cuando stdout es un pipe (normalmente jq los elimina), y -R le indica a less que renderice esos códigos en lugar de imprimirlos como texto literal. El resultado es un documento completamente con colores y desplazable — sin la estructura de árbol interactivo de jless. La navegación dentro de less usa las teclas de flecha o las teclas estilo vim j/k, y / activa la búsqueda de texto integrada de less.

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

# Desde una respuesta curl — -s evita que la barra de progreso corrompa el stream JSON
curl -s https://api.github.com/repos/jqlang/jq | jq -C . | less -R

# Ordenar claves para facilitar el escaneo visual, luego paginar
jq -CS . config.json | less -R
# -C = forzar color, -S = ordenar claves (ambos flags combinados)

# Añadir un alias para no tener que escribir el pipe completo nunca más
alias jqv='jq -C . | less -R'
# Uso: cat response.json | jqv
#   o: curl -s https://api.example.com/status | jqv

JQ_COLORS — Temas de Color Personalizados

JQ_COLORS es una variable de entorno que sobreescribe el esquema de color ANSI predeterminado de jq. Acepta una cadena de siete códigos de atributo ANSI;color separados por dos puntos, uno por tipo JSON en este orden fijo: null : false : true : números : strings : arrays : objetos. Cada código tiene el formato atributo;color donde el atributo es 0 (normal), 1 (negrita), 2 (tenue) o 4 (subrayado), y el color es un número de color ANSI estándar (30–37 = estándar, 90–97 = brillante).

# Referencia de colores ANSI para construir JQ_COLORS:
#   Atributos:  0=normal  1=negrita  2=tenue  4=subrayado
#   Colores:    30=negro  31=rojo  32=verde  33=amarillo
#               34=azul   35=magenta  36=cian  37=blanco
#   Brillantes: 90=negro-brillante  91=rojo-brillante  92=verde-brillante  93=amarillo-brillante
#               94=azul-brillante  95=magenta-brillante  96=cian-brillante  97=blanco-brillante
#
# Orden: null : false : true : números : strings : arrays : objetos

# Tema de alto contraste para terminales oscuros (recomendado)
export JQ_COLORS="1;30:0;91:0;92:0;93:0;32:1;96:1;96"
# null=gris-tenue, false=rojo-brillante, true=verde-brillante,
# números=amarillo-brillante, strings=verde, arrays=cian-negrita, objetos=cian-negrita

# Tema estilo Solarized
export JQ_COLORS="2;37:0;35:0;35:0;36:0;33:1;34:1;34"
# null=blanco-tenue, false=magenta, true=magenta,
# números=cian, strings=amarillo, arrays=azul-negrita, objetos=azul-negrita

# Mínimo (solo claves en negrita, todo lo demás plano)
export JQ_COLORS="0;90:0;39:0;39:0;39:0;39:1;39:1;39"

# Añadir el tema elegido a ~/.bashrc o ~/.zshrc para que se aplique a cada llamada de jq
echo 'export JQ_COLORS="1;30:0;91:0;92:0;93:0;32:1;96:1;96"' >> ~/.bashrc
source ~/.bashrc

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

Alias de Shell para la Visualización Diaria de JSON

Los comandos para la visualización interactiva de JSON son verbosos por defecto. Un pequeño conjunto de alias en ~/.bashrc o ~/.zshrc convierte jless y la paginación con color en comandos de una sola palabra que se integran de forma natural en cualquier flujo de trabajo. Los alias siguientes se componen — jv y jvp ambos aceptan entrada canalizad o un nombre de archivo como primer argumento.

# Añadir a ~/.bashrc o ~/.zshrc

# jv — visor interactivo (jless si está disponible, paginador con color como alternativa)
jv() {
  if command -v jless &>/dev/null; then
    jless "$@"
  else
    jq -C . "$@" | less -R
  fi
}

# jvp — ver con claves ordenadas alfabéticamente (útil para comparar respuestas)
alias jvp='jq -CS . | less -R'

# jvc — ver desde el portapapeles (macOS)
alias jvc='pbpaste | jless'

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

# Recargar sin reiniciar el terminal
source ~/.bashrc

# Ejemplos de uso tras añadir los alias anteriores

# Ver cualquier archivo o respuesta canalizada
jv deployment-config.json
curl -s https://api.github.com/users/torvalds | jv

# Ver ordenado (fácil de escanear alfabéticamente)
cat feature-flags.json | jvp

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

bat — Vista de Archivos JSON con Resaltado de Sintaxis

bat es un reemplazo de cat con resaltado de sintaxis, números de línea y un paginador integrado. Para archivos JSON en disco ofrece una experiencia de lectura limpia, similar a un editor, sin necesidad de abrir un editor de texto completo. A diferencia de jless, bat renderiza el archivo como texto estático — sin contracción, sin búsqueda, sin navegación más allá del desplazamiento. Su punto fuerte es la claridad visual para archivos estáticos de tamaño medio (configuraciones, fixtures, payloads de prueba) donde quieres color de sintaxis y números de línea pero no necesitas navegación de árbol interactiva.

# macOS
brew install bat

# Debian / Ubuntu (el binario puede llamarse batcat)
apt-get install -y bat
# alias bat=batcat   # añadir a ~/.bashrc si es necesario en Ubuntu

# Ver un archivo JSON con resaltado de sintaxis y números de línea
bat config/feature-flags.json

# Desactivar el paginador — imprimir directamente en el terminal (útil en scripts)
bat --paging=never api-response.json

# Combinar con jq: formatear con jq, ver con bat (preserva el resaltado JSON de bat)
jq '.' response.json | bat --language=json --paging=never

fx — Explorador JSON Interactivo en Node.js

fx es un visor JSON interactivo construido sobre Node.js. Su interfaz es similar a jless — árbol contraíble, navegación por teclado, búsqueda — pero añade dos características que jless no tiene: soporte de ratón (clic para expandir/contraer nodos) y la posibilidad de escribir una expresión JavaScript en la barra inferior para filtrar el documento en tiempo real. Para equipos que ya usan Node.js, fx es una opción natural y no requiere un binario separado. Para entornos de terminal puro sin Node, jless es la opción más ligera.

# Instalar globalmente vía npm
npm install -g fx

# O ejecutar sin instalar (npx almacena el paquete en caché)
curl -s https://api.github.com/users/torvalds | npx fx

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

# En fx: las teclas de flecha navegan, Intro expande/contrae, / busca
# La barra inferior acepta expresiones JavaScript para filtrado en vivo:
#   .name           → mostrar solo el campo "name"
#   .repos.slice(0,5) → primeros 5 repos

# fx también funciona como formateador no interactivo (como jq . pero con sintaxis JS)
# Pasa una expresión JavaScript como argumento — sin modo interactivo
echo '{"users":[{"id":1,"name":"Carlos Mendoza"},{"id":2,"name":"Ana Torres"}]}' \
  | fx '.users[0].name'
# Carlos Mendoza

# Encadenar con map para transformaciones de array
cat deployments.json | fx '.items.map(d => ({id: d.deploy_id, status: d.state}))'

Errores Comunes

Estos cuatro errores aparecen repetidamente cuando los desarrolladores empiezan a usar visores JSON en el terminal — cada uno tiene una solución clara una vez que entiendes por qué ocurre.

# Respuesta de API de 300 líneas — las 280 líneas superiores se desplazan de inmediato
curl -s https://api.github.com/users/torvalds | jq .
# Solo la parte inferior de la salida es visible — no se puede navegar hacia atrás

# El documento completo permanece accesible en jless — no se pierde nada
curl -s https://api.github.com/users/torvalds | jless
# j/k para desplazarse, h/l para contraer/expandir, / para buscar

# Solo 6 valores — jq usa los valores predeterminados en silencio, sin indicación de por qué
export JQ_COLORS="1;30:0;91:0;92:0;93:0;32:1;96"
echo '{"ok":true}' | jq .  # colores sin cambios — no se muestra ningún error

# Exactamente 7 valores — 6 dos puntos
export JQ_COLORS="1;30:0;91:0;92:0;93:0;32:1;96:1;96"

# Verificar el conteo antes de añadir al perfil de shell
echo "$JQ_COLORS" | tr -cd ':' | wc -c   # debe mostrar 6

# La salida de jless es para ojos humanos — canalizarla produce basura
jless response.json | grep "request_id"
# Salida: códigos de escape ANSI y secuencias de cursor, no texto limpio

# Usa jq para extracción programática — limpio y componible
jq -r '.request_id' response.json | grep "req_"

# Usa jless solo como punto final del terminal — nada después de él
jless response.json

# -C sin -R: las secuencias de escape se imprimen como texto en bruto
jq -C . response.json | less
# Salida: ^[[1;34m"status"^[[0m: ^[[0;32m"ok"^[[0m ...

# -C con -R: los códigos ANSI se renderizan como colores reales
jq -C . response.json | less -R
# Salida: JSON con colores, limpio y legible

jless vs jq vs bat vs fx — Comparación de Visores Interactivos

Las cuatro herramientas renderizan JSON con colores, pero sus capacidades interactivas difieren significativamente. Elige según si necesitas navegación contraíble, búsqueda o soporte de ratón — y si Node.js ya está en tu entorno.

Para la mayoría de situaciones: instala jless una vez y úsalo como el visor interactivo predeterminado. Mantén jq -C . | less -R como alternativa para entornos donde no puedes instalar binarios adicionales. Añade fx si tu equipo es principalmente Node.js y valora la navegación con ratón o el filtrado JavaScript en vivo.

Preguntas Frecuentes

# Abrir archivo en jless, luego pulsar / para buscar
jless api-response.json
# En jless: escribe /  →  "request_id"  →  Intro  →  n para siguiente coincidencia

# Alternativa con jq: extraer e imprimir todas las claves coincidentes en stdout
jq '.. | objects | with_entries(select(.key == "request_id"))' api-response.json

# Abrir la respuesta en jless
curl -s https://api.github.com/repos/jqlang/jq | jless
# En jless:
#   H            → contraer todas las claves del nivel superior
#   j/k          → navegar a la clave deseada
#   l            → expandir solo esa rama
#   gg           → volver a la raíz
#   G            → saltar al último elemento

# Tema de alto contraste para terminales oscuros — añadir a ~/.bashrc o ~/.zshrc
export JQ_COLORS="1;30:0;91:0;92:0;93:0;32:1;96:1;96"
# null=gris, false=rojo-brillante, true=verde-brillante,
# números=amarillo-brillante, strings=verde, arrays/objetos=cian-brillante

# Probar inmediatamente sin recargar el shell
echo '{"active":true,"errors":0,"tags":["api","v2"]}' | jq .

# Payload pequeño — jq . funciona bien
echo '{"status":"ok","version":"2.4.1"}' | jq .

# Respuesta grande o anidada — jless es mejor
curl -s https://api.github.com/repos/jqlang/jq | jless
# → árbol interactivo, sin salida que se desplace fuera de pantalla

# Exploración interactiva con jless
curl -s https://api.github.com/users/torvalds | jless

# Paginador con colores como alternativa (sin contracción, pero con desplazamiento y colores)
curl -s https://api.github.com/users/torvalds | jq -C . | less -R

# tmux en paralelo: dividir horizontalmente, luego ejecutar jless en cada panel
tmux split-window -h
# Panel izquierdo:  jless response-v1.json
# Panel derecho: jless response-v2.json

# O usa diff sobre la salida normalizada por jq para un diff de texto
diff <(jq -S . response-v1.json) <(jq -S . response-v2.json)

Herramientas Relacionadas

La herramienta Embellecedor JSON te ofrece la misma vista contraíble y con colores que jless — directamente en el navegador, sin instalación y sin terminal requerido.