How to store cURL credentials in a netrc file

Repeatedly typing or pasting secrets into curl commands increases the chance of leaks through shell history, screen sharing, or copy‑and‑paste mistakes. Centralizing credentials in a .netrc file keeps authentication details in one place while allowing commands to stay short and reusable, especially in scripts or cron jobs.

The .netrc format is a small plain‑text database that maps a machine (host name) to a login and password pair and optional fields such as account. When curl runs with --netrc or -n, it searches the appropriate file (~/.netrc on POSIX systems or _netrc on Windows) for an entry matching the request host and silently applies those credentials to HTTP, HTTPS, or FTP requests.

Because .netrc stores secrets unencrypted, file permissions and scoping are critical. Multi‑user systems, shared home directories, and backups can all expand the blast radius of a compromised file. Limiting entries to low‑privilege or scoped credentials, applying strict permissions, and avoiding overly broad “default” entries significantly reduces risk.

1. Open a terminal under the account that should own the credentials on Linux or another POSIX system.

   $ whoami
   apiuser

2. Create or open the ~/.netrc file in a text editor in the user home directory.

   $ nano ~/.netrc

   On Linux and macOS, /home/<user>/.netrc (or ~/.netrc) is used; many Windows ports of curl read credentials from %USERPROFILE%\_netrc instead.

3. Add a dedicated machine entry for each host that requires authentication.

   machine api.example.com
     login myuser
     password mysecretpassword
   
   machine files.example.com
     login ftpuser
     password ftpsecret

   Each password value appears in plain text; anyone who can read the file can reuse the credentials, so avoid high‑privilege accounts and rotate tokens periodically.

4. Optionally define a default entry for hosts that lack a specific machine block if a shared low‑risk account is acceptable.

   default
     login shareduser
     password sharedsecret

   A default stanza applies to any host without an explicit machine match, which can silently send the same credentials to unexpected services if overused.

5. Restrict permissions on the ~/.netrc file so only the owner can read and write it.

   $ chmod 600 ~/.netrc
   $ ls -l ~/.netrc
   -rw------- 1 apiuser apiuser 176 Dec  7 10:42 /home/apiuser/.netrc

   curl may ignore .netrc files that are group‑ or world‑readable, and permissive modes greatly increase the chance of credential disclosure.

6. Invoke curl with --netrc to let it load the matching credentials for a protected endpoint.

   $ curl --netrc https://api.example.com/protected
   {"status":"ok","user":"myuser"}

   Variants such as --netrc-optional tolerate missing entries without failing, and --netrc-file ~/.netrc-api allows separate credential files for different environments.

7. Use verbose output to verify that authentication succeeds without embedding credentials in the command line.

   $ curl --netrc --verbose https://api.example.com/protected
   *   Trying 203.0.113.10:443...
   * Connected to api.example.com (203.0.113.10) port 443 (#0)
   * Server auth using Basic with user 'myuser'
   > GET /protected HTTP/1.1
   > Host: api.example.com
   ##### snipped #####
   < HTTP/1.1 200 OK
   < Content-Type: application/json
   ##### snipped #####
   {"status":"ok","user":"myuser"}

   Success indicators include an HTTP 2xx status code, absence of an interactive credential prompt, and headers showing the expected authentication method.