Shellit.kak /bin/sh -c "$@" a Kakoune editor command line gateway

Shellit.kak a Kakoune editor command line gateway.
/bin/sh -c "${@:1}"

See or clone the docs/javadoc, docs/coverage, and docs/tests for the API.

Download pre-built shellit.jar with sha256 checksum.
$ openssl dgst -sha256 shellit.kak-<version>.jar

      shellit [-i | -debug] <BINARY|JAR|OTHER> [FLAGS] [args ...]

        ignore output in Kakoune client

        terminal debugging of a java.lang.Process

      is on your PATH|CLASSPATH|OTHER

      are native to the BINARY|JAR|OTHER

      Shellit a Kakoune command line gateway. Easily invoke a
      binary, jar, or any script/executable without leaving
      the kakoune command line. With automated temp file setup
      and teardown on stdin/out/err. Default invocation
      opens the temporary file in current kakoune client.
      Kakoune exit :q triggers temporary file deletion,
      invoke kakoune's :write command to save the buffers
      output to a file name and destination of your choosing.

      :shellit stderr available in kakoune *debug* buffer
      :shellit -i flag success/failure -markup in kakoune
      :shellit python3 --help
      :shellit perl --help
      :shellit --help

      :shellit brew info shellcheck
      :shellit brew home shellcheck
      :shellit howdoi -c -n 5 catch an exception kotlin
      :shellit curl

      :ansi-render see
      :shellit open

Woman had me my man-pants, press play on the motivational song spotify Schubert: Ave Maria, D.839 or youtube and put yourself in scrutineers mode. Peer review time!

HTML format:
docs/javadoc/index.html docstrings with UML diagrams and Harvard referencing style.
docs/coverage/index.html 96% coverage.
docs/tests/index.html viewable results of all tests 102/102 passing.


@see gradle wrapper
@see shadowJar

Run the gradle command from the terminal in shellit.kak top level directory:
$ gradle wrapper

$ ./gradlew shadowJar

$ gradlew.bat shadowJar

The fat-jar is located:
$ shellit.kak/build/libs/shellit.kak-<version>.jar

Build with passing tests use:
$ ./gradlew build

Shutdown the gradle daemon:
$ ./gradlew --stop

Gradle is a command line tool:
$ ./gradlew --help
$ ./gradlew tasks
$ ./gradlew dependencies --configuration compileClasspath

Gradle can also build shared and static libraries, and executables in Assembler, C/C++ and Obj-C/C++


The Software Development Kit Manager: SDKMAN! installs smoothly on Mac OSX, Linux, WLS, Cygwin, Solaris and FreeBSD. We also support Bash and ZSH shells’.

$ curl -s "" | bash
$ source "$HOME/.sdkman/bin/"
$ sdk version
$ sdk install java 11.0.6.hs-adpt  // moving target^1
$ sdk install kotlin
$ sdk install gradle  
$ sdk install kscript  // optional


# kakoune command
define-command -params .. shellit %{ evaluate-commands %sh{ java -jar <your-path-to>/shellit.kak-<version>.jar "${kak_session}" "${@:1}" } }

# .<shell>rc command
if [[ -d "$HOME/.local/jars" ]] ; then
    export JARPATH
# `.jar` suffix is no longer required from bash command line
exec java -jar "$JARPATH/$1.jar" "${@:2}"
exit 1

# .bash_alias command
alias jj=<your-path-to>/

Alternate Setup (linux/osx/*nix)

# kakoune command
define-command -params .. shellit %{ evaluate-commands %sh{ "${kak_session}" "${@:1}" } }

# author Tommaso, P 2019, How to make a JAR file Linux executable,,
# viewed on 6 Jan 2019, <>

MYSELF=`which "$0" 2>/dev/null`

[ $? -gt 0 -a -f "$0" ] && MYSELF="./$0"


if test -n "$JAVA_HOME"; then

exec "$java" $java_args -jar $MYSELF "$@"

exit 1

$ cat shellit.kak-<version>.jar > && chmod u+x,u-w,og-rwx && mv ~/.local/bin/

shellit.kak see for details.


 * bitbucket repo  ✅
 * uml diagrams  ✅
 * logger  ✅
 * mockk   ✅
 * tests and coverage  ✅
 * dokka api, docstrings and references  ✅
 * build fatjar  ✅
 * post on discuss.kakoune  ✅

Before running ./gradlew command run: $ pgrep java, note the process_id of all current running java processes.
Then run all the required ./gradlew commands, after re-run the previous pgrep command for any additional unclosed java process noting their process_id.
You can then use the: $ kill process_id to terminate the additional running java process.
The cause is strictly ./gradlew command and NOT or shellit.jar.
@see The Gradle Daemon for more information.

For best practices with internet-of-things::IO().

# kakoune command
define-command -params .. shellit %{ evaluate-commands %sh{ "${kak_session}" "${@:1}" } }

java<your>.policy -cp <path>/shellit.kak-<version>.jar org.kjd.shellit.kak.ShellitKt "${@:1}"  

Kakoune General Information

Kakoune is an open source modal editor. The source code lives on github mawww/kakoune.
A discussion on the repository structure of ’community plugins’ for Kakoune can be reviewed here: Standardi(s|z)ation of plugin file-structure layout #2402.
Read the Kakoune wiki for information on install options via a Plugin Manager.

Thank you to the Kakoune community 180+ contributors for a great modal editor in the terminal. I use it daily for the keyboard shortcuts.

That’s it for the shellit.kak readme, anything else you may need to know just pick up a book and read it Polar Bookshelf. Thanks all. Bye.

Shellit.kak is verbose in it’s api / tests / coverage / docstrings / readme.

On the kakoune command line I can run any script or binary/jar/other…If I need to view stdin/out/err from the script/binary/jar/other I can just do…:next-buffer to view it’s sdtin/out in a temporary file.


#! /usr/bin/env bash

# -------------------------------------------------------------------------------------------------- #
cat << EOF

Usage: ${0##*/} [pdf|http|name]

$ polar filename.pdf
$ polar http://.../URI-ends-with.pdf
$ polar "http://.../URI-does-not-end-with-pdf" <name>

URI = scheme:[//authority]path[?query][#fragment]

  polar :
  fd    :
  curl  :

# -------------------------------------------------------------------------------------------------- #
if [ $# -eq 0 ]; then print_help; exit; fi
# -------------------------------------------------------------------------------------------------- #
# -------------------------------------------------------------------------------------------------- #
check_curl() {
  if echo "$ARG" | grep -E '^http://|^https://'; then
    if [[ "$NARG" -eq 1 ]] ; then
      curl -O "$ARG"
      ARG="$(fd --show-errors --changed-within 1min --type f --extension pdf --max-depth 1 .)"
      curl "$1" --output "$2.pdf"
# -------------------------------------------------------------------------------------------------- #
check_polar() {
  PROCESS_NUM="$(pgrep Polar | wc -l | awk '{print $1}')"

  if [ "$PROCESS_NUM" -eq 0 ] ; then
    open -a /Applications/Polar\
    sleep 10s
# -------------------------------------------------------------------------------------------------- #
open_pdf_polar() {
  open -a /Applications/Polar\ "$ARG"
  sleep 5s
  if $CURL; then rm "$ARG"; fi
# -------------------------------------------------------------------------------------------------- #
check_curl "$ARG"
exit $?

Task/Job/Process must complete within 20 seconds, this is a design choice, so no long running tasks.

Never have to shell out or tmux spilt screen again just run it from :shellit.kak.

Example of stdout I use and remember this can be any script/binary/jar/other:

:shellit.kak 10.1016/j.sbspro.2012.09.714 10.1126/science.169.3946.635
:write file-name.txt

#! /usr/bin/env bash

# -------------------------------------------------------------------------------------------------- #
cat << EOF

Usage: ${0##*/} 10.1145/3360610 [args...]

$ cite 10.1016/j.sbspro.2012.09.714 10.1126/science.169.3946.635

Loop over args, append arg to doi path and download
with no progress indicator, sending result to stdout.
API: <>

  curl :

# -------------------------------------------------------------------------------------------------- #
if [ $# -eq 0 ]; then print_help; exit; fi
# -------------------------------------------------------------------------------------------------- #
# -------------------------------------------------------------------------------------------------- #
for arg
  curl -sLH "Accept: text/x-bibliography; style=harvard3""$arg"
# -------------------------------------------------------------------------------------------------- #
exit $?
:shellit -i raco docs cmdline

-i native flag to shellit.kak ignore output in kak client (don’t open the stdout tmp file).
raco is a native binary on $PATH.
docs argument to raco binary.
cmdline argument to docs.

Results in opening the default system browser at the search term without leaving kakoune command line.

no-mouse required, straight to work source.

Of course when in doubt just view the stdout tmp file:

:shellit raco --help

Apologies I am not trying to continuously bump this thread, I cannot edit any of my posts +24hours, so cause and effect.

Winner, winner, chicken dinner!!

:sh shfmt -s %val{buffile}
:sh shfmt -s -mn %val{buffile}
:buffer-next # for tmp file stdout

!insert-output:fails (too excited all use-cases not explored...yet! Finished on a high)

Bracing for the community rebuttal :smile:

Look at that you get all excited and the next day “BUG FOUND” :frowning: thanks to this kak_escape thread and the main discussion link, a good read.

It’s a quick bug fix to do, going to take a little extra time on weekend to adjust the code base more to my liking.

My pasts threads are always locked so I cannot edit them. All I can do is reply to my own posts, what a mess. Bye :wave:

A precursor to shellit.kak update I thought I would share a kotlin command line script I use on a daily basis.

$ notes -h


see section Application Usage
$ file notes
notes: ASCII text
$ ls -l
-r-x------ 22B notes

$ kak notes.kt


Processor: 2.5 GHz Intel Core i5 quad-core pre-2011
Memory: 8 GB 1333 MHz DDR3 pre-2011
hyperfine --warmup 3 ‘notes -h’



100ms: Unless your a Formula 1 engineer, you will never notice it.

Kotlin + Java + Command Line = Simple

Thanks guys.

Shellit.kak v2.0 - You can now build complex expressions from the kakoune command line…all invoke /bin/sh -c ... explicitly.


:sh sfmt -s %val{buffile}
:sh shellcheck -fgcc -Cnever %val{buffile}

:sh -i ls -l > file.txt
:sh notes -r | grep -E kak

:sh "pgrep Polar | wc -l | awk '{print $1}'"
:sh python3 --help && echo && pip3 --help

Or from the terminal you can send stdout to the kakoune client taking advantage of the automatic temp file setup and tear down on kakoune exit.

$ shellit.* 12345 cat file1.tex && echo && ls -l file1.tex

Where 12345 is the kak-client.

When in doubt just double quote the “complex expression” and your good to go.

If your switching between environments just bring shellit.kak with you for command line consistency.

My hope is that it improves your workflow and productivity as much as it has mine.

Thanks guys, try it out and bring it back in pieces :smile:

today’s complex expression:

:sh "ls -R | grep -v ^$ | tail -n 4 ; echo ; ls -1p | grep -v ^d | sort"

Without leaving my favorite text editor. Yah!!

Fun fact: using shellit.kak results in a 65% code base reduction to the community plugin explain-shell.kak.

define-command -docstring "Explain the selected shell command (online api)" explain-shell %{ try %{
  nop %sh{
    sel=$(echo ${kak_selection} | sed 's/^[ \t\v\f]*//;s/[ \t\v\f]*$//')
    sel_len=$(echo -n ${sel} | wc -m)
    if [ ${sel_len} -gt 1 ]; then
      shellit.kak "$kak_session" 'curl -Gs ""$(tput cols) --data-urlencode "q=${sel}"'

Yes, I have sent the author an email with an alternate refactored solution for the web sites v2 api.

Based on word count: 1-56/161

Release shellit.kak-3.0 continuum 09/04/2020

Interface Composition

Continuum allows you to manage semantic versioning and changelog generation files.

At any given time, the .changes/ directory looks like:

    └── next-release
        ├── major-DATE-TIME-RANDOM.json
        ├── minor-20200323-205319-374.json
        └── patch-20200323-205319-854.json
    ├── 1.1.0.vYEAR-MONTH-DAY.json
    ├── 1.1.1.v2020-05-25.json
    ├── 1.1.2.v2020-06-30.json

Continuum takes all the created JSON change files from the next-release directory and
concatenates them into a single JSON file for that release (e.g 1.12.0.v1999-12-31.json).


shellit [continuum|cm] [-h] [option] […]

alias cm continuum

Prefix with the shellit command:
:sh shellit.kak continuum [option] [...]

Expands to posix shell:
$ /bin/sh shellit.kak continuum [option] [...]

   $ continuum add major "a description requires double quotes, it appears in the change log"
   $ continuum add minor "a description requires double quotes, it appears in the change log"
   $ continuum add patch "a description requires double quotes, it appears in the change log"
   $ continuum release
   $ continuum current
   $ continuum changelog >

Source adapted:

$ cat

# Changelog
Note: version releases in the 0.x.y range may introduce breaking changes.

## 1.1.1 - 2020-04-09

- patch: patch update run from continuum test

## 1.1.0 - 2020-04-08

- minor: minor update run from continuum test

## 1.0.0 - 2020-04-07

- major: major update run from continuum test
- minor: minor update run from continuum test
- patch: patch update run from continuum test
$ echo 'java -cp $CLASSPATH org.kjd.shellit.kak.ShellitKt "${@}"' > shellit
$ chmod u+x,u-w,og-rwx shellit
$ mv shellit $HOME/local/bin

# kakoune command
define-command -docstring "shellit /bin/sh -c $@" \
  -params .. shellit %{ nop %sh{ shellit $kak_session "${@:1}" } }
# or
define-command -docstring "shellit /bin/sh -c $@" \
  -params .. shellit %{ nop %sh{ java -cp $CLASSPATH org.kjd.shellit.kak.ShellitKt $kak_session "${@}" } }

alias global sh shellit

# `:sh shellit cm add patch "a short description"` throws
# ERROR: continuum add requires 4 positional arguments != 6
# This is not an issue when used directly from the terminal.
# So the kakoune editor use-case workaround is:
define-command -docstring 'continuum major|minor|patch "a short description"' \
  -params .. continuum %{ nop %sh{ shellit "cm" "add" "${@:1}" } }

# kakoune usage 
:sh shellit -h
:sh shellit continuum -h
:continuum patch "a workaround for positional arguments"