Generator i konstruktor poleceń cURL

Czym jest polecenie curl?

# Plain GET — curl defaults to GET
curl https://api.example.com/users

# GET with a Bearer token (auth is just a header)
curl https://api.example.com/me \
  -H 'Authorization: Bearer YOUR_TOKEN'

# POST a JSON body — note the Content-Type header
curl -X POST https://api.example.com/users \
  -H 'Content-Type: application/json' \
  -d '{"name":"Ada","role":"admin"}'

# Multipart file upload — '@' reads the file from disk
curl -X POST https://api.example.com/upload \
  -F 'file=@report.pdf' \
  -F 'title=Q3 report'

Kluczowe funkcje

Alternatywy curl i klienty HTTP

Przykłady poleceń curl

curl https://api.example.com/users

curl https://api.example.com/me \
  -H 'Authorization: Bearer YOUR_TOKEN'

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

curl -X POST https://api.example.com/login \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  -d 'username=ada&password=s3cret'

curl -X POST https://api.example.com/upload \
  -F 'file=@report.pdf' \
  -F 'title=Q3 report'

curl -L -o archive.zip \
  https://example.com/files/archive.zip

curl -u ada:s3cret \
  https://api.example.com/private

curl -v -i https://api.example.com/health

Jak zbudować polecenie curl

1. 1

   Wybierz metodę HTTP

   Wybierz GET, POST, PUT, PATCH, DELETE, HEAD lub OPTIONS. curl domyślnie używa GET; wybranie POST lub innego czasownika dodaje `-X METODA` do wygenerowanego polecenia. Możesz też kliknąć preset, aby ustawić metodę i pasującą treść jednym kliknięciem.

2. 2

   Wprowadź URL i parametry zapytania

   Wpisz URL żądania (np. `https://api.example.com/users`). Dodaj parametry zapytania jako pary klucz/wartość, a narzędzie zakoduje je w URL i automatycznie dołączy jako `?klucz=wartość&…` do adresu — bez ręcznego kodowania.

3. 3

   Dodaj nagłówki i autoryzację

   Dodaj nagłówki żądania jako pary klucz/wartość, a następnie wybierz schemat autoryzacji: Brak, token Bearer, Basic (nazwa użytkownika/hasło) lub niestandardowy nagłówek klucza API. Właściwy nagłówek `Authorization` lub niestandardowy zostanie wygenerowany w dokładnym formacie oczekiwanym przez serwer.

4. 4

   Ustaw treść żądania

   Dla żądań POST/PUT/PATCH wybierz typ treści: wklej surowy JSON (nagłówek `Content-Type` zostanie dodany za Ciebie), zbuduj pola formularza urlencoded lub złóż upload multipart i przełącz dowolne pole na plik z prefiksem `@`.

5. 5

   Przełącz opcje

   Włącz potrzebne flagi — podążaj za przekierowaniami (`-L`), wyłącz weryfikację TLS (`-k`), tryb szczegółowy (`-v`), dołącz nagłówki (`-i`), kompresja (`--compressed`), zapisz do pliku (`-o`), limit czasu połączenia lub proxy (`-x`). Każdy przełącznik aktualizuje polecenie na żywo.

6. 6

   Kopiuj, eksportuj lub resetuj

   Skopiuj gotowe polecenie, wyeksportuj .sh, aby pobrać je jako skrypt, lub Resetuj, aby wyczyścić formularz. Użyj przełącznika Wieloliniowy, aby wybrać między wyjściem jednoliniowym a z kontynuacją odwrotnym ukośnikiem przed skopiowaniem.

Częste błędy curl

# Intended a PATCH, but -d alone implies POST
curl -d '{"role":"admin"}' \
  https://api.example.com/users/7

# Set the verb explicitly
curl -X PATCH -d '{"role":"admin"}' \
  -H 'Content-Type: application/json' \
  https://api.example.com/users/7

# Server sees urlencoded, not JSON — 400/415
curl -X POST https://api.example.com/users \
  -d '{"name":"Ada"}'

# Declare the JSON content type
curl -X POST https://api.example.com/users \
  -H 'Content-Type: application/json' \
  -d '{"name":"Ada"}'

# $name gets expanded by the shell to empty string
curl -d "{\"user\":\"$name\"}" \
  https://api.example.com/users

# Single quotes send the body literally
curl -d '{"user":"$name"}' \
  https://api.example.com/users

# -d makes this a POST, not a GET
curl -d 'page=2&limit=50' \
  https://api.example.com/users

# Query string on the URL keeps it a GET
curl 'https://api.example.com/users?page=2&limit=50'

:: cmd.exe — backslash is not a continuation char
curl -X POST https://api.example.com/users \
  -d '{"name":"Ada"}'

:: cmd.exe — one line, or use ^ to continue
curl -X POST https://api.example.com/users -d "{\"name\":\"Ada\"}"

# Space splits the argument — curl sees two args
curl https://api.example.com/search?q=hello world

# Encode the space (or quote the whole URL)
curl 'https://api.example.com/search?q=hello%20world'

Typowe zastosowania

Testowanie REST API

Buduj i wysyłaj żądania do endpointów REST bez opuszczania terminala: ustaw metodę, wklej token Bearer, wyślij treść JSON i odczytaj odpowiedź. Najszybszy sposób na potwierdzenie, że API działa prawidłowo, zanim napiszesz kod klienta.

Odtwarzanie żądań z dokumentacji

Dokumentacja API pokazuje endpointy i parametry, ale rzadko kompletne, gotowe do skopiowania polecenie. Wypełnij metodę, URL, nagłówki i autoryzację tutaj i otrzymaj polecenie curl, które działa od razu — bez walki z cytowaniem i brakującymi nagłówkami `Content-Type`.

Skrypty smoke-test w CI/CD

Wygeneruj polecenie curl do sprawdzania stanu lub smoke testu po wdrożeniu, a następnie wyeksportuj .sh, aby wrzucić je do potoku. Dodaj `--connect-timeout` i `--max-time`, aby zawieszony endpoint nie blokował budowania, i sprawdzaj kody stanu za pomocą `-w`.

Przesyłanie i pobieranie plików

Złóż upload `multipart/form-data` z `-F field=@file` lub zbuduj pobieranie `-L -o filename`, które śledzi przekierowania do CDN. Zakoduj trudne nazwy plików lub wartości zapytania najpierw naszym koderem URL.

Debugowanie webhooków

Odtwórz payload webhooka, wysyłając POST z tą samą treścią JSON, którą wysyła dostawca, z właściwymi nagłówkami podpisu i `Content-Type`. Odtwórz dokładne żądanie lokalnie, aby debugować, dlaczego handler je odrzucił.

Odtwarzalne raporty błędów

Wklej pojedyncze, autonomiczne polecenie curl do raportu błędu lub PR, aby każdy mógł odtworzyć dokładne żądanie — metodę, nagłówki, placeholder autoryzacji i treść. Znacznie czytelniejsze niż opisywanie żądania w prozie.

Nauka flag curl

Zobacz, jak każdy wybór w formularzu mapuje się na prawdziwą flagę — wybierz autoryzację Basic i obserwuj, jak pojawia się `-u`, dodaj treść JSON i obserwuj, jak dołącza się nagłówek `Content-Type`. Praktyczny sposób nauki składni, uzupełniony naszą ściągawką curl.

Przygotowanie żądania do konwersji na kod

Najpierw zbuduj i zweryfikuj żądanie jako curl, a następnie przetłumacz je na klienta HTTP swojej aplikacji. Nadchodząca karta Konwertuj zamieni wklejone polecenie curl na fetch, requests, Go, PHP, Ruby i Node.js — zacznij od polecenia curl, o którym wiesz, że działa.

Flagi i składnia curl — dokumentacja

Cytowanie i escape w powłoce

Narzędzie opakowuje wartości w apostrofy, najbezpieczniejszą formę w powłokach POSIX, ponieważ nic wewnątrz ciągu w apostrofach nie jest rozwijane. Dosłowny apostrof wewnątrz wartości jest emitowany jako sekwencja `'\''` (zamknięcie cytowania, escape apostrofu, ponowne otwarcie cytowania). W `cmd.exe` przejdź na cudzysłowy podwójne; Git Bash i WSL uruchamiają wygenerowane polecenia z apostrofami bez zmian.

-d vs --data-raw vs --data-binary

`-d`/`--data` usuwa znaki nowej linii i powrotu karetki z treści — odpowiednie dla par `key=value`, stratne dla treści wieloliniowej. `--data-raw` jest takie samo, ale nie traktuje wiodącego `@` jako nazwy pliku. `--data-binary` wysyła bajty dokładnie tak jak podane (użyj `@file`, aby przesłać surową zawartość pliku). Wszystkie trzy implikują POST, chyba że metoda zostanie nadpisana.

Multipart (-F) vs urlencoded (-d)

`-F field=value` produkuje `multipart/form-data` z wygenerowaną granicą — wymagane dla uploadów plików (`-F file=@path`) i formularzy mieszanych plik/tekst. `-d field=value` produkuje `application/x-www-form-urlencoded`, pojedynczy ciąg połączony znakiem `&`. Nigdy nie ustawiaj ręcznie `Content-Type` dla multipart; curl oblicza granicę i sam ustawia nagłówek.

Kodowanie nagłówka autoryzacji

Autoryzacja Bearer wysyła `Authorization: Bearer ` dosłownie (RFC 6750). Autoryzacja Basic z `-u user:pass` jest kodowana w Base64 do `Authorization: Basic ` — to kodowanie, nie szyfrowanie, więc używaj HTTPS. Klucz API to dowolny niestandardowy nagłówek wymagany przez usługę, np. `X-API-Key: `.

Kodowanie ciągu zapytania

Parametry zapytania dodane w konstruktorze są kodowane procentowo i dołączane jako `?klucz=wartość&klucz2=wartość2`. Znaki zarezerwowane (spacje, `&`, `=`, `#`) są escape'owane, aby URL był prawidłowy. Dla pól treści, które muszą być zakodowane, własne `--data-urlencode` curl obsługuje kodowanie w czasie żądania.

Zachowanie przy przekierowaniach (-L)

Bez `-L` curl wyświetla odpowiedź 301/302 i zatrzymuje się. Z `-L` podąża za nagłówkiem `Location` do ostatecznego URL. Zauważ, że curl usuwa nagłówek `Authorization`, gdy przekierowanie przechodzi na inny host (domyślne zachowanie bezpieczeństwa); użyj `--location-trusted` tylko wtedy, gdy rozumiesz implikacje.

Skompresowane odpowiedzi

`--compressed` dodaje nagłówek `Accept-Encoding` reklamujący obsługę gzip/deflate/brotli i transparentnie dekompresuje odpowiedź, oszczędzając przepustowość. Zdekodowana treść jest identyczna jak w żądaniu nieskompresowanym — wyłącznie optymalizacja transferu, bezpieczna do włączenia w większości wywołań API.

Wyjście: -o vs -O

`-o filename` zapisuje treść odpowiedzi do nazwanego przez Ciebie pliku; `-O` zapisuje ją pod zdalną nazwą pliku z ścieżki URL. Oba tłumią normalny zrzut na stdout. Połącz z `-L`, aby przekierowania rozwiązały się do prawdziwego zasobu przed zapisaniem pliku.

Dobre praktyki dla żądań curl

Nigdy nie koduj na stałe sekretów w udostępnianych poleceniach

Polecenie curl, które wkleisz do PR, ticketu lub czatu, będzie czytane przez innych i indeksowane przez narzędzia. Zastąp tokeny i hasła placeholderem (`YOUR_TOKEN`) lub odwołaj się do zmiennej środowiskowej (`-H "Authorization: Bearer $API_TOKEN"`). Dla długich poświadczeń curl może odczytać nagłówek z pliku z `-H @headerfile`, dzięki czemu sekret nigdy nie pojawi się w historii powłoki.

Preferuj --data-binary @file dla payloadów binarnych

Gdy treścią jest plik, którego bajty mają znaczenie — obraz, podpisany payload, JSON z istotnym białym znakiem — użyj `--data-binary @file`, a nie `-d @file`. Proste `-d` usuwa znaki nowej linii i powrotu karetki, po cichu uszkadzając zawartość binarną i wieloliniową. `--data-binary` wysyła plik dokładnie tak jak jest na dysku.

Cytuj wartości nagłówków

Zawsze opakowuj wartości `-H` w cudzysłowy: `-H 'Content-Type: application/json'`. Bez cytowania spacja po dwukropku dzieli argument i curl widzi zniekształcony nagłówek. Apostrofy zapobiegają też rozwijaniu przez powłokę `$`, `*` i innych znaków specjalnych wewnątrz wartości — dokładnie to, co to narzędzie domyślnie emituje.

Używaj --compressed, aby oszczędzać przepustowość

Dodaj `--compressed` do wywołań API i pobierania, aby zażądać kodowania gzip/brotli i mieć curl transparentnie dekompresujący. W przypadku API intensywnie korzystających z JSON może to zmniejszyć rozmiar transferu o 70–90% bez żadnych zmian w widzianej odpowiedzi — darmowe zyski w skryptach, które wielokrotnie odpytują endpointy.

Ustalaj limity czasu w skryptach

W dowolnym automatycznym kontekście dodaj `--connect-timeout` i `--max-time`, aby powolny lub zawieszony endpoint nie mógł blokować potoku na zawsze. Sprawdzenie stanu z `--max-time 10` kończy się szybko i pozwala CI przejść dalej. Połącz z `--retry N`, aby pochłaniać przejściowe problemy sieciowe bez natychmiastowego rezygnowania.

Weryfikuj z -v przed automatyzacją

Zanim wpiszesz polecenie curl do skryptu lub zadania cron, uruchom je raz z `-v`, aby zobaczyć dokładną linię żądania, nagłówki i uzgadnianie TLS. To najszybszy sposób na wykrycie złej metody, brakującego `Content-Type` lub nagłówka autoryzacji, który nie został dołączony — debuguj interaktywnie, a następnie usuń `-v` dla produkcji.

Najczęściej zadawane pytania