curl — HTTP Debug Aracı

00 curl neden vazgeçilmez

curl (Client URL) neredeyse her ağ protokolünü destekler, betiklere gömülür ve GUI gerektirmez.

Desteklenen protokoller: HTTP, HTTPS, FTP, SFTP, SCP, SMTP, IMAP, LDAP… Ama günlük kullanımda büyük çoğunlukla HTTP/HTTPS içindir.

  curl URL              → basit GET, stdout'a döker
  curl -v URL           → handshake dahil her şeyi göster
  curl -X POST -d body  → POST isteği
  curl -H 'header'      → özel header ekle
  curl | jq            → JSON yanıtı oku

wget vs curl

wget: dosya indirme odaklı, recursive site mirror yapabilir, çıktı varsayılan olarak dosyaya gider.
curl: REST API ve HTTP debug odaklı, her metodu destekler, çıktı varsayılan olarak stdout'a gider. Ağ programlamayı betiklemeye curl daha uygundur.

01 Temel GET — -o, -O, -L

İstek at, yanıtı kaydet, yönlendirme takip et.

bash●

# Temel GET — yanıt stdout'a gelir
curl https://api.example.com/users

# Yanıtı dosyaya kaydet
curl -o users.json https://api.example.com/users

# URL'deki dosya adıyla kaydet
curl -O https://example.com/releases/app-v1.2.tar.gz

# Yönlendirmeleri takip et (301, 302...)
curl -L https://git.io/kısaltılmış-url

# Hata durumunda sıfır dışı exit code (betik dostu)
curl -f https://api.example.com/health
# → HTTP 4xx/5xx durumunda exit code 22

# Sessiz mod (hata haricinde çıktı yok)
curl -s https://api.example.com/ping

# Sessiz ama stderr'e progress göster
curl -S -s -o out.json https://api.example.com/big

-o dosya

yanıtı belirtilen dosyaya yaz.

-O

URL'nin son bileşenini dosya adı olarak kullan.

-L

Location header'larını takip et (redirect'ler). Çoğu zaman gereklidir.

-f / --fail

HTTP hata kodlarında sıfır dışı exit code dön. Betiklerde curl -f URL || exit 1 kalıbı için şart.

-s / --silent

progress meter ve hata mesajlarını bastır.

-S / --show-error

-s ile birlikte: sessiz ama gerçek hata mesajlarını göster.

--max-time N

toplam istek için N saniye timeout.

--connect-timeout N

bağlantı kurma için N saniye timeout.

02 Header inceleme — -I, -v, -i

Sunucunun ne yanıt verdiğini, hangi header'ları döndüğünü ve TLS handshake'i görmek için.

bash●

# Sadece response header'ları (HEAD isteği)
curl -I https://example.com

# Örnek çıktı:
HTTP/2 200
content-type: application/json
cache-control: max-age=3600
x-request-id: abc123

# Header + body birlikte (stdout'a)
curl -i https://api.example.com/users

# Tam debug: TLS handshake + request + response dahil
curl -v https://api.example.com/users

# -v çıktısı çok fazlaysa sadece TLS bilgisi
curl -v --stderr - https://api.example.com 2>&1 | grep '^[<>*]'

-I / --head

HEAD isteği gönder — sadece header alır, body almaz. Büyük dosyanın varlığını ve metadata'sını kontrol etmek için.

-i / --include

response header'larını body öncesine ekle. Hem header hem body tek seferde stdout'a gelir.

-v / --verbose

istek ve yanıt header'ları (> giden, < gelen), TLS bilgisi. API hata ayıklamanın ilk durağı.

--trace-ascii -

ham byte düzeyinde izleme, stdout'a. En ayrıntılı mod.

-v çıktısını okumak

bash●

curl -v https://httpbin.org/get 2>&1

# * ile başlayan → curl açıklamaları (bağlantı, TLS)
* Connected to httpbin.org (34.227.213.82) port 443
* SSL connection using TLSv1.3 / TLS_AES_256_GCM_SHA384

# > ile başlayan → gönderilen istek header'ları
> GET /get HTTP/2
> Host: httpbin.org
> User-Agent: curl/8.4.0

# < ile başlayan → alınan yanıt header'ları
< HTTP/2 200
< content-type: application/json
< content-length: 298

03 HTTP metodu — -X

Varsayılan GET. Body gönderince POST olur. -X ile her metodu açıkça belirtebilirsin.

bash●

# GET (varsayılan)
curl https://api.example.com/users/42

# POST (-d eklenince otomatik POST, -X opsiyonel)
curl -X POST -d '{"name":"ali"}' https://api.example.com/users

# PUT
curl -X PUT -d '{"name":"ali","role":"admin"}' https://api.example.com/users/42

# PATCH
curl -X PATCH -d '{"role":"admin"}' https://api.example.com/users/42

# DELETE
curl -X DELETE https://api.example.com/users/42

# OPTIONS (CORS preflight kontrolü için)
curl -X OPTIONS -v https://api.example.com/users

NE OLUYOR

-d kullanınca curl otomatik olarak POST yöntemine geçer ve Content-Type: application/x-www-form-urlencoded header'ı ekler. JSON gönderiyorsan bunu -H 'Content-Type: application/json' ile geçersiz kılmalısın.

04 Body gönderme — -d, --data-binary, -F

Form verisi, JSON, ham ikili veri veya multipart — her format için doğru flag var.

bash●

# Form encoded (application/x-www-form-urlencoded)
curl -d 'username=ali&password=s3cr3t' https://api.example.com/login

# JSON body (Content-Type header'ı elle ekle)
curl -X POST \
  -H 'Content-Type: application/json' \
  -d '{"username":"ali","password":"s3cr3t"}' \
  https://api.example.com/login

# JSON dosyadan oku
curl -X POST \
  -H 'Content-Type: application/json' \
  -d @payload.json \
  https://api.example.com/users

# --data-binary: newline ve boşluk korur (dosya içeriği için)
curl -X POST --data-binary @rapor.xml \
  -H 'Content-Type: application/xml' \
  https://api.example.com/upload

# Multipart form — dosya yükleme
curl -F 'file=@photo.jpg' -F 'user=ali' https://api.example.com/upload

# MIME tipi belirterek multipart
curl -F 'file=@photo.jpg;type=image/jpeg' https://api.example.com/upload

-d 'veri'

form-encoded body. Birden fazla kullanılabilir: -d 'a=1' -d 'b=2' → a=1&b=2.

-d @dosya

dosyanın içeriğini body olarak gönder. @ ile dosya referansı.

--data-binary @dosya

-d gibi ama newline'ları strip etmez. XML, binary veya tam içerik gönderimi için.

--data-urlencode 'k=v'

otomatik URL encode et. Özel karakter içeren değerler için.

-F 'alan=değer'

multipart/form-data. Dosya yükleme için: -F 'file=@dosya.ext'.

JSON gönderirken -d vs --data-binary

-d newline'ları boşluğa çevirebilir. Çok satırlı JSON için --data-binary @dosya.json kullan veya jq -c . ile compact JSON üret: jq -c . payload.json | curl -X POST -H 'Content-Type: application/json' -d @- URL

05 Header ekleme — -H

Content-Type, Authorization, özel API header'ları — hepsi -H ile.

bash●

# Content-Type
curl -H 'Content-Type: application/json' -d '{}' URL

# Accept: yanıtta ne formatı istediğimizi söyle
curl -H 'Accept: application/json' URL

# Birden fazla header
curl \
  -H 'Content-Type: application/json' \
  -H 'Accept-Language: tr' \
  -H 'X-Request-ID: 12345' \
  URL

# Varsayılan User-Agent'ı değiştir
curl -H 'User-Agent: MyApp/1.0' URL

# Bir header'ı sil (boş string ile)
curl -H 'User-Agent:' URL   # User-Agent gönderme

# Referer header
curl -H 'Referer: https://orjin.example.com' URL

İPUCU — --header dosyadan

Çok sayıda header varsa bir dosyaya yaz ve --config dosya.txt ile yükle. Veya shell değişkeni kullan:
TOKEN="..." curl -H "Authorization: Bearer $TOKEN" URL

06 Kimlik doğrulama

Basic Auth, Bearer token, API key — üç farklı kalıp.

Basic Auth

bash●

# -u kullanıcı:parola (Base64 encode edilir, Authorization header)
curl -u ali:s3cr3t https://api.example.com/private

# Parolayı shell geçmişinde bırakmamak için (interaktif sorar)
curl -u ali https://api.example.com/private

# Digest auth
curl --digest -u ali:s3cr3t https://api.example.com/private

Basic Auth ≠ güvenli

Basic Auth sadece Base64 ile encode eder, şifrelemez. HTTPS olmadan kullanmak parolayı açık gönderir. Sadece HTTPS üzerinde kullan.

Bearer Token (JWT / OAuth2)

bash●

# Authorization: Bearer header
curl -H 'Authorization: Bearer eyJhbGciO...' URL

# Token değişkende
TOKEN=$(cat ~/.token)
curl -H "Authorization: Bearer $TOKEN" URL

# Token al, sonra kullan
TOKEN=$(curl -s -X POST -d '{"user":"ali","pass":"s3cr3t"}' \
  -H 'Content-Type: application/json' \
  https://api.example.com/auth/login | jq -r '.token')
curl -H "Authorization: Bearer $TOKEN" https://api.example.com/me

API Key

bash●

# Header olarak (en yaygın)
curl -H 'X-API-Key: sk_live_abc123xyz' URL

# Query string olarak (bazı servisler)
curl 'https://api.example.com/data?apikey=sk_live_abc123'

# .netrc dosyasından kimlik bilgisi oku (güvenli)
# ~/.netrc: machine api.example.com login apikey password sk_live_abc123
curl --netrc https://api.example.com/data

07 Cookie yönetimi — -b, -c

Session bazlı auth veya çerez gerektiren sayfalar için cookie jar kullan.

bash●

# Cookie gönder (elle)
curl -b 'session=abc123; theme=dark' URL

# Cookie jar dosyasından oku ve kaydet
curl -b cookies.txt -c cookies.txt URL

# Login → cookie al → korumalı sayfaya git
# 1. Login, cookie'yi kaydet
curl -s -X POST \
  -d 'username=ali&password=s3cr3t' \
  -c cookies.txt \
  -L \
  https://app.example.com/login

# 2. Cookie ile korumalı sayfaya eriş
curl -b cookies.txt https://app.example.com/dashboard

-b 'k=v'

Cookie header olarak gönder.

-b dosya

Netscape cookie jar formatındaki dosyadan cookie'leri oku.

-c dosya

Sunucudan gelen Set-Cookie header'larını bu dosyaya kaydet.

-j / --junk-session-cookies

Dosyadan okunurken session cookie'leri (expires=0) yoksay.

08 Dosya indirme — --limit-rate, -C

Büyük dosya indirirken bant genişliği kontrolü ve yarıda kesilen indirmeyi devam ettirme.

bash●

# İlerleme çubuğuyla indir
curl -L -o ubuntu.iso https://releases.ubuntu.com/22.04/ubuntu-22.04.iso

# Bant genişliği sınırla (200 KB/s)
curl --limit-rate 200k -o büyük-dosya.zip URL

# Kesilen indirmeyi devam ettir
curl -C - -o ubuntu.iso URL
# → -C - : otomatik offset tespiti

# Sadece belirli byte aralığını indir (Range request)
curl -r 0-1023 -o ilk1kb.bin URL    # ilk 1024 byte
curl -r 1024-2047 -o ikinci1kb.bin URL

# Paralel indirme (birden fazla curl)
curl -r 0-49999999 -o part1 URL &
curl -r 50000000-99999999 -o part2 URL &
wait
cat part1 part2 > büyük-dosya.bin

--limit-rate N

indirme/yükleme hız sınırı. 200k=200KB/s, 2M=2MB/s.

-C offset

belirtilen byte'tan devam et. -C - ile curl offset'i otomatik belirler (dosya boyutuna göre).

-r aralık

HTTP Range header ile byte aralığı iste. Sunucu destekliyorsa (206 Partial Content) çalışır.

--retry N

geçici hatalarda N kez dene.

--retry-delay N

denemeler arasında N saniye bekle.

09 JSON debug — jq ve -w ile timing

JSON yanıtı okumak için jq, performans ölçümü için -w.

jq ile JSON işleme

bash●

# Yanıtı formatla
curl -s URL | jq '.'

# Belirli alan
curl -s URL | jq '.name'
curl -s URL | jq '.users[0].email'

# Dizideki tüm id'ler
curl -s URL | jq '.[] | .id'

# Tırnaksız string çıktı (-r)
curl -s URL | jq -r '.token'

# Koşullu filtre
curl -s URL | jq '.users[] | select(.active == true) | .name'

# JSON oluştur
curl -s -X POST \
  -H 'Content-Type: application/json' \
  -d "$(jq -n --arg name "ali" --arg role "admin" '{name:$name, role:$role}')" \
  URL

-w ile timing ve metadata

bash●

# HTTP status kodu ve yanıt süresi
curl -s -o /dev/null -w "%{http_code} %{time_total}\n" URL

# Örnek çıktı:
200 0.342

# Detaylı timing (her fazın süresi)
curl -s -o /dev/null -w "
  DNS:        %{time_namelookup}s
  Connect:    %{time_connect}s
  TLS:        %{time_appconnect}s
  TTFB:       %{time_starttransfer}s
  Total:      %{time_total}s
  Bytes:      %{size_download}
  HTTP:       %{http_code}
" URL

%{http_code}

HTTP yanıt kodu (200, 404, 500…).

%{time_total}

toplam süre saniye cinsinden.

%{time_namelookup}

DNS çözümleme süresi.

%{time_connect}

TCP bağlantı süresi.

%{time_appconnect}

TLS handshake süresi (HTTPS için).

%{time_starttransfer}

ilk byte'ı alma süresi (TTFB).

%{size_download}

indirilen byte sayısı.

%{url_effective}

redirect sonrası gerçek URL.

Birleşik örnek: API sağlık kontrolü

bash●

#!/bin/bash
# API sağlık kontrolü — uyarı verir
STATUS=$(curl -s -o /dev/null -w "%{http_code}" --max-time 5 https://api.example.com/health)

if [ "$STATUS" != "200" ]; then
  echo "UYARI: API sağlık kontrolü başarısız — HTTP $STATUS"
  exit 1
fi
echo "API sağlıklı (HTTP $STATUS)"

Hatırlanacaklar

curl -v URL → bağlantı, TLS, request, response header'larını göster
curl -I URL → HEAD isteği, sadece header
-X POST -H 'Content-Type: application/json' -d @file.json → JSON POST
-u user:pass → Basic Auth, -H 'Authorization: Bearer TOKEN' → Bearer
-b cookies.txt -c cookies.txt → cookie jar oku+yaz
-s -o /dev/null -w "%{http_code}" → sadece status kodu
-f → 4xx/5xx'te sıfır dışı exit, betiklerde kullan
curl -s URL | jq '.alan' → JSON ayrıştır
-C - -o dosya URL → kesilen indirmeyi devam ettir