Forem: siyadhkc

I built a JSON CLI tool with Bun and TypeScript — here's what actually happened

siyadhkc — Mon, 11 May 2026 01:31:57 +0000

I wanted a tool that could flatten JSON, filter it, colorize output, and fetch from a URL — all from
the terminal. Something between jq and gron but with a cleaner, more intuitive API. So I built
jray. This is the honest post-mortem of how it went.

GitHub: github.com/siyadhkc/jray
Website:siyadhkc.github.io/Jray

Why I built it

Every time I'm debugging an API response or poking around some nested config file, I reach for jq.
And every time, I spend the first five minutes googling the syntax again. jq is powerful — genuinely
— but it's its own language, and unless you're writing complex transformations daily, that overhead
adds up.

gron is the other tool I kept coming back to. It flattens JSON into greppable dot-notation, which
is exactly what you want when you're trying to find where a deeply nested key lives. But gron is
read-only. You can't filter and get structured output back. You can't fetch from a URL. The color
situation is nonexistent.

So I scoped out what I actually needed:

Flatten JSON to dot-notation paths (a.b.c = value) so I can see structure at a glance
Filter by key pattern without learning a query language
Fetch directly from a URL so I don't have to curl | jray every time
Color output by default on TTY
Fast enough that it doesn't feel like overhead when I'm in the middle of something

Bun was the obvious runtime choice. Fast cold start, native TypeScript support, a built-in test
runner, and bun build --compile that bundles everything into a single self-contained binary. No
Node.js version headaches, no separate install step for the runtime.

How it's structured

I kept the architecture intentionally flat. No frameworks, minimal dependencies. The core logic is
split into focused modules:

flatten.ts — recursive flatten and unflatten. Takes a nested object and produces a map of dot-notation paths to primitive values. Unflatten goes the other direction.
filter.ts — glob-style pattern matching on the flattened keys. user.* gives you everything under user, **.id matches any id at any depth.
color.ts — ANSI color output. Keys in one color, values type-aware (strings, numbers, booleans each get their own).
fetch.ts — thin wrapper around Bun.fetch that handles the request, checks content type, and pipes the response into the flatten pipeline.
cli.ts — argument parsing and wiring. Reads from stdin, a file path, or a URL depending on what flags you pass.

The whole thing compiles down to a single binary:

bun build ./src/cli.ts --compile --outfile jray

No runtime dependency on Bun after that. You ship the binary, it works.

The problems I actually ran into

npm name conflict

First thing I did after writing the initial working version was try to publish as jray. Already
taken — and not squatted. An actual published package with actual users. So I had to switch to a
scoped package: @siyadkc/jray.

That sounds like a small change but it cascades. The README, the install command in all the
examples, the binary name in package.json, the GitHub Actions publish step, the Dev.to article
draft I'd already half-written — all of it needed updating. It also changes how users install it
slightly, since scoped packages require the @ prefix. Not a dealbreaker, but check npm before you
name your CLI.

Package size bloat

My first publish was heavier than it needed to be. Bun's compiled binary includes the runtime,
which is expected and fine. But the npm package itself had no files field, so it was packaging
everything — source maps, test files, the node_modules from dev, local configs. None of that
belongs in a published package.

Fix was straightforward:

"files": ["dist/", "README.md"]

That single field cut the published package weight significantly. Always define files. The npm
registry doesn't know what's dev and what's production unless you tell it.

Windows compatibility

I had a postinstall script that ran chmod +x on the binary. Works perfectly on Linux and macOS.
On Windows it throws and the install fails. I wrapped it in a try-catch and updated the docs to note
that Windows users should either run the binary path directly or use WSL. Not the cleanest solution,
but honest about the platform situation. Full Windows support is on the roadmap.

GitHub Actions for CI and publishing

The pipeline itself wasn't complicated — install Bun, run tests, publish to npm on a version tag.
But there's one specific thing that tripped me up: not using --frozen-lockfile in CI.

Without it, bun install in CI can silently update the lockfile, which means your CI might be
testing against different dependency versions than what you developed against. Always use:

- uses: oven-sh/setup-bun@v1
  with:
    bun-version: latest
- run: bun install --frozen-lockfile
- run: bun test

Publishing to npm from Actions requires setting NPM_TOKEN as a repository secret and passing it
through to the publish step. Once that's wired, releases are a tag push away.

What it actually does

# Install
bun add -g @siyadkc/jray

# Flatten JSON from stdin
echo '{"user":{"name":"Eliot","age":24}}' | jray
# user.name = "Eliot"
# user.age = 24

# Flatten a local file
jray data.json

# Filter by key pattern
jray --filter "user.*" data.json
# user.name = "Eliot"
# user.age = 24

# Fetch from a URL and flatten
jray --fetch https://api.example.com/users/1

# Disable color (for piping into other tools)
jray --no-color data.json

The filter uses glob-style matching against the full dot-path of each key. So user.* matches one
level under user, while **.id would match any id at any depth in the document. It's
intentionally simpler than jq's filter syntax — the goal is something you can remember without
looking it up.

Where it sits vs the competition

gron is the closest thing and the most direct comparison. It also flattens to dot-notation and
it's what made me realize there was a gap to fill. But gron has no color output, no URL fetching,
and no NDJSON streaming support. jray has all three.

jq is in a different category. It's a transformation tool — you write expressions, you reshape
data, you do complex operations. jray is an inspection tool. You throw data at it and you
understand the structure immediately. They're complementary more than they're competing.

fx is another one that comes up. Interactive, powerful, but it's a TUI. If you're in a script or
piping between tools, you don't want a TUI. jray is designed to be pipeline-friendly from the
start.

The longer-term vision is broader than just JSON. Supporting YAML and TOML with the same flatten
and filter interface makes it a universal structured-data CLI. There's also TOON (Token Oriented
Object Notation), which is an emerging format that's genuinely useful for LLM developer workflows
since it's optimized for tokenization. That's a real differentiator if the format gets traction.

The launch

Published to npm, wrote this article, posted on X . Also shared in the Bun
Discord since the community there is small enough that people actually read it.

The GitHub Pages site is live. It's getting redesigned right now — moving toward a flatter, more
minimal aesthetic with an interactive playground section where you can paste JSON directly in the
browser and see the flatten and filter output in real time. No install required to try it. That
single feature will probably do more for adoption than any amount of posting.

What I'd do differently

I'd define the files field before the first publish, not after. I'd also check npm for name
conflicts before I was emotionally attached to the name. And I'd set up the CI pipeline before
the first push to main so I wasn't debugging GitHub Actions at the same time I was trying to
ship.

The architecture decisions held up fine. Bun was the right call. The modular structure meant I
could add fetch.ts and color.ts without touching the core flatten logic. That's about as much
as you can ask from a first project's structure.

Try it

bun add -g @siyadkc/jray

GitHub: github.com/siyadhkc/jray

If you're working on something similar with Bun, or you have opinions on the filter API design,
drop a comment. Always curious how other people are solving the same problems.

This is my first article writing on this platform so if i made any narration mistake or anything feel free to tell me, i will improve my writing skill and the way of telling this
-- let's get connected --

From Hardware to Hacking: How Understanding Systems Changed My Approach to Security

siyadhkc — Wed, 15 Apr 2026 15:56:13 +0000

Introduction

I didn’t start my journey in cybersecurity. I started with hardware and networking, learning how systems actually function at a low level — how machines communicate, how configurations impact behavior, and how failures happen.

The Shift to Development

Later, I moved into development, working with Python and full-stack technologies. Building applications helped me understand how software is structured, but it also revealed something important:

Most applications are not built with security as a priority.

The Turning Point

This realization pushed me toward cybersecurity, specifically:

Web application security
API security
Cloud platforms (AWS, Azure, GCP)

Instead of just building systems, I began analyzing how they can be exploited.

A Different Way of Thinking

The biggest shift was in mindset:

From:
“How do I build this system?”

To:
“How can this system fail or be attacked?”

This dual perspective — builder and attacker — is critical in modern cybersecurity.

What’s Next

I’ll be sharing:

Practical security insights
Real-world learning experiences
Breakdowns of vulnerabilities and misconfigurations

If you’re interested in understanding systems deeply — not just building them, but also testing their limits — follow along.

I built a modern alternative to gron using Bun and TypeScript

siyadhkc — Sun, 12 Apr 2026 17:16:36 +0000

The problem

Working with JSON in the terminal is painful. jq is powerful
but requires learning a whole query language. grep works but
matches values too — not just paths.

For example if I search for "name" in my JSON:

grep matches json.user.name ✅ (correct)
grep also matches json.bio = "my name is Alice" ❌ (wrong)

So I built jray.

What jray does

jray flattens any JSON into one line per value:

$ jray data.json
json.organization.name = "Acme Corporation"
json.users[0].name = "Alice Pemberton"
json.users[0].role = "admin"
json.users[0].active = true
json.billing.plan = "enterprise"

Now you can grep it, awk it, pipe it — using tools you already know.

Four commands that cover everything

# Flatten with color output
jray data.json

# Fetch a URL directly — no curl needed
jray https://jsonplaceholder.typicode.com/users/1

# Filter by path only (never matches values)
jray data.json --filter "billing"

# Extract any subtree as clean JSON
jray data.json --select "billing"

# Print just the values
jray data.json --values

# Reconstruct original JSON
jray data.json | jray --ungron

The comparison with existing tools

Feature	jray	jq	gron
Flatten to lines	✅	❌	✅
Reconstruct JSON	✅	❌	✅
Filter by path	✅	✅	❌
Extract subtree	✅	✅	❌
Fetch from URLs	✅	❌	✅
Color output	✅	✅	✅
No query language	✅	❌	✅
TypeScript / modern	✅	❌	❌

What I learned building it

This was my first open source CLI tool. Key lessons:

1. Separate your CLI from your logic
cli.ts handles only I/O — reading files, printing output.
flatten.ts, filter.ts etc. know nothing about terminals.
This makes everything testable in isolation.

2. Use unknown not any in TypeScript
JSON is dynamic but that doesn't mean any. Using unknown
forces you to check types before using values — much safer.

3. Recursive functions are perfect for JSON
JSON is a tree. Walking a tree with recursion is the
cleanest pattern — each call handles one node and
delegates children back to itself.

4. Bun is genuinely fast and simple
Native TypeScript, built-in fetch, fast startup.
For a CLI tool, Bun is a great choice.

5. The README matters as much as the code
Nobody uses a tool they can't understand in 30 seconds.
Writing clear examples with real output is as important
as writing the code itself.

Install and try it

npm install -g @siyadkc/jray

Then:

jray https://jsonplaceholder.typicode.com/users/1

GitHub: github.com/siyadhkc/Jray

for more info Website: https://siyadhkc.github.io/Jray/

This is my first open source tool. Feedback on the code
quality is very welcome — especially from experienced
TypeScript developers!