{"id":14008458,"url":"https://github.com/jaredrummler/KtSh","last_synced_at":"2025-07-24T03:32:58.497Z","repository":{"id":37465573,"uuid":"76073983","full_name":"jaredrummler/KtSh","owner":"jaredrummler","description":"Execute shell commands on Android or the JVM","archived":false,"fork":false,"pushed_at":"2022-06-05T22:14:46.000Z","size":3583,"stargazers_count":716,"open_issues_count":12,"forks_count":153,"subscribers_count":33,"default_branch":"main","last_synced_at":"2024-11-22T05:04:43.768Z","etag":null,"topics":["android","root","shell","superuser"],"latest_commit_sha":null,"homepage":"http://jaredrummler.github.io/ktsh/","language":"Kotlin","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/jaredrummler.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2016-12-09T22:08:03.000Z","updated_at":"2024-11-15T19:03:46.000Z","dependencies_parsed_at":"2022-07-14T22:30:30.665Z","dependency_job_id":null,"html_url":"https://github.com/jaredrummler/KtSh","commit_stats":null,"previous_names":["jaredrummler/android-shell","jrummyapps/android-shell"],"tags_count":1,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jaredrummler%2FKtSh","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jaredrummler%2FKtSh/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jaredrummler%2FKtSh/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jaredrummler%2FKtSh/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/jaredrummler","download_url":"https://codeload.github.com/jaredrummler/KtSh/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":227410706,"owners_count":17774787,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["android","root","shell","superuser"],"created_at":"2024-08-10T11:01:41.712Z","updated_at":"2024-11-30T19:31:11.854Z","avatar_url":"https://github.com/jaredrummler.png","language":"Kotlin","readme":"# KtSh\n\n\u003cimg src=\".github/ktsh-demo.gif\" align=\"left\" hspace=\"10\" vspace=\"10\"\u003e\u003c/a\u003e\n\n**An open source library to execute shell commands on Android or the JVM, written in Kotlin.**\n\n\u003ca target=\"_blank\" href=\"LICENSE\"\u003e\u003cimg src=\"http://img.shields.io/:license-apache-blue.svg\" alt=\"License\" /\u003e\u003c/a\u003e\n\u003ca target=\"_blank\" href=\"https://travis-ci.org/jaredrummler/KtSh\"\u003e\u003cimg src=\"https://travis-ci.org/jaredrummler/KtSh.svg?branch=master\" alt=\"Build Status\" /\u003e\u003c/a\u003e\n\u003ca target=\"_blank\" href=\"https://maven-badges.herokuapp.com/maven-central/com.jaredrummler/ktsh\"\u003e\u003cimg src=\"https://maven-badges.herokuapp.com/maven-central/com.jaredrummler/ktsh/badge.svg\" alt=\"Maven Central\" /\u003e\u003c/a\u003e\n\u003ca target=\"_blank\" href=\"https://twitter.com/jaredrummler\"\u003e\u003cimg src=\"https://img.shields.io/twitter/follow/jaredrummler.svg?style=social\" /\u003e\u003c/a\u003e\n\n# Downloads\n\nDownload [the latest JAR](https://repo1.maven.org/maven2/com/jaredrummler/ktsh/1.0.0/ktsh-1.0.0.jar) or grab via Gradle:\n\n```groovy\nimplementation 'com.jaredrummler:ktsh:1.0.0'\n```\n\nAlternatively, you can simply copy [`Shell.kt`](library/src/main/kotlin/com/jaredrummler/ktsh/Shell.kt) file to your project.\n\n# Usage\n\n#### Basic usage:\n\n```kotlin\nval shell = Shell(\"sh\")                         // create a shell\nval result = shell.run(\"echo 'Hello, World!'\")  // execute a command\nif (result.isSuccess) {                         // check if the exit-code was 0\n    println(result.stdout())                    // prints \"Hello, World!\"\n}\n```\n\n#### Construct a new `Shell` instance:\n\n```kotlin\n// Construct a new shell instance with additional environment variables\nval shell = Shell(\"sh\", \"USER\" to \"Chuck Norris\", \"ENV_VAR\" to \"VALUE\")\n\n// Construct a new shell instance with path to the shell:\nval bash = Shell(\"/bin/bash\")\n```\n\nNote: If the shell does not exist a `Shell.NotFoundException` is thrown as a `RuntimeException`.\n\n#### Execute a command and get the result:\n\n```kotlin\nval shell = Shell.SH\nval result: Shell.Command.Result = shell.run(\"ls\")\n```\n\nA `Shell.Command.Result` contains the following:\n\n- `stdout`:   A list of lines read from the standard input stream.\n- `stderr`:   A list of lines read from the standard error stream.\n- `exitCode`: The exit status from running the command.\n- `details`:  Additional information (start, stop, elapsed time, id, command)\n\n#### Add a callback when stdout or stderr is read:\n\n```kotlin\nshell.addOnStderrLineListener(object : Shell.OnLineListener {\n  override fun onLine(line: String) {\n      // do something\n  }\n})\n```\n\n#### Add a callback that is invoked each time a command completes:\n\n```kotlin\nshell.addOnCommandResultListener(object : Shell.OnCommandResultListener {\n  override fun onResult(result: Shell.Command.Result) {\n    // do something with the result\n  }\n})\n```\n\n#### Execute a command with custom options:\n\nOptionally, you can configure how each command executes by setting a timeout, redirecting stderr to stdout, add callbacks for when the command reads a line from stdout/stderr or is cancelled.\n\n```kotlin\n// NOTE: all of these are optional\nval result = Shell.SH.run(command) {\n  // Kill the command after 1 minute\n  timeout = Shell.Timeout(1, TimeUnit.MINUTES)\n  // Redirect STDOUT to STDERR\n  redirectErrorStream = false\n  // Callbacks:\n  onCancelled = {\n    // The command was cancelled\n  }\n  onStdErr = { line: String -\u003e\n    // Do something when reading a line from standard error stream\n  }\n  onStdOut = { line: String -\u003e\n    // Do something when reading a line from standard output stream\n  }\n  // Do not notify any listeners added via Shell.addOnStderrLineListener and Shell.addOnStdoutLineListener\n  notify = false\n}\n```\n\n#### Check the state of the shell:\n\n```kotlin\nif (shell.isRunning()) {\n  // The shell is running a command\n} else if (shell.isShutdown()) {\n  // The shell has been killed\n} else if (shell.isIdle()) {\n  // The shell is open and not running any commands\n}\n```\n\nor\n\n```kotlin\nwhen (shell.state) {\n  State.Idle -\u003e TODO()\n  State.Running -\u003e TODO()\n  State.Shutdown -\u003e TODO()\n}\n```\n\n#### Shutdown the shell\n\n```kotlin\nshell.shutdown()\n```\n\n#### Interrupt waiting for a command to complete:\n\n```kotlin\nshell.interrupt()\n```\n\n# Background processing on Android\n\nCreating a new instance of a `Shell` or executing commands should be done on a separate thread other than the UI thread. This is up to the library user. An example of this can be found in the [demo](demo) project using Kotlin coroutines and AndroidX libraries:\n\n```kotlin\nfun run(\n    shell: Shell,\n    command: String,\n    callback: (result: Shell.Command.Result) -\u003e Unit\n) = viewModelScope.launch {\n    val result = withContext(Dispatchers.IO) { shell.run(command) }\n    withContext(Dispatchers.Main) { callback(result) }\n}\n\n```\n# Structure\n\n* `buildSrc` - contains dependencies, plugins, versions for Gradle build logic\n* `build.gradle.kts` - root gradle config file\n* `settings.gradle.kts` - root gradle settings file\n* `library` - the ktsh library\n* `library/src/test` - unit tests for the library\n* `demo` - Android demo project using ktsh\n* `scripts` - scripts to publish library to maven central\n* `.github` - any files for the github page\n\n# Similar projects:\n\n- [libsu](https://github.com/topjohnwu/libsu) by John Wu (topjohnwu)\n- [libsuperuser](https://github.com/Chainfire/libsuperuser) by Jorrit Jongma (Chainfire)\n\n# License\n\n    Copyright (C) 2021 Jared Rummler\n\n    Licensed under the Apache License, Version 2.0 (the \"License\");\n    you may not use this file except in compliance with the License.\n    You may obtain a copy of the License at\n\n       http://www.apache.org/licenses/LICENSE-2.0\n\n    Unless required by applicable law or agreed to in writing, software\n    distributed under the License is distributed on an \"AS IS\" BASIS,\n    WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n    See the License for the specific language governing permissions and\n    limitations under the License.\n","funding_links":[],"categories":["Java"],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjaredrummler%2FKtSh","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjaredrummler%2FKtSh","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjaredrummler%2FKtSh/lists"}