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 --