Bash JSON Viewer — jless & JQ_COLORS

Gdy potrzebujesz przeglądarki JSON w bash do interaktywnej eksploracji zamiast skryptowania, standardowe jq . nie wystarcza — output przewija się poza górę terminala i nie można wrócić do 300-wierszowej odpowiedzi API. Ten przewodnik obejmuje narzędzia zbudowane specjalnie do interaktywnego przeglądania JSON w terminalu: jless (zwijane drzewo z nawigacją vim-keys), JQ_COLORS do niestandardowych schematów kolorów, jq -C | less -R do kolorowego przewijania, aliasy powłoki do codziennego użytku oraz fx jako alternatywa Node.js. Dla skryptowania, CI/CD i walidacji zapoznaj się z towarzyszącym przewodnikiem formatowania JSON w Bash. Do przeglądania w przeglądarce bez instalacji narzędzie Upiększacz JSON działa natychmiast. Przykłady przetestowane na Bash 5.x (macOS przez Homebrew, Ubuntu 22.04+) i kompatybilne z Bash 3.2+ (systemowa powłoka macOS).

Interaktywne vs. Skryptowe przeglądanie JSON

Przekierowanie JSON do jq . to właściwy wybór, gdy chcesz sformatowany output dla małego ładunku lub gdy wynik trafia do kolejnego polecenia. To zły wybór, gdy musisz eksplorować odpowiedź API z 200 polami — output przelatuje przez okno terminala i nie daje możliwości nawigacji, zwijania sekcji ani wyszukiwania konkretnego pola bez ponownego uruchomienia polecenia z filtrem. Interaktywne przeglądarki JSON renderują ten sam sformatowany, kolorowy output wewnątrz trwałego pagera, gdzie kontrolujesz nawigację. Dane są identyczne; różnica tkwi w interfejsie.

# jq . — output przewija się poza ekran dla dużych odpowiedzi
curl -s https://api.github.com/users/torvalds | jq .
# 300+ wierszy przewija się — kontekst natychmiast tracisz

# jless — otwiera interaktywny pager, nic się nie przewija
curl -s https://api.github.com/users/torvalds | jless
# Cały dokument widoczny, zwijany, przeszukiwalny z j/k/h/l

jless — Interaktywna Przeglądarka JSON

jless to dedykowana przeglądarka JSON dla terminala. W przeciwieństwie do zwykłego potoku przez jq, renderuje dokument jako trwałe zwijane drzewo: każdy obiekt i tablica może być niezależnie rozwijana lub zwijana za pomocą l i h, nawigacja używa klawiszy vim, a wyszukiwanie przyrostowe natychmiast znajduje każdy klucz lub wartość. Strumieniuje dane przyrostowo, więc otwiera duże pliki i odpowiedzi API w czasie poniżej sekundy niezależnie od rozmiaru — tam gdzie jq buforuje cały dokument przed wyświetleniem. Sięgam po jless jako pierwsze narzędzie, gdy odpowiedź API jest zbyt duża do szybkiego przejrzenia.

Instalacja

# macOS
brew install jless

# Linux — gotowy plik binarny z 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/

# Weryfikacja
jless --version

Podstawowe użycie

# Otwórz lokalny plik — interaktywna przeglądarka uruchamia się natychmiast
jless api-response.json

# Przekieruj dowolny strumień JSON bezpośrednio do jless
curl -s https://api.github.com/users/torvalds | jless

# Otwórz z wszystkimi węzłami zwiniętymi do najwyższego poziomu (przydatny punkt startowy)
jless --mode line api-response.json

# Załaduj konkretny element tablicy i obejrzyj w izolacji
jq '.[0]' deployments.json | jless

Nawigacja i wyszukiwanie w praktyce

# Wewnątrz jless:
#
#   j / ↓        w dół
#   k / ↑        w górę
#   l / →        rozwiń węzeł (lub Enter)
#   h / ←        zwiń węzeł
#   H            zwiń bieżący + wszystkich sąsiadów → przegląd wysokiego poziomu
#   L            rozwiń wszystko rekurencyjnie
#
#   /            rozpocznij wyszukiwanie do przodu — wpisz nazwę klucza i naciśnij Enter
#   n / N        następne / poprzednie dopasowanie
#
#   g / gg       przejdź do początku
#   G            przejdź do końca
#   q            wyjdź

Tabela Skrótów Klawiszowych jless

Wszystkie skróty są dostępne natychmiast po otwarciu jless — nie wymagają konfiguracji. Model nawigacji jest celowo identyczny z vim, aby istniejąca pamięć mięśniowa się przeniosła.

jq -C | less -R — Kolorowe Przewijanie Bez Dodatkowych Narzędzi

Jeśli jless nie jest zainstalowany i potrzebujesz przewijanego, kolorowego widoku odpowiedzi JSON, jq -C . | less -R to solidna rezerwa. Flaga -C wymusza kody kolorów ANSI nawet gdy stdout jest potokiem (normalnie jq je usuwa), a -R mówi less, aby renderował te kody zamiast drukować je jako dosłowny tekst. Wynikiem jest w pełni kolorowy, przewijalny dokument — bez interaktywnej struktury drzewa jless. Nawigacja wewnątrz less używa klawiszy strzałek lub vim-style j/k, a / uruchamia wbudowane wyszukiwanie tekstowe less.

# Podstawowy kolorowy pager
jq -C . response.json | less -R

# Z odpowiedzi curl — -s zapobiega pojawieniu się paska postępu w strumieniu JSON
curl -s https://api.github.com/repos/jqlang/jq | jq -C . | less -R

# Posortuj klucze dla łatwiejszego skanowania, następnie przejrzyj
jq -CS . config.json | less -R
# -C = wymuś kolor, -S = sortuj klucze (obie flagi połączone)

# Dodaj alias, żeby nie wpisywać pełnego potoku za każdym razem
alias jqv='jq -C . | less -R'
# Użycie: cat response.json | jqv
#    lub: curl -s https://api.example.com/status | jqv

JQ_COLORS — Niestandardowe Schematy Kolorów

JQ_COLORS to zmienna środowiskowa nadpisująca domyślny schemat kolorów ANSI jq. Przyjmuje ciąg siedmiu kodów attribute;color oddzielonych dwukropkami, po jednym dla każdego typu JSON w tej stałej kolejności: null : false : true : liczby : ciągi : tablice : obiekty. Każdy kod ma format atrybut;kolor, gdzie atrybut to 0 (normalny), 1 (pogrubiony), 2 (przyciemniony) lub 4 (podkreślony), a kolor to standardowy numer ANSI (30–37 = standardowe, 90–97 = jasne).

# Informacje o kolorach ANSI do budowania JQ_COLORS:
#   Atrybuty:  0=normalny  1=pogrubiony  2=przyciemniony  4=podkreślony
#   Kolory:    30=czarny  31=czerwony  32=zielony  33=żółty
#              34=niebieski  35=magenta  36=cyjan  37=biały
#   Jasne:     90=jasny-czarny  91=jasny-czerwony  92=jasny-zielony  93=jasny-żółty
#              94=jasny-niebieski  95=jasna-magenta  96=jasny-cyjan  97=jasny-biały
#
# Kolejność: null : false : true : liczby : ciągi : tablice : obiekty

# Motyw wysokiego kontrastu dla ciemnych terminali (zalecany)
export JQ_COLORS="1;30:0;91:0;92:0;93:0;32:1;96:1;96"
# null=przyciemniony-szary, false=jasny-czerwony, true=jasny-zielony,
# numbers=jasny-żółty, strings=zielony, arrays=pogrubiony-cyjan, objects=pogrubiony-cyjan

# Motyw w stylu Solarized
export JQ_COLORS="2;37:0;35:0;35:0;36:0;33:1;34:1;34"
# null=przyciemniony-biały, false=magenta, true=magenta,
# numbers=cyjan, strings=żółty, arrays=pogrubiony-niebieski, objects=pogrubiony-niebieski

# Minimalny (tylko pogrubione klucze, reszta zwykła)
export JQ_COLORS="0;90:0;39:0;39:0;39:0;39:1;39:1;39"

# Dodaj wybrany motyw do ~/.bashrc lub ~/.zshrc, aby stosował się przy każdym wywołaniu jq
echo 'export JQ_COLORS="1;30:0;91:0;92:0;93:0;32:1;96:1;96"' >> ~/.bashrc
source ~/.bashrc

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

Aliasy Powłoki do Codziennego Przeglądania JSON

Polecenia do interaktywnego przeglądania JSON są domyślnie rozwlekłe. Mały zestaw aliasów w ~/.bashrc lub ~/.zshrc sprawia, że jless i kolorowe przewijanie stają się jednowyrazowymi poleceniami, które naturalnie wpasowują się w każdy przepływ pracy. Aliasy poniżej komponują się — jv i jvp oba akceptują wejście z potoku lub nazwę pliku jako pierwszy argument.

# Dodaj do ~/.bashrc lub ~/.zshrc

# jv — interaktywna przeglądarka (jless jeśli dostępny, kolorowy pager jako rezerwa)
jv() {
  if command -v jless &>/dev/null; then
    jless "$@"
  else
    jq -C . "$@" | less -R
  fi
}

# jvp — przeglądaj z kluczami posortowanymi alfabetycznie (przydatne do porównywania odpowiedzi)
alias jvp='jq -CS . | less -R'

# jvc — przeglądaj ze schowka (macOS)
alias jvc='pbpaste | jless'

# jvf — przeglądaj i filtruj: jvf '.users[0]' response.json
jvf() {
  local filter="$1"; shift
  jq -C "$filter" "$@" | less -R
}

# Przeładuj bez restartu terminala
source ~/.bashrc

# Przykłady użycia po dodaniu powyższych aliasów

# Przeglądaj dowolny plik lub odpowiedź z potoku
jv deployment-config.json
curl -s https://api.github.com/users/torvalds | jv

# Przeglądaj posortowane (łatwe do skanowania alfabetycznie)
cat feature-flags.json | jvp

# Zagłęb się w subdokument interaktywnie
jvf '.database' infra/app-config.json
jvf '.users[] | select(.role == "admin")' users.json

bat — Przeglądanie Plików JSON z Podświetlaniem Składni

bat to zamiennik cat z podświetlaniem składni, numerami wierszy i wbudowanym pagerem. Dla plików JSON na dysku zapewnia czyste, edytorowe doświadczenie czytania bez otwierania pełnego edytora tekstu. W przeciwieństwie do jless, bat renderuje plik jako statyczny tekst — brak zwijania, brak wyszukiwania, brak nawigacji poza przewijaniem. Jego siłą jest wizualna klarowność dla plików statycznych średniego rozmiaru (konfigi, fixtures, ładunki testowe), gdzie chcesz kolorowanie składni i numery wierszy, ale nie potrzebujesz interaktywnej nawigacji drzewem.

# macOS
brew install bat

# Debian / Ubuntu (plik binarny może się nazywać batcat)
apt-get install -y bat
# alias bat=batcat   # dodaj do ~/.bashrc jeśli potrzeba na Ubuntu

# Przeglądaj plik JSON z podświetlaniem składni i numerami wierszy
bat config/feature-flags.json

# Wyłącz pager — drukuj bezpośrednio do terminala (przydatne w skryptach)
bat --paging=never api-response.json

# Połącz z jq: formatuj przez jq, przeglądaj przez bat (zachowuje podświetlanie JSON)
jq '.' response.json | bat --language=json --paging=never

fx — Interaktywny Eksplorator JSON na Node.js

fx to interaktywna przeglądarka JSON zbudowana na Node.js. Jej interfejs jest podobny do jless — zwijane drzewo, nawigacja klawiaturowa, wyszukiwanie — ale dodaje dwie funkcje, których jless nie ma: obsługa myszy (kliknij aby rozwinąć/zwinąć węzły) oraz możliwość wpisania wyrażenia JavaScript w dolnym pasku do filtrowania dokumentu w czasie rzeczywistym. Dla zespołów już działających na Node.js, fx jest naturalnym wyborem i nie wymaga osobnego pliku binarnego. W czystych środowiskach terminalowych bez Node, jless jest lżejszym wyborem.

# Zainstaluj globalnie przez npm
npm install -g fx

# Lub uruchom bez instalowania (npx cachuje pakiet)
curl -s https://api.github.com/users/torvalds | npx fx

# Podstawowe użycie interaktywne
fx api-response.json
curl -s https://api.github.com/repos/jqlang/jq | fx

# W fx: klawisze strzałek do nawigacji, Enter rozwija/zwija, / wyszukuje
# Dolny pasek akceptuje wyrażenia JavaScript do filtrowania na żywo:
#   .name           → pokaż tylko pole "name"
#   .repos.slice(0,5) → pierwsze 5 repozytoriów

# fx działa też jako nieinteraktywny formater (jak jq . ale ze składnią JS)
# Przekaż wyrażenie JavaScript jako argument — brak trybu interaktywnego
echo '{"users":[{"id":1,"name":"Sarah Chen"},{"id":2,"name":"Marcus Osei"}]}' \
  | fx '.users[0].name'
# Sarah Chen

# Łańcuch z map do transformacji tablic
cat deployments.json | fx '.items.map(d => ({id: d.deploy_id, status: d.state}))'

Typowe Błędy

Te cztery błędy pojawiają się wielokrotnie, gdy programiści zaczynają używać terminalowych przeglądarek JSON — każdy ma jasne rozwiązanie, gdy tylko zrozumiesz dlaczego do niego dochodzi.

# 300-wierszowa odpowiedź API — pierwszych 280 wierszy natychmiast się przewija
curl -s https://api.github.com/users/torvalds | jq .
# Widoczny tylko dolny fragment outputu — nie można wrócić

# Pełny dokument dostępny w jless — nic nie jest utracone
curl -s https://api.github.com/users/torvalds | jless
# j/k do przewijania, h/l do zwijania/rozwijania, / do wyszukiwania

# Tylko 6 wartości — jq cicho używa wartości domyślnych, brak wskazania dlaczego
export JQ_COLORS="1;30:0;91:0;92:0;93:0;32:1;96"
echo '{"ok":true}' | jq .  # kolory niezmienione — brak błędu

# Dokładnie 7 wartości — 6 dwukropków
export JQ_COLORS="1;30:0;91:0;92:0;93:0;32:1;96:1;96"

# Zweryfikuj licznik przed dodaniem do profilu powłoki
echo "$JQ_COLORS" | tr -cd ':' | wc -c   # musi dać 6

# Output jless jest dla ludzkich oczu — przekierowanie daje śmieć
jless response.json | grep "request_id"
# Output: kody ucieczki ANSI i sekwencje kursora, nie czysty tekst

# Używaj jq do programowego wyodrębniania — czyste, komponowalne
jq -r '.request_id' response.json | grep "req_"

# Używaj jless tylko jako końcowy punkt w terminalu — nic po nim
jless response.json

# -C bez -R: sekwencje ucieczki drukowane jako surowy tekst
jq -C . response.json | less
# Output: ^[[1;34m"status"^[[0m: ^[[0;32m"ok"^[[0m ...

# -C z -R: kody ANSI renderowane jako prawdziwe kolory
jq -C . response.json | less -R
# Output: kolorowy JSON, czysty i czytelny

jless vs jq vs bat vs fx — Porównanie Interaktywnych Przeglądarek

Wszystkie cztery narzędzia renderują kolorowy JSON, ale ich możliwości interaktywne znacznie się różnią. Wybieraj na podstawie tego, czy potrzebujesz zwijania drzewa, wyszukiwania lub obsługi myszy — i czy Node.js jest już w Twoim środowisku.

W większości przypadków: zainstaluj jless raz i używaj jako domyślnej interaktywnej przeglądarki. Trzymaj jq -C . | less -R jako rezerwę dla środowisk gdzie nie możesz instalować dodatkowych plików binarnych. Dodaj fx jeśli Twój zespół jest przede wszystkim na Node.js i ceni nawigację myszą lub filtrowanie JavaScript na żywo.

Często Zadawane Pytania

# Otwórz plik w jless, następnie naciśnij / do wyszukiwania
jless api-response.json
# W jless: wpisz /  →  "request_id"  →  Enter  →  n do następnego dopasowania

# Alternatywa z jq: wyodrębnij i wydrukuj wszystkie pasujące klucze
jq '.. | objects | with_entries(select(.key == "request_id"))' api-response.json

# Otwórz odpowiedź w jless
curl -s https://api.github.com/repos/jqlang/jq | jless
# W jless:
#   H            → zwiń wszystkie klucze najwyższego poziomu
#   j/k          → przejdź do interesującego klucza
#   l            → rozwiń tylko tę gałąź
#   gg           → powrót do korzenia
#   G            → przejście do ostatniego elementu

# Motyw wysokiego kontrastu dla ciemnych terminali — dodaj do ~/.bashrc lub ~/.zshrc
export JQ_COLORS="1;30:0;91:0;92:0;93:0;32:1;96:1;96"
# null=szary, false=jaskrawoczerwony, true=jaskrawozielony,
# numbers=jaskrawożółty, strings=zielony, arrays/objects=jaskrawocyjan

# Test bez przeładowania powłoki
echo '{"active":true,"errors":0,"tags":["api","v2"]}' | jq .

# Małe dane — jq . jest w porządku
echo '{"status":"ok","version":"2.4.1"}' | jq .

# Duża lub zagnieżdżona odpowiedź — lepszy jless
curl -s https://api.github.com/repos/jqlang/jq | jless
# → interaktywne drzewo, nic nie przewija się poza ekran

# Interaktywna eksploracja z jless
curl -s https://api.github.com/users/torvalds | jless

# Kolorowy pager jako rezerwa (bez zwijania, ale z przewijaniem i kolorem)
curl -s https://api.github.com/users/torvalds | jq -C . | less -R

# tmux obok siebie: podziel poziomo, następnie uruchom jless w każdym panelu
tmux split-window -h
# Lewy panel:  jless response-v1.json
# Prawy panel: jless response-v2.json

# Lub użyj diff na wyjściu znormalizowanym przez jq
diff <(jq -S . response-v1.json) <(jq -S . response-v2.json)

Powiązane Narzędzia

Narzędzie Upiększacz JSON daje ten sam zwijany, kolorowy widok co jless — bezpośrednio w przeglądarce, bez instalacji i bez terminala.