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