Bash JSON Görüntüleyici — jless & JQ_COLORS

Betik yazmak yerine interaktif keşif için bir bash JSON görüntüleyiciye ihtiyaç duyduğunuzda, standart jq . borusu yetersiz kalır — çıktı terminalin üst kısmına kayar ve 300 satırlık bir API yanıtında geriye gitmenin yolu kalmaz. Bu kılavuz terminalde JSON'ı interaktif görüntülemek için özel olarak tasarlanmış araçları kapsar: jless (vim tuş gezintisiyle daraltılabilir ağaç), JQ_COLORS özel renk temaları, jq -C | less -R renkli sayfalama, günlük kullanım için shell takma adları ve fx Node.js alternatifi olarak. Betik yazma, CI/CD ve doğrulama iş akışları için Bash'te JSON Biçimlendirme kılavuzuna bakın. Sıfır kurulumlu tarayıcı görüntüleyici için JSON Güzelleştirici aracı anında çalışır. Örnekler Bash 5.x (Homebrew ile macOS, Ubuntu 22.04+) üzerinde test edilmiştir ve Bash 3.2+ (macOS sistem shell'i) ile uyumludur.

İnteraktif ve Betiksel JSON Görüntüleme

JSON'ı jq .'ye yönlendirmek, küçük bir yük için biçimlendirilmiş çıktı istediğinizde veya sonuç başka bir komuta beslendiğinde doğru seçimdir. 200 alanlı bir API yanıtını keşfetmeniz gerektiğinde yanlış seçimdir — çıktı terminal penceresinden uçup gider ve filtreyle komutu yeniden çalıştırmadan gezinme, bölümleri daraltma veya belirli bir alan arama imkânı kalmaz. İnteraktif JSON görüntüleyiciler, navigasyonu kontrol ettiğiniz kalıcı bir sayfalayıcıda aynı biçimlendirilmiş ve renkli çıktıyı render eder. Veri aynıdır; fark arayüzdedir.

# jq . — output scrolls off screen for large responses
curl -s https://api.github.com/users/torvalds | jq .
# 300+ lines scroll past — you lose context immediately

# jless — opens an interactive pager, nothing scrolls off
curl -s https://api.github.com/users/torvalds | jless
# Full document visible, collapsible, searchable with j/k/h/l

jless — İnteraktif JSON Görüntüleyici

jless, terminal için özel olarak geliştirilmiş bir JSON görüntüleyicidir. Düz bir jq borusunun aksine, belgeyi kalıcı daraltılabilir ağaç olarak render eder: her nesne ve dizi l ve h ile bağımsız olarak genişletilebilir veya daraltılabilir, gezinme vim tarzı tuşlar kullanır ve artan arama herhangi bir anahtar veya değeri anında bulur. Girişi artımlı olarak akışa alır, bu nedenle jq tüm belgeyi tamponlarken büyük dosyaları ve API yanıtlarını boyuttan bağımsız olarak bir saniyenin altında açar. Bir API yanıtı tek bakışta taranamayacak kadar büyük olduğunda ilk araç olarak jless'e yöneliyorum.

Kurulum

# macOS
brew install jless

# Linux — prebuilt binary from 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/

# Verify
jless --version

Temel kullanım

# Open a local file — interactive tree viewer launches immediately
jless api-response.json

# Pipe any JSON stream directly into jless
curl -s https://api.github.com/users/torvalds | jless

# Open with all nodes collapsed to top level (useful starting point for large documents)
jless --mode line api-response.json

# Load a specific array element and view it in isolation
jq '.[0]' deployments.json | jless

Uygulamada gezinme ve arama

# Inside jless:
#
#   j / ↓        move down
#   k / ↑        move up
#   l / →        expand node (or Enter)
#   h / ←        collapse node
#   H            collapse current + all siblings → high-level overview
#   L            expand everything recursively
#
#   /            start forward search — type a key name and press Enter
#   n / N        next / previous search match
#
#   g / gg       jump to start
#   G            jump to end
#   q            quit

jless Klavye Kısayolları Referansı

Tüm kısayollar jless açıldıktan hemen sonra kullanılabilir — yapılandırma gerekmez. Gezinme modeli, mevcut kas hafızasının aktarılabilmesi için kasıtlı olarak vim ile aynıdır.

jq -C | less -R — Ek Araç Gerektirmeden Renkli Sayfalama

jless kurulu değilse ve JSON yanıtının kaydırılabilir, renkli görünümüne ihtiyaç duyuyorsanız, jq -C . | less -R yetenekli bir yedek seçenektir. -C bayrağı, stdout bir boru olduğunda bile ANSI renk kodlarını zorla uygular (normalde jq bunları kaldırır) ve -R, less'e bu kodları düz metin olarak değil renk olarak render etmesini söyler. Sonuç, jless'in interaktif ağaç yapısı olmadan tamamen renklendirilmiş, kaydırılabilir bir belgedir. less içinde gezinme ok tuşlarını veya vim tarzı j/kkullanır ve /, less'in yerleşik metin aramasını tetikler.

# Basic colorized pager
jq -C . response.json | less -R

# From a curl response — -s prevents progress bar from corrupting the JSON stream
curl -s https://api.github.com/repos/jqlang/jq | jq -C . | less -R

# Sort keys for easier visual scanning, then page
jq -CS . config.json | less -R
# -C = force color, -S = sort keys (both flags combined)

# Add an alias so you never have to type the full pipe again
alias jqv='jq -C . | less -R'
# Usage: cat response.json | jqv
#    or: curl -s https://api.example.com/status | jqv

JQ_COLORS — Özel Renk Temaları

JQ_COLORS, jq'nun varsayılan ANSI renk şemasını geçersiz kılan bir ortam değişkenidir. Bu sabit sırada her JSON türü için bir tane olmak üzere yedi ANSI özniteliği;renk kodundan oluşan iki nokta üst üste ile ayrılmış bir dize alır: null : false : true : sayılar : dizeler : diziler : nesneler. Her kod öznitelik;renk biçimindedir; öznitelik 0 (normal), 1 (kalın), 2 (soluk) veya 4 (altı çizili), renk ise standart ANSI renk numarasıdır (30–37 = standart, 90–97 = parlak).

# ANSI color reference for building JQ_COLORS:
#   Attributes:  0=normal  1=bold  2=dim  4=underline
#   Colors:      30=black  31=red  32=green  33=yellow
#                34=blue   35=magenta  36=cyan  37=white
#   Bright:      90=bright-black  91=bright-red  92=bright-green  93=bright-yellow
#                94=bright-blue  95=bright-magenta  96=bright-cyan  97=bright-white
#
# Order: null : false : true : numbers : strings : arrays : objects

# High-contrast theme for dark terminals (recommended)
export JQ_COLORS="1;30:0;91:0;92:0;93:0;32:1;96:1;96"
# null=dim-gray, false=bright-red, true=bright-green,
# numbers=bright-yellow, strings=green, arrays=bold-cyan, objects=bold-cyan

# Solarized-style theme
export JQ_COLORS="2;37:0;35:0;35:0;36:0;33:1;34:1;34"
# null=dim-white, false=magenta, true=magenta,
# numbers=cyan, strings=yellow, arrays=bold-blue, objects=bold-blue

# Minimal (bold keys only, everything else plain)
export JQ_COLORS="0;90:0;39:0;39:0;39:0;39:1;39:1;39"

# Add your chosen theme to ~/.bashrc or ~/.zshrc so it applies to every jq call
echo 'export JQ_COLORS="1;30:0;91:0;92:0;93:0;32:1;96:1;96"' >> ~/.bashrc
source ~/.bashrc

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

Günlük JSON Görüntüleme İçin Shell Takma Adları

İnteraktif JSON görüntüleme komutları varsayılan olarak uzundur. ~/.bashrc veya ~/.zshrc'deki küçük bir takma ad seti, jless ve renkli sayfalamayı herhangi bir iş akışına doğal olarak entegre olan tek kelimelik komutlara dönüştürür. Aşağıdaki takma adlar birleştirilebilir — jv ve jvp her ikisi de yönlendirilmiş girişi veya ilk bağımsız değişken olarak dosya adını kabul eder.

# Add to ~/.bashrc or ~/.zshrc

# jv — interactive viewer (jless if available, colorized pager fallback)
jv() {
  if command -v jless &>/dev/null; then
    jless "$@"
  else
    jq -C . "$@" | less -R
  fi
}

# jvp — view with keys sorted alphabetically (useful for comparing responses)
alias jvp='jq -CS . | less -R'

# jvc — view from clipboard (macOS)
alias jvc='pbpaste | jless'

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

# Reload without restarting terminal
source ~/.bashrc

# Usage examples after adding aliases above

# View any file or piped response
jv deployment-config.json
curl -s https://api.github.com/users/torvalds | jv

# View sorted (easy to scan alphabetically)
cat feature-flags.json | jvp

# Drill into a sub-document interactively
jvf '.database' infra/app-config.json
jvf '.users[] | select(.role == "admin")' users.json

bat — Sözdizimi Vurgulamalı JSON Dosyası Görüntüleme

bat, sözdizimi vurgulama, satır numaraları ve yerleşik sayfalayıcıya sahip bir cat alternatifidir. Diskteki JSON dosyaları için tam bir metin editörü açmadan temiz, editör tarzı bir okuma deneyimi sunar. jless'in aksine bat, dosyayı statik metin olarak render eder — daraltma yok, arama yok, kaydırmanın ötesinde gezinme yok. Güçlü yanı, interaktif ağaç gezintisi gerekmediğinde sözdizimi rengi ve satır numaraları istediğiniz orta boyutlu statik dosyalar (yapılandırmalar, fikstürler, test yükleri) için görsel açıklıktır.

# macOS
brew install bat

# Debian / Ubuntu (binary may be named batcat)
apt-get install -y bat
# alias bat=batcat   # add to ~/.bashrc if needed on Ubuntu

# View a JSON file with syntax highlighting and line numbers
bat config/feature-flags.json

# Disable pager — print directly to terminal (useful in scripts)
bat --paging=never api-response.json

# Combine with jq: format with jq, view with bat (preserves bat's JSON highlighting)
jq '.' response.json | bat --language=json --paging=never

fx — İnteraktif Node.js JSON Gezgini

fx, Node.js üzerinde oluşturulmuş interaktif bir JSON görüntüleyicidir. Arayüzü jless'e benzer — daraltılabilir ağaç, klavye gezintisi, arama — ancak jless'in sahip olmadığı iki özellik ekler: fare desteği (genişletmek/daraltmak için tıklama) ve belgeyi gerçek zamanlı filtrelemek için alt çubukta JavaScript ifadesi yazabilme. Node.js'i zaten çalıştıran ekipler için fx doğal bir uyumdur ve ayrı bir ikili gerektirmez. Node olmayan saf terminal ortamları için jless daha yalın bir seçimdir.

# Install globally via npm
npm install -g fx

# Or run without installing (npx caches the package)
curl -s https://api.github.com/users/torvalds | npx fx

# Basic interactive use
fx api-response.json
curl -s https://api.github.com/repos/jqlang/jq | fx

# In fx: arrow keys navigate, Enter expands/collapses, / searches
# Bottom bar accepts JavaScript expressions for live filtering:
#   .name           → show only the "name" field
#   .repos.slice(0,5) → first 5 repos

# fx also works as a non-interactive formatter (like jq . but with JS syntax)
# Pass a JavaScript expression as argument — no interactive mode
echo '{"users":[{"id":1,"name":"Sarah Chen"},{"id":2,"name":"Marcus Osei"}]}' \
  | fx '.users[0].name'
# Sarah Chen

# Chain with map for array transformations
cat deployments.json | fx '.items.map(d => ({id: d.deploy_id, status: d.state}))'

Yaygın Hatalar

Geliştiriciler terminal JSON görüntüleyicilerini ilk kullanmaya başladığında bu dört hata tekrar tekrar karşımıza çıkar — nedenini anladıktan sonra her birinin net bir çözümü vardır.

# 300-line API response — top 280 lines immediately scroll off
curl -s https://api.github.com/users/torvalds | jq .
# Only the bottom of the output is visible — cannot navigate back

# Full document stays accessible in jless — nothing is lost
curl -s https://api.github.com/users/torvalds | jless
# j/k to scroll, h/l to collapse/expand, / to search

# Only 6 values — jq silently uses defaults, no indication of why
export JQ_COLORS="1;30:0;91:0;92:0;93:0;32:1;96"
echo '{"ok":true}' | jq .  # colors unchanged — no error shown

# Exactly 7 values — 6 colons
export JQ_COLORS="1;30:0;91:0;92:0;93:0;32:1;96:1;96"

# Verify the count before adding to shell profile
echo "$JQ_COLORS" | tr -cd ':' | wc -c   # must output 6

# jless output is for human eyes — piping it produces garbage
jless response.json | grep "request_id"
# Output: ANSI escape codes and cursor sequences, not clean text

# Use jq for programmatic extraction — clean, composable
jq -r '.request_id' response.json | grep "req_"

# Use jless only as the terminal endpoint — nothing after it
jless response.json

# -C without -R: escape sequences print as raw text
jq -C . response.json | less
# Output: ^[[1;34m"status"^[[0m: ^[[0;32m"ok"^[[0m ...

# -C with -R: ANSI codes are rendered as actual colors
jq -C . response.json | less -R
# Output: colorized JSON, clean and readable

jless vs jq vs bat vs fx — İnteraktif Görüntüleyici Karşılaştırması

Dört araç da renkli JSON render eder, ancak interaktif yetenekleri önemli ölçüde farklıdır. Daraltılabilir gezinme, arama veya fare desteğine ihtiyaç duyup duymadığınıza ve Node.js'in ortamınızda zaten olup olmadığına göre seçim yapın.

Çoğu durumda: jless'i bir kez kurun ve varsayılan interaktif görüntüleyici olarak kullanın. Ek ikili yükleyemeyeceğiniz ortamlar için jq -C . | less -R'yi yedek olarak saklayın. Ekibiniz Node.js öncelikli ise ve fare gezintisine veya canlı JavaScript filtrelemeye değer veriyorsa fx'i ekleyin.

Sıkça Sorulan Sorular

# Open file in jless, then press / to search
jless api-response.json
# In jless: type /  →  "request_id"  →  Enter  →  n for next match

# jq alternative: extract and print all matching keys to stdout
jq '.. | objects | with_entries(select(.key == "request_id"))' api-response.json

# Open the response in jless
curl -s https://api.github.com/repos/jqlang/jq | jless
# In jless:
#   H            → collapse all top-level keys
#   j/k          → navigate to the key you want
#   l            → expand only that branch
#   gg           → return to root
#   G            → jump to last element

# High-contrast theme for dark terminals — add to ~/.bashrc or ~/.zshrc
export JQ_COLORS="1;30:0;91:0;92:0;93:0;32:1;96:1;96"
# null=gray, false=bright-red, true=bright-green,
# numbers=bright-yellow, strings=green, arrays/objects=bright-cyan

# Test immediately without reloading shell
echo '{"active":true,"errors":0,"tags":["api","v2"]}' | jq .

# Small payload — jq . is fine
echo '{"status":"ok","version":"2.4.1"}' | jq .

# Large or nested response — jless is better
curl -s https://api.github.com/repos/jqlang/jq | jless
# → interactive tree, no output scrolled off screen

# Interactive exploration with jless
curl -s https://api.github.com/users/torvalds | jless

# Colorized pager fallback (no collapse, but still scrollable with color)
curl -s https://api.github.com/users/torvalds | jq -C . | less -R

# tmux side-by-side: split horizontally, then run jless in each pane
tmux split-window -h
# Left pane:  jless response-v1.json
# Right pane: jless response-v2.json

# Or use diff on jq-normalized output for a text diff
diff <(jq -S . response-v1.json) <(jq -S . response-v2.json)

İlgili Araçlar

JSON Güzelleştirici aracı, jless ile aynı daraltılabilir ve renkli görünümü doğrudan tarayıcıda sunar — kurulum gerekmez, terminal gerekmez.