# 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/jdhq/configuration) and [jq](https://jqlang.github.io/jq/).

## 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':
#   10-19 Life admin/15 Travel/15.52 Family trip
#   20-29 Hobbies/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 <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.

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

## Help

```sh
p76 help         # shows all commands
p76 version      # print the version
```

## Known bugs

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

See the repository README for update instructions.

## 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 system ID and the final path segment.

```
D25:…/11.11 Structure & registrations $
```

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

## 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 🫠.