# The JD CLI > Tools to help you use Johnny.Decimal at your command-line. 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.[^pr] [^pr]: PRs welcome if you do. Requires the [configuration file](https://johnnydecimal.com/documentation/configuration) and [jq](https://jqlang.github.io/jq/). This page shows you what it does – for installation instructions, see [the GitHub repository at cli.johnnydecimal.com](https://github.com/johnnydecimal/cli.johnnydecimal.com/blob/main/README.md#installation). ## Basic movement ```sh 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. ```sh 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. ```sh jd family trip # cd to 15.52 without ambiguity ``` If the first term is a number, your search is scoped to that category/area. ```sh 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. ```sh 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. ```sh jd 67.89 # JDex entry exists; folder does not # 67.89 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. ```sh jd 98.76 # jd: the JDex has 98.76 but there is no folder for category 98 ``` ## Multiple systems If you have [multiple systems](https://johnnydecimal.com/documentation/multiple-systems-overview), the script detects them from the configuration file and gives you a command for each. Say I have `d25` and `p76` defined. ```sh 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. ```sh 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. ```sh 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`. ```sh 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. ```sh 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. ```sh ~/.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](https://johnnydecimal.com/jdhq/mcp-server) tells your agent all of this. You don't need to. ## Help ```sh 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](https://github.com/woefe/git-prompt.zsh) if you know what that is; otherwise ignore. ## Install The code and installation documentation is at [cli.johnnydecimal.com](https://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 🫠.