(2025-07-28) Two popular external commands can make you a shell REST API king
-----------------------------------------------------------------------------
There exists a widespread myth that you need at least Python or some other
full-featured programming environment to interact with modern REST APIs of
various online services. In fact though, if you are running a normal OS like
Linux or BSD, you only need two external commands available in any
distribution's package manager. Everything else is already there in the
POSIX environment, and I'm going to show you how to make use of it.
The first of these two commands is, of course, curl. This is the Swiss army
knife of clients that does pretty much all the legwork for you when it comes
to connection through all sorts of different protocols (up to the newest
HTTP versions, WebSockets (need to research that more though) and even
Gopher, yeah), all you need is specify what to send and (optionally) which
parts of the response to return. The only things curl can't do (_yet_) are
torrenting and parallel chunk downloads (well, you've got aria2 for those
things) but those are not relevant to our API story anyway. The mainstream
has adopted curl so much that all sorts of API manuals even show its
command-line calls alongside Python, JS and other languages in their example
sections. That's quite a success story, I must admit.
Sending requests and receiving responses, however, is just one half of the
story. The other one is preparing those requests and processing those
responses. Of course, the GET request fields, as well as standard HTTP form
fields, can be handled with curl itself, but how do we deal with the other
data types? Given that the de facto standard of POSTing and responses for
modern HTTP APIs is JSON, only one command-line program comes to the rescue,
one that's much younger than curl but no less important: jq. Yep, that's the
second tool in our today's box. Again, there is a common misconception that
jq only can parse JSON text, but in fact, it also can serialize various data
into JSON too. It even has a small sublanguage to perform variable
subsitution in the required places while it fully handles all the escaping
for you. And I'm gonna show how we can make use of it... right now.
So, how to showcase the possibilities of this sh+curl+jq wombo-combo in the
most succint way possible? For once, let's ride the hype wave and create the
simplest possible chat client for OpenAI-compatible API endpoints. Because
yeah, there are plenty of them, even Ollama exposes one if you must. For
this example, I'm gonna hardcode everything and assume a lot has been set
already, but will include the link to the full chat script ([1]) in the
footer. Without further ado, here's the example in POSIX shell:
#!/bin/sh
hist=''
inithist=''
API_ROOT='
https://text.pollinations.ai/openai'
MODEL='openai-fast'
TEMP=0.6
prompt() { printf "\e[1;32m>> \e[0m"; }
clearhist() { hist="$inithist"; }
startswith() { case $1 in "$2"*) true;; *) false;; esac; }
setsys() {
inithist="$(jq -nc --arg sp "$*" '[{role:"system",content:$sp}]')"
clearhist
}
setsys 'You are a helpful assistant.'
while prompt && read -r line; do
[ -z "$line" ] && continue
[ "$line" == "/clear" ] && clearhist && echo "Session cleared" && continue
hist="$(jq -nc --argjson h "$hist" --arg msg "$line" \
'$h+[{"role":"user","content":$msg}]')"
data="$(jq -nc --arg m "$MODEL" --arg t "$TEMP" --argjson msgs "$hist" \
'{model:$m,stream:true,private:true,messages:$msgs,temperature:$t}')"
curl -sSLN "${API_ROOT}/chat/completions" \
-H "Content-Type: application/json" \
${OPENAI_API_KEY:+-H "Authorization: Bearer $OPENAI_API_KEY"} \
-H "Accept: text/event-stream" --data-raw "$data" 2>/dev/null | \
while IFS= read -r chunk; do
[ -z "$chunk" ] && continue
data="${chunk#data: }"
[ "$data" == "[DONE]" ] && break
delta=''
startswith "$data" '{' && delta="$(printf '%s' "$data" \
| jq -rj '.choices[0].delta.content // empty' 2>/dev/null;printf x)"
delta="${delta%?}"
[ -n "$delta" ] && printf "\e[0;33m%s\e[0m" "$delta"
tailbuf="$tailbuf$delta"
done
echo
hist="$(jq -nc --argjson h "$hist" --arg a "$tailbuf" \
'$h+[{"role":"assistant","content":$a}]')"
tailbuf=""
line=''
done
This example chat script uses the "openai-fast" (GPT 4.1 Nano) model from the
pollinations.ai provider (more famously known for its free image generation
service). Of course, the full shee.sh script has a lot more going on but
this example also is pretty self-sufficient and shows everything that needs
to be shown:
- terminal escape sequences;
- pure POSIX startswith function implementation;
- shaping complex JSON objects with jq -nc;
- parsing complex JSON objects with jq -rj;
- specifying optional command parameters based on environment variable
presence;
- preserving trailing newlines by appending another character and then
chopping it off;
- passing SSE response stream from curl for line-by-line shell processing.
Mind you, this is a pretty complicated case, most APIs won't even have a
thing or two shown here. For instance, not everyone uses SSE, let alone SSE
with JSON response chunks, not everyone needs to maintain JSON state across
calls, not everyone needs to make authorization tokens optional and
dependent upon the environment. But this example combines all those
techniques for you to make use of them whenever you find them necessary.
And, at the end of the day, this is just an LLM chat app written in POSIX
shell with no external dependencies except curl and jq. Why? Because we can.
--- Luxferre ---
[1]:
gopher://hoi.st/9/files/shee.sh
