xref: /curl/docs/cmdline-opts/variable.md (revision 4ff7f516)
1---
2c: Copyright (C) Daniel Stenberg, <daniel@haxx.se>, et al.
3SPDX-License-Identifier: curl
4Long: variable
5Arg: <[%]name=text/@file>
6Help: Set variable
7Category: curl
8Added: 8.3.0
9Multi: append
10See-also:
11  - config
12Example:
13  - --variable name=smith --expand-url "$URL/{{name}}"
14---
15
16# `--variable`
17
18Set a variable with `name=content` or `name@file` (where `file` can be stdin
19if set to a single dash (`-`)). The name is a case sensitive identifier that
20must consist of no other letters than a-z, A-Z, 0-9 or underscore. The
21specified content is then associated with this identifier.
22
23Setting the same variable name again overwrites the old contents with the new.
24
25The contents of a variable can be referenced in a later command line option
26when that option name is prefixed with `--expand-`, and the name is used as
27`{{name}}`.
28
29--variable can import environment variables into the name space. Opt to either
30require the environment variable to be set or provide a default value for the
31variable in case it is not already set.
32
33--variable %name imports the variable called `name` but exits with an error if
34that environment variable is not already set. To provide a default value if
35the environment variable is not set, use --variable %name=content or
36--variable %name@content. Note that on some systems - but not all -
37environment variables are case insensitive.
38
39When expanding variables, curl supports a set of functions that can make the
40variable contents more convenient to use. You apply a function to a variable
41expansion by adding a colon and then list the desired functions in a
42comma-separated list that is evaluated in a left-to-right order. Variable
43content holding null bytes that are not encoded when expanded, causes an
44error.
45
46Available functions:
47
48## trim
49removes all leading and trailing white space.
50
51## json
52outputs the content using JSON string quoting rules.
53
54## url
55shows the content URL (percent) encoded.
56
57## b64
58expands the variable base64 encoded
59