OnlyCLI vs curl vs HTTPie: When to Use What

4 min read

Developers have no shortage of ways to hit HTTP APIs. curl ships everywhere. HTTPie optimizes for readability. OnlyCLI generates API-specific CLIs from OpenAPI. This post maps the trade-offs and shows the same GitHub REST call three ways so you can choose the right tool per task.

The guiding question is not “which tool is best?” but which layer you want to maintain: raw HTTP strings, ergonomic HTTP syntax, or commands that track your API contract as it evolves.

The Landscape of API Tools

At a high level:

  • curl — Universal HTTP client; you specify method, URL, and headers manually.
  • HTTPie — Human-friendly syntax and defaults; still generic across APIs.
  • OnlyCLI — Typed commands derived from your spec: paths become flags, tags become subcommand groups, descriptions become --help.

None replaces the others entirely. The question is which layer you want to work in: raw HTTP, ergonomic HTTP, or contract-shaped commands.

curl: Universal but Verbose

curl is the lingua franca of scripts and stack overflow answers. It can do anything HTTP supports—TLS options, custom verbs, multipart, proxies—but you carry the contract in your head.

To fetch a public repository with a bearer token:

curl -sS -H "Authorization: Bearer $TOKEN" \
  -H "Accept: application/vnd.github+json" \
  "https://api.github.com/repos/octocat/Hello-World"

Strengths:

  • Available on virtually every CI image and server.
  • Precise control over every header and option.
  • Easy to embed in any language that can spawn a process.

Weaknesses:

  • Verbose for complex query strings and JSON bodies.
  • No built-in knowledge of which endpoints exist or required parameters.
  • Typos in URLs or header names fail at runtime, not “compile” time.

HTTPie: User-Friendly but Generic

HTTPie (http / https CLI) reduces friction: JSON bodies, sessions, and syntax sugar for headers and query params.

http GET https://api.github.com/repos/octocat/Hello-World \
  Authorization:"Bearer $TOKEN" \
  Accept:application/vnd.github+json

Strengths:

  • Readable invocations for ad hoc debugging.
  • Pleasant defaults for JSON APIs.
  • Good fit when you do not have an OpenAPI spec or you hop between unrelated APIs hourly.

Weaknesses:

  • Still generic: you must read docs to remember path shape and parameters.
  • Complex GitHub operations (pagination, previews, nested resources) accumulate flags and copied JSON.

OnlyCLI: API-Specific and Self-Documenting

OnlyCLI turns OpenAPI into a Go CLI. After generation and go build, the same repository lookup becomes:

./github repos get --owner octocat --repo Hello-World

The binary applies the correct path, adds standard headers your template encodes, and serializes --data for writes. ./github repos get --help lists exactly the flags that operation accepts—because they came from the spec.

Strengths:

  • Discoverability for humans and agents (--help, SKILL.md).
  • Consistency across dozens of endpoints from one generator.
  • Output pipelines (--format, transforms, templates) shared across commands.

Weaknesses:

  • Requires a maintained OpenAPI document and a regenerate step when the API changes.
  • Overkill for a one-off request to a random third-party site.

Side-by-Side: One GitHub REST Call

Below, TOKEN holds a PAT or OAuth token with appropriate scopes.

# curl — full URL and headers explicit
curl -sS -H "Authorization: Bearer $TOKEN" \
  -H "Accept: application/vnd.github+json" \
  "https://api.github.com/repos/octocat/Hello-World"

# HTTPie — same semantics, lighter syntax
http GET https://api.github.com/repos/octocat/Hello-World \
  Authorization:"Bearer $TOKEN" \
  Accept:application/vnd.github+json

# OnlyCLI-generated CLI — contract encoded in flags
./github repos get --owner octocat --repo Hello-World

All three return JSON (modulo formatting). Only the third names owner and repo the way the OpenAPI parameters do—reducing mental mapping from documentation to invocation.

Feature Comparison Table

Capability curl HTTPie OnlyCLI-generated CLI
Ships / installs trivially on servers Excellent Good Binary you distribute
Learn curve for new API Steep Medium Low (per generated CLI)
Contract awareness None None From OpenAPI
Scripting in bash Excellent Good Excellent
Custom headers / odd HTTP Excellent Good Depends on generator options
Pagination helpers Manual Manual Often built into runtime
Agent-friendly discovery Poor Poor Strong (SKILL.md, help)

When to Use Each

  • curl — CI probes, minimal containers, odd protocols, copy-paste portability.
  • HTTPie — Exploratory debugging across many unrelated hosts in one afternoon.
  • OnlyCLI — Repeated work against one or few APIs with a real spec: internal platforms, partner integrations, GitHub-scale ecosystems.

Combining Tools

Choice is not exclusive. A common pattern:

./github search repos --q 'language:go stars:>1000' --format json | jq '.items[].full_name'

Use the generated CLI for known operations and jq, curl, or HTTPie for one-offs—or to hit endpoints not yet in your subset spec. If you need raw bytes (binary releases, arbitrary MIME), curl still leads.

When your OpenAPI is incomplete or lagging

Real teams often ship partial OpenAPI, or generate a CLI from a filtered spec for faster builds. In that gap, curl and HTTPie remain the escape hatch: you can still call new beta routes while you wait for the spec to catch up. Regenerate the OnlyCLI project when the contract stabilizes so flags and help text snap back in line with the source of truth.

Errors, exit codes, and scripts

  • curl uses HTTP-level semantics; you typically add -f / --fail when you want nonzero exits on 4xx/5xx.
  • HTTPie prints readable errors; automation should still check exit status explicitly.
  • OnlyCLI-generated CLIs aim for nonzero exit on transport failures and unsuccessful HTTP status codes, with JSON error bodies on stderr where applicable—ideal for set -e shell pipelines.

Takeaway

curl maximizes portability. HTTPie maximizes human ergonomics for generic HTTP. OnlyCLI maximizes alignment with your API contract—fewer mistakes, faster onboarding, better automation. Pick the layer that matches how often you touch that API and whether you own the OpenAPI source of truth.

New to OnlyCLI? Start with Getting Started with OnlyCLI.