Write a curl config file

Commands you run repeatedly grow options until they no longer fit on a screen. A fifteen-option command is where mistakes hide.

A curl config file puts those options in a file, one per line. A colleague can read it. You can diff it. And curl reads it with a single flag.

Write the file

Create smoke.curl:

# transfer policy for the API smoke check
url = "https://example.org/"
fail-with-body
show-error
silent
max-time = 10

The format rules are few. Use the long option names without the leading dashes. One option per line. Options that take a value use = (a space works too). Lines starting with # are comments.

Use the comments. A config file is documentation that happens to execute.

Run it:

curl --config smoke.curl

Same transfer as typing all five options by hand. But now the file describes the policy clearly. It lives in version control, and changes show up in diffs and code review.

Command-line options still work alongside the file, for temporary overrides:

curl --config smoke.curl --verbose

That’s the division I use. Stable policy in the file. Situational flags on the command line.

If you mistype an option name in the file, curl refuses to run at all:

curl: smoke.curl:4: 'show-erro' is unknown
curl: cannot read config from 'smoke.curl'

No transfer happens, and the exit code is non-zero. A typo in the policy file becomes a loud failure with a line number, not a silently dropped option. One catch: if silent comes before the typo in the file, curl hides that first line and prints only a generic config error.

Keep secrets elsewhere

Config files get committed, shared, and copied between machines. That’s their value. So keep secrets out of them.

A header = "Authorization: Bearer ..." line in a committed file is a leaked credential. Pass secrets at run time, from an environment variable or a secret manager. Let the file hold only what’s safe for anyone to read.

The invisible config file

curl may load a default config file on its own. On Linux and macOS it’s ~/.curlrc, and it gets read even when you never asked.

If your curl behaves differently from a colleague’s, check for it. A proxy that appears from nowhere, a user agent you didn’t set. A .curlrc is often the reason.

When you need a command that behaves the same on every machine, disable that file with --disable (short form -q):

curl -q --config smoke.curl

-q must be the first option on the command line, or curl ignores it. For scripts you share, start with -q and an explicit --config. That’s the whole reason you wrote the policy down.

Try this: run cat ~/.curlrc. If it exists, you may have just found why some of your commands behaved oddly.