`jq -r` Is the Flag That Makes JSON Output Actually Usable in Shell Pipelines Instead of Fighting You With Quotes

Why this command matters: one of the fastest ways to make a shell pipeline annoying is to extract a JSON string with jq and then discover it still has JSON quotes wrapped around it when you wanted plain text.

What jq -r does

The jq manual describes --raw-output or -r as writing string results directly to standard output rather than formatting them as JSON strings with quotes.

A simple example:

echo '{"name":"api"}' | jq -r '.name'

Without -r, jq would output:

"api"

With -r, it outputs:

api

That tiny difference is exactly why the flag matters so much in shell work.

Why default jq output is often the wrong shape for scripts

Default jq output is correct JSON. That is great if the next consumer is another JSON-aware tool. It is awkward if the next consumer is:

1. xargs
2. export
3. sed
4. a shell variable
5. another CLI expecting plain text

Developers then waste time trimming quotes, calling tr -d '"', or writing brittle post-processing that should never have been needed.

jq -r exists so you can ask for the right output shape immediately.

Practical examples

Extract a tag from an API response:

tag=$(curl -s https://example.com/version.json | jq -r '.tag')

Print URLs one per line for another tool:

jq -r '.items[].url' response.json

These are exactly the situations where raw string output is more useful than valid JSON string notation.

The important limitation

The jq manual is precise here: -r affects string results. If your filter returns objects or arrays, jq will still print JSON for those values.

That means -r is not “make everything plain text.” It is “when the filter result is a string, emit the raw string.”

That distinction matters because some developers expect -r to magically flatten structured data. It does not.

If your output is still structured, you need a different filter, not just a different flag.

Why this makes shell scripts cleaner

Shell pipelines become easier to reason about when tools exchange values in the shapes they actually need.

Using jq -r helps avoid:

1. accidental embedded quotes in variables
2. malformed URLs passed to curl
3. ugly string cleanup after extraction
4. subtle bugs in conditional comparisons

This is one of those tiny flags that improves reliability because it removes needless transformation steps.

Less glue code usually means fewer shell bugs.

Related flags worth knowing

The jq manual also documents related output options:

1. -j for join output without a newline
2. --raw-output0 for NUL-terminated raw output
3. -c for compact JSON

These matter when the shell boundary gets trickier. But for normal text extraction, -r is the default flag most people should remember first.

The mental model to keep

Think of jq in two modes:

1. JSON in, JSON out
2. JSON in, plain strings out

Default jq is excellent at the first. -r is what makes the second mode ergonomic.

That mental model helps you decide quickly whether the next step in your pipeline expects structured data or plain text.

Final recommendation

Whenever you are using jq to extract a string for use in shell scripts or other plain-text-oriented tools, reach for -r early. It is one of the simplest ways to make JSON pipelines less awkward and much more reliable.

Sources

• jq manual