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.
- 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
npm install -g @stephen_byrne_/ncurlgo install github.com/stephenbyrne99/ncurl@latestThis will download the pre-built binary for your platform.
# Clone the repository
git clone https://github.com/stephenbyrne99/ncurl.git
cd ncurl
# Build using the installation script
./scripts/install.shThe 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.
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 ~/.bashrcFor Zsh users (.zshrc):
echo 'export ANTHROPIC_API_KEY="your-key-here"' >> ~/.zshrc
source ~/.zshrcFor Fish users (config.fish):
echo 'set -x ANTHROPIC_API_KEY "your-key-here"' >> ~/.config/fish/config.fish
source ~/.config/fish/config.fishFor 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/.
# 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'| 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.
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.mdSee the evaluations documentation for more information about creating custom test cases and extending the framework.
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
Contributions are welcome! Please check out the contributing guidelines for more information.
- Fork & clone, then run
go vet ./...before opening a PR. - Keep commits small and descriptive.
- All checks must pass before merge.
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.
MIT © 2025 Stephen Byrne