The JD CLI

Tools that help you work at your command-line. They're compatible with bash (3.2+) and zsh and are MIT licensed so you're free to adapt them for other shells.1

Requires the configuration file and jq.

This page shows you what it does – for installation instructions, see the GitHub repository at cli.johnnydecimal.com.

Basic movement

jd 11.11         # cd to a folder by ID
jd tripsy        # cd to a folder by name

Names match by search. If there's more than one, you'll be shown a list. Search ignores case.

jd trip

# jd: 2 matches for 'trip':
#   ├─ 15 Travel
#   │  └─ 15.52 Family trip
#   └─ 21 Fun projects
#      └─ 21.15 Replacing Tripsy

You can use multiple search terms.

jd family trip   # cd to 15.52 without ambiguity

If the first term is a number, your search is scoped to that category/area.

jd 21 trip       # cd to 21.15 without ambiguity
jd 20-29 trip    # broader search, same result

It supports movement to any level of your system.

jd               # cd to the system root
jd 20-29         # cd to an area
jd 22            # cd to a category
jd 23.45         # cd to an ID
jd W0189         # cd to a work package

Creates the folder if required

If the filesystem folder doesn't exist and a JDex entry is found, the folder will be created.

jd 67.89         # JDex entry exists; folder does not

# 67.89 <Title> is created and you're taken there

This needs a jdex path in your configuration file, so the tool can read the entry's name.

Only ID folders will be created. If the parent category folder doesn't exist, an error is thrown.

jd 98.76

# jd: the JDex has 98.76 but there is no folder for category 98

Multiple systems

If you have multiple systems, the script detects them from the configuration file and gives you a command for each.

Say I have d25 and p76 defined.

d25 12.34        # <d25 root>/…/12.34
p76 56.78        # <p76 root>/…/56.78

jd still works, acting on your default system.

Move to a JDex folder

If your JDex is files on disk (e.g. Obsidian), the jdex verb moves you there.

jd jdex 11.11    # cd to <JDex path>/<11.11's parent folder>

You can use jdex as a command directly. If you have multiple systems, it acts on the default.

jdex 11.11       # cd to <JDex path>/<11.11's parent folder>

Create a new ID or work package

jd new creates items.

It's a beta feature because it writes data and is in active development: turn it on with jd beta on.

jd new id 21 My new thing        # the next free ID in category 21
jd new id 21.34 My new thing     # exactly 21.34, if it's free
jd new wp 21.34 My new project   # a work package for 21.34
  • jd new id creates the JDex note and the folder.
  • jd new wp creates the next W number, a project in your task app, the JDex note, and the folder.
    • Currently supports Things. Requires templates that I haven't distributed yet.
  • The title doesn't need quotes. Everything after the number up to the first word that starts with -- is the title.
  • Notes come from templates in your filesystem. ID template.md is looked for in the category's .03, then the area's, then 00.03. Work package templates are in W0003.
    • If templates aren't found you get a blank note.
    • I'll document this soon.
  • --dry-run shows you what would happen but takes no action.
jd new id 21 My new thing --dry-run

# jd: 21.53 My new thing
#      note    …/21 Products & services/21.53 My new thing.md
#      from    …/00.03 Templates/ID template.md
#      folder  …/21 Products & services/21.53 My new thing
#      nothing was made

jd new id --help and jd new wp --help do what you'd expect.

From a script or an agent

In your shell, jd is a function. The program behind it is ~/.jd/cli/bin/jd. Anything can run that directly without having to source something every time: a script, cron, or your agent.

~/.jd/cli/bin/jd 11.11                        # prints the folder for 11.11
~/.jd/cli/bin/jd --system P76 22              # another system
~/.jd/cli/bin/jd new id 21 A title --json     # one JSON object on stdout
  • A move prints one absolute path and exits 0, so cd "$(~/.jd/cli/bin/jd 11.11)" works.
  • --system is only read as the first word, so it can't be mistaken for a title.
  • --json on jd new prints { "ok": true, … } or { "ok": false, "code": "…", "message": "…" }. Branch on code. The message is for people, and may be reworded.
  • Match lists, reports, and errors go to stderr.

The MCP server tells your agent all of this. You don't need to.

Help

jd help          # shows all commands
jd version       # print the version

A shorter path in your zsh prompt

Johnny.Decimal paths can be long. This is by design: you should name your folders expressively, for human consumption. But if you show it in your prompt you end up with something like this.

/Users/Shared/D25 Johnny.Decimal/10-19 Business administration/11 The business & its people/11.11 Structure & registrations $

This utility shortens it to only show the final folder and, if you have multiple systems, the SYS: identifier at the front.

D25:…/11.11 Structure & registrations $

My multi-line prompt

If you want my multi-line prompt:

┏╸D25:…/11.11 Structure & registrations
┗╸mymac ❯❯
  • First line is the shortened path. If the last command failed, its exit status is in front of it.
  • Second line is your hostname then a couple of ❯❯ chevrons.
  • I use this on multiple machines, where I set different bright chevron colours to help me know where I am. Set JD_CHEVRON1 and JD_CHEVRON2.
  • Optional: For git status, the prompt calls gitprompt. Load git-prompt.zsh if you know what that is; otherwise ignore.

Install

The code and installation documentation is at cli.johnnydecimal.com. I won't repeat it here as I'll just forget to update it.

Known bugs

Many! This tool is very early in its development and will change often. I'll blog major changes.

See the repository README for update instructions.

AI attribution

  • Johnny:
    • Designs the utility, i.e. decides what it does and how it behaves.
    • Writes the words on this page.
  • Claude:
    • Writes the code.
    • Writes the text in the repository, e.g. the installation instructions, which Johnny then edits to save you from reading too much Claude 🫠.

Footnotes

  1. PRs welcome if you do. ↩