AnotherTerm-docs

Another Term documentation (wiki replacement)

View this documentation on GitHub View the described project on GitHub GitHub all releases Get it on Google Play Support Project

termsh

It resides in the native libraries directory in order to prevent accidental deletion and the “execute” field in the favorite editor contains proper TERMSH variable definition by default.

Note: Please, don’t forget to define TERMSH_UID environment variable (see description below) in case, you are using any chrooted environment where an emulated user ID is not the same as the real one.

For version MkIIIv67 and later:

Location

TERMSH="$LIB_DIR/libtermsh.so"

Usage

"$TERMSH" [-r|--raw] <command> [<args...>]

Commands

Note: Any UI elements (except notifications) and related commands will block until a terminal activity corresponding to the related session is shown.

help
This message.

notify [-i|--id <id>] [--] [<message>]
notify -r|--remove -i|--id <id>
Display notification, stdin will be used if no message argument provided.
  • -i|--id <id> — notification id.
  • -r|--remove — remove notification by id.

clipboard-copy [<string>]
Copy to clipboard (only when the user is interacting with the current session UI).
If no <string> is provided, the stdin is used.
It always uses text/plain mime type and presumes UTF-8 input encoding.

The clipboard-copy permission must be granted. Exit code 1 will be returned otherwise.


uri [--] <file>
uri [-m|--mime <mime>] [-n|--name <name>] [-s|--size <size>]
uri -c|--close-stream [--] <URI>
uri -l|--list-streams
Get own content provider URI for specified file or stream or close previously opened stream.
Command exits immediately unless -w|--wait is specified. In case of stream, the <URI> will automatically be unbound when stream is read to its EOF or it can be closed by -c|--close-stream <URI> option.
  • -m|--mime <mime> — Mime type, */* - default.
  • -n|--name <name> — name to use for representing a stream.
  • -s|--size <size> — size in bytes to provide in the query answer if input is a stream. The Google GMail client, for example, treats absence of the size as zero size even in case of a stream.
  • -w|--wait — wait for the stream until it reaches EOF then close it and exit; $TERMSH termination also closes the stream. Use when you need to keep a shell pipe line running;
    example: tar -czv * | "$TERMSH" uri -w
  • -c|--close-stream <URI> — unbind the stream <URI> and free related resources.
  • -l|--list-streams — list all bound stream URIs.

view|edit [<options...>] [--] <file|URI>
Open for view / edit with appropriate temporary access rights.
Command exits after interaction with user.
  • -N|--notify — post a notification instead of open the chooser dialog.
  • -m|--mime <mime> — Mime type, */* - default.
  • -p|--prompt <prompt> — to show in chooser dialog.
  • -r|--recipient <recipient> — a particular activity to send this intent to. <recipient> can be:
    • An activity class name of this application.
    • An activity of another application in form: <package>/<activity_class>
      (<activity_class> can begin with a '.' (dot) to use <package> as it's prefix:
      foo.bar/.Act => foo.bar/foo.bar.Act).

    Example:

    "$TERMSH" view -r 'green_green_avk.anotherterm.FavoriteEditorActivity' -u 'local-terminal:/opts?execute=my_awesome_script'
  • -u|--uri — use URI instead of file.

send [<options...>] [--] [<file|URI> ...]
Send (android.intent.action.SEND or android.intent.action.SEND_MULTIPLE).
<file|URI> is treated as a file path if it does not match /^(?:[a-z0-9+.-]+):\/\//i.
'-' is used to represent the stdin.
Command exits after a stream was sent or after interaction with user if a file or URI is specified.
  • -N|--notify — post a notification instead of open the chooser dialog.
  • -m|--mime <mime> — Mime type for an stdin stream, */* - default.
  • -n|--name <name> — name to use for representing an stdin stream.
  • -s|--size <size> — size in bytes to provide in the query answer if input is an stdin stream. The Google GMail client, for example, treats absence of the size as zero size even in case of a stream.
  • -p|--prompt <prompt> — to show in the chooser dialog.
  • --text <text> — android.intent.extra.TEXT.
  • --text-stdin — the same but from the stdin1.
  • --html <HTML> — android.intent.extra.HTML_TEXT.
    android.intent.extra.TEXT will be set to Html.fromHtml(<HTML>) if no --text <text> or --text-stdin is specified.
  • --html-stdin — the same but from the stdin1.
  • --subject <subject> — android.intent.extra.SUBJECT.
  • --email-to <address[ address]...> — android.intent.extra.EMAIL.
  • --email-cc <address[ address]...> — android.intent.extra.CC.
  • --email-bcc <address[ address]...> — android.intent.extra.BCC.

Examples:

convert cat.jpg -grayscale average - | "$TERMSH" send -m image/jpeg --subject 'My cat' --text 'Attached.' -

Note: Many applications, including the Google GMail client, require the stream size to be known beforehand… Streaming will not work with them in the case above.

convert cat.jpg -grayscale average cat_gray.jpg && "$TERMSH" send --subject 'My cat' --text 'Attached.' cat_gray.jpg

This will.

Or just resharing text content by value:

"$TERMSH" cat "$INPUT_URI" | "$TERMSH" send --text-stdin

can be useful to create an e-mail letter using a text file as its content.


pick [<options...>] [--] [<path>]
Show document picker dialog and put the selected content (or its URI) to:
  • file if <path> is a file;
  • file with the name provided by the content provider (or deduced from the URI)2 if <path> is a directory;
  • stdout if nothing is specified.
The http an https schemes are also supported along with the content and file ones.
Command exits after content was received or right after chooser dialog result if a URI is specified.
  • --insecure — connect via HTTPS even in case of invalid certificate.
  • -N|--notify — post a notification instead of open the chooser dialog.
  • -m|--mime <mime> — Mime type, */* - default.
  • -p|--prompt <prompt> — to show in chooser dialog.
  • -u|--uri — output URI instead of content.
  • -f|--force — permit destination overwriting.

Examples:

"$TERMSH" pick .
"$TERMSH" pick | tar -zxv


copy [-f|--force] [--insecure] [--progress] [-fp|--from-path|-fu|--from-uri <from>] [-tp|--to-path|-tu|--to-uri <to>]
Copy content. Only single files are supported now. The source URI scheme could be content, http or https. The destination URI scheme could be content only. If <from> or <to> is not specified, stdin or stdout will be used respectively. <to> can be a directory2.
  • -f|--force — permit destination overwriting.
  • --insecure — connect via HTTPS even in case of invalid certificate.
  • --progress — output current progress to stderr.

cat [--insecure] [--progress] [<URI> ...]
Concatenate specified URIs content to the stdout, '-' is used to represent the stdin. The URIs scheme could be content, http or https. If no URIs are given, the stdin will be used.
  • --insecure — connect via HTTPS even in case of invalid certificate.
  • --progress — output current progress to stderr.

Examples:

"$TERMSH" cat "content://$APP_ID.linksprovider/html/some_url_to_be_wrapped_into_html"

uri="$("$TERMSH" pick -u)"
"$TERMSH" cat "$uri" > "$("$TERMSH" name "$uri").new"


with-uris <name> <arg0> [<args...>] <URIs>

Warning: This command will probably not work with Android versions ≥ 10.

This command is supposed to be used with content sharing, viewing and editing feature. It runs a command with specified <URIs> represented by the procfs fd entries. The <URIs> is a single argument with the entries delimited by whitespaces. The URIs' content provider must be able to return the whole file descriptors for them.

It returns the actual command exit status and 127 or 1 in case of own failure.

Effect is the same as of 

execp(name, arg0, args..., "/proc/PID/fd/FD_URI0 /proc/PID/fd/FD_URI1 ...")

Example:

(Presuming Linux under PRoot is installed.)

~/edit.sh:

#!/bin/bash

msg() {
 echo
 echo "$1"
 echo
 read -n 1 -s -p 'Press any key' -t 5
}

if [[ -n $INPUT_URI ]]
then
 case "$INPUT_MIME" in
 text/*)
  termsh with-uris mcedit mcedit "$INPUT_URI"
  ;;
 *)
  export USE_OWN=1 # - marker for mc.ext
  # to avoid using Android applications as viewers
  termsh with-uris mcview mcview "$INPUT_URI"
  ;;
 esac
else
 msg 'Nothing to open'
fi

“Execute” field in favorite settings:

/system/bin/sh "$DATA_DIR/proots/linuxcontainers-debian-buster/run" '' '~/edit.sh'


name <URI>
Get the name provided by content provider (or deduced from the URI)2. 

size [--insecure] <URI>
Get the size provided by content provider or HTTP content-length header (or null if not defined). 

mime [--insecure] <URI>
Get the mime-type provided by content provider or HTTP content-type header (or */* if not defined). 

serial -l|--list
serial [-a|--adapter <address>] [-i|--insecure] [<baudrate>[/<databits>[/<stopbits>[/<parity>[/<flowcontrol>]]]]]
Connect to an USB serial dongle and use stdin / stdout.
  • -a|--adapter — use a dongle specified by <address>;
  • -i|--insecure — don't use a secure connection (Bluetooth);
  • -l|--list — list available UART dongles in the form <address> <description>.

Possible values:

  • baudrate: a positive number or 0*
  • databits: -*, 8, 7, 6, 5
  • stopbits: -*, 1, 1.5, 2
  • parity: -*, none, even, odd, mark, space
  • flowcontrol: -*, off, xon_xoff, rts_cts, dsr_dtr

* — preserve current value

Default: 0/-/-/-/-

Note: Alas, UART port settings (<baudrate>, <databits>, <stopbits>, <parity>, <flowcontrol>) cannot be applied to Bluetooth dongles using the Android Bluetooth stack.
See details.


uri-encode <string> [<allowed>]
URL-escape a <string> but don't touch characters from an <allowed> string.

If the <allowed> is not specified, java.net.URLEncode.encode(string, "UTF8") will be used. It escapes according to the application/x-www-form-urlencoded MIME format.

If the <allowed> is specified (even empty), android.net.Uri.encode(string, allowed) will be used. [A-Za-z0-9_!.~\'()*-] are always unaffected.


uri-decode <string>
URL-unescape a <string>.

request-permission <name> <message>
Ask the user by a dialog.
  • <name> — can be: favmgmt, pluginexec, clipboard-copy.
  • <message> — to show.

Return codes:

  • 0 — granted by user;
  • 1 — error occurred;
  • 2 — denied by user;
  • 3 — already granted.

revoke-permission <name>
Just revoke.

has-favorite <name>
Return 0 exit code if a favorite named <name> exists, 2 otherwise.

'Favorite management' permission must be granted in a favorite starting the shell from which this command is called. Exit code 1 will be returned otherwise.


create-shell-favorite [-t|--term <terminal_string>] <name> <execute>
Create a shell favorite named <name> executing <execute> script string. It fails with exit code 2 if <name> is already in use.

'Favorite management' permission must be granted in a favorite starting the shell from which this command is called. Exit code 1 will be returned otherwise.


plugin [--] <package_name> [<args...>]
plugin -h|--help [--] <package_name>
Execute a plugin specified by <package_name> or show its info page.

'Plugins execution' permission must be granted in a favorite starting the shell from which this command is called. Exit code 1 will be returned otherwise.


wakelock {is-held|acquire [<timeout>]|release}

is-held returns:

  • 0 — lock is active;
  • 2 — lock is not active.

<timeout> is a decimal value in seconds with one millisecond granularity.


show-XWL-session <UUID>

MkIV-dev24 and later (Wayland only)

Show a running XWayland session terminal window.

<UUID> is the UUID previously passed as a Wayland helper UUID and can be passed as either a decimal or 0xhexidecimal or 0octal value.

Example


Environment variables

  1. The scratchpad marshalling limit applies. ↩ ↩2

  2. If file name deduction fails, unnamed is used and exit code 2 is returned. ↩ ↩2 ↩3