🌊 curly

Talk to APIs like a human. No more memorizing curl syntax. Curly is a natural language interface for curl. Type English, get working curl commands.

# Instead of this:
curl -X POST -H "Content-Type: application/json" -d '{"name":"John"}' https://api.example.com/users

# Just say this:
curly "create user John at api.example.com"

Why Curly?

Ever spent 10 minutes crafting the perfect curl command? Curly lets you describe what you want in plain English and handles the rest. It's like having a curl expert in your terminal.

🎯 Perfect for:

• Quick API testing without remembering flag syntax
• Teaching/Learning - see how natural language maps to curl
• Daily workflow - faster than looking up curl docs
• Safe production work - built-in warnings for dangerous operations

Installation

npm install -g curly-cli

That's it! No configuration needed for basic usage.

Usage

🚀 Instant Usage (No API Key Required)

Curly works out-of-the-box with direct mode:

# GET request
curly get api.github.com/users/github

# POST with JSON
curly post httpbin.org/post -d '{"hello": "world"}'

# Custom headers
curly get api.example.com -H "Authorization: Bearer $TOKEN"

🤖 Natural Language Mode (Optional)

Want to use plain English? Set up AI in 30 seconds:

# Interactive setup
curly init

# Or use environment variable
export OPENAI_API_KEY=sk-...  # Get from platform.openai.com

Now you can talk naturally:

# Simple requests
curly "get github user octocat"
curly "check if httpbin.org is up"

# Complex operations
curly "post a new todo saying 'buy milk' to jsonplaceholder.typicode.com"
curly "update user 123 at api.example.com with name Jane"
curly "delete all cookies from mysite.com with auth header"

# It understands context
curly "show me the headers from api.github.com"
curly "get the latest commits from facebook/react"

Real-World Examples

🧪 API Testing

# Test your local API
curly "post to localhost:3000/register with email [email protected] and password secret123"

# Check production health
curly "get health status from api.myapp.com"

# Debug webhooks
curly "send a test webhook to localhost:4000/webhook with event user.created"

🔐 Authentication

# Bearer tokens
curly "get my profile from api.example.com with bearer token"
# Reads from $TOKEN environment variable automatically

# API keys
curly "get weather for Seattle from weather-api.com with my api key"
# Reads from $API_KEY environment variable

# Basic auth
curly "get protected data from api.example.com with basic auth user:pass"

📊 Data Operations

# Upload JSON data
curly "send user data to api.example.com/users" < user.json

# Download files
curly "download logo from example.com/logo.png" > logo.png

# Bulk operations
curly "post each line as a user to api.example.com/bulk" < users.txt

🛠️ DevOps & Monitoring

# Check service status
curly "get metrics from prometheus:9090"

# Trigger deployments
curly "post to jenkins/job/deploy/build with token"

# Health checks
curly "check if all services are healthy at status.myapp.com"

Features at a Glance

| Feature | Description | |---------|-------------| | 🎯 Direct Mode | Works offline, no AI needed - curly get api.com | | 💬 Natural Language | Describe in English - curly "get users from api.com" | | 🛡️ Safety First | Warnings before dangerous operations (DELETE, production URLs) | | 🎨 Smart Defaults | Auto-detects JSON, adds headers, pretty-prints | | ⚡ Fast | Direct mode is instant, AI mode takes ~1 second | | 🔒 Secure | Never logs API keys, uses environment variables | | 📱 All HTTP Methods | GET, POST, PUT, PATCH, DELETE, HEAD, OPTIONS | | 🌐 Localhost Shortcuts | :3000 → http://localhost:3000 |

Command Reference

Direct Mode Syntax

curly <method> <url> [options]

Options:

• -d, --data <data> - HTTP body data
• -H, --header <header> - Custom header (repeatable)
• -X, --request <method> - HTTP method (alternative syntax)

Global Options:

• --dry - Preview command without executing
• --pretty - Pretty-print JSON responses
• --headers - Include response headers in output
• --stats - Show request statistics
• --verbose - Show detailed curl output

Natural Language Tips

Curly understands various ways to express the same intent:

# All of these work:
curly "get users from github"
curly "fetch github users"
curly "show me users on github.com"
curly "list all users from the github api"

# Be specific about the domain:
curly "get api.github.com/users"     # ✅ Clear
curly "get github users"              # ✅ Smart detection
curly "get users"                     # ❌ Too vague

Configuration

Quick Setup

# Option 1: Interactive setup (Recommended)
curly init

# Option 2: Environment variable
export OPENAI_API_KEY=sk-...

# Option 3: Config file (~/.curlyrc)
echo "OPENAI_API_KEY=sk-..." > ~/.curlyrc

Advanced Configuration

# Choose AI Provider (OpenAI or Anthropic)
AI_PROVIDER=openai              # or 'anthropic'

# API Keys
OPENAI_API_KEY=sk-...          # Get from platform.openai.com
ANTHROPIC_API_KEY=sk-ant-...   # Get from console.anthropic.com

# Models (optional)
OPENAI_MODEL=gpt-4o            # Default: gpt-4o-2024-11-20
ANTHROPIC_MODEL=claude-3-sonnet # Default: claude-3-5-sonnet-20241022

# Safety Level
SAFETY_LEVEL=normal            # strict, normal, or relaxed

Troubleshooting

"AI service unavailable"

# Check your setup
curly init

# Verify API key
echo $OPENAI_API_KEY

# Test direct mode (always works)
curly get httpbin.org/get

"Command not found"

# Ensure global installation
npm install -g curly-cli

# Or use npx
npx curly-cli get api.example.com

"Could not extract URL"

Be more specific about the domain:

# ❌ Too vague
curly "get users"

# ✅ Include domain
curly "get users from api.github.com"

Safety Features

Curly protects you from accidents:

# High-risk operations require confirmation
curly "delete all users from prod-api.company.com"
> ⚠️  Safety Check Required
> 🔴 DELETE operation will permanently remove data
> 🔴 Target appears to be a production environment
> Execute this command? (y/N)

# Dry run to preview
curly --dry "delete user 123"
> Command to execute:
> curl -X DELETE https://api.example.com/users/123

Comparison with curl

| Task | curl | curly | |------|------|-------| | Simple GET | curl https://api.com | curly get api.com | | POST JSON | curl -X POST -H "Content-Type: application/json" -d '{"key":"value"}' https://api.com | curly post api.com -d '{"key":"value"}' | | With auth | curl -H "Authorization: Bearer $TOKEN" https://api.com | curly get api.com -H "Authorization: Bearer $TOKEN" | | Natural language | ❌ Not supported | curly "get data from api.com with auth" | | Safety warnings | ❌ No protection | ✅ Warns before dangerous operations | | JSON detection | ❌ Manual headers | ✅ Automatic |

Contributing

We love contributions! See CONTRIBUTING.md for guidelines.

# Setup development environment
git clone https://github.com/josharsh/curly.git
cd curly
npm install
npm run dev

License

MIT © josharsh

Ready to simplify your API interactions?

npm install -g curly-cli

Report Bug · Request Feature · Documentation