1--- 2c: Copyright (C) Daniel Stenberg, <daniel@haxx.se>, et al. 3SPDX-License-Identifier: curl 4Long: write-out 5Short: w 6Arg: <format> 7Help: Use output FORMAT after completion 8Category: verbose 9Added: 6.5 10Multi: single 11See-also: 12 - verbose 13 - head 14Example: 15 - -w '%{response_code}\n' $URL 16--- 17 18# `--write-out` 19 20Make curl display information on stdout after a completed transfer. The format 21is a string that may contain plain text mixed with any number of 22variables. The format can be specified as a literal "string", or you can have 23curl read the format from a file with "@filename" and to tell curl to read the 24format from stdin you write "@-". 25 26The variables present in the output format are substituted by the value or 27text that curl thinks fit, as described below. All variables are specified as 28%{variable_name} and to output a normal % you just write them as %%. You can 29output a newline by using \n, a carriage return with \r and a tab space with 30\t. 31 32The output is by default written to standard output, but can be changed with 33%{stderr} and %output{}. 34 35Output HTTP headers from the most recent request by using *%header{name}* 36where *name* is the case insensitive name of the header (without the trailing 37colon). The header contents are exactly as sent over the network, with leading 38and trailing whitespace trimmed (added in 7.84.0). 39 40Select a specific target destination file to write the output to, by using 41*%output{name}* (added in curl 8.3.0) where *name* is the full file name. The 42output following that instruction is then written to that file. More than one 43*%output{}* instruction can be specified in the same write-out argument. If 44the file name cannot be created, curl leaves the output destination to the one 45used prior to the *%output{}* instruction. Use *%output{>>name}* to append 46data to an existing file. 47 48**NOTE:** 49In Windows the %-symbol is a special symbol used to expand environment 50variables. In batch files all occurrences of % must be doubled when using this 51option to properly escape. If this option is used at the command prompt then 52the % cannot be escaped and unintended expansion is possible. 53 54The variables available are: 55 56## `certs` 57Output the certificate chain with details. Supported only by the OpenSSL, 58GnuTLS, Schannel and Secure Transport backends. (Added in 7.88.0) 59 60## `content_type` 61The Content-Type of the requested document, if there was any. 62 63## `errormsg` 64The error message. (Added in 7.75.0) 65 66## `exitcode` 67The numerical exit code of the transfer. (Added in 7.75.0) 68 69## `filename_effective` 70The ultimate filename that curl writes out to. This is only meaningful if curl 71is told to write to a file with the --remote-name or --output 72option. It's most useful in combination with the --remote-header-name 73option. (Added in 7.26.0) 74 75## `ftp_entry_path` 76The initial path curl ended up in when logging on to the remote FTP 77server. (Added in 7.15.4) 78 79## `header_json` 80A JSON object with all HTTP response headers from the recent transfer. Values 81are provided as arrays, since in the case of multiple headers there can be 82multiple values. (Added in 7.83.0) 83 84The header names provided in lowercase, listed in order of appearance over the 85wire. Except for duplicated headers. They are grouped on the first occurrence 86of that header, each value is presented in the JSON array. 87 88## `http_code` 89The numerical response code that was found in the last retrieved HTTP(S) or 90FTP(s) transfer. 91 92## `http_connect` 93The numerical code that was found in the last response (from a proxy) to a 94curl CONNECT request. (Added in 7.12.4) 95 96## `http_version` 97The http version that was effectively used. (Added in 7.50.0) 98 99## `json` 100A JSON object with all available keys. (Added in 7.70.0) 101 102## `local_ip` 103The IP address of the local end of the most recently done connection - can be 104either IPv4 or IPv6. (Added in 7.29.0) 105 106## `local_port` 107The local port number of the most recently done connection. (Added in 7.29.0) 108 109## `method` 110The http method used in the most recent HTTP request. (Added in 7.72.0) 111 112## `num_certs` 113Number of server certificates received in the TLS handshake. Supported only by 114the OpenSSL, GnuTLS, Schannel and Secure Transport backends. 115(Added in 7.88.0) 116 117## `num_connects` 118Number of new connects made in the recent transfer. (Added in 7.12.3) 119 120## `num_headers` 121The number of response headers in the most recent request (restarted at each 122redirect). Note that the status line IS NOT a header. (Added in 7.73.0) 123 124## `num_redirects` 125Number of redirects that were followed in the request. (Added in 7.12.3) 126 127## `onerror` 128The rest of the output is only shown if the transfer returned a non-zero error. 129(Added in 7.75.0) 130 131## `proxy_ssl_verify_result` 132The result of the HTTPS proxy's SSL peer certificate verification that was 133requested. 0 means the verification was successful. (Added in 7.52.0) 134 135## `redirect_url` 136When an HTTP request was made without --location to follow redirects (or when 137--max-redirs is met), this variable shows the actual URL a redirect 138*would* have gone to. (Added in 7.18.2) 139 140## `referer` 141The Referer: header, if there was any. (Added in 7.76.0) 142 143## `remote_ip` 144The remote IP address of the most recently done connection - can be either 145IPv4 or IPv6. (Added in 7.29.0) 146 147## `remote_port` 148The remote port number of the most recently done connection. (Added in 7.29.0) 149 150## `response_code` 151The numerical response code that was found in the last transfer (formerly 152known as "http_code"). (Added in 7.18.2) 153 154## `scheme` 155The URL scheme (sometimes called protocol) that was effectively used. (Added in 7.52.0) 156 157## `size_download` 158The total amount of bytes that were downloaded. This is the size of the 159body/data that was transferred, excluding headers. 160 161## `size_header` 162The total amount of bytes of the downloaded headers. 163 164## `size_request` 165The total amount of bytes that were sent in the HTTP request. 166 167## `size_upload` 168The total amount of bytes that were uploaded. This is the size of the 169body/data that was transferred, excluding headers. 170 171## `speed_download` 172The average download speed that curl measured for the complete download. Bytes 173per second. 174 175## `speed_upload` 176The average upload speed that curl measured for the complete upload. Bytes per 177second. 178 179## `ssl_verify_result` 180The result of the SSL peer certificate verification that was requested. 0 181means the verification was successful. (Added in 7.19.0) 182 183## `stderr` 184From this point on, the --write-out output is written to standard 185error. (Added in 7.63.0) 186 187## `stdout` 188From this point on, the --write-out output is written to standard output. 189This is the default, but can be used to switch back after switching to stderr. 190(Added in 7.63.0) 191 192## `time_appconnect` 193The time, in seconds, it took from the start until the SSL/SSH/etc 194connect/handshake to the remote host was completed. (Added in 7.19.0) 195 196## `time_connect` 197The time, in seconds, it took from the start until the TCP connect to the 198remote host (or proxy) was completed. 199 200## `time_namelookup` 201The time, in seconds, it took from the start until the name resolving was 202completed. 203 204## `time_pretransfer` 205The time, in seconds, it took from the start until the file transfer was just 206about to begin. This includes all pre-transfer commands and negotiations that 207are specific to the particular protocol(s) involved. 208 209## `time_redirect` 210The time, in seconds, it took for all redirection steps including name lookup, 211connect, pretransfer and transfer before the final transaction was 212started. `time_redirect` shows the complete execution time for multiple 213redirections. (Added in 7.12.3) 214 215## `time_starttransfer` 216The time, in seconds, it took from the start until the first byte is received. 217This includes time_pretransfer and also the time the server needed to calculate 218the result. 219 220## `time_total` 221The total time, in seconds, that the full operation lasted. 222 223## `url` 224The URL that was fetched. (Added in 7.75.0) 225 226## `url.scheme` 227The scheme part of the URL that was fetched. (Added in 8.1.0) 228 229## `url.user` 230The user part of the URL that was fetched. (Added in 8.1.0) 231 232## `url.password` 233The password part of the URL that was fetched. (Added in 8.1.0) 234 235## `url.options` 236The options part of the URL that was fetched. (Added in 8.1.0) 237 238## `url.host` 239The host part of the URL that was fetched. (Added in 8.1.0) 240 241## `url.port` 242The port number of the URL that was fetched. If no port number was specified 243and the URL scheme is known, that scheme's default port number is 244shown. (Added in 8.1.0) 245 246## `url.path` 247The path part of the URL that was fetched. (Added in 8.1.0) 248 249## `url.query` 250The query part of the URL that was fetched. (Added in 8.1.0) 251 252## `url.fragment` 253The fragment part of the URL that was fetched. (Added in 8.1.0) 254 255## `url.zoneid` 256The zone id part of the URL that was fetched. (Added in 8.1.0) 257 258## `urle.scheme` 259The scheme part of the effective (last) URL that was fetched. (Added in 8.1.0) 260 261## `urle.user` 262The user part of the effective (last) URL that was fetched. (Added in 8.1.0) 263 264## `urle.password` 265The password part of the effective (last) URL that was fetched. (Added in 8.1.0) 266 267## `urle.options` 268The options part of the effective (last) URL that was fetched. (Added in 8.1.0) 269 270## `urle.host` 271The host part of the effective (last) URL that was fetched. (Added in 8.1.0) 272 273## `urle.port` 274The port number of the effective (last) URL that was fetched. If no port 275number was specified, but the URL scheme is known, that scheme's default port 276number is shown. (Added in 8.1.0) 277 278## `urle.path` 279The path part of the effective (last) URL that was fetched. (Added in 8.1.0) 280 281## `urle.query` 282The query part of the effective (last) URL that was fetched. (Added in 8.1.0) 283 284## `urle.fragment` 285The fragment part of the effective (last) URL that was fetched. (Added in 8.1.0) 286 287## `urle.zoneid` 288The zone id part of the effective (last) URL that was fetched. (Added in 8.1.0) 289 290## `urlnum` 291The URL index number of this transfer, 0-indexed. Unglobbed URLs share the 292same index number as the origin globbed URL. (Added in 7.75.0) 293 294## `url_effective` 295The URL that was fetched last. This is most meaningful if you have told curl 296to follow location: headers. 297