form.md (5188B)
1 --- 2 c: Copyright (C) Daniel Stenberg, <daniel@haxx.se>, et al. 3 SPDX-License-Identifier: curl 4 Long: form 5 Short: F 6 Arg: <name=content> 7 Help: Specify multipart MIME data 8 Protocols: HTTP SMTP IMAP 9 Mutexed: data head upload-file 10 Category: http upload post imap smtp 11 Added: 5.0 12 Multi: append 13 See-also: 14 - data 15 - form-string 16 - form-escape 17 Example: 18 - --form "name=curl" --form "file=@loadthis" $URL 19 --- 20 21 # `--form` 22 23 For the HTTP protocol family, emulate a filled-in form in which a user has 24 pressed the submit button. This makes curl POST data using the Content-Type 25 multipart/form-data according to RFC 2388. 26 27 For SMTP and IMAP protocols, this composes a multipart mail message to 28 transmit. 29 30 This enables uploading of binary files etc. To force the 'content' part to be 31 a file, prefix the filename with an @ sign. To just get the content part from 32 a file, prefix the filename with the symbol \<. The difference between @ and 33 \< is then that @ makes a file get attached in the post as a file upload, 34 while the \< makes a text field and just gets the contents for that text field 35 from a file. 36 37 Read content from stdin instead of a file by using a single "-" as filename. 38 This goes for both @ and \< constructs. When stdin is used, the contents is 39 buffered in memory first by curl to determine its size and allow a possible 40 resend. Defining a part's data from a named non-regular file (such as a named 41 pipe or similar) is not subject to buffering and is instead read at 42 transmission time; since the full size is unknown before the transfer starts, 43 such data is sent as chunks by HTTP and rejected by IMAP. 44 45 Example: send an image to an HTTP server, where 'profile' is the name of the 46 form-field to which the file **portrait.jpg** is the input: 47 48 curl -F profile=@portrait.jpg https://example.com/upload.cgi 49 50 Example: send your name and shoe size in two text fields to the server: 51 52 curl -F name=John -F shoesize=11 https://example.com/ 53 54 Example: send your essay in a text field to the server. Send it as a plain 55 text field, but get the contents for it from a local file: 56 57 curl -F "story=<hugefile.txt" https://example.com/ 58 59 You can also instruct curl what Content-Type to use by using `type=`, in a 60 manner similar to: 61 62 curl -F "web=@index.html;type=text/html" example.com 63 64 or 65 66 curl -F "name=daniel;type=text/foo" example.com 67 68 You can also explicitly change the name field of a file upload part by setting 69 filename=, like this: 70 71 curl -F "file=@localfile;filename=nameinpost" example.com 72 73 If filename/path contains ',' or ';', it must be quoted by double-quotes like: 74 75 curl -F "file=@\"local,file\";filename=\"name;in;post\"" \ 76 https://example.com 77 78 or 79 80 curl -F 'file=@"local,file";filename="name;in;post"' \ 81 https://example.com 82 83 Note that if a filename/path is quoted by double-quotes, any double-quote 84 or backslash within the filename must be escaped by backslash. 85 86 Quoting must also be applied to non-file data if it contains semicolons, 87 leading/trailing spaces or leading double quotes: 88 89 curl -F 'colors="red; green; blue";type=text/x-myapp' \ 90 https://example.com 91 92 You can add custom headers to the field by setting headers=, like 93 94 curl -F "submit=OK;headers=\"X-submit-type: OK\"" example.com 95 96 or 97 98 curl -F "submit=OK;headers=@headerfile" example.com 99 100 The headers= keyword may appear more than once and above notes about quoting 101 apply. When headers are read from a file, empty lines and lines starting 102 with '#' are ignored; each header can be folded by splitting 103 between two words and starting the continuation line with a space; embedded 104 carriage-returns and trailing spaces are stripped. 105 Here is an example of a header file contents: 106 107 # This file contains two headers. 108 X-header-1: this is a header 109 110 # The following header is folded. 111 X-header-2: this is 112 another header 113 114 To support sending multipart mail messages, the syntax is extended as follows: 115 116 - name can be omitted: the equal sign is the first character of the argument, 117 118 - if data starts with '(', this signals to start a new multipart: it can be 119 followed by a content type specification. 120 121 - a multipart can be terminated with a '=)' argument. 122 123 Example: the following command sends an SMTP mime email consisting in an 124 inline part in two alternative formats: plain text and HTML. It attaches a 125 text file: 126 127 curl -F '=(;type=multipart/alternative' \ 128 -F '=plain text message' \ 129 -F '= <body>HTML message</body>;type=text/html' \ 130 -F '=)' -F '=@textfile.txt' ... smtp://example.com 131 132 Data can be encoded for transfer using encoder=. Available encodings are 133 *binary* and *8bit* that do nothing else than adding the corresponding 134 Content-Transfer-Encoding header, *7bit* that only rejects 8-bit characters 135 with a transfer error, *quoted-printable* and *base64* that encodes data 136 according to the corresponding schemes, limiting lines length to 76 137 characters. 138 139 Example: send multipart mail with a quoted-printable text message and a 140 base64 attached file: 141 142 curl -F '=text message;encoder=quoted-printable' \ 143 -F '=@localfile;encoder=base64' ... smtp://example.com 144 145 See further examples and details in the MANUAL.