https://github.com/stephenbyrne99/ncurl
curl in natural language
https://github.com/stephenbyrne99/ncurl
cli curl go
Last synced: 13 days ago
JSON representation
curl in natural language
- Host: GitHub
- URL: https://github.com/stephenbyrne99/ncurl
- Owner: stephenbyrne99
- License: mit
- Created: 2025-04-30T21:14:10.000Z (24 days ago)
- Default Branch: main
- Last Pushed: 2025-05-07T10:42:49.000Z (18 days ago)
- Last Synced: 2025-05-07T11:35:46.515Z (18 days ago)
- Topics: cli, curl, go
- Language: Go
- Homepage:
- Size: 10.3 MB
- Stars: 4
- Watchers: 2
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
Awesome Lists containing this project
README
# ncurl – cURL in natural language
[](https://github.com/stephenbyrne99/ncurl/actions/workflows/ci.yml)
[](https://pkg.go.dev/github.com/stephenbyrne99/ncurl)
`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 npm
```bash
npm install -g @stephen_byrne_/ncurl
```
### Option 2: Using Go Install
```bash
go install github.com/stephenbyrne99/ncurl@latest
```
This will download the pre-built binary for your platform.
### Option 3: Building from Source
```bash
# 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):**
```bash
echo 'export ANTHROPIC_API_KEY="your-key-here"' >> ~/.bashrc
source ~/.bashrc
```
**For Zsh users (.zshrc):**
```bash
echo 'export ANTHROPIC_API_KEY="your-key-here"' >> ~/.zshrc
source ~/.zshrc
```
**For Fish users (config.fish):**
```bash
echo 'set -x ANTHROPIC_API_KEY "your-key-here"' >> ~/.config/fish/config.fish
source ~/.config/fish/config.fish
```
**For PowerShell users:**
```powershell
[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
```bash
# 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 ` | Set timeout in seconds (default: 30) |
| `-m ` | 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 ` | Search command history |
| `-rerun ` | Rerun the nth command in history |
| `-i` | Interactive history selection |
| `-version` | Show version information |
Check the [usage documentation](docs/usage.md) 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:
```bash
# 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](docs/evaluations.md) 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](CONTRIBUTING.md) 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