(Command LookUp)

Got an overwhelming number of command line scripts and functions? So many you've actually started to forget what options you have available, or what some of them do? Try Clu!

What does it do?

Clu allows provides a full text search of the name, description, and details of your scripts. When a script includes a "help" command, Clu will call it and display current usage docs instead of potentially outdated ones from its cache.

Scroll down to see some examples of its output.

Future looking

The intent is to support tldr style "cheats" for your scripts too. The example TOML template below contains commented out cheats if you feel like writing them now, but Clu currently ignores that data.

Being able to arrow through search results and choose one to see the full details of.

Installation

Clu is written in Raku, and uses the zef package manager for installation.

If you've already got Raku and zef installed then just run:

zef install Clu

Raku install quick-guide

Use Homebrew to install Rakudo. That's the Raku virtual machine. If you install the Rakudo Star Bundle then zef will come along for the ride. You can download it from those links, or install it with homebrew.

brew install rakudo-star

Now, go back and run the zef install command above.

Usage

Usage:
  clu add <path>
  clu find [<search_strings> ...]
  clu list
  clu remove <command_name>
  clu show <command_name>
  clu template <destination>
  clu update <path>

Documenting a new Command

The first step is to create a TOML file for each cli tool you wish to document. Clu doesn't care where these live. My advice is to put them alongside your script, so that when you share your script with others, it can go along for the ride, even if they're not using Clu, TOML is still very readable.

Clu doesn't care what the file is named, so long as it ends with .toml but personally I've been using the convention of <command_name>.meta.toml and putting it in the same directory as the command I'm documenting.

The template comand will generate a TOML file for you where you just have to fill in the blanks.

run clu template path/to/my_command.meta.toml

For example: If you have a foo command you'd make a foo.meta.toml file. It doesn't matter if you're documenting an executable or a shell function.

Edit your new TOML file.
run clu add path/to/my_command.meta.toml

That's it. If you ever need to update / change the documentation just edit the TOML file and run clu update <path/to/my_command.meta.toml>. It'll find the command with the matching name in the database, and replace it.

Showing a command

clu show <command_name> will display the name, description, and usage of the specified command (if found).

Output looks like this:

❯ clu show rg-ignores
rg-ignores : finds files that rg may be using to ignore patterns

USAGE: rg-ignores <path>

       Use me when rg isn't finding something you expect
       and rg --hidden isn't helping.
       Looks for files that RipGrep will consult
       in order to find patterns to ignore.

       Note: using --hidden --no-ignore is a short term fix

--------------------
type: executable
lang: bash
location: /Users/masukomi/bin/rg-ignores

source repo: https://github.com/masukomi/masuconfigs
source url: https://github.com/masukomi/masuconfigs/blob/master/bin/rg-ignores

Finding a command

clu find <search terms> Don't bother quoting the search terms. Something like clu find foo bar baz is fine.

Clu will perform a full text search for your terms on the name, description, and language fields, and display the results.

If you want more details, run clu show <command name> for the command you've found.

Output looks like this:

❯ clu find find
rg-ignores          | finds files that rg may be using to ignore patterns
git-oldest-ancestor | finds the oldest common ancestor between two git treeishes

Listing all commands

clu list will list everything for you. Output looks like this:

❯ clu list
backtrace_details   | Pairs a backtrace with the corresponding lines of code
bak                 | bak moves or copies the proffered file to a .back version
blankless           | converts whitespace-only lines to empty lines.
color_test          | outputs a smooth gradient band along the RGB spectrum
git-branch-pr       | Shows or opens the Pull Request for the current branch
git-oldest-ancestor | finds the oldest common ancestor between two git treeishes
hr                  | outputs a horizontal rule the width of your terminal
is_brewed           | indicates if a package is installed via homebrew
rg-ignores          | finds files that rg may be using to ignore patterns
watch_when          | Polls a command and reports when its output changes

Updating a command

clu update <path/to/my_command.meta.toml> will find the existing command with the name specified in the TOML and update its data. If you have changed the name of the command you'll need to remove and add instead of update.

Removing a command

clu remove <command_name> will remove the command with the specified name.

Syncing between machines

There's no inherent syncing here. Sorry. You can copy the db from ~/.config/clu/database.db to another machine, or, you can boot it up on a new system and run something like this to ingest all your toml files.

find ~/folder/with/my/clu_toml_files -name "*.meta.toml" -exec clu add '{}' \;