DEV Community: Kengah Ireneaus

sysk a CLI health monitor in bash and python, how i built it

Kengah Ireneaus — Tue, 01 Sep 2026 17:55:18 +0000

Sysk architecture

Design notes on Sysk, a small system health monitor.

Intro

Sysk is a command-line system health monitor built in Bash and Python.

Bash collects machine data, handles flags, and drives the user interface. Python runs the inference and decision engines.

This article records the design of v1: what the system does, which decisions shaped it, and where those decisions cost something.

System design

The pipeline is four stages:

collect --> infer --> decide --> print

v1 collects data across five modules:

cpu
disk
memory
thermal
sound

Each module presented a different reading problem. The rest of the article follows the pipeline above.

1. Data collection (Bash)

Decision 1: read kernel files instead of running helper programs

The main collection decision was to read kernel-exported files rather than treat programs such as top or free as the source of truth.

Advantages

fewer extra binaries, so fewer runtime dependencies
one read model per module
data taken from the same place the kernel already exposes
no wait for a helper tool to start and format output

Disadvantages

you parse kernel-formatted text yourself
each file has its own layout, so the learning curve is steep

Files and directories used

/proc/meminfo          -> memory
/proc/cpuinfo          -> cpu identity
/proc/loadavg          -> load average
/proc/stat             -> cpu accounting
/proc/uptime           -> uptime

/sys/block             -> disks
/sys/class/thermal     -> thermal zones and cooling
/sys/class/hwmon       -> hardware monitors (fans, sensors)

This rule is not absolute. Hardware identity and sound did not fit it cleanly. dmidecode, smartctl, and pactl are still dependencies. Sound, in particular, is read through pactl rather than a kernel file.

Finding the right file for each module was messy. Once the path was known, the output looked cryptic at first glance, but it was stable enough to parse.

Decision 2: many scripts, one entry point

Reading files raised the next question: how should the project be structured?

Each major function became its own script, sourced from a single entry point. That was easy to say and immediately produced four portability questions:

How does the program find itself, no matter where it is launched from?
How do scripts share variables without hard-coding absolute paths?
In what order should scripts be sourced so that dependencies exist before they are used?
What does “runs on another machine” actually require?

Those questions produced the portable layout.

1. Resolve the application path

export SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd -P)"

This is the usual “where am I?” idiom. A pure string-manipulation version exists, but the cd / pwd -P form follows symlinks and is the one Sysk uses.

2. Export directory names from that root

export SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
export XDG_CONFIG_HOME=${XDG_CONFIG_HOME:-${SCRIPT_DIR}/.config}
export DUMPS_PATH=${DUMPS_PATH:-${SCRIPT_DIR}/logs}
export CACHE_PATH=${CACHE_PATH:-${SCRIPT_DIR}/.cache}
export CONFIG_DIR="$CACHE_PATH/sysk"
export ENGINE_DIR=${ENGINE_DIR:-${SCRIPT_DIR}/engine}
export RULE_DIR="$ENGINE_DIR/.rules"
export RESULT_DIR="$ENGINE_DIR/results"
export DATE="$(date +%Y_%m_%d)"

Defaults can be overridden by the environment. Paths are derived from SCRIPT_DIR instead of being pasted in as /home/kit/....

3. Source scripts in a fixed order

core -> device scripts -> hardware scripts

for script in "$CORE_DIR"/*.sh; do
    source "$script"
done

for dir in "$DEVICE_DIR"/*; do
    for script in "$dir"/*.sh; do
        source "$script"
    done
done

for script in "$HW_DIR"/*.sh; do
    source "$script"
done

Core files are numbered so the source order is obvious:

00_error.sh
01_privileged.sh
02_check_deps.sh
03_install_deps.sh
04_cleanup.sh
05_parse_flags.sh
tui.sh

00_error.sh — named error codes
01_privileged.sh — root / sudo handling
02_check_deps.sh — missing binaries
03_install_deps.sh — install those binaries
04_cleanup.sh — cleanup and traps
05_parse_flags.sh — getopts
tui.sh — text interface

Privileged work

Some reads (dmidecode, parts of disk data) need elevated permission. A one-line sudo "$@" was not enough. The questions were:

what if the user is already root?
what if sudo is missing?
what if the user refuses permission?
how do you drop sudo again after the privileged step?

01_privileged.sh answers those with small predicates:

is_root() {
    [[ $EUID -eq 0 ]] && return "$ERR_SUCCESS"
    return "$ERR_FAILURE"
}

is_sudo_available() {
    command -v sudo >/dev/null 2>&1 && return "$ERR_SUCCESS"
    return "$ERR_FAILURE"
}

is_sudo_active() {
    sudo -n true >/dev/null 2>&1 && return "$ERR_SUCCESS"
    return "$ERR_FAILURE"
}

kill_sudo() {
    is_sudo_active && {
        sudo -k
        return "$ERR_SUCCESS"
    }
    printf 'sudo not active, aborting...\n' >&2
    return "$ERR_BAD_USAGE"
}

Checking and installing dependencies

Even with a file-first design, Sysk still depends on a few programs: dmidecode, smartctl, pactl, and jq.

The flow is:

check dependencies -> get permission -> install missing ones

Store the required names in an array.
Run command -v on each name; keep the missing ones.
Ask for permission.
Detect the package manager and install the missing set.
Confirm the set is present.

declare -r PACKAGE_MANAGERS=(
    apt dnf pacman zypper emerge
)

os_pkg_manager=""

get_pkg_manager() {
    for pkg in "${PACKAGE_MANAGERS[@]}"; do
        if command -v "$pkg" >/dev/null 2>&1; then
            os_pkg_manager=$pkg
            return 0
        fi
    done
    printf 'unknown package manager, aborting...\n' >&2
    exit 1
}

Collection per module

Each module binds the files it cares about and hides the parsing behind a writer.

CPU

readonly CPU_INFO_FILE="/proc/cpuinfo"
readonly LOAD_INFO_FILE="/proc/loadavg"
readonly CPU_USAGE_FILE="/proc/stat"
readonly UPTIME_INFO_FILE="/proc/uptime"

Memory

readonly MEM_INFO_FILE="/proc/meminfo"

Disks

readonly DRIVE_DIR="/sys/block"

mapfile -t drives < <(
    find "$DRIVE_DIR"/* -maxdepth 1 -printf '%f\n' | grep -Ev '(^loop|ram|zram)'
)

Thermal

readonly SYSTEM_THERMAL_ZONE_PATH="/sys/class/thermal/thermal_zone"
readonly SYSTEM_FAN_INFO_PATH="/sys/class/hwmon"

Sound — collected through pactl, not /proc.

Storing collected data

Snapshots are JSON, written with jq and a per-module filter file:

write_memory_json() {
    local MEM_CONFIG="$CONFIG_DIR/memory_$DATE.json"
    mkdir -p "$CONFIG_DIR"

    jq -n \
        --arg total_mem "$(get_total_mem)" \
        --arg available_mem "$(get_available_mem)" \
        -f "$FEATURE_DIR/build_memory.jq" \
        > "$MEM_CONFIG"
}

Example thermal snapshot:

{
  "average_temp": 31.87,
  "thermal_zones": 3,
  "zone_temparatures": {
    "acpitz": "29.80",
    "x86_pkg_temp": "38.00"
  },
  "cooling": {
    "fan_zones": "2",
    "fan_speed": "fan1_input=\"0\"\nfan2_input=\"0\""
  }
}

Problem. The JSON shape is not the same across modules. Some values are scalars, some are objects, some are nested. That leaked into inference and into the rule files.

Fix for v1.

each module has its own rule file
each module has its own build_*.jq filter
a source field in the YAML tells the engine where to read
a resolve function walks that path

A uniform snapshot schema is still future work.

2. Inference and decision (Python)

Inference pipeline:

load data -> load rules -> set status per field -> write result

The engine is a Python script. It uses the standard library plus PyYAML, and it reads the same environment variables Bash exported (CACHE_PATH, RULE_DIR, RESULT_DIR, DATE).

Loading

def load_rules(rule_path: Path) -> dict:
    with rule_path.open(encoding="utf-8") as rule:
        return safe_load(rule)

def load_json(data_path: Path) -> Any:
    try:
        with data_path.open(encoding="utf-8") as data:
            return load(data)
    except (FileNotFoundError, OSError, JSONDecodeError) as err:
        print(f"[ERROR] failed to load {data_path}: {err}", file=sys.stderr)
        sys.exit(1)

Rules live in engine/.rules as YAML. Each field names the value it wants through source:

module: cpu
check_interval: 10
system_vars:
  cpu_cores: "auto"

fields:
  - name: cpu_usage_percent
    source: "usage"
    type: "percentage"
    base_value: 100
    warning_multiplier: 0.83
    critical_multiplier: 0.90
    unit: "%"

  - name: load_avg5
    source: "load_avg.1"
    type: "load"
    base_value: "cores"
    warning_multiplier: 1
    critical_multiplier: 1.5
    unit: ""

The collector JSON could not be renamed. The mapping therefore lives in the rules, not in a hard-coded Python dictionary.

Decision 3: a path language instead of one parser per module

source is a small path:

a bare key for a top-level field — usage
dots for nesting — core_info.cores_usage
an integer segment for a list index — load_avg.1

resolve walks that path:

def resolve(data: dict, source: str) -> Any:
    current = data
    for obj in source.split("."):
        if obj.isdigit():
            current = get_list_value(current, int(obj))
        else:
            current = get_dict_value(current, obj)
    return current

The helpers catch KeyError, IndexError, and TypeError, print on stderr, and exit. resolve itself stays a straight loop.

Because cpu, memory, and thermal still do not share one value shape, evaluate dispatches to a small private helper per module (_evaluate_cpu, and so on) and merges the results into one dictionary. v1 loads the three modules it already has rules for. Disk and sound collection exist; their inference rules are not finished in the same way.

The public main in inference.py is only orchestration: check environment variables, check input paths, create RESULT_DIR if needed, evaluate, write result_{DATE}.json.

Decision engine

load result -> find warning and critical fields -> write a cause log if needed

The decision script does not re-parse /proc. It reads today’s result file.

The decision I made for v1: if every field is OK, exit 0 and write nothing extra. If any field is not OK, write cause_{DATE}.log and return a non-zero status (90) so Bash can tell an alert from a clean run.

3. Flags, display, and the entry point

v1 uses short flags only, parsed with getopts:

parse_args() {
    while getopts ':hvrm:' opt; do
        case "$opt" in
            h) usage; exit 0 ;;
            v) printf '%s version %s\n' "$PROGNAME" "$VERSION"; exit 0 ;;
            # ...
        esac
    done
}

Action flags such as -h and -v print and exit inside the parser. Setting flags only store values. The TUI runs only when the session is a terminal and quiet mode is off.

Main procedure

All of the pieces meet in one function:

check files and directories
parse flags
install missing dependencies
collect snapshots
run inference
run decision
show the TUI unless -q was passed
exit

main() {
    check_req_files || exit "$ERR_FAILURE"
    check_req_dirs  || exit "$ERR_FAILURE"

    parse_args "$@"
    install_missing_deps

    write_cpu_json &
    write_memory_json
    write_thermal_json
    write_disk_json
    write_sound_json

    mkdir -p "$DUMPS_PATH"
    python3 "$ENGINE_DIR/inference.py" && python3 "$ENGINE_DIR/decision.py"

    display_tui || exit "$ERR_FAILURE"
    exit "$ERR_SUCCESS"
}

main "$@"

Decision 4: collect in the background where it hurts

The first runs collected modules one after another. CPU sampling waits about one second to compute usage, so the whole collect stage felt slow.

write_cpu_json & starts that slow job in the background so the other writers can proceed. That made the collect stage feel almost instant.

This only stays correct if the entry point waits for the background job before inference starts. Otherwise Python can open a CPU file that is not finished yet. A wait after the writers is part of this design, not an optional extra.

What v1 is not

The project is small on purpose.

no long options
no previous-day comparison of result files
no uniform JSON schema across modules
disk and sound are collected; they are not fully inferred like cpu, memory, and thermal
the TUI is a banner and a status list, not a full-screen toolkit

Dated result files are already named result_{DATE}.json so a later version can compare runs without changing the collector.

Layout

sysk/
├── lib/
│   ├── core/          # 00_error.sh ... 05_parse_flags.sh, tui.sh
│   ├── devices/
│   └── hw/
├── engine/
│   ├── .rules/        # cpu.yml, memory.yml, thermal.yml
│   ├── inference.py
│   ├── decision.py
│   └── results/
└── sysk               # entry point

That is the architecture of v1: files in, JSON snapshots, YAML rules, a small path walker, a verdict, and a Bash wrapper that the user actually types. Many features could still be added. The shape above is what is running now.

if you are interested in the project you can check it out at https://github.com/4kit1-glitch/sysk

thanks for being along with me in my journey

Defensive Scripting with bash

Kengah Ireneaus — Mon, 31 Aug 2026 15:08:00 +0000

DEFENSIVE PROGRAMMING IN BASH

Bash is a very powerful tool, but it is important to employ strategies that catch errors early, provide clear logging, and handle unexpected situations cleanly.

The scripts you write may be subjected to unexpected behaviours and events such as a required directory not present, a required shell command not present, or, commonly, permission errors.

I have been writing Bash scripts for a while, and I have gathered the best techniques from structuring scripts to seamless error handling, which we will explore: some key practices to enhance reliability of your scripts.

This guide assumes prior exposure to Bash.

Structuring a Bash script

Bash being a flexible language as it is follows no strict structure, but here is the one I recommend.

#!/bin/bash

# global variables immutable and referenced by whole script
readonly PROGNAME=$(basename "$0")

# sourced script
source my_script.sh

# program logic grouped into functions
do_something() {
    # logic
    return $?
}

main() {
    # main procedure
    return $?
}
# calling main 
main || {
    printf "program failed" >&2
    exit 1
}

export vs local vs global

Try to keep global variables to a minimum
SHOUTING_SNAKE_CASE VAR NAMING
readonly declaration
use variable names to replace cryptic $1

Globals I recommend you always use in your programs:

readonly PROG_NAME=$(basename "$0")
readonly PROG_DIR=$(readlink -m $(dirname "$0"))
# or even better 
export SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"

Sourcing and splitting a script

Splitting the logic of your script into multiple scripts will show easier to manage as the script gets larger.

All other variables should be local.

#!/usr/bin/env bash
change_owner_of_file() {
    local filename=$1
    local user=$2
    local group=$3

    chown $user:$group $filename
}

Modular coding, functions and arguments

Grouping procedures into functions and specifying its return code in case of failure or success is the way to go.
Some distinctive functions I use are:

info() -- for logging successful events

track all changes made by script, especially cron jobs

#!/bin/bash

info() {
    echo "[INFO] [$TIME] $*" >> "$info_logs"
}

# or you can use separate info files for each event, but that might take up space when doing scripting on small-space devices like Raspberry Pi boards

error() -- for logging failed events and warnings

error logging very important for building daemons
easily get reason why script may have failed mid-run

#!/bin/bash

error() {
    echo "[ERROR] [$TIME] $*" >> "$err_logs"
}

main() -- single point of entry for your program

keeps code clean
procedures become descriptive

    main() {
    # check req files
    # check req dirs
    # install missing deps
    # confirm installation
    # run data collections
    # run inference engine and generate results
    # run decision engine and generate results
    # run tui if -q flag isn't given, which just pretty-print results and decision
    # exit 
    check_req_files || {
        printf "Required files missing" >&2
        exit "$ERR_FAILURE"
    }
    check_req_dirs || {
        printf "Required directories missing" >&2
        exit "$ERR_FAILURE"
    }

    parse_args "$@"
    # installing missing dependencies
    install_missing_deps

    # running data collections
    write_cpu_json &
    write_memory_json
    write_thermal_json
    write_disk_json 
    write_sound_json

    # run engine
    python3 "$ENGINE_DIR"/inference.py && python3 "$ENGINE_DIR"/decision.py

    display_tui || {
        exit "$ERR_FAILURE"
    }
    exit "$ERR_SUCCESS"
}

main "$@"
# code taken from sysk

Commenting

From my experience, Bash syntax isn't really presentable. It gets messy fast as the program expands. All the cryptic ?*&&^^ symbols become confusing, because a single symbol can be used in 2 or more cases representing different things.

A simple comment # this does this will go a long way.

giving strict instructions:
# DONT TOUCH THIS # USE PRINTF NOT ECHO

Wrapping lines

When using a code editor like VS Code, they give you automatic wrap-line options.
Yes, it works, but when migrating the code to another IDE it breaks.
So if code is too long, wrap with the \.
Also makes script look clean.

jq -n \
--arg name "$names" \
-f "$file"

/dev/null and /dev/zero

Think of /dev/null as a black hole. It is essentially the equivalent of a write-only file.
Everything written to it disappears. Attempts to read or output from it result in nothing.
Suppressing stdout.

cat $filename >/dev/null
# Contents of the file will not list to stdout.

It can be very useful when you need a command to run without any output.

Debugging

Bash has no built-in debugger, but there are many workarounds.

using shellcheck
- ShellCheck is one of the best ways to write a safe script. Sometimes it might be annoying to use because of the many options, but a script which can pass through ShellCheck successfully has probably no syntax error. But it can't catch runtime errors or logic errors.
using set -x and set +x
- this echoes each line before producing output
- use to debug a particular piece of code where you feel the error might be from
```
    set -x
    echo "use case" >> $file
    set +x
```
using sh -n scriptname
- catches syntax errors without executing script
- some syntax errors may escape

Handling failures and testing using if statements

Setting error-handling options

Bash is set by default to run to completion even when it encounters an error.

#!/bin/bash
echo "program starts"
ech "program continues" # command doesn't exist
echo "program end"

Running this gives:

program starts
./test.sh: line 3: ech: command not found
program end

This and other common unexpected behaviours can be avoided using shell options.

set -o errexit or set -e: this option ensures that the script exits when any command returns a non-zero status unless handled with ||
set -o nounset or set -u: ensures the script treats unset variables as errors
set -o pipefail: this option causes the pipeline to fail if any command within it fails

These commands can be combined as set -euo pipefail.

#!/bin/bash
set -euo pipefail
echo "program starts"
ech "program continues" # command doesn't exist
echo "program end"

Running this we get:

program starts
./test.sh: line 4: ech: command not found

Some problems with the set -euo pipefail

While it might seem very convenient to use the guard line, there are some unexpected behaviours which might be unwanted, especially with the set -e flag, which is very problematic.

Conditions disable set -e
- the test of if, while and until
- on the left of && and ||
- inverted with the ! flag

false && echo never # false fails but script continues
false && echo this runs

Command substitution and subshells don't automatically inherit the set -e flag:

set -e 
result=$(false)
echo "gets here" # still successfully runs

This can be fixed with shopt -s inherit_errexit shell option (Bash 4.4+).

local, export and readonly: they mask return values so they always succeed even if substituted command fails

export answer=$(find /bin/bash) # bad
# better
declare word=$()
export word

This can be fixed by declaring and assigning on separate lines.

This demonstrates set -e can give a fake sense of safety.

Explicitly catching and handling errors

As shown above, the shell options are a good way to perform error handling in a script, but they are not perfect. That said, the best way to handle errors is to use conditionals.

In Bash, an exit status of 0 represents success; any other represents a failure, but there are special exit codes that specify a particular event.
The exit code of the last command to run is stored in the $? special variable.

echo "hello world"
echo "$?" # outputs 0

# some special return codes
readonly ERR_SUCCESS=0  # operation successful
readonly ERR_FAILURE=1  # operation failed general 
readonly ERR_PERMISSION_DENIED=126 # permission denied
readonly ERR_COMMAND_FAILED=126 # command runs but fails
readonly ERR_NOT_FOUND=127  # command or file not found
readonly ERR_BAD_USAGE=2    # bad use of script or function

Catching these codes with || and && is the way to go.

find "$file"* || {
    echo "no file with name $file"
    exit 127
}

Handling unexpected exit events using traps

Trap exit events to perform cleanup tasks or handle unexpected
trap [command] [signals]

Let's take a script designed to run non-stop for 60 seconds, maybe performing data movement or log parsing, and we don't want any interruption, maybe from Ctrl + C.

#!/bin/bash

trap "echo Booh!" SIGINT SIGTERM
echo "pid is $$"

while true; do
    sleep 60    # script last 60 seconds
done

You can do more research on traps.

Conclusion

Following these practices will ensure to a certain level that your Bash script will be robust.

Reference

Note: this article summarises my discoveries with Bash. There are many pitfalls and gotchas which have not been mentioned here.

Remember there is no perfect guide to Bash. The best way to learn is to practice and encounter the errors yourself.

Thanks for reading to this level. If you have any doubts, please don't hesitate to share in the comments. Happy scripting.

A Practical Guide to jq in Shell Scripts

Kengah Ireneaus — Sun, 16 Aug 2026 18:01:26 +0000

A Practical Guide to jq in Shell Scripts

While building sykd (a system health monitor daemon for linux servers) i needed to collect system data as json so i could process easily in python on doing research if found out about the jq shell program for creating and parsing json in bash, but learning the commands was quite tedious and the man page is large and very difficult to read so i came out with this guide to ease and summarize the major commands you might need.

jq is a lightweight and flexible command-line JSON processor. It is one of the most useful tools for working with JSON data directly inside shell scripts and pipelines.

Installation

Debian / Ubuntu: sudo apt install jq
macOS: brew install jq
Other systems: Use your package manager or download binaries from the official site.

Basic Usage

jq [options] '<filter>' [file...]

Input can come from a file, a pipe, or standard input. The filter expression selects or transforms the data.

Quick note: jq reads JSON from stdin by default. If you want to generate JSON inside jq without reading input, use -n.

Useful Options

Option	Purpose
`-r`	Raw output (no JSON quotes around strings)
`-c`	Compact (single-line) output
`-n`	Start with `null` input (useful for generating JSON)
`-s`	Slurp entire input into an array
`--arg`	Pass a string variable
`--argjson`	Pass a JSON value (preferred for arrays/objects)

Other helpful runtime options:

Option	Purpose
`--rawfile name filename`	Read an entire file as a raw string into variable `$name`
`--slurpfile name filename`	Read file and slurp into array `$name` (like `-s` but into variable)

Example: jq --slurpfile all files.json '.[0] + $all[0]'

Essential Filters

Goal	Filter Example
Pretty-print	`.`
Extract a field	`.name` or `.["name"]`
Nested field	`.user.address.city`
Array element	`.[0]` or `.[-1]`
Iterate array	`.[]`
Select matching objects	`.[] \
Build a new object	{% raw %}`{name, age}`
Transform every element	`map(.name)`
Length	`length`
List keys	`keys`
Conditional	`if .active then "yes" else "no" end`

You can define reusable functions inside jq using def. Example:

def greet: "Hello, " + .name + "!";
. | greet

This will output "Hello, <name>!" for an object with a name key.

Practical Examples

Pretty-print a file

jq . data.json

Extract a single value

jq -r '.version' package.json

Filter an array of objects

jq '.[] | select(.status == "active") | .name' users.json

Create a new structure

jq '{names: map(.name), total: length}' people.json

Use in a pipeline

curl -s https://api.example.com/data | jq '.results[] | .id'

Generate JSON from scratch

jq -n '{name: "example", version: 1}'

Create multiple objects programmatically

jq -n '[range(3) | {index: ., squared: (. * .)}]'

This produces:

[
{"index":0,"squared":0},
{"index":1,"squared":1},
{"index":2,"squared":4}
]

Passing a Bash Array to jq

Bash arrays cannot be passed directly. Convert the array to a JSON array first, then supply it with --argjson.

Recommended Method

my_array=("apple" "banana" "cherry")

# Convert bash array → JSON array
json_array=$(printf '%s\n' "${my_array[@]}" | jq -R . | jq -s .)

# Use it inside jq
jq --argjson arr "$json_array" '$arr'

One-liner version:

jq --argjson arr "$(printf '%s\n' "${my_array[@]}" | jq -R . | jq -s .)" \
   '$arr[]'

Numeric Arrays

numbers=(10 20 30)
json_numbers=$(printf '%s\n' "${numbers[@]}" | jq -s .)

jq --argjson nums "$json_numbers" '$nums | map(. * 2)'

Feed as Input Instead

printf '%s\n' "${my_array[@]}" | jq -R . | jq -s .

Tips for Reliable Shell Scripts

Always quote the filter when it contains spaces or special characters.
Prefer --argjson for arrays and objects; use --arg only for plain strings.
Test filters interactively before embedding them in scripts.
For complex logic, store the filter in a separate .jq file and call it with -f.
When embedding multi-line filters in shell variables, use a heredoc to keep quoting simple:

filter=$(cat <<'EOF'
.[] | select(.status=="active") | {id, name}
EOF
)

curl -s api | jq -f <(echo "$filter")

Prefer --argjson when you need to pass non-string structured data; --arg always passes a string.
When values may contain newlines or special characters, convert them to JSON with jq -R . before passing.
For newline-delimited JSON (NDJSON/JSONL), use jq -c . to ensure compact output and --slurp if you need to combine records into an array.
Use try ... catch for safe extraction and defaults:

try .foo.bar catch "default"

Use inputs to read multiple JSON documents from stdin (useful with -n):

# echo multiple JSON objects and process them with inputs
printf '%s
' '{"x":1}' '{"x":2}' | jq -n '[inputs | .x]'

Additional Examples and Patterns

Selecting and Transforming

Extract and rename fields:

jq '.[] | {identifier: .id, user: .name, active: .status == "active"}' users.json

Build an index (map id → object):

jq 'map({ (.id|tostring): . }) | add' users.json

Group by a key and count per group:

jq 'group_by(.category) | map({category: .[0].category, count: length})' items.json

Working with Strings

Trim and lowercase a field:

jq '.name | ascii_downcase | gsub("^ +| +$"; "")' person.json

Join array of strings:

jq -r '.tags | join(",")' article.json

Numeric operations

Sum field values:

jq '[.[] | .size] | add' files.json

Find maximum:

jq 'max_by(.score) | .score' scores.json

Advanced: reduce, recurse, and more

Use reduce to accumulate values:

jq 'reduce .[] as $item (0; . + $item.value)' metrics.json

Recursively find all keys named id in nested structure:

jq '.. | objects | .id? // empty' nested.json

Streaming large JSON (`jq --stream`)

For very large JSON documents use --stream to get path/value pairs; processing is more manual but uses much less memory:

jq --stream 'select(.[0][-1]=="targetKey") | .[1]' large.json

Working with NDJSON / JSONL

To parse newline-delimited JSON and combine into an array:

jq -s '.' file.jsonl

Process each line independently (streaming):

jq -c '. | {id: .id, ok: (.value > 0)}' file.jsonl

Filters in separate `.jq` files

Save a complex filter to filters.jq:

def summarize:
   {total: (map(.value) | add), count: length};

.items | map({k: .key, v: .value}) | summarize

Call it from shell:

jq -f filters.jq data.json

Passing environment variables into `jq`

Pass a shell variable as JSON (string):

name="O'Reilly"
jq --arg name "$name" '. + {author: $name}' book.json

Pass an environment variable that is already JSON:

json_obj='{"a":1}'
jq --argjson o "$json_obj" '. + $o' base.json

Error handling and safe accesses

Use ? to avoid errors when a key may not exist:

jq '.maybe?.nested // "default"' data.json

Use try to catch runtime errors:

jq 'try .items[] catch empty' data.json

Common pitfalls

Forgetting to quote filters when they contain shell-sensitive characters — always wrap your filter in single quotes in shell.
Passing arrays with --arg (creates a JSON string, not an array) — use --argjson or jq -s conversion.
Assuming jq modifies files in-place — it writes to stdout; redirect output to a file to save changes.

Performance tips

Use --stream for very large JSON that can't fit in memory.
Avoid unnecessary map + add for simple reductions; reduce can be more efficient.
Use compiled filters in -f files for complex repeated transformations.

Examples: Real shell script snippets

Filter API result and extract IDs into a bash array:

readarray -t ids < <(curl -s "https://api.example.com/items" | jq -r '.items[].id')

for id in "${ids[@]}"; do
   echo "Got id: $id"
done

Pass a bash array of words safely into jq and filter by membership:

words=(alpha beta "complex value")
json_words=$(printf '%s\n' "${words[@]}" | jq -R . | jq -s .)

curl -s dataset.json | jq --argjson words "$json_words" '[.[] | select(.name as $n | $words | index($n))]'

Create a small portable CLI using jq and bash:

#!/usr/bin/env bash
data_file=${1:-data.json}
case $2 in
   list)
      jq -r '.items[] | "\(.id) - \(.name)"' "$data_file" ;;
   stats)
      jq '{total: (.items | length), sum: (.items | map(.value) | add)}' "$data_file" ;;
   *) echo "Usage: $0 <file> {list|stats}"; exit 2 ;;
esac

Conclusion

With a few core filters and the correct technique for passing arrays, jq becomes a powerful and reliable tool inside any shell workflow. The patterns shown above cover the majority of day-to-day JSON processing needs.

Happy scripting!

A Month With Bash — Part 3: Building Projects

Kengah Ireneaus — Tue, 04 Aug 2026 00:36:48 +0000

A Month With Bash — Part 3: Building Projects

After all the expansions and syntax, I moved on to regex in bash. It wasn't too hard since I'd already worked with regex in Python, but alongside it I learned grep, sed, and awk — tools that turned out to be extremely useful for automation.

I built a few mini projects and started automating some of my small day-to-day tasks. I won't go too deep into that here, but you can check out my learning-bash GitHub repo, which has all my learning scripts.

From there I covered conditionals, loops, and repetitive tasks.

Finally

I learned about array variables in bash and shell options,
went even further testing different ways of looping, and that's when I started actual project building(I am still building )

#!/usr/bin/env bash

## looping with range functions -- somehow

# python style looping {start..end}
for i in {1..10}; do    # this uses brace expansion so using vars wont work becase of execution sequencing
    echo $i
done

clear

## c - slyle looping 
for (( i = 0; i < 10; i++ )); do # variables works here well
    echo "hello $i"
done

## using variables to loop

clear
start=1
stop=10
step=2

for i in $(seq $start $stop); do # this uses the seq command
    echo "hello world"
done

Conclusion

Spending so much time on bash wasn't a waste. Not only did it force me to learn a huge number of commands, it changed how I think about my own machine — most of what I used to do manually, I can now automate. That shift alone made the month worth it.
i am still learning and trying to get the best practices and things not to do

THANK YOU FOR READING THIS FAR. That is a rough summary of me writing bash for a month there is really a lot left unsaid here but still building and learning. If you are just starting out with bash or if you haven't tried it hope this helps
feel free to drop questions advice and corrections

A Month With Bash — Part 2: Expansions

Kengah Ireneaus — Tue, 04 Aug 2026 00:26:00 +0000

A Month With Bash — Part 2: Expansions

Continuing from where I left off, the next thing I learned was special parameters in bash:

"$*"
$#
$?
$@
$N
$-
$0

Another important concept I picked up is how bash executes shell scripts. Bash is one of those languages that interprets each line as it goes — but it doesn't stop if a line fails. It continues on unless you explicitly set set -o pipefail (or -e, depending on what you want it to catch).

Generally, the procedure looks like this:

Tokenizing: splitting the line into tokens, usually split using the IFS value.

Brace expansion: a mechanism by which arbitrary strings can be generated.

echo file{1,2,3}.txt
## output: file1.txt file2.txt file3.txt

Bash preserves the order from left to right.

Tilde expansion: this is where expansion of special symbols takes place.

~ represents the HOME built-in variable
~+ represents PWD, the current working directory
and others

DIR=~/Desktop # this is $HOME/Desktop
echo "$DIR"

Parameter expansion: introduced with the $ symbol.

# ${} — the braces can be omitted for normal variables but not for array-type variables

Command substitution: very important — it lets you assign the output of a command to a variable, and use commands inside if and for statements. Done with $(command to execute).

week_name="$(date +%A)" # gets the current day of the week
echo "$week_name"

Generally, $() spawns a new shell instance, so it's advisable to avoid it where possible, for latency reasons.

Arithmetic expansion: just from the name, this allows evaluation of arithmetic expressions and substitution of the result. It starts with $(( expression )). There are some rules — bash doesn't support floating point arithmetic natively, so you'd reach for bc if you need it. I won't go deep into that here since this isn't a full bash tutorial.

Here's a simple BMI calculator I wrote while practicing this:

#!/usr/bin/env bash

# script calculates user's BMI and gives a recommendation

set -euo pipefail

# ---------------- read parameters ----------------
weight="$1"
height="$2"

bmi=$(bc -q <<< "scale=2; $weight / ($height^2)")

# ---------------- test ----------------
if (( $(bc -q <<< "$bmi < 18.5") )); then
    echo "UNDERWEIGHT"
elif (( $(bc -q <<< "$bmi < 25") )); then
    echo "normal weight"
elif (( $(bc -q <<< "$bmi < 30") )); then
    echo "overweight"
else
    echo "obese"
fi

Process substitution: this saves the output of a process into a temporary file-like descriptor under /dev/fd/N. It lets you feed command output into programs that expect a file as input. Done with >(command) and <(command).

#!/usr/bin/env bash

# script demonstrates process substitution
# process substitution is when you want to use the output of a command
# as the input to a command that needs files as parameters

set -euo pipefail

# gets the difference between two texts without making temp files
echo "$(diff -p <(echo "hello mr beast") <(echo "hello mr beast."))"

# note: <(cmd) uses the output of a command as a file
# >(cmd) takes input from a program and feeds it to the command as a file

Word splitting and globbing: occurs after expansion, only on unquoted values.

Next up: regex, grep/sed/awk, and moving into building actual projects.

A month with bash

Kengah Ireneaus — Mon, 03 Aug 2026 14:20:00 +0000

A Month With Bash

*this began as one long write-up but i decided to split it into three parts

A month ago I decided to learn bash so I could use my Fedora machine more effectively. My original plan was to just learn some commands and get over with it, but as I began reading resources and books, I quickly noticed how important it is for Linux users, automation experts, and system admins. The thing that amazed me most is that I could literally automate almost every repetitive process I do on my PC.

Getting Started

Starting off with bash wasn't really bad or difficult, maybe because I already had experience programming in C and Python. Learning the basic syntax of bash wasn't much of a problem — things like variables and printing to the terminal were quite easy to grasp. I also learned some theory on shell types and their differences, which wasn't too hard either.

# create, assign, and print a variable
my_var="declared"
echo "$my_var"

Moving Deeper Into Bash

After the basics, where bash just seemed like a small programming language, things changed once I started learning about the bash environment. This is what began to show me what makes it special and unique. I learned about:

Shell initialization scripts
- System-wide
- Individual user scripts
- How to configure them

Honestly, these files affect system behavior, so it's better to avoid touching them unless you know what you're doing. This part was quite confusing at first, but with practice it became clearer. I still don't fully understand every use case of these initialization scripts off-hand, and explaining them isn't the goal of this post.

After that I took some time to learn about reserved variables — just a curated table of them. They're very useful because they enable some handy functionality, and they're good to use when making a script portable. Some important ones:

HOME
IFS
PWD
PATH
DIRSTACK

location="$HOME" # this stores the location of the home directory
echo "$location"

Next up: special parameters, expansions, and how bash actually executes a script line by line.

DEV Community: Kengah Ireneaus

sysk a CLI health monitor in bash and python, how i built it

Sysk architecture

Intro

System design

1. Data collection (Bash)

Decision 1: read kernel files instead of running helper programs

Decision 2: many scripts, one entry point

Privileged work

Checking and installing dependencies

Collection per module

Storing collected data

2. Inference and decision (Python)

Loading

Decision 3: a path language instead of one parser per module

Decision engine

3. Flags, display, and the entry point

Main procedure

Decision 4: collect in the background where it hurts

What v1 is not

Layout

Defensive Scripting with bash

DEFENSIVE PROGRAMMING IN BASH

Structuring a Bash script

export vs local vs global

Sourcing and splitting a script

Modular coding, functions and arguments

info() -- for logging successful events

error() -- for logging failed events and warnings

main() -- single point of entry for your program

Commenting

Wrapping lines

/dev/null and /dev/zero

Debugging

Handling failures and testing using if statements

Setting error-handling options

Some problems with the set -euo pipefail

Explicitly catching and handling errors

Handling unexpected exit events using traps

Conclusion

Reference

A Practical Guide to jq in Shell Scripts

A Practical Guide to jq in Shell Scripts

Installation

Basic Usage

Useful Options

Essential Filters

Practical Examples

Passing a Bash Array to jq

Recommended Method

Numeric Arrays

Feed as Input Instead

Tips for Reliable Shell Scripts

Additional Examples and Patterns

Selecting and Transforming

Working with Strings

Numeric operations

Advanced: reduce, recurse, and more

Streaming large JSON (jq --stream)

Working with NDJSON / JSONL

Filters in separate .jq files

Passing environment variables into jq

Error handling and safe accesses

Common pitfalls

Performance tips

Examples: Real shell script snippets

Conclusion

A Month With Bash — Part 3: Building Projects

A Month With Bash — Part 3: Building Projects

Finally

Conclusion

A Month With Bash — Part 2: Expansions

A Month With Bash — Part 2: Expansions

A month with bash

A Month With Bash

Getting Started

Moving Deeper Into Bash

Streaming large JSON (`jq --stream`)

Filters in separate `.jq` files

Passing environment variables into `jq`