cURL by Example: Cookie Storage
Manage sessions and persistent state. This example covers the "cookie engine", the Netscape cookie file format, and session handling.
Code
# Save cookies to a "cookie jar" file
curl -c cookies.txt https://example.com/login -d "user=admin&pass=123"
# Send cookies from a file (activates cookie engine)
curl -b cookies.txt https://example.com/dashboard
# Send ad-hoc cookies (no file needed)
curl -b "session_id=abc12345; theme=dark" https://example.com/settings
# Session handling: Read from file, write updates back
curl -b cookies.txt -c cookies.txt https://example.com/refresh_token
# Ignore session cookies when loading from file (start fresh session)
curl -b cookies.txt -j https://example.com/loginExplanation
Cookies are fundamental to maintaining state in the stateless HTTP protocol. They enable session management, user authentication persistence, shopping carts, user preferences, and tracking across multiple requests. cURL has a sophisticated built-in "cookie engine" that can record and send cookies just like a web browser, allowing you to simulate persistent sessions and user interactions. This cookie engine is activated whenever you use the -b flag (or --cookie to read/send cookies) or the -c flag (or --cookie-jar to save/write cookies). Once activated, the engine manages cookies automatically according to standard cookie rules including domain matching, path restrictions, expiration handling, and secure flag enforcement.
cURL adopted the Netscape cookie file format for storing cookies on disk, a legacy format that was once used by Netscape Navigator and early Mozilla browsers. While modern browsers have moved to database-based cookie storage, this text-based format remains useful for cURL due to its simplicity and human readability. Each cookie entry occupies a single line in the file, and lines starting with a hash symbol (#) are treated as comments. The format consists of seven tab-separated fields in this specific order: (1) Domain - the domain that created and can access the cookie, (2) Flag - a boolean (TRUE/FALSE) indicating whether all machines within a domain can access the cookie (also called "include subdomains" or "tailmatch"), (3) Path - the URL path on the server for which the cookie is valid, (4) Secure - a boolean (TRUE/FALSE) indicating whether the cookie should only be transmitted over HTTPS, (5) Expiration - a Unix timestamp (seconds since epoch) specifying when the cookie expires, with 0 typically indicating a session cookie, (6) Name - the cookie's name, and (7) Value - the cookie's value. This standardized format allows cookies to persist across different cURL invocations and even be shared between different tools that support the format.
The -b flag (or --cookie) has dual functionality: it can accept either a filename or a raw cookie string. When provided with a filename, cURL reads cookies from that file (which must be in Netscape format) and sends any matching cookies (based on domain, path, and other rules) with the request. When provided with a raw string in the format name1=value1; name2=value2, cURL sends those cookies directly without involving a file. If the argument contains no equals sign, cURL interprets it as a filename. The -c flag (or --cookie-jar) specifies where cURL should save all cookies from its in-memory store when the operation completes. This includes both cookies that were loaded from a file with -b and any new or updated cookies received from the server during the request. A powerful pattern is using both flags with the same file (-b cookies.txt -c cookies.txt), which allows cURL to maintain an active, persistent session by reading existing cookies and saving any updates—this simulates a browser maintaining session state across multiple page loads.
Session cookies are temporary cookies designed to exist only for the duration of a browsing session. They typically lack an expiration date (or have an expiration of 0) and are meant to be discarded when the browser closes. When you use -c to save cookies to a file, cURL includes session cookies in the output. However, the -j flag (or --junk-session-cookies) gives you control over session cookie handling when loading from a file. When combined with -b (e.g., curl -b cookies.txt -j), it tells cURL to ignore session cookies from the input file while still loading persistent cookies. This is useful for testing scenarios where you want to simulate a user returning to a site after closing their browser—persistent cookies (like "remember me" tokens) remain, but session cookies (like shopping cart contents) are discarded. This fine-grained control over cookie behavior enables sophisticated testing and automation scenarios.
Code Breakdown
-c cookies.txt enables the engine and saves cookies to disk.-b cookies.txt loads cookies and sends them if they match the domain/path.-j is useful for testing "fresh" logins without deleting the cookie file.
