Run shell commands from Kotlin scripts, apps or Gradle tasks with ease.

Turtle simplifies the process of running external commands and processes from your Kotlin (or Java) code. It comes bundled with a selection of built-in functions, such as opening MacOS applications and dealing with Git. Running shell commands easily is particularly useful from within Kotlin scripts, command line applications and Gradle tasks.

Turtle is mainly aimed at MacOS, some of the shell commands may not exist or work as expected on Linux or Windows. It is planned in the future to alter the API surface to make this clearer when calling commands.

Features • Install • Usage • Contributing

Simply specify the comamnd and its arguments to easily run and retrieve output.

Various commands are provided, such as creating a Git commit and opening files.

Specify a sequence of commands to run within a function block.

When a command produces an error, the exit code and error output is thrown as an exception.

Turtle is provided as a Gradle/Maven dependency.

• v0.5.0 onwards are available via Maven Central.
• v0.3.0 and v0.4.0 had issues, so please use v0.5.0 or later.
• Earlier releases were available via Bintray/JCenter.

dependencies {
  implementation("com.lordcodes.turtle:turtle:0.10.0")
}

dependencies {
  implementation 'com.lordcodes.turtle:turtle:0.10.0'
}

Note: As mentioned above Turtle is mainly aimed at MacOS and so some shell commands may not exist or work as expected on Linux or Windows.

To run a single custom command, just call shellRun() and provide the command and arguments.

val output = shellRun("git", listOf("rev-parse", "--abbrev-ref", "HEAD"))
println(output) // Current branch name, e.g. master

The working directory can be provided, to run the command in a particular location. ShellLocation provides easy access to some useful locations, such as the user's home directory.

val turtleProject = ShellLocation.HOME.resolve("projects/turtle")
val output = shellRun("git", listOf("rev-parse", "--abbrev-ref", "HEAD"), turtleProject)
println(output) // Current branch name, e.g. master

To run a series of commands or use the built-in commands, just call shellRun {}.

shellRun {
  command("mkdir tortoise")

  changeWorkingDirectory("tortoise")

  git.commit("Initial commit")
  git.addTag("v1.2", "Release v1.2")

  files.openApplication("Spotify")
}

The initial working directory can be specified.

val turtleProject = ShellLocation.HOME.resolve("projects/turtle")
shellRun(turtleProject) {
  …
}

shellRun {
  git.init()
  git.status()
  git.commit("Commit message")
  git.commitAllChanges("Commit message")
  git.push("origin", "master")
  git.pull()
  git.checkout("release")
  git.clone("https://github.com/lordcodes/turtle.git")
  git.addTag("v1.1", "Release v1.1")
  git.pushTag("v1.1")
  git.currentBranch()
}

shellRun {
  files.openFile("script.kts")
  files.openApplication("Mail")
  files.createSymlink("target", "link")
  files.readSymlink("link")
}

Extra commands can easily be added by either calling command or by extending ShellScript. If you have created a command that you think should be built in, please feel free to open a PR.

Instead of returning output as a String via command, you can instead receive it as a Sequence using commandSequence. The sequence provides standard output and standard error line-by-line.

commandSequence("cat", listOf("/path/to/largeFile.txt")).forEach { line ->
    println(line)
}

If you notice any bugs or have a new feature to suggest, please check out the contributing guide. If you want to make changes, please make sure to discuss anything big before putting in the effort of creating the PR.

To reach out, please contact @lordcodes on Twitter.