ncurl – cURL in natural language

ncurl lets you describe HTTP requests in plain language. It uses Anthropic's Claude to translate your description into a fully-specified request, executes it, and returns the results.

WARNING: Pure vibe coded to test claude code vs codex - not production ready.

✨ Features

• Natural Language Interface: Describe API requests however you want
• Command History: Save, search, and rerun previous commands
• Response Handling: Well-formatted output for both text and binary responses
• Evaluation Framework: Test and validate natural language interpretation accuracy
• JSON Mode: Output only response bodies for easy piping
• Verbose Mode: See the full request details
• Cross-Platform: Works on macOS, Linux, and Windows

Quick install

Option 1: Using Go Install

go install github.com/stephenbyrne99/ncurl@latest

Option 2: Using npm

npm install -g @stephen_byrne_/ncurl

This will download the pre-built binary for your platform.

Option 3: Building from Source

# Clone the repository
git clone https://github.com/stephenbyrne99/ncurl.git
cd ncurl

# Build using the installation script
./scripts/install.sh

The script will build from source and install to ~/.local/bin (or ~/bin if .local/bin doesn't exist). If needed, it will also provide instructions to add the installation directory to your PATH.

Setting Up Your API Key

Prerequisite: You need an Anthropic API key to use ncurl.

Add your API key to your shell's configuration file:

For Bash users (.bashrc):

echo 'export ANTHROPIC_API_KEY="your-key-here"' >> ~/.bashrc
source ~/.bashrc

For Zsh users (.zshrc):

echo 'export ANTHROPIC_API_KEY="your-key-here"' >> ~/.zshrc
source ~/.zshrc

For Fish users (config.fish):

echo 'set -x ANTHROPIC_API_KEY "your-key-here"' >> ~/.config/fish/config.fish
source ~/.config/fish/config.fish

For PowerShell users:

[Environment]::SetEnvironmentVariable("ANTHROPIC_API_KEY", "your-key-here", "User")

Replace "your-key-here" with your actual Anthropic API key from https://console.anthropic.com/.

🚀 Quick Start

# Simple GET
ncurl "download https://httpbin.org/get"

# POST with JSON and a shorter timeout
ncurl -t 10 "POST to httpbin with a name field being hello"

# Use command history
ncurl -history

# Pipe prettified JSON through jq
ncurl "get github stephenbyrne99 ncurl repo" | jq '.body | fromjson | .stargazers_count'

📋 Command Options

| Option | Description | |--------|-------------| | -t <seconds> | Set timeout in seconds (default: 30) | | -m <model> | Specify Anthropic model to use (default: claude-3-7-sonnet) | | -j | Output response body as JSON only | | -v | Verbose output (include request details) | | -history | View command history | | -search <term> | Search command history | | -rerun <n> | Rerun the nth command in history | | -i | Interactive history selection | | -version | Show version information |

Check the usage documentation for more detailed examples.

📊 Evaluation Framework

ncurl includes a comprehensive evaluation system to test the accuracy of its natural language interpretation. Use the ncurl-eval utility to run test cases and measure performance:

# Build the evaluation tool
go build -o ncurl-eval ./cmd/ncurl-eval

# Run all built-in test cases
./ncurl-eval

# Save results to a file
./ncurl-eval -output results.md

See the evaluations documentation for more information about creating custom test cases and extending the framework.

🗂️ Project Structure

ncurl/
├── cmd/
│   ├── ncurl/          # CLI entry-point
│   └── ncurl-eval/     # Evaluation tool
├── internal/
│   ├── httpx/          # Request struct + executor
│   ├── llm/            # Anthropic wrapper
│   ├── history/        # Command history management
│   └── evals/          # Evaluation framework
├── docs/               # Documentation
├── go.mod              # Go module definition
└── README.md

🤝 Contributing

Contributions are welcome! Please check out the contributing guidelines for more information.

1. Fork & clone, then run go vet ./... before opening a PR.
2. Keep commits small and descriptive.
3. All checks must pass before merge.

Why?

I wanted to square off codex vs claude code on building something I would find mildly useful, and have them get it to a complete + production level with as little input as possible.

📝 License

MIT © 2025 Stephen Byrne