Inspect your curl installation

curl is two things. It’s the command-line tool you type, and it’s a library, libcurl, that other programs embed. The tool is built from many optional pieces. Different operating systems ship different builds, with a different TLS library, different protocols, different features.

The curl on a fresh Mac is not the curl inside an Alpine container. Even when the version numbers look close.

That’s why we start here. When an option misbehaves, my first question is always the same: what exact curl am I running?

Read the version output

Run this before anything else:

curl --version

You get something like this:

curl 8.7.1 (x86_64-apple-darwin24.0) libcurl/8.7.1 (SecureTransport) LibreSSL/3.3.6
Release-Date: 2024-03-27
Protocols: dict file ftp ftps http https imap imaps ...
Features: alt-svc AsynchDNS HSTS HTTP2 IPv6 SSL ...

Read it line by line.

The first line gives you the version, the platform, and the TLS backend. That’s the library curl uses for HTTPS. Here it’s SecureTransport with LibreSSL. On Linux it’s often OpenSSL. The backend explains real differences in behavior, like where curl looks for trusted certificates.

The Protocols line lists every URL scheme this build accepts. The Features line tells you what was compiled in. If HTTP2 is not there, no option will make this curl speak HTTP/2.

Save this output with your notes. “It failed on curl 8.7.1 with LibreSSL” is evidence. “It failed on my laptop” is not.

Match the documentation to the build

Options get added in specific versions. --json only exists since curl 7.82.0, and plenty of servers still run older builds. The online man page describes the latest curl, not necessarily yours.

So ask your own build:

curl --help all | grep json
man curl

curl --help all lists every option this binary understands. man curl opens the manual that shipped with it.

If grep prints nothing, that option doesn’t exist in your curl. The tutorial you copied it from is not wrong. Your curl is older. Now you know that before wasting an hour on a mystery error like curl: option --json: is unknown.

Try this on a server or container you use: run curl --version there and compare it with your laptop. The differences you find are the differences that will bite you later.