The 'jd' command-line app

Alpha software. Not for the faint-hearted.

jd is a cross-platform command-line app. It will perform local validation of your JDex and filesystem. And serve as the synchronisation agent between your local machine and JDHQ. Here's a list of things it will eventually/probably do, in no particular order:

  • Validate your JDex (i.e. it conforms to the rules of the system).
  • Valdiate that your filesystem matches your JDex. The app requires a JDex: your JDex is the canonical representation of the system.
  • Fix any validation errors.
  • Background monitor for errors (e.g. you create a new filesystem folder without creating a JDex entry).
  • Auto-create/rename filesystem folders based on JDex changes.
  • Manage and enforce standard metadata fields (e.g. a new locations).
  • Synchronise JDex metadata to JDHQ: make edits in Obsidian, see them represented on the site.
  • Via an LLM, answer questions about your system, automatically file documents, automatically build a system from a folder of chaos.
  • All operations saved both in a machine-readable journal enabling undo, and human-readable in your JDex.

Design principles

Safety first

You'll be pointing this app at your production data. There's no margin for error.

No delete operators, every change is logged

Any changes require interative confirmation or a --yes flag.

A guardrail for your LLM

People are pointing their LLM at their filesystem and asking it to do stuff. This is terrifying.

Instead, point your LLM at jd. It's the gatekeeper. It knows the rules, knows your system. It can modify JDex entries and move files. But every action is logged, and deletion is currently impossible.

Better still, use jd ask which queries a privacy-first cloud LLM for you.1 It's your guardrail. Responses are sanitised. The LLM simply can't execute a dodgy command. It doesn't act on your files. It advises jd, and it acts on your data with a limited, logged instruction set.

Install

jd is a single binary. Download and put it in your PATH.

macOS

# Apple Silicon
curl -fL -o /usr/local/bin/jd https://static.johnnydecimal.com/cli/jd-darwin-arm64

# Intel
curl -fL -o /usr/local/bin/jd https://static.johnnydecimal.com/cli/jd-darwin-x64

chmod +x /usr/local/bin/jd
jd --version

If you downloaded the binary through a browser instead of using curl, macOS marks it 'quarantined' and refuses to run it. Strip the quarantine flag with:

xattr -d com.apple.quarantine /usr/local/bin/jd

Linux

curl -fL -o /usr/local/bin/jd https://static.johnnydecimal.com/cli/jd-linux-x64
chmod +x /usr/local/bin/jd
jd --version

Windows

Download jd-windows-x64.exe, rename it to jd.exe, and put it somewhere on your PATH.

Confirmation prompts

Commands that modifies data (adding a location, moving a file, renaming a folder, applying an LLM-proposed plan) prompt before taking action:

12.34  file my-bank-statement.pdf
Proceed? [y/N]

To skip the prompt, every mutating command takes -y (or --yes):

jd file my-bank-statement.pdf 12.34 -y

Configure

Requires environment variables as documented here. Run jd help for more information. All user-facing commands are documented.

Current LAS/SBS unsupported

Told you this was an early release. ;-)

This tool's scan function requires a bunch of YAML frontmatter that the current Life Admin and Small Business System downloads don't contain. So it's 'broken' out of the box.

But you'll see from those failures the intent. And I'll build the YAML into those downloads shortly. I should also be able to provide a jd migrate function: everything's very predictable.

Versioning and expiry

Update often while jd is at v0.x. Every binary expires 6 weeks from its build date and refuses to run after that. While I'm building it to be stable, I can't know what might change in these early stages.

You'll see a one-line warning 7 days before expiry:

jd 0.0.2 expires in 5 days (2026-06-14). Update: https://johnnydecimal.com/jdhq/jd/

After expiry, you'll need to re-run the install command to update.

If you absolutely need to keep using an expired binary, set:

export JD_BYPASS_EXPIRY=1

The tool will run with a louder warning. You shouldn't do this.

API

It consumes the JDHQ API, which you're free to use yourself.

Upgrading the LLM features

jd ask uses an LLM to suggest how to organise files and update the JDex. That works today if you're a Lifetime member. Each tool call costs me money and I haven't thought about how this might work long-term. I might turn this off at any time. To try it out, upgrade to Lifetime. ;-)

More to come

Very early days. Keep an eye on the site updates/RSS feed. And I know it's huge for a CLI. To make it cross-platform it's written in TypeScript and compiled with bun. I wish it wasn't so. Don't email me.

Download

Footnotes

  1. Affiliate link. Other than the $10 it earns me, I'm not affiliated with Synthetic. I just think they offer a good product. And I trust their small indie team, who are very active on Discord. ↩