curl-requests

Curl requests

Use curl as a narrow transport tool, not as authority to mutate an external system. Establish the intended method, target environment, endpoint contract, and observable result before sending the request. A diagnostic task does not authorize POST, PUT, PATCH, DELETE, deployment, or another side effect.

Safe defaults

• Put --disable first so an uninspected user-level .curlrc cannot silently add redirects, credentials, proxies, output paths, or weaker transport settings. Omit it only when the assigned operation explicitly depends on a known curl config.
• Use HTTPS unless the target is a verified local plaintext service.
• Set --connect-timeout and --max-time from the operation's expected latency. A health check should be short; a known upload may need longer.
• Use --fail-with-body when an HTTP status of 400 or greater must produce a failing exit code while retaining the error body for local diagnosis. Use --fail when the body is unnecessary or may contain sensitive data. These options do not treat 3xx as failure.
• Add -sS when machine-readable output is useful. Preserve the status code separately with --write-out when the result must prove both transport and application behavior.
• Let --data, --form, and other data options select their normal request method. Do not add -X POST unless the server contract specifically requires overriding curl's method selection.
• -I sends a HEAD request. -i preserves the selected method and includes response headers in output. They are not interchangeable.

curl --disable -sS --fail-with-body \
  --connect-timeout 3 --max-time 15 \
  -H "Accept: application/json" \
  --write-out "\nHTTP_CODE:%{http_code}\n" \
  "https://example.invalid/resource"

For JSON, preserve the endpoint's documented schema:

curl --disable -sS --fail-with-body \
  --connect-timeout 3 --max-time 15 \
  -H "Content-Type: application/json" \
  --data '{"name":"example"}' \
  "https://example.invalid/items"