jello(1)

💖 jello — the manual page, bestie edition 💖

okay so welcome to jello, aka the JSON filter that's giving main character energy ✨ (manual name's jello, section 1, iykyk 🎀)

---

🌸 NAME 🌸

Jello — filter JSON and JSON Lines data with Python syntax. that's it, that's the whole vibe 💅

---

✨ SYNOPSIS ✨

okay so jello is basically jq's cooler cousin 🫶 — it processes JSON and JSON Lines data too, except it lets you use standard python dict and list syntax instead of whatever jq is doing. no cap.

JSON or JSON Lines can be piped straight into jello (and lowkey, JSON Lines get automatically slurped into a list of dictionaries 🦋) and then they're available to you as the variable _. iconic.

Processed data can be output as:

• JSON
• JSON Lines
• bash array lines
• or a grep-able schema 👑

---

💜 USAGE 💜

cat data.json | jello [OPTIONS] [QUERY | -q <query_file>]

jello [OPTIONS] [QUERY | -q <query_file>] [-f <input_files>]

QUERY is optional and can be, like, most any valid python code. alternatively, you can specify a query file with -q to load the query from a file 📄.

inside the query, _ is the sanitized JSON from STDIN or the input file(s) you specified with -f, presented as a python dict or a list of dicts. periodt.

if QUERY or a query file is omitted, then the original JSON input just gets pretty printed. no drama, no fuss 🌈.

you can use dot notation or traditional python bracket notation to access key names:

Note: reserved key names that can't be accessed using dot notation can still be accessed via standard python dictionary notation. (e.g. _.foo["get"] instead of _.foo.get)

a simple query, as a lil treat:

$ cat data.json | jello _.foo

or

$ cat data.json | jello '_["foo"]'

or

$ jello _.foo -f data.json

---

🎀 Options 🎀

every single one, bestie, we're not skipping a single flag 🔥

• -c — compact print JSON output instead of pretty printing
• -C — force color output even when using pipes (overrides -m and the NO_COLOR env variable)
• -e — empty data (don't process data from STDIN or file)
• -f — load input data from JSON file or JSON Lines files (must be the final option, if used ⚠️)
• -i — initialize environment with a custom config file
• -l — lines output (suitable for bash array assignment)
• -m — monochrome output
• -n — print selected null values
• -q — load query from a file
• -r — raw output of selected strings (no quotes)
• -R — raw string input (don't auto convert input to dict/list)
• -s — print the JSON schema in grep-able format
• -t — print type annotations in schema view
• -h — help
• -v — version info

---

🌼 Simple Examples 🌼

no options passed? jello simply pretty prints the JSON. a little gift to you 🎁

$ echo '{"foo":"bar","baz":[1,2,3]}' | jello
{
  "foo": "bar",
  "baz": [
    1,
    2,
    3
  ]
}

prefer compact output? use the -c option, she's efficient like that 💅

$ echo '{"foo":"bar","baz":[1,2,3]}' | jello -c
{"foo":"bar","baz":[1,2,3]}

use the -l option to convert lists/arrays into lines:

$ echo '{"foo":"bar","baz":[1,2,3]}' | jello -l _.baz
1
2
3

the -l option also lets you create JSON Lines ✨:

$ echo '[{"foo":"bar","baz":[1,2,3]},{"fiz":"boo","buz":[4,5,6]}]' | jello -l
{"foo":"bar","baz":[1,2,3]}
{"fiz":"boo","buz":[4,5,6]}

you can print a grep-able schema using the -s option 👑:

$ echo '{"foo":"bar","baz":[1,2,3]}' | jello -s
_ = {};
_.foo = "bar";
_.baz = [];
_.baz[0] = 1;
_.baz[1] = 2;
_.baz[2] = 3;

---

🦋 Assigning Results to a Bash Array 🦋

use the -l option to print JSON array output in a manner suitable to be assigned to a bash array. the -r option can be used to remove quotation marks around strings. if you want null values to be printed as null, use the -n option — otherwise they get printed as blank lines 🙈.

bash variable:

variable=($(cat data.json | jello -rl _.foo))

bash array variable:

variable=()
while read -r value; do
    variable+=("$value")
done < <(cat data.json | jello -rl _.foo)

---

💖 Examples 💖

⭐ Printing the Grep-able Schema ⭐

$ jc -a | jello -s
_ = {};
_.name = "jc";
_.version = "1.17.2";
_.description = "JSON CLI output utility";
_.author = "Kelly Brazil";
_.author_email = "kellyjonbrazil@gmail.com";
_.website = "https://github.com/kellyjonbrazil/jc";
_.copyright = "(C) 2019-2021 Kelly Brazil";
_.license = "MIT License";
_.parser_count = 80;
_.parsers = [];
...

⭐ Printing the Grep-able Schema with Type Annotations ⭐

$ jc -a | jello -st
_ = {};                                               //  (object)
_.name = "jc";                                        //  (string)
_.version = "1.17.2";                                 //  (string)
_.description = "JSON CLI output utility";            //  (string)
_.author = "Kelly Brazil";                            //  (string)
_.author_email = "kellyjonbrazil@gmail.com";          //  (string)
_.website = "https://github.com/kellyjonbrazil/jc";   //  (string)
_.copyright = "(C) 2019-2021 Kelly Brazil";           //  (string)
_.license = "MIT License";                            //  (string)
_.parser_count = 80;                                  //  (number)
_.parsers = [];                                       //   (array)
...

⭐ Printing the JSON Structure ⭐

$ jc dig example.com | jello -st | grep '(object)\|(array)'
_ = [];                                               //   (array)
_[0] = {};                                            //  (object)
_[0].flags = [];                                      //  (array)
_[0].opt_pseudosection = {};                          //  (object)
_[0].opt_pseudosection.edns = {};                     //  (object)
_[0].opt_pseudosection.edns.flags = [];               //   (array)
_[0].question = {};                                   //  (object)
_[0].answer = [];                                     //  (array)
_[0].answer[0] = {};                                  //  (object)
...

⭐ Lambda Functions and Math ⭐

look at her doing math, she's so smart 😭

$ echo '{"t1":-30, "t2":-20, "t3":-10, "t4":0}' | jello '\
keys = _.keys()
vals = _.values()
cel = list(map(lambda x: (float(5)/9)*(x-32), vals))
dict(zip(keys, cel))'
{
  "t1": -34.44444444444444,
  "t2": -28.88888888888889,
  "t3": -23.333333333333336,
  "t4": -17.77777777777778
}

$ jc -a | jello 'len([entry for entry in _.parsers if "darwin" in entry.compatible])'
45

⭐ For Loops ⭐

output as JSON array:

$ jc -a | jello '\
result = []
for entry in _.parsers:
  if "darwin" in entry.compatible:
    result.append(entry.name)
result'
[
  "airport",
  "airport_s",
  "arp",
  "crontab",
  "crontab_u",
  ...
]

output as bash array:

$ jc -a | jello -rl '\
result = []
for entry in _.parsers:
  if "darwin" in entry.compatible:
    result.append(entry.name)
result'
airport
airport_s
arp
crontab
crontab_u
...

⭐ List and Dictionary Comprehension ⭐

output as JSON array:

$ jc -a | jello '[entry.name for entry in _.parsers if "darwin" in entry.compatible]'
[
  "airport",
  "airport_s",
  "arp",
  "crontab",
  "crontab_u",
  ...
]

output as bash array:

$ jc -a | jello -rl '[entry.name for entry in _.parsers if "darwin" in entry.compatible]'
airport
airport_s
arp
crontab
crontab_u
...

⭐ Environment Variables ⭐

$ echo '{"login_name": "joeuser"}' | jello '\
True if os.getenv("LOGNAME") == _.login_name else False'
true

⭐ Using 3rd Party Modules ⭐

you can import and use your favorite modules to manipulate the data, no gatekeeping here 🫶. for example, using glom:

$ jc -a | jello '\
from glom import *
glom(_, ("parsers", ["name"]))'
[
  "airport",
  "airport_s",
  "arp",
  "blkid",
  "crontab",
  "crontab_u",
  "csv",
  ...
]

⭐ Non-JSON Data Input (YAML, CSV, etc.) ⭐

you can work with other types of data with the -R (raw string input) option 🌈. for example, if you would like to read in YAML data you can load the data as a raw string, import the yaml library, and load the string data into _ with the yaml library:

$ cat values.yaml
var1: value1
var2: value2
var3: value3

$ jello -Rr '
import yaml
_ = yaml.safe_load(_)
_["var2"]
' -f values.yaml

value2

Note: dot notation is not supported with the -R option unless the library used to convert the raw string supports this. (e.g. python-benedict)

---

...and that's part 1, bestie — there's more coming, don't go anywhere 💜

💖 ADVANCED USAGE 💖

Okay bestie, this is where it gets fun. Like, main character energy for your JSON. Buckle up. 🎀

🌸 Custom Configuration File

You can use the -i option to initialize the jello environment with your own configuration file. And when I say your own, I mean it — this file accepts valid python code where you can enable/disable jello options, customize your colors, add import statements for your favorite modules, and define your own functions. It's giving "build your own adventure" but for JSON filtering. ✨

The file must be named .jelloconf.py and must be located in the proper directory based on the OS platform:

• Linux, unix, macOS: ~/
• Windows: %appdata%/

Do not skip the filename or the location, bestie. It literally will not get found and then you'll be sad. 😭

---

🦋 Setting Options

To set jello options in the .jelloconf.py file, import the jello.lib.opts class, add any of the following and set to True or False:

from jello.lib import opts
opts.mono = True            # -m option
opts.compact = True         # -c option
opts.empty = True           # -e option
opts.lines = True           # -l option
opts.raw = True             # -r option
opts.raw_input = True       # -R option
opts.force_color = True     # -C option
opts.nulls = True           # -n option
opts.schema = True          # -s option
opts.types = True           # -t option

Look at that little mapping. Every flag from the options list, right there, ready to be your default. Iconic behavior honestly. 💅

---

💅 Setting Colors

You can customize the colors by importing the jello.lib.opts class and setting the following variables to one of the following string values: black, red, green, yellow, blue, magenta, cyan, gray, brightblack, brightred, brightgreen, brightyellow, brightblue, brightmagenta, brightcyan, or white.

from jello.lib import opts
opts.keyname_color = 'blue'            # Key names
opts.keyword_color = 'brightblack'     # true, false, null
opts.number_color = 'magenta'          # integers, floats
opts.string_color = 'green'            # strings

Note: Any colors set via the JELLO_COLORS environment variable will take precedence over any color values set in the .jelloconf.py configuration file

So like… the env var is the loud friend who talks over you. Respect it. 🙈

---

🧚 Importing Modules

To import a module (e.g. glom) during initialization, just add the import statement to your .jelloconf.py file:

from glom import *

Then you can use glom in your jello filters without importing:

$ jc -a | jello -i 'glom(_, "parsers.25.name")'
"lsblk"

No import in the one-liner, no cap. The conf file already handled it. So convenient. 🌈

---

⭐ Adding Functions

You can also add functions to your initialization file. For example, you could simplify glom use by adding the following function to .jelloconf.py:

def g(query):
    import glom
    return glom.glom(_, query)

Then you can use the following syntax to filter the JSON data:

$ jc -a | jello -i 'g("parsers.6.compatible")'
[
  "linux",
  "darwin",
  "cygwin",
  "win32",
  "aix",
  "freebsd"
]

Or create names for commonly used queries:

def darwin_compatible():
    result = []
    for entry in _.parsers:
      if "darwin" in entry.compatible:
        result.append(entry.name)
    return result

Then use the predefined query like so:

$ jc -a | jello -i 'darwin_compatible()'
[
  "airport",
  "airport-s",
  "arp"
]

Not you writing your own little reusable query library. That's highkey genius behavior. 👑

---

🍓 Setting Custom Colors via Environment Variable

In addition to setting custom colors in the .jelloconf.py initialization file, you can also set them via the JELLO_COLORS environment variable. Any colors set in the environment variable will take precedence over any colors set in the initialization file.

The JELLO_COLORS environment variable takes four comma separated string values in the following format:

JELLO_COLORS=<keyname_color>,<keyword_color>,<number_color>,<string_color>

Where colors are: black, red, green, yellow, blue, magenta, cyan, gray, brightblack, brightred, brightgreen, brightyellow, brightblue, brightmagenta, brightcyan, white, or default

For example, to set to the default colors:

JELLO_COLORS=blue,brightblack,magenta,green

or

JELLO_COLORS=default,default,default,default

Four slots, four colors, in that exact order: key names, keywords, numbers, strings. Do not shuffle them, bestie, or your output is gonna look cursed. 💀

---

💜 Disable Colors via Environment Variable

You can set the NO_COLOR environment variable to any value to disable color output in jello. Note that using the -C option to force color output will override both the NO_COLOR environment variable and the -m option.

So like, -C is the strongest vibe in the room. It wins. Periodt. 💅

---

🫶 AUTHOR 🫶

Kelly Brazil (kellyjonbrazil@gmail.com)

https://github.com/kellyjonbrazil/jello

Shoutout to the author, fr fr. Absolute legend for building this. 🌸

---

💖 COPYRIGHT 💖

Copyright (c) 2020-2025 Kelly Brazil

License: MIT License

---

And that's the whole page, bestie! 🎀 This is jello(1), version 1.6.1, dated 2025-05-29 — go filter some JSON and slay. ✨