curl untuk Pemula: Panduan Lengkap

Catatan singkat tentang siapa yang menulis artikel ini. Kami adalah Geonode dan kami menjual proxy, jadi curl adalah alat yang paling sering kami sarankan kepada orang-orang untuk digunakan saat mendiagnosis suatu masalah. Penjelasan jujur untuk pemula: curl bukanlah alat proxy dan Anda tidak memerlukan proxy untuk mempelajarinya. Semua yang dijelaskan di bawah ini dapat dijalankan terhadap titik akhir publik dari koneksi Anda sendiri, secara gratis. Proksi baru menjadi relevan jauh kemudian, ketika Anda membuat permintaan dalam jumlah yang cukup banyak sehingga target mulai membatasi laju permintaan Anda, atau ketika Anda perlu melihat tampilan suatu halaman dari negara lain. Kedua hal tersebut bukanlah masalah bagi pemula. Pelajari alat ini terlebih dahulu.

Apa Itu curl dan Untuk Apa Digunakan

curl adalah program baris perintah untuk mentransfer data menggunakan URL. Manual resminya menjelaskan bahwa program ini mendukung "DICT, FILE, FTP, FTPS, GOPHER, GOPHERS, HTTP, HTTPS, IMAP, IMAPS, LDAP, LDAPS, MQTT, MQTTS, POP3, POP3S, RTSP, SCP, SFTP, SMB, SMBS, SMTP, SMTPS, TELNET, TFTP, WS, dan WSS" — meskipun dalam praktiknya hampir semua orang menggunakannya untuk HTTP dan HTTPS.

Kegunaannya:

• Memanggil API dari terminal atau skrip
• Memeriksa apakah sebuah URL berfungsi, dan apa yang dikembalikannya
• Melihat dengan tepat apa yang dikirimkan kembali oleh server, termasuk semua header
• Mengunduh berkas
• Debugging: mereproduksi permintaan di luar aplikasi Anda untuk mengetahui apakah masalahnya ada pada kode Anda atau server

Apa yang bukan: sebuah browser. Alat ini tidak menjalankan JavaScript, tidak menampilkan apa pun, dan tidak mempertahankan sesi kecuali Anda memerintahkannya. Sebuah halaman yang terlihat lengkap di browser mungkin hanya mengembalikan kerangka yang hampir kosong ke curl, dan hal itu wajar terjadi, bukan berarti ada yang rusak.

Permintaan Pertama Anda

curl https://example.com

Perintah ini melakukan permintaan GET dan menampilkan isi respons di terminal Anda. Jika hasilnya berupa teks HTML yang panjang, berarti curl berfungsi dengan baik.

Empat variasi yang langsung berguna:

Lihat header serta isi respons dengan -i

, yang dijelaskan di -i, --show-headers

: "Tampilkan header respons dalam hasil keluaran."

curl -i https://example.com

Simpan ke berkas dengan -o

(nama yang Anda pilih) atau -O

(nama server jarak jauh):

curl -o page.html https://example.com
curl -O https://example.com/file.zip

Ikuti pengalihan dengan -L

: "Ikuti pengalihan HTTP dan ulangi permintaan dengan metode yang ditentukan semula." Tanpa opsi ini, curl akan berhenti pada pengalihan pertama dan menampilkan halaman pengalihan alih-alih halaman tujuan.

curl -L https://example.com

Tetap diam tetapi tetap laporkan kesalahan dengan -sS

. -s

menonaktifkan indikator kemajuan, sedangkan -S

mempertahankan pesan kesalahan. Kombinasi keduanya adalah yang Anda butuhkan dalam skrip apa pun.

curl -sS https://example.com

Jika Anda hanya mengingat satu baris dari artikel ini, jadikanlah baris ini:

curl -sSL https://example.com

Membaca Respons

Para pemula sering kali hanya fokus pada isi respons (body), padahal jawabannya sebenarnya ada di bagian header.

curl -i https://example.com

HTTP/2 200
content-type: text/html; charset=UTF-8
content-length: 1256

Baris pertama menunjukkan status. 200

berarti berhasil. 301

dan 302

adalah pengalihan (redirect) — tambahkan -L

. 401

dan 403

berarti Anda tidak diizinkan mengaksesnya. 404

berarti halaman tersebut tidak ada. 429

berarti kecepatan permintaan Anda terlalu tinggi. 500

dan angka di atasnya berarti server mengalami masalah.

content-type

memberitahu Anda apa yang sebenarnya Anda terima, dan hal ini menjawab banyak kebingungan. Jika Anda memanggil API dengan mengharapkan JSON dan melihat text/html

, Anda mendapatkan halaman kesalahan atau pengalihan login, dan kesalahan parsing yang akan Anda temui hanyalah gejala, bukan penyebabnya.

Untuk mendapatkan header tanpa isi:

curl -sS -o /dev/null -D - https://example.com

Perintah ini melakukan permintaan GET biasa, membuang isi, dan menampilkan header. Cara ini lebih andal daripada -I

, yang mengirimkan permintaan HEAD

dan dapat berperilaku berbeda — perbedaan ini dibahas dalam panduan kami tentang permintaan HEAD curl.

Untuk ringkasan alih-alih header mentah, -w

menampilkan nilai-nilai terpilih:

curl -sS -o /dev/null -w 'status=%{response_code} time=%{time_total}s\n' https://example.com

Informasi lebih lanjut tentang cara membaca header dengan benar terdapat di menampilkan header respons dengan curl.

Mengirim Data

Bagian lainnya dari tugas ini.

POST dengan data formulir:

curl -d "name=Ada&role=engineer" https://api.example.com/users

Menggunakan -d secara otomatis menggunakan metode POST dan menetapkan Content-Type: application/x-www-form-urlencoded.

POST dengan JSON — dan inilah kesalahan paling umum yang dilakukan pemula, karena -d saja tidak menetapkan tipe konten JSON:

curl -X POST https://api.example.com/users \
  -H "Content-Type: application/json" \
  -d '{"name":"Ada","role":"engineer"}'

Jika Anda mengabaikan header tersebut, banyak API akan mengembalikan kode status 415 Unsupported Media Type, yang merupakan kesalahan yang membingungkan sampai Anda tahu bahwa itu merujuk pada Content-Type Anda, bukan data Anda. Kami telah membahas kesalahan spesifik tersebut dalam artikel apa itu kode status 415.

Data dari berkas, menggunakan @ yang berarti "baca berkas ini":

curl -X POST https://api.example.com/users \
  -H "Content-Type: application/json" \
  -d @payload.json

Permintaan GET dengan parameter kueri yang dibangun dari pasangan kunci-nilai, menggunakan -G:

curl -G https://api.example.com/search -d "q=proxy" -d "limit=10"

Metode lain dengan -X. Gunakan hanya untuk metode yang tidak memiliki opsi khusus — PUT, DELETE, PATCH. Perhatikan peringatan dalam manual bahwa -X "hanya mengubah kata yang sebenarnya digunakan dalam permintaan HTTP, tidak mengubah cara kerja curl", itulah sebabnya -X HEAD tidak berfungsi dan -I ada.

Header, Otentikasi, dan Cookie

Header khusus dengan -H

, dapat diulang:

curl -H "Authorization: Bearer eyJhbG..." \
     -H "Accept: application/json" \
     https://api.example.com/me

Otentikasi dasar dengan -u

:

curl -u username:password https://api.example.com/private

Hilangkan kata sandi dan curl akan meminta kata sandi tersebut, sehingga kata sandi tidak tersimpan dalam riwayat shell Anda:

curl -u username https://api.example.com/private

User agent dengan -A

, karena curl secara default mengidentifikasi dirinya sebagai curl dan beberapa server merespons secara berbeda:

curl -A "Mozilla/5.0 (compatible; MyBot/1.0; +https://example.com/bot)" https://example.com

Jika Anda sedang menulis klien otomatis, user agent yang jujur dengan URL kontak merupakan etika yang baik sekaligus keuntungan praktis — otomatisasi anonim jauh lebih mudah diblokir daripada otomatisasi yang teridentifikasi.

Cookie. curl tidak menyimpannya antar pemanggilan kecuali Anda memintanya:

curl -c cookies.txt -d "user=ada&pass=secret" https://example.com/login
curl -b cookies.txt https://example.com/dashboard

-c

menulis cookie jar, -b

membacanya. Inilah cara Anda menangani apa pun yang memerlukan sesi.

Melihat Apa yang Sebenarnya Dikirim Melalui Jaringan

Kebiasaan yang membedakan orang yang bisa melakukan debugging dengan cepat dari orang yang hanya menebak-nebak.

curl -v https://example.com

Manual tersebut menjelaskan awalan-awalan berikut: ">

" (header yang dikirim oleh curl), "<

" (header yang diterima oleh curl), "}

" (data yang dikirim oleh curl), "{

" (data yang diterima oleh curl), "*

" (informasi tambahan yang disediakan oleh curl).

Untuk melihat hanya apa yang Anda kirim:

curl -v https://example.com 2>&1 | grep '^>'

Ini menghilangkan seluruh kategori kebingungan, karena header yang Anda tetapkan dalam kode tidak selalu sama dengan header yang dikirimkan. Perpustakaan menambahkan nilai default, mengganti nilai, dan mengubah urutan. Ketika server "mengabaikan" header Anda, periksa terlebih dahulu apakah Anda benar-benar mengirimkannya.

Output verbose dikirim ke stderr, itulah sebabnya 2>&1

diperlukan sebelum piping — hal ini disengaja, agar isi pesan tetap bersih di stdout.

Sebuah peringatan yang tercantum dalam manual dan layak untuk diulang: output verbose dan trace "mungkin berisi data sensitif, termasuk nama pengguna, kredensial, atau konten data rahasia". Sunting terlebih dahulu sebelum menempelkannya ke tiket.

Opsi yang Perlu Diingat

Semua yang disebutkan di atas dapat diringkas menjadi beberapa opsi saja.

Dua yang terakhir adalah yang sering dilewati oleh pemula dan kemudian mereka menyesalinya.

--fail penting karena curl secara default menganggap 404 sebagai transfer yang berhasil — curl mengunduh halaman kesalahan dan keluar dengan kode 0. Dalam skrip, itu berarti Anda menyimpan halaman kesalahan HTML dengan nama installer.dmg dan melanjutkan proses. --fail membuat kesalahan HTTP menghasilkan kode keluar non-nol dan tanpa output.

Timeout penting karena curl tidak memiliki batas waktu secara keseluruhan secara default. Permintaan yang macet akan membuat skrip Anda terhenti tanpa batas waktu. --connect-timeout 5 -m 30 membatasi hal tersebut. Ada penjelasan lebih lanjut mengenai hal ini di mengatur timeout dengan curl.

Baris yang sebaiknya dimasukkan ke dalam setiap skrip:

curl --fail --silent --show-error --location --connect-timeout 5 --max-time 30 "$URL"

Contoh Praktis dari Awal hingga Akhir

Menggabungkan berbagai elemen dalam tugas yang realistis: memanggil API publik, memeriksa apakah berhasil, dan menangani kasus kegagalan.

Langkah pertama — lihat apa yang dikembalikan oleh endpoint. Mulailah dengan header, bukan isi pesan:

curl -sS -o /dev/null -D - https://api.github.com/repos/curl/curl

Anda akan mendapatkan baris status dan header. Jika statusnya 200

dan content-type

menunjukkan JSON, berarti Anda terhubung ke tempat yang tepat.

Langkah kedua — periksa isi permintaan (body) yang sudah diformat. JSON mentah dalam satu baris sulit dibaca, jadi alirkan melalui jq

:

curl -sS https://api.github.com/repos/curl/curl | jq '{name, stargazers_count, language}'

Jika jq

belum terpasang, python3 -m json.tool

dapat melakukan pemformatan tanpa ketergantungan tambahan.

Langkah ketiga — periksa apa yang Anda kirim. Jika ada yang tidak berfungsi sebagaimana mestinya, periksa permintaan tersebut daripada menebak-nebak:

curl -v https://api.github.com/repos/curl/curl 2>&1 | grep '^>'

Langkah keempat — buat agar aman untuk skrip. Tambahkan penanganan kegagalan dan batas waktu, serta ambil status secara terpisah dari isi permintaan:

#!/usr/bin/env bash
set -euo pipefail

URL="https://api.github.com/repos/curl/curl"
BODY=$(mktemp)

STATUS=$(curl --silent --show-error --location \
              --connect-timeout 5 --max-time 30 \
              --write-out '%{response_code}' --output "$BODY" \
              "$URL")

case "$STATUS" in
  200) jq -r '.stargazers_count' < "$BODY" ;;
  404) echo "not found" >&2; exit 1 ;;
  429) echo "rate limited, retry after: $(date)" >&2; exit 1 ;;
  *)   echo "unexpected status $STATUS" >&2; head -c 200 "$BODY" >&2; exit 1 ;;
esac

rm -f "$BODY"

Tiga hal di atas layak diterapkan dalam setiap kode yang Anda tulis. --write-out '%{response_code}'

dengan --output

memisahkan status dari isi respons sehingga Anda dapat melakukan percabangan berdasarkan status tersebut. Menampilkan 200 karakter pertama dari isi respons saat status tidak terduga mengubah masalah yang membingungkan menjadi kesalahan yang mudah dipahami. Dan --connect-timeout

dengan --max-time

memastikan skrip tetap selesai meskipun koneksi jaringan terputus.

Langkah kelima — patuhi batas frekuensi. API publik mencantumkan batas-batasnya dalam header. Membacanya tidak memerlukan biaya apa pun dan mencegah cara paling umum yang menyebabkan pemblokiran:

curl -sS -o /dev/null -D - https://api.github.com/repos/curl/curl | grep -i ratelimit

Kesalahan Umum Pemula

Lupa menggunakan -L. Anda akan mendapatkan respons singkat yang berisi pemberitahuan pengalihan dan menyimpulkan bahwa URL tersebut rusak. Padahal tidak.

Lupa menggunakan --fail dalam skrip. 404 akan berubah menjadi halaman kesalahan yang tersimpan dan kode keluar nol. Tanpa peringatan, dan akan menimbulkan biaya besar di kemudian hari.

Menggunakan -d dengan JSON tanpa mengatur Content-Type. Menghasilkan 415 atau kesalahan parsing yang membingungkan di server.

Penggunaan tanda kutip dalam shell. Tanda kutip tunggal mempertahankan semuanya secara harfiah; tanda kutip ganda memungkinkan shell memperluas $ dan tanda backtick. Untuk isi JSON yang mengandung tanda kutip ganda, bungkuslah dengan tanda kutip tunggal. Jika data Anda juga mengandung tanda kutip tunggal, simpan dalam berkas dan gunakan -d @file.json.

Menganggap curl melihat apa yang dilihat browser. curl tidak menjalankan JavaScript. Respons yang hampir kosong dari halaman yang tampak penuh di browser berarti konten dirender di sisi klien, dan curl berperilaku dengan benar.

Mengabaikan kode status. Isi respons yang menunjukkan "error" dengan status 200 dan isi respons yang menunjukkan "error" dengan status 500 merupakan masalah yang berbeda. Bacalah keduanya.

Menyertakan kredensial di baris perintah. Kredensial tersebut akan tersimpan dalam riwayat shell dan terlihat dalam daftar proses oleh pengguna lain di mesin tersebut. Gunakan -u user dan biarkan curl meminta kredensial, atau baca dari variabel lingkungan.

Menonaktifkan verifikasi sertifikat agar sesuatu berfungsi. -k menonaktifkan peringatan yang sebenarnya memberi tahu Anda sesuatu. Cari tahu apa isinya terlebih dahulu.

Langkah Selanjutnya

Setelah menguasai dasar-dasarnya, langkah-langkah selanjutnya yang wajar adalah:

Pengunduhan yang tepat — melanjutkan transfer yang terputus, pengunduhan paralel, pembatasan kecepatan. Dibahas dalam mengunduh file dengan curl.

Timeout dan percobaan ulang, yang membuat skrip tidak lagi rentan. Lihat cara mengatur batas waktu dengan curl.

Membaca header sebagai data, dengan %{header_json} yang memberikan output JSON alih-alih teks yang perlu diparsing.

curl versus wget, karena keduanya memiliki fungsi yang tumpang tindih dan unggul dalam hal yang berbeda — curl vs wget membahas kapan sebaiknya menggunakan yang mana.

Proksi, saat Anda akhirnya membutuhkannya: -x http://host:port mengarahkan permintaan melalui proksi. Sangat berguna untuk pemeriksaan geografis dan mendistribusikan beban; benar-benar tidak diperlukan untuk belajar atau penggunaan yang sederhana.

Buku panduan. man curl cukup panjang dan merupakan sumber referensi yang otoritatif. Membaca entri untuk sebuah opsi yang sudah Anda gunakan adalah cara yang andal untuk menemukan opsi yang sebenarnya Anda inginkan.

Pertanyaan Terkait

Untuk apa curl digunakan?

Mentransfer data melalui URL dari baris perintah atau skrip — memanggil API, memeriksa respons yang dikembalikan server, mengunduh berkas, dan mereproduksi permintaan di luar aplikasi untuk mengisolasi masalah. Curl mendukung banyak protokol, tetapi sebagian besar digunakan untuk HTTP dan HTTPS.

Bagaimana cara membuat permintaan GET dengan curl?

curl https://example.com. GET adalah metode default, jadi tidak perlu menggunakan flag. Tambahkan -L untuk mengikuti pengalihan (redirect) dan -i untuk melihat header respons bersamaan dengan isi respons.

Bagaimana cara mengirim JSON dengan curl?

curl -X POST -H "Content-Type: application/json" -d '{"key":"value"}' URL. Header ini sangat penting — -d saja akan mengirimkan tipe konten form-encoded, dan API yang mengharapkan JSON biasanya akan menolaknya dengan kode status 415.

Mengapa curl tidak mengembalikan apa pun?

Ada beberapa kemungkinan: isi respons benar-benar kosong, Anda mengikuti pengalihan yang tidak Anda ikuti (tambahkan -L), konten dirender oleh JavaScript yang tidak dieksekusi oleh curl, atau permintaan gagal dan Anda tidak melihat kesalahannya karena menggunakan -s tanpa -S. Jalankan dengan -i untuk melihat kode status.

Apa perbedaan antara opsi -o dan -O di curl?

Opsi -o filename menyimpan ke nama yang Anda pilih. Opsi -O menyimpan dengan nama file dari URL, tanpa menyertakan jalur (path). Gunakan opsi -o jika URL tidak memiliki nama file yang berguna atau jika Anda memerlukan nama file tertentu.

Bagaimana cara melihat permintaan yang dikirim oleh curl?

curl -v URL dan cari baris yang dimulai dengan >. Output terperinci (verbose) dikirim ke stderr, jadi tambahkan 2>&1 sebelum melakukan piping. Ini adalah cara tercepat untuk memastikan bahwa header yang Anda konfigurasikan benar-benar terkirim melalui jaringan.

Apakah curl mengikuti pengalihan (redirect) secara default?

Tidak. Tambahkan -L. Ini adalah alasan paling umum mengapa perintah curl pemula mengembalikan respons singkat yang tidak terduga — Anda melihat halaman pengalihan, bukan halaman tujuan.

Apakah saya memerlukan proxy untuk menggunakan curl?

Tidak. curl berfungsi dengan baik saat mengakses titik akhir publik dari koneksi Anda sendiri. Proxy hanya relevan jika Anda melakukan permintaan dalam jumlah yang cukup banyak hingga terkena pembatasan laju, atau ketika Anda perlu melihat konten apa yang disajikan oleh suatu situs di negara lain. Keduanya bukanlah alasan untuk membeli apa pun saat sedang belajar.

Kesimpulan

curl memiliki sejumlah opsi yang bisa membuat orang gentar, namun inti fungsinya yang berguna sangatlah sedikit. Gunakan -i untuk melihat header, -L untuk mengikuti pengalihan, -o untuk menyimpan, -H untuk menambahkan header, -d untuk mengirim data, -u untuk otentikasi, -v untuk melihat apa yang terjadi, dan --fail ditambah pengaturan batas waktu (timeout) untuk proses yang berjalan tanpa pengawasan. Itulah seluruh fitur yang diperlukan bagi kebanyakan orang.

Dua kebiasaan yang lebih penting daripada bendera apa pun: baca kode status dan Content-Type sebelum membaca isi pesan, karena keduanya biasanya langsung menyebutkan masalahnya; dan gunakan -v untuk memeriksa apa yang sebenarnya Anda kirimkan, bukan apa yang Anda maksudkan untuk dikirimkan, karena perbedaan antara keduanya adalah tempat di mana sebagian besar bug tersembunyi.

Segala hal di luar itu tercantum dalam manual, yang panjang, otoritatif, dan layak untuk dibaca sekilas setiap kali Anda sedang menulis solusi sementara. Opsi yang Anda inginkan biasanya tersedia.