Ask cURL

Make HTTP requests by describing what you want. Secrets stay safe via 1Password references.

Quick Reference

From natural language to cURL

1. User describes: "GET my GitHub repos", "POST to Slack webhook with message 'deployed'"
2. Agent builds the cURL command with proper headers, auth, body
3. Secrets injected at runtime via op run — never exposed in shell history or logs

Secret injection

Use 1Password secret references (op://vault/item/field) instead of raw tokens:

# BAD — token in plaintext
curl -H "Authorization: <raw token redacted>" https://api.github.com/user

# GOOD — secret injected at runtime by op
op run --env-file=.env.curl -- curl -H "Authorization: Bearer $GITHUB_TOKEN" https://api.github.com/user

Execution flow

describe request → build curl → inject secrets (op run) → execute → parse response

Building Requests

Standard patterns

# GET with auth
curl -s -H "Authorization: Bearer $TOKEN" \
  -H "Accept: application/json" \
  "https://api.example.com/resource"

# POST JSON
curl -s -X POST \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $TOKEN" \
  -d '{"key": "value"}' \
  "https://api.example.com/resource"

# File upload
curl -s -X POST \
  -H "Authorization: Bearer $TOKEN" \
  -F "file=@/path/to/file" \
  "https://api.example.com/upload"

# With query params
curl -s -G \
  --data-urlencode "q=search term" \
  --data-urlencode "limit=10" \
  "https://api.example.com/search"

Always include

• -s (silent — no progress bar)
• -w '\n%{http_code}' (append status code for validation)
• -H "Accept: application/json" (when expecting JSON)
• --fail-with-body (fail on HTTP errors but still show response body)
• --max-time 30 (timeout — never hang forever)

Secret Management

With 1Password (op:// references)

The preferred approach. Secrets never touch disk or shell history.

# Read a single secret
op read "op://Development/GitHub PAT/credential"

# Run curl with secrets injected from 1Password Environment
op run --env-file=~/.config/ask-curl/env.curl -- curl -s \
  -H "Authorization: Bearer $GITHUB_TOKEN" \
  "https://api.github.com/user"

# Inline single secret
curl -s -H "Authorization: Bearer $(op read 'op://Development/GitHub PAT/credential')" \
  "https://api.github.com/user"

Environment file format (~/.config/ask-curl/env.curl)

# 1Password secret references — resolved at runtime by `op run`
GITHUB_TOKEN=op://Development/GitHub PAT/credential
OPENAI_API_KEY=op://Development/OpenAI/api key
SLACK_WEBHOOK=op://Development/Slack Webhook/url
ANTHROPIC_API_KEY=op://Development/Anthropic/api key

Without 1Password (fallback)

If op is unavailable, fall back to env vars (warn the user):

# Check if op is available
if command -v op &>/dev/null; then
  TOKEN=$(op read "op://Development/GitHub PAT/credential")
else
  echo "⚠ 1Password CLI not available — using env var fallback"
  TOKEN="${GITHUB_TOKEN:?GITHUB_TOKEN not set}"
fi

Response Handling

Parse JSON responses

# Pipe to jq for extraction
curl -s ... | jq '.data[] | {id, name}'

# Pretty print
curl -s ... | jq .

# Extract single field
curl -s ... | jq -r '.access_token'

Validate responses

# Check HTTP status
response=$(curl -s -w '\n%{http_code}' ...)
http_code=$(echo "$response" | tail -1)
body=$(echo "$response" | sed '$d')

if [ "$http_code" -ge 400 ]; then
  echo "Error $http_code: $body"
fi

Chained Requests

For multi-step flows (auth → use token → process):

# Step 1: Get auth token
TOKEN=$(curl -s -X POST \
  -d "grant_type=client_credentials" \
  -d "client_id=$(op read 'op://Dev/OAuth App/client_id')" \
  -d "client_secret=$(op read 'op://Dev/OAuth App/client_secret')" \
  "https://auth.example.com/token" | jq -r '.access_token')

# Step 2: Use token
curl -s -H "Authorization: Bearer $TOKEN" \
  "https://api.example.com/protected/resource"

Request History

Log requests to ~/.config/ask-curl/history.jsonl for replay:

# Append to history (sanitized — no secrets)
echo '{"ts":"'$(date -u +%Y-%m-%dT%H:%M:%SZ)'","method":"GET","url":"https://api.example.com/user","status":200}' \
  >> ~/.config/ask-curl/history.jsonl

# Replay last request
tail -1 ~/.config/ask-curl/history.jsonl | jq -r '.curl_command'

Safety Rules

1. NEVER echo, log, or display secrets — use op read inline or op run
2. NEVER write tokens to files — use op:// references in env files
3. Always confirm before POST/PUT/PATCH/DELETE — show the command first, ask to proceed
4. Sanitize history — strip Authorization headers and tokens before logging
5. Timeout all requests — --max-time 30 minimum
6. Warn on non-HTTPS — flag any http:// URL (except localhost)