How to Use the curl trace-ascii Flag

This article explains the purpose of the --trace-ascii flag in the curl command-line tool. You will learn how this option helps in debugging network connections by logging detailed transmission data in a highly readable ASCII format, how it differs from other verbose options, and how to implement it in your terminal workflows.

What is the curl --trace-ascii Flag?

The --trace-ascii flag is a debugging tool in curl used to log all incoming and outgoing data of a network request to a specified file. It records everything that passes between the client and the server, including raw request headers, response headers, and the transmission bodies, while excluding hexadecimal representations.

This flag is particularly useful when you need to inspect the exact bytes sent and received over text-based protocols like HTTP, SMTP, or FTP, without cluttering the output with binary hex dumps.

Syntax and Basic Usage

To use --trace-ascii, you must specify a file path where curl will write the log. The basic syntax is:

curl --trace-ascii <output_file> <URL>

For example, to trace a request to https://example.com and save the log to a file named trace.txt, run:

curl --trace-ascii trace.txt https://example.com

If you want to direct the trace output directly to your terminal instead of a file, you can use a hyphen (-) as the filename:

curl --trace-ascii - https://example.com

How It Differs From Other curl Debugging Flags

While curl offers multiple ways to inspect network traffic, --trace-ascii fills a specific niche between basic verbosity and low-level packet inspection.

  • -v / --verbose: This flag displays connection details, SSL handshakes, and headers in the terminal. However, it does not show the actual request or response body data.
  • --trace <file>: This flag logs everything, including headers and bodies, but outputs the data in both hexadecimal (hex) and ASCII formats. This is ideal for binary protocols but makes text-based protocols harder to read.
  • --trace-ascii <file>: Like --trace, it logs all data. However, it strips away the hex dump column, displaying only the readable ASCII text. This makes it the superior choice for debugging web APIs and HTML pages.

Understanding the Output Format

The generated trace file categorizes data using specific prefixes to show the direction and type of data flow:

  • == Info:: Connection events, SSL handshakes, and protocol details.
  • => Send header: HTTP headers sent from curl to the server.
  • => Send data: Request body payload sent to the server (e.g., POST data).
  • <= Recv header: HTTP headers received from the server.
  • <= Recv data: The response body received from the server (e.g., HTML, JSON).

By reading these prefixes, you can trace the exact sequence of a request and pinpoint issues such as incorrect headers, malformed payloads, or unexpected server redirects.