IT:AD:cURL
- See also:
- IT:AD:Httpie ← friendlier.
Summary
Command line tool to perform HTTP requests to a service.
curl is a command line tool for transferring data with URL syntax, supporting DICT, FILE, FTP, FTPS, Gopher, HTTP, HTTPS, IMAP, IMAPS, LDAP, LDAPS, POP3, POP3S, RTMP, RTSP, SCP, SFTP, SMTP, SMTPS, Telnet and TFTP. curl supports SSL certificates, HTTP POST, HTTP PUT, FTP uploading, HTTP form based upload, proxies, cookies, user+password authentication (Basic, Digest, NTLM, Negotiate, kerberos...), file transfer resume, proxy tunneling and a busload of other tricks.
Examples of use would be:
- automated tests of POX or REST services.
- uploading data or file to a remote service
Process
Download
* http://curl.haxx.se/download.html * Download Wizard: http://curl.haxx.se/dlwiz/?type=bin&os=Win32&flav=-&ver=-
Installation
The download is a single *.exe. Copy it to your c:\Windows\
directory (or add it to the PATH) so that it can be found, and not get an error message from the command line:
'curl.exe' is not recognized as an internal or external command, operable program or batch file.
Usage
Open a Console (using Start/Run/cmd
)
Type cURL
and one or more of the switches as described below.
Tutorial
A tutorial that will get you started, from which I've alread extracted most of the examples that follow. * Tuturial: http://curl.haxx.se/docs/httpscripting.html
Examples
Get help:
-h, --help This help text curl.exe -h
Verb:GET a page (just body, no headers):
curl.exe http://skysigal.com
In some scenarios, (eg: http://skysigal.com) you may not be seeing the same response as what you would see within a browser. That's because you were sent a redirect 302 that curl won't follow until you add the --location
flag:
-L, --location Follow redirects (H) curl.exe -L http://skysigal.com
Verb:GET a page (with headers):
-v, --verbose Make the operation more talkative -L, --location Follow redirects (H) -i, --include Include protocol headers in the output (H/F) curl.exe -v -L -i http://skysigal.com
Verb:GET just the headers:
-v, --verbose Make the operation more talkative -L, --location Follow redirects (H) -I, --head Show document info only curl.exe -v -L -I http://skysigal.com
Verb:GET with parameters:
-v, --verbose Make the operation more talkative -L, --location Follow redirects (H) curl.exe -v -L http://skysigal.com?v=1&v=2
Verb:POST (using Content-Type application/x-www-form-urlencoded
):
-v, --verbose Make the operation more talkative -L, --location Follow redirects (H) -d, --data DATA HTTP POST data (H) curl.exe -v -L -d "v=John%20Smith&v=2" http://skysigal.com
Verb:POST (using Content-Type application/x-www-form-urlencoded
, and encoding being done for you):
-v, --verbose Make the operation more talkative -L, --location Follow redirects (H) --data-urlencode DATA HTTP POST data url encoded (H) curl.exe -v -L --data-urlencode "v1=John Smith&v2=2" http://skysigal.com
Verb:POST (using Content-Type multipart/form-data
):
-v, --verbose Make the operation more talkative -L, --location Follow redirects (H) -F, --form CONTENT Specify HTTP multipart POST data (H) curl.exe -v -L -F myuploadfieldname={localfilename} -F mysubmitbtnname=OK http://skysigal.com
Verb:PUT to a file:
-v, --verbose Make the operation more talkative -L, --location Follow redirects (H) -X, --request COMMAND Specify request command to use curl.exe -v -L -X PUT -data ... http://skysigal.com
Content-Type:
-v, --verbose Make the operation more talkative -L, --location Follow redirects (H) -H, --header LINE Custom header to pass to server (H) curl.exe -v -L --header "Content-Type: text/xml"
Content-Type & Accept:
-v, --verbose Make the operation more talkative -L, --location Follow redirects (H) -H, --header LINE Custom header to pass to server (H) curl.exe -v -L --header "Content-Type: text/xml" -H "Accept:application/json" -X POST -d "<xml>...</xml>"
Basic Authentication:
-v, --verbose Make the operation more talkative -L, --location Follow redirects (H) -u, --user USER[:PASSWORD] Server user and password curl.exe -v -L -u name:pwd http://skysigal.com
Proxy & Proxy User
-v, --verbose Make the operation more talkative -L, --location Follow redirects (H) -x, --proxy [PROTOCOL://]HOST[:PORT] Use proxy on given port -U, --proxy-user USER[:PASSWORD] Proxy user and password curl.exe -v -L -x myproxy --proxy-user user:pwd http://skysigal.com curl.exe -v -L -x myproxy --U user:pwd http://skysigal.com
Allow redirection (eg for a PRG)
-v, --verbose Make the operation more talkative -L, --location Follow redirects (H) curl.exe -v --location -X POST .... curl.exe -v -L -X POST ....
Cookies:
-v, --verbose Make the operation more talkative -L, --location Follow redirects (H) -b, --cookie STRING/FILE String or file to read cookies from (H) curl.exe -v -L --cookie "name=xyz" ....
Certificates:
See tutorial
CURL With WebAPI
Verb:GET:
-v, --verbose Make the operation more talkative -i, --include Include protocol headers in the output (H/F) curl.exe -v -i -H "Accept:application/json" http://skysigal.com/MyService/13
Verb:POST, sending JSON
-v, --verbose Make the operation more talkative -H, --header LINE Custom header to pass to server (H) -X, --request COMMAND Specify request command to use -d, --data DATA HTTP POST data (H) curl.exe -v -H "Content-Type: application/json" -H "Accept:application/json" -X POST -d '{\"screencast\":{\"subject\":\"tools\"}}' http://skysigal.com/myService
Verb:PUT, sending JSON
-v, --verbose Make the operation more talkative -H, --header LINE Custom header to pass to server (H) -X, --request COMMAND Specify request command to use -d, --data DATA HTTP POST data (H) curl.exe -v -H "Content-Type: application/json" -H "Accept:application/json" -X PUT -data '{\"screencast\":{\"subject\":\"tools\"}}' http://skysigal.com/myService
Verb:DELETE, sending JSON
-v, --verbose Make the operation more talkative -i, --include Include protocol headers in the output (H/F) curl.exe -v -i X -H "Accept:application/json" DELETE http://skysigal.com/MyService/13
More examples
Example for proxy:
# Upload IPA to TestFlight -F, --form CONTENT Specify HTTP multipart POST data (H) curl -U $USER:$password -x kbproxy.corp.bank.nzpfs.co.nz:8080 http://testflightapp.com/api/builds.json \ -F file=@$currentDir/kiwibank.ipa \ -F api_token='522a258c6954cf0fe7539ecbfe318023_MzUzMzI4MjAxMi0wMy0xMiAxNjowNTo0Ni42NzU4...' \ -F team_token='e2056e8b707fe6e4d66acdd36b747e51_MzQwMjEyMDExLTEwLTExIDE5OjEzOjEyLjkwMDM...' \ -F notes='Auto-build 2: Return of Auto-build' \ -F notify=True \ -F distribution_lists='SIT'
Syntax
Common:
-b, --cookie STRING/FILE String or file to read cookies from (H) -d, --data DATA HTTP POST data (H) -G, --get Send the -d data with a HTTP GET (H) -H, --header LINE Custom header to pass to server (H) -I, --head Show document info only -i, --include Include protocol headers in the output (H/F) -L, --location Follow redirects (H) --basic Use HTTP Basic Authentication (H) --ntlm Use HTTP NTLM authentication (H) -o, --output FILE Write output to <file> instead of stdout -x, --proxy [PROTOCOL://]HOST[:PORT] Use proxy on given port --proxy-anyauth Pick "any" proxy authentication method (H) --proxy-basic Use Basic authentication on the proxy (H) --proxy-negotiate Use Negotiate authentication on the proxy (H) --proxy-ntlm Use NTLM authentication on the proxy (H) -U, --proxy-user USER[:PASSWORD] Proxy user and password -x, --proxy [PROTOCOL://]HOST[:PORT] Use proxy on given port -X, --request COMMAND Specify request command to use -u, --user USER[:PASSWORD] Server user and password -v, --verbose Make the operation more talkative
Full:
C:\Users\Sky>curl http://skysigal.com/ -h Usage: curl [options...] <url> Options: (H) means HTTP/HTTPS only, (F) means FTP only --anyauth Pick "any" authentication method (H) -a, --append Append to target file when uploading (F/SFTP) --basic Use HTTP Basic Authentication (H) --cacert FILE CA certificate to verify peer against (SSL) --capath DIR CA directory to verify peer against (SSL) -E, --cert CERT[:PASSWD] Client certificate file and password (SSL) --cert-type TYPE Certificate file type (DER/PEM/ENG) (SSL) --ciphers LIST SSL ciphers to use (SSL) --compressed Request compressed response (using deflate or gzip) -K, --config FILE Specify which config file to read --connect-timeout SECONDS Maximum time allowed for connection -C, --continue-at OFFSET Resumed transfer offset -b, --cookie STRING/FILE String or file to read cookies from (H) -c, --cookie-jar FILE Write cookies to this file after operation (H) --create-dirs Create necessary local directory hierarchy --crlf Convert LF to CRLF in upload --crlfile FILE Get a CRL list in PEM format from the given file -d, --data DATA HTTP POST data (H) --data-ascii DATA HTTP POST ASCII data (H) --data-binary DATA HTTP POST binary data (H) --data-urlencode DATA HTTP POST data url encoded (H) --delegation STRING GSS-API delegation permission --digest Use HTTP Digest Authentication (H) --disable-eprt Inhibit using EPRT or LPRT (F) --disable-epsv Inhibit using EPSV (F) -D, --dump-header FILE Write the headers to this file --egd-file FILE EGD socket path for random data (SSL) --engine ENGINGE Crypto engine (SSL). "--engine list" for list -f, --fail Fail silently (no output at all) on HTTP errors (H) -F, --form CONTENT Specify HTTP multipart POST data (H) --form-string STRING Specify HTTP multipart POST data (H) --ftp-account DATA Account data string (F) --ftp-alternative-to-user COMMAND String to replace "USER [name]" (F) --ftp-create-dirs Create the remote dirs if not present (F) --ftp-method [MULTICWD/NOCWD/SINGLECWD] Control CWD usage (F) --ftp-pasv Use PASV/EPSV instead of PORT (F) -P, --ftp-port ADR Use PORT with given address instead of PASV (F) --ftp-skip-pasv-ip Skip the IP address for PASV (F) --ftp-pret Send PRET before PASV (for drftpd) (F) --ftp-ssl-ccc Send CCC after authenticating (F) --ftp-ssl-ccc-mode ACTIVE/PASSIVE Set CCC mode (F) --ftp-ssl-control Require SSL/TLS for ftp login, clear for transfer (F) -G, --get Send the -d data with a HTTP GET (H) -g, --globoff Disable URL sequences and ranges using {} and [] -H, --header LINE Custom header to pass to server (H) -I, --head Show document info only -h, --help This help text --hostpubmd5 MD5 Hex encoded MD5 string of the host public key. (SSH) -0, --http1.0 Use HTTP 1.0 (H) --ignore-content-length Ignore the HTTP Content-Length header -i, --include Include protocol headers in the output (H/F) -k, --insecure Allow connections to SSL sites without certs (H) --interface INTERFACE Specify network interface/address to use -4, --ipv4 Resolve name to IPv4 address -6, --ipv6 Resolve name to IPv6 address -j, --junk-session-cookies Ignore session cookies read from file (H) --keepalive-time SECONDS Interval between keepalive probes --key KEY Private key file name (SSL/SSH) --key-type TYPE Private key file type (DER/PEM/ENG) (SSL) --krb LEVEL Enable Kerberos with specified security level (F) --libcurl FILE Dump libcurl equivalent code of this command line --limit-rate RATE Limit transfer speed to this rate -l, --list-only List only names of an FTP directory (F) --local-port RANGE Force use of these local port numbers -L, --location Follow redirects (H) --location-trusted like --location and send auth to other hosts (H) -M, --manual Display the full manual --mail-from FROM Mail from this address --mail-rcpt TO Mail to this receiver(s) --mail-auth AUTH Originator address of the original email --max-filesize BYTES Maximum file size to download (H/F) --max-redirs NUM Maximum number of redirects allowed (H) -m, --max-time SECONDS Maximum time allowed for the transfer --metalink Process given URLs as metalink XML file --negotiate Use HTTP Negotiate Authentication (H) -n, --netrc Must read .netrc for user name and password --netrc-optional Use either .netrc or URL; overrides -n --netrc-file FILE Set up the netrc filename to use -N, --no-buffer Disable buffering of the output stream --no-keepalive Disable keepalive use on the connection --no-sessionid Disable SSL session-ID reusing (SSL) --noproxy List of hosts which do not use proxy --ntlm Use HTTP NTLM authentication (H) -o, --output FILE Write output to <file> instead of stdout --pass PASS Pass phrase for the private key (SSL/SSH) --post301 Do not switch to GET after following a 301 redirect (H) --post302 Do not switch to GET after following a 302 redirect (H) --post303 Do not switch to GET after following a 303 redirect (H) -#, --progress-bar Display transfer progress as a progress bar --proto PROTOCOLS Enable/disable specified protocols --proto-redir PROTOCOLS Enable/disable specified protocols on redirect -x, --proxy [PROTOCOL://]HOST[:PORT] Use proxy on given port --proxy-anyauth Pick "any" proxy authentication method (H) --proxy-basic Use Basic authentication on the proxy (H) --proxy-digest Use Digest authentication on the proxy (H) --proxy-negotiate Use Negotiate authentication on the proxy (H) --proxy-ntlm Use NTLM authentication on the proxy (H) -U, --proxy-user USER[:PASSWORD] Proxy user and password --proxy1.0 HOST[:PORT] Use HTTP/1.0 proxy on given port -p, --proxytunnel Operate through a HTTP proxy tunnel (using CONNECT) --pubkey KEY Public key file name (SSH) -Q, --quote CMD Send command(s) to server before transfer (F/SFTP) --random-file FILE File for reading random data from (SSL) -r, --range RANGE Retrieve only the bytes within a range --raw Do HTTP "raw", without any transfer decoding (H) -e, --referer Referer URL (H) -J, --remote-header-name Use the header-provided filename (H) -O, --remote-name Write output to a file named as the remote file --remote-name-all Use the remote file name for all URLs -R, --remote-time Set the remote file's time on the local output -X, --request COMMAND Specify request command to use --resolve HOST:PORT:ADDRESS Force resolve of HOST:PORT to ADDRESS --retry NUM Retry request NUM times if transient problems occur --retry-delay SECONDS When retrying, wait this many seconds between each --retry-max-time SECONDS Retry only within this period -S, --show-error Show error. With -s, make curl show errors when they occur -s, --silent Silent mode. Don't output anything --socks4 HOST[:PORT] SOCKS4 proxy on given host + port --socks4a HOST[:PORT] SOCKS4a proxy on given host + port --socks5 HOST[:PORT] SOCKS5 proxy on given host + port --socks5-hostname HOST[:PORT] SOCKS5 proxy, pass host name to proxy -Y, --speed-limit RATE Stop transfers below speed-limit for 'speed-time' secs -y, --speed-time SECONDS Time for trig speed-limit abort. Defaults to 30 --ssl Try SSL/TLS (FTP, IMAP, POP3, SMTP) --ssl-reqd Require SSL/TLS (FTP, IMAP, POP3, SMTP) -2, --sslv2 Use SSLv2 (SSL) -3, --sslv3 Use SSLv3 (SSL) --ssl-allow-beast Allow security flaw to improve interop (SSL) --stderr FILE Where to redirect stderr. - means stdout --tcp-nodelay Use the TCP_NODELAY option -t, --telnet-option OPT=VAL Set telnet option --tftp-blksize VALUE Set TFTP BLKSIZE option (must be >512) -z, --time-cond TIME Transfer based on a time condition -1, --tlsv1 Use TLSv1 (SSL) --trace FILE Write a debug trace to the given file --trace-ascii FILE Like --trace but without the hex output --trace-time Add time stamps to trace/verbose output --tr-encoding Request compressed transfer encoding (H) -T, --upload-file FILE Transfer FILE to destination --url URL URL to work with -B, --use-ascii Use ASCII/text transfer -u, --user USER[:PASSWORD] Server user and password --tlsuser USER TLS username --tlspassword STRING TLS password --tlsauthtype STRING TLS authentication type (default SRP) -A, --user-agent STRING User-Agent to send to server (H) -v, --verbose Make the operation more talkative -V, --version Show version number and quit -w, --write-out FORMAT What to output after completion --xattr Store metadata in extended file attributes -q If used as the first parameter disables .curlrc