# The 'jd' command-line app

> A command-line helper for the Johnny.Decimal system.

> [Alpha software](https://en.wikipedia.org/wiki/Software_release_life_cycle#Alpha:~:text=2%5D-,Alpha,version). 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](https://synthetic.new/?referral=ZxTT9aggSn2SKOf) for you.[^affiliate] 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.

[^affiliate]: 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.

## Install

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

### macOS

```sh
# 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:

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

### Linux

```sh
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`](https://static.johnnydecimal.com/cli/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`):

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

## Configure

Requires environment variables [as documented here](/jdhq/environment-variable-standards/). 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:

```sh
export JD_BYPASS_EXPIRY=1
```

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

## API

It consumes the [JDHQ API](/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](/sign-up/). ;-)

## 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](https://bun.com). I wish it wasn't so. Don't email me.

## Download

{/* JD-RELEASE-START — auto-managed by cli.johnnydecimal.com/scripts/release.sh */}
- 2026-05-08 v0.0.7
  - [jd-darwin-arm64](https://static.johnnydecimal.com/cli/v0.0.7/jd-darwin-arm64)
  - [jd-darwin-x64](https://static.johnnydecimal.com/cli/v0.0.7/jd-darwin-x64)
  - [jd-linux-x64](https://static.johnnydecimal.com/cli/v0.0.7/jd-linux-x64)
  - [jd-windows-x64.exe](https://static.johnnydecimal.com/cli/v0.0.7/jd-windows-x64.exe)
  - [SHA256 sums](https://johnnydecimal.com/cli/jd-v0.0.7-sha256.txt)
{/* JD-RELEASE-END */}