Spędziłem absurdalnie dużo późnych nocy na debugowaniu skryptów, które miały po prostu „pobrać plik i iść dalej”. W dziewięciu przypadkach na dziesięć winny był cURL — robił dokładnie to, co mu kazałem, a nie to, czego naprawdę chciałem. Okazuje się, że między „curl -O działa” a „curl -O działa niezawodnie w produkcji” jest spora przepaść.
Właśnie tę lukę ma wypełnić ten poradnik. cURL jest domyślnie zainstalowany na macOS, większości dystrybucji Linuxa oraz w Windows 10 i nowszych, więc najpewniej już masz go na swoim komputerze. Ale między cichymi błędami przekierowań, tajemniczymi 403 i przejściem od „pobierz jeden plik” do „pobierz 500 plików bez zapychania terminala” łatwo utknąć. Pokażę Ci flagi, które naprawdę mają znaczenie, kroki i komendy, których sam używam, najczęstsze błędy oraz moment, w którym cURL rzeczywiście przestaje wystarczać — i po co sięgnąć wtedy zamiast niego.
Czym jest cURL i dlaczego warto się nim zainteresować?
cURL to darmowe, otwartoźródłowe narzędzie wiersza poleceń do przesyłania danych do lub z serwera za pomocą URL. Obsługuje HTTP, HTTPS, FTP, SFTP i mnóstwo innych protokołów, dlatego pojawia się wszędzie — od skryptów bash, przez Dockerfile, po pipeline’y CI. Pod maską polecenie curl, które wpisujesz w terminalu, korzysta z libcurl, czyli biblioteki transferowej w C, osadzanej w wielu aplikacjach i bindingach językowych. Przykładem jest rozszerzenie cURL w PHP; popularna biblioteka Requests w Pythonie to osobny klient HTTP zbudowany na urllib3, a nie na libcurl.
Aktualna stabilna wersja w chwili pisania tego tekstu to curl 8.21.0, wydana w czerwcu 2026 — ale nie zakładaj, że system operacyjny dostarcza dokładnie ten build. Wersje pakietowe cURL w dystrybucjach często pozostają w tyle za głównym projektem o miesiące, czasem dłużej, więc warto uruchomić curl --version, zanim założysz, że masz dostęp do flagi takiej jak --parallel.
Po co pobierać pliki przez cURL? Najczęstsze zastosowania
Często słyszę pytanie, po co w ogóle używać narzędzia z linii komend, skoro przeglądarki radzą sobie z pobieraniem plików całkiem dobrze. Odpowiedź jest prosta: przeglądarka jest świetna, dopóki nie trzeba niczego automatyzować.
| Zastosowanie | Dlaczego cURL sprawdza się świetnie |
|---|---|
| Pobieranie binariów w pipeline’ach CI/CD | Można to skryptować, bez interfejsu graficznego |
| Pobieranie odpowiedzi API lub eksportów danych | Obsługuje własne nagłówki, autoryzację i przekierowanie wyjścia |
| Wznawianie dużych pobrań przez SSH | Wbudowana obsługa wznawiania (-C -) |
| Automatyzacja cyklicznych pobrań (cron) | Lekki, dobrze współpracuje ze skryptami shellowymi |
| Pobieranie plików chronionych logowaniem | Elastyczne flagi uwierzytelniania (basic, token, cookies, .netrc) |
Pobranie w przeglądarce to jednorazowe kliknięcie. cURL zamienia tę samą czynność w coś, co można zaplanować, wpiąć w pipeline, ponowić po błędzie i uruchomić identycznie na stu serwerach naraz. I właśnie w tym tkwi jego siła — nie jest „efektowny”, tylko powtarzalny.
Najważniejsze flagi cURL do pobierania plików
Wracam ciągle do tych samych kilkunastu flag, które załatwiają 90% mojej pracy. Oto skrócona ściąga, którą chciałbym dostać lata temu — uporządkowana według tego, co faktycznie robią.
Flagi do wyjścia i zapisywania plików
-O(--remote-name) zapisuje plik z ostatniego fragmentu URL jako nazwę pliku. Wygodne, ale może bez ostrzeżenia nadpisać istniejący plik o tej samej nazwie.-o <nazwa_pliku>(--output) pozwala samodzielnie wskazać dokładną nazwę pliku:curl -o raport.pdf https://example.com/downloads/file.pdf.-J(--remote-header-name) używa nazwy pliku z nagłówkaContent-Dispositionserwera zamiast tej z URL. To bywa wygodne przy pobieraniu z API, ale traktuj nazwy plików podane przez serwer jako niezaufane dane — zapisuj je do osobnego folderu, a nie do katalogu domowego, zgodnie z zaleceniami bezpieczeństwa cURL.
Flagi zachowania, których potrzebuje każde pobieranie
-L(--location) każe curl podążać za przekierowaniami HTTP. Bez tego odpowiedź 3xx zostanie zapisana jako mała strona HTML z przekierowaniem zamiast właściwego pliku — to zdecydowanie najczęstszy błąd typu „czemu moje pobieranie nie działa?”.-C -(--continue-at -) wznawia przerwane pobieranie od miejsca, w którym się zatrzymało.-s/-Sdziałają cicho, ale nadal pokazują błędy — przydatne w skryptach, kiedy nie chcesz zaśmiecać logów paskiem postępu.--limit-rate 1Mogranicza przepustowość (przydatne na współdzielonym łączu albo gdy nie chcesz zapchać sieci pomiarowej).--connect-timeout 10i--max-time 300sprawiają, że zawieszone połączenie nie zamrozi skryptu na zawsze.--retry 3i--retry-delay 5automatycznie ponawiają próbę przy przejściowych błędach — zgodnie z stroną podręcznika cURL, warto łączyć to z--retry-all-errorstylko wtedy, gdy dokładnie to samo żądanie naprawdę można bezpiecznie powtórzyć.
Flagi do postępu i debugowania
-#pokazuje prosty pasek postępu zamiast domyślnej tabeli statystyk.-vwypisuje szczegółowe informacje, w tym pełne nagłówki żądania i odpowiedzi — mój pierwszy wybór, gdy coś zachowuje się dziwnie.-I(--head) pobiera tylko nagłówki odpowiedzi, co świetnie sprawdza się jako szybki test przed dużym pobraniem.-wpozwala wypisać własny wynik po transferze, np.curl -o /dev/null -s -w "%{http_code}\n" <url>, żeby sprawdzić sam kod statusu.
Zanim zaczniesz
- Poziom trudności: początkujący do średnio zaawansowanego (sekcje o pobieraniu zbiorczym i uwierzytelnianiu są trochę bardziej zaawansowane)
- Szacowany czas: około 15–20 minut na przejście przez podstawowe komendy
- Czego potrzebujesz: terminala (Terminal na macOS, shell Linuxa lub PowerShell/WSL w Windows), zainstalowanego curl (sprawdź poleceniem
curl --version) oraz testowego URL — jako przykład użyję publicznego assetu z GitHub Releases, bo jest stabilny i ogólnodostępny
Jak pobierać pliki za pomocą cURL: krok po kroku
Krok 1: Pobierz jeden plik
Najprościej: curl -O <url> zapisuje plik pod oryginalną nazwą, a curl -o myfile.zip <url> pozwala od razu go zmienić.
curl -LO https://github.com/curl/curl/releases/download/curl-8_21_0/curl-8.21.0.tar.gz
Od teraz -L dodaję zawsze, bez wyjątków — zbyt wiele razy przekierowanie zamieniało mój „download” w 400-bajtowy plik HTML. Powinieneś zobaczyć w terminalu wskaźnik postępu, który dojdzie do końca, a potem plik pojawi się w bieżącym katalogu.
Gdy komenda się powiedzie, pasek postępu osiąga 100%, a curl-8.21.0.tar.gz pojawia się w bieżącym katalogu. Zanim go użyjesz, sprawdź plik:
ls -lh curl-8.21.0.tar.gz
Krok 2: Pobierz i zmień nazwę pliku
Użyj -o, gdy chcesz własną lokalną nazwę pliku, niezależnie od tego, jak kończy się URL:
curl -L -o curl-latest.tar.gz -S https://github.com/curl/curl/releases/download/curl-8_21_0/curl-8.21.0.tar.gz
-S ponownie włącza pokazywanie błędów, jeśli gdzieś indziej w skrypcie użyłeś też -s. Taki zestaw — -L -o <nazwa> -S — to praktycznie moja domyślna komenda do pobrania pojedynczego pliku.
Krok 3: Wznów przerwane pobieranie
Jeśli duży plik rozłączy się w połowie (słabe Wi‑Fi, skok VPN, cokolwiek), nie zaczynaj od zera. Uruchom:
curl -C - -LO https://example.com/large-file.iso
Jest jednak haczyk: działa to tylko wtedy, gdy serwer obsługuje zapytania zakresowe bajtów. Accept-Ranges: bytes jest przydatną pozytywną wskazówką, ale jego brak nie dowodzi, że zakresy są niewspierane. Pewny test to odpowiedź serwera na rzeczywiste żądanie zakresowe: wznowione pobieranie zwykle zwraca 206 Partial Content z poprawnym Content-Range. Uruchom komendę wznowienia i sprawdź status przez -v albo -D -; jeśli serwer ignoruje zakres albo odrzuca przesunięcie, zacznij pobieranie świadomie od nowa, zamiast zakładać, że częściowy plik nadaje się do użycia.
Krok 4: Pobierz z paskiem postępu albo po cichu
Jeśli chcesz czystszy widok w interaktywnym terminalu: curl -# -LO <url>. Jeśli piszesz skrypty lub zadania cron i zależy Ci tylko na błędach, bez hałasu: curl -sS -LO <url>. Wersji cichej używam niemal wszędzie, poza ręcznym debugowaniem.
Krok 5: Ogranicz prędkość pobierania
Na współdzielonym łączu biurowym (albo gdy nie chcę być tą osobą, która zjada całe pasmo podczas wideorozmowy) ograniczam transfer tak:
curl --limit-rate 1M -LO https://example.com/big-dataset.zip
Jednostki K, M i G oznaczają odpowiednio kilobajty, megabajty i gigabajty na sekundę.
Krok 6: Zapisz nagłówki odpowiedzi obok pliku
Czasem muszę wiedzieć dokładnie, co serwer zwrócił — typ zawartości, nagłówki cache i tym podobne — bez zaśmiecania terminala:
curl -L -D headers.txt -o file.zip https://example.com/file.zip
Ta komenda zapisuje nagłówki odpowiedzi do headers.txt, a właściwy plik trafia do file.zip. Świetne przy diagnozowaniu niezgodności content-type albo sprawdzaniu, czy CDN rzeczywiście cache’uje to, co myślisz, że cache’uje.
Wskazówki i typowe pułapki
- Wskazówka: Zawsze domyślnie używaj
-L. Naprawdę nie widzę żadnej wady w dodaniu tej flagi, a zapomnienie o niej kosztowało mnie godziny. - Wskazówka: W skryptach łącz
--failz komendą pobierania, żeby odpowiedź spoza zakresu 2xx faktycznie powodowała błąd i zakończenie skryptu, zamiast po cichu zapisać stronę błędu jako plik. - Pułapka: Nie łącz
-C -z--remove-on-error— cURL podaje, że te opcje są niezgodne, ponieważ wznawianie wymaga, by częściowy plik nadal istniał. - Pułapka:
-Omoże nadpisać pliki bez ostrzeżenia. Jeśli pobierasz wsadowo do współdzielonego katalogu, użyj--output-dir, żeby trzymać wszystko w jednym miejscu.
Jak pobierać wiele plików i robić pobieranie wsadowe za pomocą cURL
Przykłady z jednym plikiem są najłatwiejsze. Prawdziwe workflow, które budowałem — pobieranie nocnych eksportów danych, synchronizacja binariów między serwerami buildowymi — wymagały współbieżności, a tu większość poradników po prostu się urywa. Warto znać trzy podejścia, z których każde jest trochę bardziej zaawansowane od poprzedniego.
Podejście 1: Wiele URL-i w jednej komendzie cURL
Najprościej po prostu wypisać adresy:
curl -LO https://example.com/a.zip -LO https://example.com/b.zip -LO https://example.com/c.zip
To działa, ale jest sekwencyjne — curl kończy jeden plik, zanim zacznie następny. Dobre dla trzech plików, bolesne dla trzystu.
Podejście 2: Równoległe pobieranie z --parallel (curl 7.66+)
Od curl 7.66 możesz dodać --parallel (albo -Z), aby pobierać wiele URL-i równocześnie:
curl --parallel --parallel-max 5 --remote-name-all \
https://example.com/a.zip https://example.com/b.zip https://example.com/c.zip
Warto wiedzieć, że domyślny limit równoległości to aż 50, czyli znacznie więcej jednoczesnych połączeń, niż większość serwerów (albo Twoja sieć) będzie wdzięczna. Ja ustawiam --parallel-max jawnie i zachowawczo — zwykle 4 do 8 — zamiast ufać domyślnej wartości.
Podejście 3: xargs i pętle Bash dla współbieżności z listy URL-i
Przy dużej liście adresów w pliku tekstowym zwykle sięgam po xargs:
cat urls.txt | xargs -n1 -P 8 curl -O -L
Albo, jeśli chcę mieć większą kontrolę nad tym, co dzieje się z każdym zadaniem, używam pętli bash z procesami w tle:
while read -r url; do
curl -O -L "$url" &
done < urls.txt
wait
wait na końcu ma znaczenie — bez niego skrypt zakończy się, zanim pobieranie w tle dobiegnie końca.
Kiedy zamiast tego użyć wget albo aria2
Powiem wprost: cURL nie zawsze jest właściwym narzędziem. Jeśli chcesz skopiować całe drzewo katalogów strony, wget -r robi rekurencyjne crawlowanie „z pudełka” w sposób, do którego cURL po prostu nie został zaprojektowany. Jeśli potrzebujesz pobierania wieloźródłowego, dzielonego na segmenty, żeby wycisnąć maksimum z jednego ogromnego pliku, aria2c bywa naprawdę szybsze.
| Narzędzie | Najlepsze zastosowanie |
|---|---|
| cURL | Precyzja, skryptowanie, pobieranie pojedynczych plików lub małych paczek, praca z API |
| wget | Rekurencyjne pobieranie i mirroring stron, prostsze zbiorcze pobieranie plików statycznych |
| aria2 | Pobieranie wieloźródłowe i segmentowe, maksymalizacja przepustowości przy dużych plikach |
Moc cURL zawsze leżała w precyzji i łączeniu elementów — potoki, skrypty, elastyczność protokołów — a nie w brutalnym crawlowaniu.
Jak pobierać chronione pliki za pomocą cURL: wzorce uwierzytelniania
Większość poradników o cURL kończy na -u user:pass i tyle. To relikt wcześniejszego internetu. W 2026 pliki, które faktycznie pobieram, pochodzą z REST API, paneli opartych na sesjach i systemów CI — a każdy z nich wymaga innego rodzaju danych uwierzytelniających.
Basic Auth
curl -u username:password -O https://legacy-server.example.com/file.zip
Działa w przypadku starszych serwerów FTP albo prostych endpointów HTTP. Pamiętaj tylko, że hasło trafia do historii powłoki i listy procesów, jeśli nie zachowasz ostrożności — nie używałbym tego do niczego wrażliwego.
Uwierzytelnianie Bearer / OAuth Token
To jest opcja, o której w wielu poradnikach mówi się za mało, a ja korzystam z niej najczęściej:
curl -H "Authorization: Bearer $GITHUB_TOKEN" \
-LO https://api.github.com/repos/curl/curl/releases/assets/12345
To prawdziwy wzorzec pobierania prywatnego assetu z GitHub Releases — podmień token i identyfikator assetu. REST API i zasoby chronione OAuth2 mówią dziś właśnie tym językiem.
Uwierzytelnianie oparte na cookies
W aplikacjach webowych, gdzie logowanie tworzy sesję, zapisz plik cookies podczas logowania i użyj go ponownie przy pobieraniu:
curl -c cookies.txt -d "user=me&pass=secret" https://example.com/login
curl -b cookies.txt -O https://example.com/protected/file.zip
Plik .netrc w środowiskach skryptowych i CI
To mój ulubiony sposób dla wszystkiego, co ma działać bez nadzoru. Utwórz plik ~/.netrc (albo _netrc w Windows):
machine example.com
login myusername
password mypassword
Zabezpiecz go poleceniem chmod 600 ~/.netrc, a potem odwołuj się do niego tak:
curl --netrc -LO https://example.com/protected-file.zip
Zaletą jest to, że dane logowania nigdy nie trafiają do historii terminala ani do źródeł skryptu — naprawdę ważne w CI/CD, gdzie logi często zapisują cały skrypt w całości.
| Metoda uwierzytelniania | Flaga/opcja | Najlepsze zastosowanie |
|---|---|---|
| Basic auth | -u user:pass | Starsze FTP, prosty HTTP |
| Bearer token | -H "Authorization: Bearer <token>" | REST API, OAuth2 |
| Cookie auth | -b cookies.txt (+ -c do zapisu) | Aplikacje webowe oparte na sesji |
Plik .netrc | --netrc lub --netrc-file | CI/CD, środowiska skryptowe |
Rozwiązywanie najczęstszych błędów pobierania cURL
To jest sekcja, której naprawdę brakowało mi na początku, bo prawie nikt jej nie opisuje. „Dlaczego moje pobieranie curl nie działa” to prawdziwe, częste i frustrujące zapytanie — a poprawki zwykle sprowadzają się do jednej linii, gdy już znasz przyczynę.
| Objaw | Prawdopodobna przyczyna | Naprawa |
|---|---|---|
curl: (60) SSL certificate problem | Samopodpisany lub wygasły certyfikat | --cacert <file> albo -k (tylko dev) |
403 Forbidden / pusty plik | Serwer blokuje domyślny User-Agent curl | -A "Mozilla/5.0..." albo -H "User-Agent: ..." |
Pobieranie zaczyna się od 0 przy -C - | Serwer nie obsługuje Range | Sprawdź curl -I <url> i szukaj Accept-Ranges: bytes |
| Zapisano plik o rozmiarze 0 B | Nie podążono za przekierowaniem | Dodaj flagę -L |
curl: (28) Operation timed out | Wolny serwer lub problemy z siecią | --connect-timeout 10 --max-time 300 + --retry 3 |
| Zapisano stronę HTML zamiast pliku | Strona wymaga renderowania JavaScript | curl nie wykonuje JS — zobacz sekcję poniżej |
Błędy certyfikatu SSL: co znaczą i jak je naprawić
Błąd 60 oznacza, że curl nie mógł zweryfikować certyfikatu SSL serwera — zwykle dlatego, że jest samopodpisany, wygasły albo wystawiony przez urząd certyfikacji, któremu curl nie ufa. Jeśli kontrolujesz serwer, wskaż curlowi właściwy pakiet CA przez --cacert /path/to/ca.pem. Flaga -k (--insecure) całkowicie pomija weryfikację, co jest w porządku w lokalnym środowisku deweloperskim, ale bardzo złym pomysłem w czymkolwiek związanym z produkcją albo danymi realnych użytkowników.
403 Forbidden i puste pobrania
Zaskakująco wiele serwerów blokuje żądania, które identyfikują się jako curl/8.21.0 (domyślny User-Agent cURL), uznając je za boty albo scrapery. Zwykle wystarczy udawać przeglądarkę:
curl -A "Mozilla/5.0 (Windows NT 10.0; Win64; x64)" -LO https://example.com/file.zip
Żeby sprawdzić, co naprawdę wraca, zanim pobierzesz cały plik, używam: curl -o /dev/null -s -w "%{http_code}\n" <url>.
Timeouty, ponawianie prób i niestabilne połączenia
To jest komenda, którą wytatuowałbym sobie na ramieniu, gdybym był odważniejszy w kwestii tatuaży.
Mój sprawdzony zestaw do pobierania, którego naprawdę używam w skryptach produkcyjnych, łączy wszystkie flagi niezawodności:
curl -L -C - --retry 5 --retry-delay 3 --connect-timeout 10 --max-time 600 --fail -O <url>
Czyli: podążanie za przekierowaniami, wznowienie, pięć ponowień z 3-sekundowym opóźnieniem, 10-sekundowy timeout połączenia, 10-minutowy limit całkowity i twardy fail przy złym statusie HTTP — praktycznie wszystko, czego nauczyłem się dodawać przez bolesne doświadczenie.
cURL w prawdziwej automatyzacji: pipeline’y CI/CD, potoki i bezpieczeństwo skryptów
Przekazywanie wyjścia cURL do innych narzędzi
curl wcale nie musi niczego zapisywać na dysk — bezpośrednie przekazanie wyjścia do innej komendy to jedna z jego najbardziej niedocenianych cech:
curl -sL https://example.com/archive.tar.gz | tar xz
curl -s https://api.example.com/data | jq '.results'
Pobieranie i rozpakowywanie albo pobieranie i parsowanie w jednej linii. To wzorzec, którego używam ciągle przy jednorazowych pobraniach danych.
Używanie cURL w GitHub Actions i CI/CD
Minimalny krok w GitHub Actions, który pobiera binarkę z logiką ponawiania i wyraźnie kończy się błędem, jeśli coś pójdzie nie tak:
- name: Download binary
run: |
curl -L --fail --retry 3 --retry-delay 5 \
-o app-binary "https://example.com/releases/app-binary"
Wszelkie tokeny przechowuj jako sekrety CI i odwołuj się do nich przez zmienne środowiskowe — nigdy nie wpisuj ich na sztywno do samego skryptu. I używaj --fail (albo --fail-with-body, jeśli do debugowania potrzebujesz treści błędu), żeby uszkodzone pobranie rzeczywiście psuło build, zamiast cicho przechodzić z bezwartościowymi danymi.
Bezpieczeństwo komendy curl | sh
To pytanie pojawia się niemal na każdym forum dla developerów, i słusznie: podanie curl bezpośrednio do sh oznacza wykonywanie zdalnego kodu, którego nie sprawdziłeś, opierając się wyłącznie na zaufaniu, że serwer nie został przejęty i połączenie nie zostało podsłuchane. To jest realne ryzyko — nie paranoja, tylko zwykła obawa o łańcuch dostaw.
Bezpieczniejszy wzorzec polega na tym, żeby najpierw pobrać plik, przejrzeć skrypt, sprawdzić sumę kontrolną albo podpis GPG, jeśli są dostępne, a dopiero potem go uruchomić:
curl -sL https://example.com/install.sh -o install.sh
cat install.sh # naprawdę to przeczytaj
sha256sum install.sh # porównaj z opublikowaną sumą kontrolną, jeśli jest dostępna
bash install.sh
Znane instalatory, takie jak rustup i Homebrew, nadal używają wzorca curl | sh, i w ich konkretnych przypadkach jest on zwykle akceptowany, bo maintainerzy i kanał dystrybucji są dobrze ugruntowani. Ja i tak wolę poświęcić dodatkowe dziesięć sekund na sprawdzenie skryptu, niż przekonać się boleśnie, że nie powinienem był ufać mu w ciemno.
Kiedy cURL nie wystarcza: strony renderowane przez JS, antyboty i dane strukturalne
Jest taki scenariusz, który często wywraca ludzi do góry nogami, choć zwykle nie jest to ich wina: uruchamiasz curl -O na czymś, co wygląda jak zwykła strona, a zamiast treści dostajesz pustą powłokę HTML, stronę wyzwania Cloudflare albo coś przypominającego śmieci. curl zrobił dokładnie to, do czego został stworzony — pobrał surową odpowiedź HTTP — ale nie umie wykonywać JavaScriptu, rozwiązywać CAPTCHA ani przechodzić przez systemy odcisku palca antybotów. To nie są błędy cURL; to po prostu nie należy do jego zakresu działania.
Dlaczego cURL zawodzi na nowoczesnych stronach
Nowoczesne aplikacje SPA często zwracają niemal pusty szkielet HTML, a właściwa treść jest renderowana po stronie klienta przez JavaScript po załadowaniu strony — czego curl nigdy nie uruchomi. Do tego systemy takie jak Cloudflare i Akamai aktywnie serwują strony wyzwania każdemu, kto nie wygląda jak prawdziwa przeglądarka, a powtarzające się żądania curl z tego samego IP bardzo szybko mogą zostać ograniczone albo oznaczone jako ruch botów.
Następny krok: API do scrapowania AI dla developerów
Powiedziałbym, że curl jest właściwym narzędziem dla około 80% pobrań plików i danych — zasobów statycznych, odpowiedzi API, wszystkiego, co jest zwykłym zasobem HTTP. To te pozostałe 20%, czyli strony mocno oparte na JavaScript albo chronione przed botami, sprawiają, że widziałem developerów walczących godzinami z nagłówkami i User-Agentami, zanim w końcu odpuszczali i sięgali po inną warstwę.
Właśnie tę lukę mój zespół chciał domknąć tworząc Thunderbit, obok rozszerzenia Chrome, z którego większość osób nas kojarzy. Po stronie developerów otwarte API Thunderbit daje POST /distill, które zwraca czysty Markdown gotowy dla LLM z podanego URL — z renderowaniem strony obsługiwanym przez usługę — oraz POST /extract, które zwraca ustrukturyzowany JSON zgodny ze schematem, gdy potrzebujesz prawdziwych danych polowych zamiast tekstu do czytania. Jest też serwer MCP, dzięki któremu agenci w Claude lub Cursor mogą wywoływać thunderbit_distill i thunderbit_extract w trakcie zadania, oraz CLI (npx @thunderbit/thunderbit-cli distill <url>), które bardzo przypomina cURL w terminalu. Wyjście JSON możesz przekazać do jq, np. thunderbit distill <url> --format json | jq -r '.data.markdown'; wyjście --format markdown możesz z kolei skierować do narzędzia tekstowego albo do pliku.
Porównanie obok siebie jest bardzo wyraźne. Zapytanie curl do strony renderowanej przez JS może zwrócić głównie pusty <div id="root"></div>. Odpowiednik thunderbit distill zwraca renderowaną treść strony w czystym Markdown. Distill kosztuje 1 kredyt za URL, a Extract 20 kredytów za URL. Obecne limity zależne od endpointu są różne: Batch Distill obsługuje do 100 URL-i na jedno zadanie, a Batch Extract przyjmuje do 50 URL-i ze wspólnym schematem. Sprawdź aktualną dokumentację API, zanim zaplanujesz obciążenie produkcyjne.
Jeśli dopiero zaczynasz z tym tematem, nasze własne wyjaśnienie czym właściwie jest web scraping będzie dobrym punktem startowym, a przewodnik po scrapowaniu bez kodowania opisuje tę samą sprawę z perspektywy osób nietechnicznych w Twoim zespole. Dla szerszego porównania narzędzi z tej kategorii przygotowaliśmy też zestawienie najlepszych AI web scraperów, które warto znać.
Krótka ściąga: cURL do pobierania plików
| Zadanie | Komenda |
|---|---|
| Podstawowe pobranie | curl -LO <url> |
| Własna nazwa pliku | curl -L -o myfile.zip <url> |
| Wznawianie pobierania | curl -C - -LO <url> |
| Cicho, ale z pokazaniem błędów | curl -sSL -O <url> |
| Pobieranie równoległe | curl --parallel --parallel-max 5 -O <url1> -O <url2> |
| Uwierzytelnianie tokenem Bearer | curl -H "Authorization: Bearer <token>" -LO <url> |
| Sprawdzona komenda do skryptów | curl -LO --retry 5 --retry-delay 3 --max-time 600 --fail <url> |
| Przekazanie do narzędzia do rozpakowania | curl -sL <url> | tar xz |
Podsumowanie i najważniejsze wnioski
Pobieranie pliku przez curl zaczyna się banalnie — curl -O i właściwie gotowe — ale prawdziwa umiejętność leży w warstwach pod spodem: wiedzieć, kiedy dodać -L, kiedy wznowić zamiast zaczynać od nowa, jaki wzorzec uwierzytelniania naprawdę pasuje do Twojego workflow i co zrobić, gdy zamiast oczekiwanego pliku pojawi się 403 albo pusta powłoka HTML. Każde z tych podejść kiedyś mnie uratowało, zwykle tuż po tym, jak boleśnie przekonałem się, dlaczego było ważne.
curl nadal pozostaje moim domyślnym narzędziem do prostego pobierania plików i skryptowalnej pracy HTTP — jest szybki, dostępny praktycznie wszędzie i świetnie komponuje się z resztą potoku shellowego. Ale gdy trafiasz na stronę renderowaną przez JavaScript albo ścianę antybotów, to nie jest problem, który rozwiążesz kolejną flagą cURL; to znak, że potrzebujesz innej warstwy, i właśnie wtedy API takie jak Thunderbit przejmuje zadanie bez wyciągania Cię z terminala.
Dodaj tę ściągę do zakładek, przetestuj komendę z ponawianiem i wznawianiem przy następnym niestabilnym pobieraniu, a jeśli trafisz na mur, po którym curl zwraca już tylko śmieci, będziesz wiedzieć, jak wygląda następny krok — na stronie z cennikiem Thunderbit znajdziesz aktualny podział kredytów, jeśli chcesz sprawdzić, ile kosztuje taki przeskok, a nasz kanał YouTube zawiera walkthrough, jeśli wolisz oglądać niż czytać.
FAQ o pobieraniu plików za pomocą cURL
Jak pobrać plik przez cURL i zapisać go pod konkretną nazwą?
Użyj -o i podaj wybraną nazwę pliku: curl -L -o twojanazwa.ext <url>. Dodaj -L, żeby przekierowania nie zepsuły pobierania.
Jak wznowić nieudane pobieranie cURL?
Uruchom curl -C - -LO <url>. Działa to tylko wtedy, gdy serwer obsługuje zapytania zakresowe — najpierw sprawdź curl -I <url> i szukaj w odpowiedzi Accept-Ranges: bytes.
Czy cURL może pobierać pliki wymagające logowania?
Tak, na cztery główne sposoby: basic auth (-u user:pass), token Bearer (-H "Authorization: Bearer <token>"), sesje oparte na cookies (-b cookies.txt) albo plik .netrc w środowiskach skryptowych. Pełny opis i zastosowania znajdziesz w sekcji o uwierzytelnianiu powyżej.
Jaka jest różnica między cURL a wget przy pobieraniu plików?
cURL obsługuje więcej protokołów i zwykle lepiej sprawdza się w skryptach, potokach oraz przy precyzyjnym pobieraniu pojedynczych plików lub małych partii. wget jest stworzony do rekurencyjnego crawlowania i mirroringu całych katalogów stron, więc lepiej nadaje się do masowego pobierania statycznych zasobów.
Dlaczego cURL pobiera stronę HTML zamiast właściwego pliku?
Najczęściej są dwie przyczyny: zapomniałeś flagi -L i serwer przekierował Cię gdzie indziej albo strona wymaga JavaScriptu do wyrenderowania właściwej treści — a curl po prostu nie wykonuje JS. W drugim przypadku potrzebujesz narzędzia z możliwością renderowania, a nie kolejnych flag cURL.
