curl
curl command-line HTTP client for making requests, testing APIs, debugging web services, handling authentication, uploading/downloading files, and automating web interactions. Use when interacting wit
SKILL.mdskills/curl/SKILL.md
GitHubcurl is a command-line utility for testing and automating web requests with APIs, authentication, and downloading/uploading files with web servers.
Table of contents
- Core Concepts
- Basic Requests
- HTTP Methods
- Headers & Authentication
- Sending Data
- File Uploads & Downloads
- Cookies & Sessions
- Debugging & Verbose Output
- TLS & Certificates
- Automation & Scripting
- Common API Workflows
- Troubleshooting
- Best Practices
- References
Core Concepts
| Concept | Description |
|---|---|
| URL | Target endpoint |
| Method | HTTP verb (GET, POST, PUT, DELETE, PATCH, HEAD, OPTIONS) |
| Headers | Metadata sent with request |
| Body | Data payload |
| Status Code | Server response indicator |
| Response Headers | Metadata returned by server |
Basic Requests
Simple GET Request
curl https://example.com
Follow redirects:
curl -L https://example.com
Save output to file:
curl -o output.html https://example.com
HTTP Methods
POST
curl -X POST https://api.example.com
PUT
curl -X PUT https://api.example.com/resource/1
DELETE
curl -X DELETE https://api.example.com/resource/1
Custom Method
curl -X PATCH https://api.example.com/resource/1
Headers & Authentication
Add Headers
curl -H "Content-Type: application/json" https://api.example.com
Multiple headers:
curl \
-H "Authorization: Bearer TOKEN" \
-H "Accept: application/json" \
https://api.example.com
Basic Auth
curl -u username:password https://example.com
Bearer Token
curl -H "Authorization: Bearer YOUR_TOKEN" https://api.example.com
API Key Header
curl -H "x-api-key: YOUR_API_KEY" https://api.example.com
Sending Data
JSON POST
curl -X POST https://api.example.com/users \
-H "Content-Type: application/json" \
-d '{"name":"John","email":"john@example.com"}'
Form Data
curl -X POST https://example.com/login \
-d "username=admin&password=pass123"
Multipart Form (File Upload)
curl -F "file=@report.pdf" https://example.com/upload
File Uploads & Downloads
Download File
curl -O https://example.com/file.zip
Custom filename:
curl -o myfile.zip https://example.com/file.zip
Resume Download
curl -C - -O https://example.com/file.zip
Cookies & Sessions
Send Cookie
curl -b "sessionid=abc123" https://example.com
Store Cookies
curl -c cookies.txt https://example.com
Use Stored Cookies
curl -b cookies.txt https://example.com/dashboard
Debugging & Verbose Output
Verbose Mode
curl -v https://example.com
Show Headers Only
curl -I https://example.com
Include Response Headers in Output
curl -i https://example.com
Trace Full Request
curl --trace-ascii debug.txt https://example.com
TLS & Certificates
Ignore Certificate Errors
curl -k https://example.com
Specify Certificate
curl --cert client.pem https://secure.example.com
Force TLS Version
curl --tlsv1.2 https://example.com
Automation & Scripting
Silent Mode
curl -s https://api.example.com
Return Only HTTP Status Code
curl -s -o /dev/null -w "%{http_code}" https://example.com
Timeout
curl --max-time 10 https://example.com
Retry on Failure
curl --retry 5 https://example.com
Pipe to jq (JSON parsing)
curl -s https://api.example.com/users | jq '.'
Common API Workflows
Auth → Token → Request
TOKEN=$(curl -s -X POST https://api.example.com/login \
-H "Content-Type: application/json" \
-d '{"username":"admin","password":"pass"}' | jq -r '.token')
curl -H "Authorization: Bearer $TOKEN" https://api.example.com/profile
Health Check
curl -f https://api.example.com/health || echo "Service down"
REST Resource Creation
curl -X POST https://api.example.com/items \
-H "Content-Type: application/json" \
-d '{"name":"item1"}'
Troubleshooting
403 Forbidden
- Missing authentication header
- Invalid API key
- IP blocked
415 Unsupported Media Type
Ensure:
-H "Content-Type: application/json"
Connection Refused
- Server not running
- Wrong port
- Firewall blocking
SSL Errors
Try:
curl -k https://example.com
Or verify certificate chain.
Best Practices
- Always specify
Content-Typefor JSON - Use
-sin automation scripts - Use
-fto fail on HTTP errors - Avoid exposing tokens in shell history
- Store secrets in environment variables
- Combine with
jqfor structured parsing - Log response codes in automation workflows
Safe Usage
- Do not send credentials over HTTP (use HTTPS)
- Avoid logging sensitive headers
- Protect API tokens
- Validate responses before processing in automation
AWS Integration
Feedback Loop Integration
curl is used to run external probes — with no AWS credentials — directly against AWS endpoints. Under the External Probe path, curl results bypass the pipeline and return directly. While AWS CLI checks verify configuration, curl verifies actual reachability from outside the account.
Probe commands per service are in skills/validation-rules/probes.md. Service-specific endpoint discovery is in each service skill (e.g., skills/s3/SKILL.md, skills/rds/SKILL.md).
Common AWS Validation Requests
Verify S3 bucket is publicly accessible:
curl -s -o /dev/null -w "%{http_code}" https://s3.amazonaws.com/BUCKET_NAME
Check if an ALB/CloudFront endpoint enforces HTTPS redirect:
curl -s -o /dev/null -w "%{http_code}" -L http://ENDPOINT
Test EC2 metadata endpoint (from within an instance):
curl -s -H "X-aws-ec2-metadata-token-ttl-seconds: 21600" -X PUT http://169.254.169.254/latest/api/token
Verify API Gateway returns 403 without auth:
curl -s -o /dev/null -w "%{http_code}" https://API_ID.execute-api.REGION.amazonaws.com/STAGE/
Check if a public RDS/ElastiCache endpoint responds (should timeout if properly secured):
curl -s --max-time 5 -o /dev/null -w "%{http_code}" http://ENDPOINT:PORT || echo "Connection refused/timed out"
For Critic scoring of curl probe results, see the Scoring Rubric and Service exceptions in agents/roles.md.