ask-curl

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"