TOML configuration guide for Tool-Tree

This guide is for Tool-Tree, the component that powers the function menu in the com.tool.tree Android app. All page configuration files must use TOML (XML is no longer supported). The parser lives in com.omarea.krscript.config.PageConfigReader and uses the org.tomlj:tomlj library.

This reference is intended for anyone authoring or maintaining a Tool-Tree .toml page: it documents every node type, every field (with its aliases, type, and default), and the runtime behavior around them - dependency evaluation, shell-script integration, page lifecycle, and load ordering. Sections 2-3 cover the shared rules and fields every node relies on; sections 5-16 document each node type in turn; sections 17-23 cover cross-cutting mechanics; sections 24-26 provide a worked example, a checklist of common mistakes, and a changelog of recently added fields.

A TOML configuration file describes the node tree of a page: each page is a list of nodes (group, action, switch, picker, text, page, editor, download, resource, menu, fab) displayed in the order they appear in the file. All nodes are declared flat at the top level of the document (dot-notation nesting like [[group.action]] has been removed) - a node that follows a [[group]] (and precedes the next one) automatically becomes a child of that group.

2. Syntax rules

2.1. Tables vs. arrays of tables

The parser accepts both a single TOML table such as [action] and an array-of-tables form such as [[action]]. The single-table form gives one entry; the double-bracket form is the repeatable form and is the recommended style for page nodes and child collections.

2.2. Node type = TOML table name

There is no separate type field for page nodes. A node's type is determined by its TOML table name. The root page parser reads the supported node tables from the document root:

2.3. Group children = nearest preceding [[group]] (dot-notation removed)

All page-node types are declared as root-level [type] or [[type]] entries in the document. The dotted [[group.action]] / [[subgroup.type]] style is not supported. A child node simply belongs to the most recently declared [[group]] above it in the file; the parser assigns root entries to groups by source order.

[[group]]
title = "CPU"

[[switch]]        # child of group "CPU"
...

[[action]]        # also a child of group "CPU"
...

[[group]]
title = "Battery"

[[switch]]        # child of group "Battery"
...

2.4. Display order = position in file

Display order is always top-to-bottom by the position of the [[name]] entry in the file, regardless of node type (group, action, page, text, switch ...) - even when types are interleaved (e.g. an action, then a page, then another action). The position is read directly from the tomlj API, so there is no need for an order field.

2.5. Boolean fields: static vs. shell-backed

Tool-Tree does not treat every TOML boolean-looking field the same way. Ordinary boolean fields use a strict truthy parser; only fields explicitly defined as Bool|Shell (or a field with equivalent custom shell handling) execute a non-boolean string as a shell command.

For example, support/visible and action show can execute a shell expression when given a non-boolean string. By contrast, confirm and auto-off are ordinary booleans; a string such as "echo 1" does not become a shell command there.

2.6. String resource references

Static display-text fields that Tool-Tree passes through its string-resource resolver may include a reference to the app's string resources via @string/name or @string:name. This includes titles, descriptions, summaries, option titles, parameter labels/placeholders, row text, warning text, row confirmation text, and lock messages. If the resource is not found, the original string is kept.

[[group]]
title = "@string/group_battery_title"

[[switch]]
title = "@string/switch_fast_charge_title"
desc = "@string:switch_fast_charge_desc"
get = "getprop sys.fastcharge"
set = "setprop sys.fastcharge $state"

2.7. load-key / load-text / load-toml - inline key/value substitution and dynamic TOML

A page may declare one directive line anywhere in the document (typically at the very top):

load-key = "strings_en.txt"

[[switch]]
title = "@wifi_title"
get = "settings get global wifi_on"
set = "settings put global wifi_on $state"

Before the TOML is parsed, the parser reads the key file and substitutes every @name token in the whole document with the matching value. This is a plain text pre-processing step (it runs on the raw file, before Toml.parse()), so @name works inside any string field - titles, descs, scripts, options, lock messages...

The key file itself is a simple list of lines name = "value" (name starts with a letter/underscore; value is quoted; \ escape sequences are supported):

# strings_en.txt
wifi_title = "Wi-Fi booster"
wifi_desc = "Keep Wi-Fi on during sleep"

Inline key text: load-text / load-text-sh

load-text takes the key lines directly, so no separate key file is needed. It can be combined with load-key in the same page:

load-key = "strings_en.txt"
load-text = """
extra_title = "Added inline"
wifi_desc = "Overrides the key file"
"""
load-text-sh = 'cat lang/more.bash'

Dynamic TOML: load-toml / load-toml-sh

These directives are handled in the same step as load-key, before Toml.parse(). All load-key-sh and load-toml-sh scripts run together in one shell round-trip. Order inside that round-trip: every load-toml-sh first (file order), load-key-sh last - so a toml script may create or delete the key file (e.g. lang/auto.bash) before the key path is resolved. Each load-toml* line is replaced in place by the loaded text, then {ROT}/{LOT} and the @name substitution run once over the merged document - so dynamic output can use @name too, and nodes keep the position (and group) of the directive line.

load-key = "strings_en.txt"
load-toml-sh = 'bash $ETC/menu-addon.sh "$PAGE_CONFIG_DIR"'

[[group]]
title = "@main_title"

# menu-addon.sh prints only what it needs - no [[group]]
echo '[[menu]]
[[menu.items]]
title = "@pin_text"
type = "checkbox"
get = "[ -f pin ] && echo 1"
silent = true
script = "touch pin"'

2.8. Path placeholders: {HOME}, {ICON}

These are resolved by the path lookup itself (PathAnalysis), not by the whole-document text substitution above - so they only take effect inside fields that are actually treated as a path: icon/icon-sh output, photo, bg, logo, row icon/photo, html-file, the editor's file, resource-file/resource-dir, and load-key/load-key-sh above.

2.9. Built-in variables: {ROT}, {LOT}, {TEXT_ROOT}

Unlike {HOME}/{ICON}, these are substituted directly on the raw document text and are always available with no load-key directive required. They report root state or provide a root-status label:

[[action]]
title = "Flash module"
lock = "{LOT}|Requires root access"
script = "..."

3. Shared fields (NodeInfoBase + ClickableNode + RunnableNode)

These are the shared fields used by most visible page nodes through NodeInfoBase, with additional fields inherited by clickable and runnable nodes. Some page-level containers such as [[group]], [[menu]], [[fab]], and the invisible [[resource]] node are parsed by specialized code and do not accept every shared field listed below.

4.1. NodeInfoBase (shared by normal page nodes)

4.2. ClickableNode (for page, action, switch, picker, editor, download)

4.3. RunnableNode (for action, switch, picker, download)

4. [[group]] - Container for child nodes

[[group]] is a container that groups related nodes. It has no icon and is not clickable - it's just a title with a list of child nodes below it.

5.1. Group fields

5.2. Demo

[[group]]
title = "CPU"

[[action]]
title = "Optimize CPU"
desc = "Set governor to performance"
script = "echo performance > /sys/devices/system/cpu/cpu0/cpufreq/scaling_governor"

[[picker]]
title = "Governor"
get = "cat /sys/devices/system/cpu/cpu0/cpufreq/scaling_governor"
set = "echo $state > /sys/devices/system/cpu/cpu0/cpufreq/scaling_governor"

[[group]]
title = "Memory"

[[action]]
title = "Clear cache"
script = "sync; echo 3 > /proc/sys/vm/drop_caches"

5.3. Grouping rules (no nesting)

Since dot-notation was removed, groups can no longer be nested inside each other. Every [[group]] is a top-level sibling: declaring a new [[group]] closes the previous one, and all following entries belong to the new group. Entries declared before the first [[group]] are rendered directly on the page without a group header. To stop wrapping without opening another group, put an empty [[end]] line: everything after it is rendered directly on the page again (e.g. a [[text]] with no card) until the next [[group]]. [[end]] is optional and only needed for this; a following [[group]] already closes the previous group by itself. It also clears the hidden state of a group with support = false.

5. [[page]] - Sub-page

[[page]] is not an action - it's a link to another page. Clicking it opens a new page (another .toml file, an HTML page, or another Activity).

6.1. Page-specific fields

These fields are handled directly by [[page]]. A page can also use the inherited NodeInfoBase and ClickableNode fields listed in the next two tables.

6.2. NodeInfoBase fields

All NodeInfoBase fields below are available on [[page]]. The same fields are shared by other normal page nodes; see §3 Shared fields for their general behavior.

6.3. ClickableNode fields

All ClickableNode fields below are available on [[page]]. They control the page item presentation, locking, SDK constraints, images, and shortcuts; see §3 Shared fields for the common definitions.

6.4. Demo

[[page]]
title = "App list"
desc = "Manage installed apps"
config = "pages/app_list.toml"

[[page]]
title = "Advanced settings"
desc = "Open external config file"
config = "/sdcard/Tool-Tree/advanced.toml"

6. [[action]] - Action (runs a shell script)

[[action]] is the most common node type: clicking it shows a dialog (if it has confirm/params/warning), then runs the script and shows the output in a log dialog.

7.1. Action fields

7.2. Demo

[[action]]
title = "Optimize CPU"
desc = "Set governor to performance"
menu = true
key = "optimize_cpu"
script = "echo performance > /sys/devices/system/cpu/cpu0/cpufreq/scaling_governor"

[[action]]
title = "Clear cache"
desc = "Clear system cache"
confirm = true
warn = "This will clear all app caches"
script = "sync; echo 3 > /proc/sys/vm/drop_caches"
auto-off = true

7. [[action.params]] - Input parameters

Per-param script (apply): each param can carry a snippet; on confirm, the snippets of all non-readonly params are merged (hidden ones only with depend-include-hidden = true, the default) (in param order) and run together, followed by the action script.

[[action]]
title = "Setup"
script = 'echo "Done: $mode"'

[[action.params]]
name = "mode"
type = "spinner"
options = ["a|Mode A", "b|Mode B"]
apply = 'setprop sys.mode $mode'

[[action.params]]
name = "wifi"
type = "switch"
apply = '[ "$wifi" = "1" ] && svc wifi enable || svc wifi disable'

With mode=b, wifi=1 the merged script is:

setprop sys.mode $mode
[ "$wifi" = "1" ] && svc wifi enable || svc wifi disable
echo "Done: $mode"

Dynamic params: see params-sh in section 7.1.

[[action]]
title = "Wi-Fi setup"
params-sh = "sh {HOME}/gen_wifi_params.sh"
script = "echo $ssid $pass"

gen_wifi_params.sh prints:

[[params]]
name = "ssid"
title = "Network"
type = "spinner"
options-sh = "nmcli -t -f SSID dev wifi"

[[params]]
name = "pass"
title = "Password"
type = "password"

Each [[action.params]] defines one input field in the dialog shown when the user clicks an action. The parameter's value is passed to the action's script via the $param_name environment variable.

8.1. Basic param fields

8.2. Common type values

8.3. Demo

[[action]]
title = "Set CPU max freq"
script = """
for cpu in /sys/devices/system/cpu/cpu*/cpufreq; do
  [ "$all_cpus" = "0" ] && [ "$cpu" != "/sys/devices/system/cpu/cpu0/cpufreq" ] && continue
  echo $freq > "$cpu/scaling_max_freq"
  echo $gov > "$cpu/scaling_governor"
done
"""

[[action.params]]
name = "freq"
title = "Frequency (kHz)"
desc = "Enter max frequency"
type = "text"
value = "2400000"

[[action.params]]
name = "gov"
title = "Governor"
type = "spinner"
value = "performance"

[[action.params.options]]
title = "Performance"
value = "performance"

[[action.params.options]]
title = "Powersave"
value = "powersave"

[[action.params]]
name = "all_cpus"
title = "Apply to all CPUs"
type = "switch"
value = "1"

[[action.params]]
name = "cfg"
title = "Config file"
type = "file"
suffix = "conf"

8.4. Dependencies (depend-*)

A param can be hidden/shown (or switched to readonly) based on the value of another param. This is a large feature - see section 3 for details.

8. [[switch]] - On/off toggle

[[switch]] displays an ON/OFF toggle. When the user toggles it, the set script is called with the env var $state set to "1" or "0". When the page loads, the get script is called to read the current state.

9.1. Switch fields

9.2. Demo

[[group]]
title = "Display"

[[switch]]
title = "Dark mode"
desc = "Enable dark UI"
get = "cmd uimode night get | grep -q yes && echo 1"
set = "cmd uimode night $([ \"$state\" = \"1\" ] && echo yes || echo no)"

[[switch]]
title = "Auto brightness"
get = "settings get system screen_brightness_mode"
set = "settings put system screen_brightness_mode $state"

9. [[picker]] - Value selector

[[picker]] displays a current value; clicking it opens a popup to choose one (or more) values from a list. When the user confirms, the set script is called with $state = the chosen value.

10.1. Picker fields

10.2. Demo

[[picker]]
title = "Governor"
get = "cat /sys/devices/system/cpu/cpu0/cpufreq/scaling_governor"
set = "echo $state > /sys/devices/system/cpu/cpu0/cpufreq/scaling_governor"

[[picker.options]]
title = "Performance"
value = "performance"

[[picker.options]]
title = "Powersave"
value = "powersave"

[[picker]]
title = "Max freq"
get = "cat /sys/devices/system/cpu/cpu0/cpufreq/scaling_max_freq"
set = "echo $state > /sys/devices/system/cpu/cpu0/cpufreq/scaling_max_freq"
option-sh = "cat /sys/devices/system/cpu/cpu0/cpufreq/scaling_available_frequencies | tr ' ' '\\n'"

10. [[text]] - Rich text block

[[text]] is a non-clickable display block containing multiple rich-text rows. Use it for notices, instructions, or inline image/gif blocks.

11.1. Text fields

11.2. Demo

[[text]]
title = "Notice"

[[text.rows]]
text = "CAUTION"
bold = true

[[text.rows]]
text = "The actions below may affect the system."

[[text.rows]]
line = true

[[text.rows]]
text = "  $ run backup --full"
monospace = true

[[text.rows]]
text = "See more at: example.com/docs"
italic = true

11. [[text.rows]] - Rich text row

Dynamic rows (rows-sh): every node that has rows (text, action, page, switch, picker, download, editor) accepts rows-sh, a script that prints the rows as inline TOML.

[[text]]
rows-sh = "sh {HOME}/gen_rows.sh"

gen_rows.sh prints:

[[rows]]
text = "CPU: 8 cores"
bold = true

[[rows]]
text = "Temp: 41 C"

This is the most common display component: used in [[text]], [[action]], [[page]], [[download]], [[action.params-rows]] and [[switch]], [[picker]], [[editor]]. Each row is a single line of text that can have style, icon, toggle, photo, etc.

12.1. Row fields

12.2. Demo

[[text]]
title = "Device info"

[[text.rows]]
text = "Device info"
bold = true

[[text.rows]]
line = true

[[text.rows]]
text = "Model: Pixel 7"

[[text.rows]]
text = "Android: 14"

[[text.rows]]
text = "ro.build.fingerprint=google/raven/..."
monospace = true

[[text.rows]]
line = true

[[text.rows]]
text = "Updated 2024-08-26"
align = "center"
italic = true

[[text.rows]]
line = true

[[text.rows]]
text = "Show notifications"
toggle = "switch"
get = "settings get global heads_up_notifications_enabled"
set = "settings put global heads_up_notifications_enabled $state"

12.3. Inline HTML block (html-file / html-url)

A row can also render a full HTML page inline, in its own WebView block below the text - useful for content richer than Markdown can express (custom layout, images, JS-driven widgets).

[[text.rows]]
text = "Changelog"
bold = true

[[text.rows]]
html-file = "changelog.html"
html-height = 300

[[text.rows]]
text = "Project homepage"

[[text.rows]]
html-url = "https://example.com"

12.4. Inline Markdown syntax reference (markdown = true)

When a row has markdown (alias md) set to true, its text/sh result is parsed as simple inline Markdown before display. Marks can be escaped with \ (e.g. \* shows a literal *).

[[text.rows]]
text = "Status: `{OK}(green)` - link: `[details](https://example.com)` - `big|20`"
markdown = true

12.5. Pinning rows to the left / center / right of the same line

Rows that would join the same line by default (no break/line/margin-top on a later row, no margin-bottom on an earlier one) are grouped, then bucketed by align into up to 3 zones: normal = left, center = center, right = right. If each zone has at most 4 rows and at least one row uses center/right, the group renders as a true multi-column line: left content stays flush left, center is centered across the full line width, right is flush against the right edge - regardless of how many rows end up in each zone (1 to 4). Unlike the earlier version of this feature, a pinned row can now have anything a normal row can: icon/icon-sh/toggle/link/activity/script/markdown/underline/strikethrough all work in any zone.

[[text.rows]]
text = "kkkkk"

[[text.rows]]
text = "ffffffg"
align = "right"

Up to 4 rows per zone, mixed content, three zones at once:

[[text.rows]]
text = "CPU"

[[text.rows]]
text = "68°C"

[[text.rows]]
text = "Governor"
align = "center"

[[text.rows]]
text = "Details"
align = "right"
link = "https://example.com/cpu"

12.6. Reset a single row on demand (reset)

A row with reset = N acts as a refresh button for row index N (0-based, within the same [[text.rows]] list): tapping it re-runs only that row's sh/icon-sh/progress-sh and updates just that row's text, without rebinding the whole block (icons/GIFs/other rows are left untouched). Combine with script to run a script first and then refresh the row that displays its result.

[[text.rows]]
sh = "cat /sys/class/thermal/thermal_zone0/temp"
icon = "ic_temperature"

[[text.rows]]
text = "🔄 Refresh"
align = "right"
reset = 0

Besides a numeric index, reset also accepts two special string values:

12.7. Inline progress bar (progress) and flash highlight (flash)

A row can embed a small horizontal progress bar inline, right after its text/icon - useful for battery/thermal/storage gauges without leaving the text flow. The bar is driven either statically or by a script:

[[text]]
title = "Storage"

[[text.rows]]
sh = "df -h /data | tail -1 | awk '{print $5}'"
text = "/data usage"
progress-sh = "df /data | tail -1 | awk '{gsub(\"%\",\"\"); print $5}'"
progress-max = 100
progress-color = "#FF9800"
progress-track-color = "#33888888"
progress-width = 120
progress-height = 8

[[text.rows]]
text = "🔄 Refresh"
align = "right"
reset = "all"

The companion flash effect makes a reset-driven value change visible: whenever a row is updated through reset and its rendered text actually differs from before, a highlight rectangle is drawn behind the new text and fades out over a short animation. It is on by default - set flash = false on a row to opt out, or flash-color to use a custom color instead of the default amber.

12. [[editor]] - Open file in the text editor

[[editor]] lets the user open a file in the built-in text editor (TextEditorActivity) to view or edit it. If the file does not exist, the editor creates it when the user saves.

13.1. Editor fields

13.2. Demo

[[editor]]
title = "Edit build.prop"
desc = "/system/build.prop"
file = "/system/build.prop"
readonly = "test -w /system/build.prop || echo 1"

[[editor]]
title = "Create new script"
desc = "/sdcard/myscript.sh"
file = "/sdcard/myscript.sh"
value = "#!/system/bin/sh\necho hello"

[[editor]]
title = "Active config"
file-sh = "echo /data/adb/modules/demo/$(getprop ro.product.device).conf"

[[editor]]
title = "View-only script (no Run)"
file = "/sdcard/myscript.sh"
run = false

13. [[download]] - Download a file via HTTP

[[download]] is a new node type that displays download progress directly in the item (no separate dialog). When download completes, it runs the script with the env var $state = path of the downloaded file (cached, random name). The URL can be static (url) and/or dynamic (url-sh).

14.1. Download fields

14.2. Demo

[[download]]
title = "Download update"
url = "https://example.com/update.zip"
script = "unzip -o $state -d /sdcard/update && echo Update installed"

14. [[resource]] - Extract assets

[[resource]] is an invisible node (it returns null after initialization). It only extracts assets from the APK to storage (typically /data/data/<pkg>/files/... or cache). This is how to ship script files, images, etc. from the APK to outside so shell can call them.

You can also put resource-file/resource-dir fields directly inside [[page]]/[[action]]/[[switch]]/[[picker]]/[[text]] - no need to declare a separate [[resource]] entry. (Not available on [[group]].)

15.1. Fields

[[resource]]
resource-file = "busybox"

[[resource]]
resource-dir = "scripts"

# Or inline on the node that needs it - no separate [[resource]] entry required:
[[action]]
title = "Run bundled script"
resource-file = "run.sh"
script = "sh /data/data/com.tool.tree/files/run.sh"

15. [[menu]] / [[fab]] - Overflow menu and FAB

This feature replaces the old [[page.options]] mechanism (declared in the parent page, built eagerly even when the sub-page was never opened). Now the menu and FAB are declared directly inside the page's own TOML file, just like [[action]]/[[text]] - they are only read (and only their inner shell runs) when the page is actually opened.

16.1. Structure

A [[menu]] or [[fab]] block is a container, NOT a single entry:

• handler (or handler-sh): the DEFAULT script that runs when clicking a child item, if that item does not declare its own script. handler-sh is an alias here; it is not a separately evaluated dynamic-output field.
• icon (or icon-path): custom icon for the container itself (NOT an item) - see below
• [[...items]]: the list of items shown in the menu/FAB. Items support the menu/FAB fields documented in §16.2; do not assume that every inherited node field is rendered or enforced here.

16.2. Item fields (inside menu/fab)

16.3. Demo

# Regular page content
[[switch]]
title = "Performance mode"
desc = "Enable performance governor"
get = "getprop sys.perf.mode"
set = "setprop sys.perf.mode $state"

[[action]]
title = "Clear cache"
script = "sync; echo 3 > /proc/sys/vm/drop_caches"

# Toolbar overflow menu (3-dot icon) - not part of the page content list above
[[menu]]
handler = "echo Menu: $key"
icon = "menu_icon.png"

[[menu.items]]
title = "Refresh"
type = "refresh"

[[menu.items]]
title = "Show module"
type = "checkbox"
get = "test -f /data/adb/modules/my_module/disable || echo 1"
script = "touch /data/adb/modules/my_module/disable"

[[menu.items]]
title = "Select governor"
type = "spinner"
options = ["performance|Performance", "powersave|Power saving", "schedutil|Balanced"]
script = "echo $state > /sys/devices/system/cpu/cpu0/cpufreq/scaling_governor"

[[menu.items]]
title = "View log"
config = "logcat.toml"

[[menu.items]]
title = "Open in browser"
link = "https://example.com"

# Floating action button - also not part of the page content list
[[fab]]
icon = "fab_icon.png"
[[fab.items]]
title = "Add rule"
type = "file"
suffix = "toml"
script = "sh $state"

16. Dependencies (depend-*)

This is the largest feature of [[action.params]]: a param can be hidden/shown (or switched to readonly) based on the value of one (or more) other params in the same action. This is how to build complex dialogs that are still easy to manage - the UI auto-hides irrelevant fields when the user picks a different mode.

17.1. depend-* fields (only for [[action.params]])

17.2. Demo - simple dependency

[[action]]
title = "Backup"
script = """
if [ "$mode" = "file" ]; then
  cp "$src_file" /sdcard/backup/
else
  cp -r "$dst_folder" /sdcard/backup/
fi
"""

[[action.params]]
name = "mode"
title = "Backup mode"
type = "spinner"
value = "file"

[[action.params.options]]
title = "Single file"
value = "file"

[[action.params.options]]
title = "Whole folder"
value = "folder"

[[action.params]]
name = "src_file"
title = "Source file"
type = "file"
depend-on = "mode"
depend-value = "file"

[[action.params]]
name = "dst_folder"
title = "Destination folder"
type = "folder"
depend-on = "mode"
depend-value = "folder"

17.3. depend-logic reference

17.4. depend-default and depend-initial

When no dependency condition matches, the fallback visibility is controlled by depend-default (default: show). The separate depend-initial value controls the state shown before the first dependency evaluation.

17. Shell-script fields - overview

In Tool-Tree, many fields accept a static value plus a dedicated -sh field, or explicitly allow a shell expression in the field itself. These modes are not interchangeable; the table below lists the dynamic fields supported by the current parser and UI.

18. resolveBoolOrShell

The resolveBoolOrShell() function is used only where the parser explicitly allows a static boolean or a shell expression. "1"/"true" are true, "0"/"false" are false, and another string is executed immediately; only output exactly equal to "1" is true.

19. Pending states

To reduce shell round-trips while parsing, the parser collects dynamic work intended for the parse-time pending pass and submits those scripts together after the document has been parsed.

After the whole document is parsed, resolvePendingStates() submits its collected scripts in a single batch via ScriptEnvironmen.executeMultipleResultRoot(), then distributes the results to the affected nodes/rows. Dynamic action-parameter fields such as value-sh, label-sh, placeholder-sh, options-sh, and parameter readonly are evaluated later when the action dialog is opened.

20. process = true

Setting process = true on a [[page]] instructs the rendering engine to build and render child nodes progressively on the UI as they are parsed, accompanied by a linear progress indicator, rather than holding display until the entire tree has loaded. Note that a [[group]] is emitted to the UI only after ALL of its children have been collected (group + children appear together), while items outside any group are emitted one by one as soon as they are parsed.

While the first real item is still being built, the page shows placeholder-count shimmering skeleton cards up-front so it doesn't look empty (default: 1). As soon as the FIRST real item finishes loading, the skeleton(s) are hidden immediately - they no longer wait for the whole page to finish loading.

[[page]]
title = "Kernel tweaks"
config = "kernel.toml"
process = true
placeholder-count = 3

21. Page lifecycle

Sub-pages trigger lifecycle callbacks during initialization and reading. before-load executes before parsing begins, followed by after-load upon parsing completion. Dependent on the parse status, load-ok or load-fail shell scripts execute accordingly.

22. Script output control sequences

While a script (from [[action]], [[switch]], [[download]] ...) is running, its log dialog is not just a plain text viewer. If a running script echos a line matching one of the special tags below, the log dialog intercepts that line (it is not printed as normal output) and performs a UI action instead. This lets a shell script drive dialogs, prompts, progress bars, and even control the app process itself, without leaving the log screen.

23.1. exit:[kill] / exit:[restart]

Terminates the app process from inside a running script. exit:[kill] simply kills the app process; exit:[restart] relaunches the app first and then kills the old process, giving the effect of a full app restart.

[[action]]
title = "Apply and restart app"
confirm = true
warn = "The app will restart to apply changes"
script = """
setprop persist.sys.my_tweak 1
echo "exit:[restart]"
"""

23.2. choose:[value1|Label1,value2|Label2,...]

Pauses the script and renders a row of buttons directly in the log dialog. Each option is value|Label (the |Label part is optional - if omitted, the value itself is used as the label). When the user taps one, its value is written back to the script's standard input, and the script resumes.

[[action]]
title = "Set governor"
script = """
echo "choose:[performance|Performance,powersave|Power saving,schedutil|Balanced]"
read governor
echo "userspace" > /sys/devices/system/cpu/cpu0/cpufreq/scaling_governor 2>/dev/null
for cpu in /sys/devices/system/cpu/cpu*/cpufreq/scaling_governor; do
  echo "$governor" > "$cpu"
done
echo "Governor set to: $governor"
"""

23.3. pick:[values] / pickv:[values] / pickh:[values]

Same idea as choose:[...] (comma-separated value|Label list, sent back via stdin on tap), but rendered as tappable links inline in the log text rather than as separate buttons. pickv:[...] (or plain pick:[...]) stacks the choices vertically; pickh:[...] lays them out horizontally.

[[action]]
title = "Choose log level"
script = """
echo "Select a verbosity level:"
echo "pickh:[1|Low,2|Medium,3|High]"
read level
echo "Verbosity set to level $level"
"""

23.4. input:[prompt]

Shows a text input field in the log dialog with prompt as its hint. Whatever the user types and submits is written back to the script's standard input, letting the script keep going with free-form text instead of a fixed list of choices.

[[action]]
title = "Rename backup"
script = """
echo "input:[Enter a name for this backup]"
read name
mv /sdcard/backup/last.zip "/sdcard/backup/${name}.zip"
echo "Saved as ${name}.zip"
"""

23.5. progress:[current/total]

Drives the progress bar shown at the top of the log dialog. Echo this repeatedly while a long-running task advances. current = -1 switches the bar to indeterminate (spinning) mode; current >= total hides the bar (task finished).

[[action]]
title = "Copy large folder"
script = """
echo "progress:[-1/100]"
total=$(ls /sdcard/source | wc -l)
i=0
for f in /sdcard/source/*; do
  cp "$f" /sdcard/target/
  i=$((i+1))
  echo "progress:[$i/$total]"
done
echo "progress:[$total/$total]"
echo "Done: $i files copied"
"""

23.6. am:[...] (send an Android Intent)

Sends an Android Intent directly from a shell script, without needing a separate am start binary call wired up elsewhere. Supported sub-commands are start, startservice, foregroundservice, and broadcast, using the same -a/-d/-n flags as the standard Android am command line tool, plus typed extras.

[[action]]
title = "Open developer options"
script = """
echo "am:[start -a android.settings.APPLICATION_DEVELOPMENT_SETTINGS]"
"""

[[action]]
title = "Broadcast a custom event"
script = """
echo "am:[broadcast -a com.example.MY_ACTION --es status ok --ei code 200]"
"""

23. Full example

A representative TOML configuration showcasing groups, actions, parameters, switches, and rich text rows:

# Top-level item (declared before the first [[group]]) - shown without a group header
[[text]]
title = "NOTICE"

[[text.rows]]
text = "Every entry below belongs to the nearest [[group]] above it"
italic = true

[[group]]
title = "System Performance"

[[switch]]
title = "Performance Mode"
desc = "Enable performance governor"
get = "getprop sys.perf.mode"
set = "setprop sys.perf.mode $state"
lock-sh = "[ -f /data/adb/.perf-ready ] && echo 1"

[[action]]
title = "Set CPU Frequency"
script = "echo $freq > /sys/devices/system/cpu/cpu0/cpufreq/scaling_max_freq"
reload = "perf-mode"

[[action.params]]
name = "freq"
title = "Frequency (kHz)"
type = "spinner"

[[action.params.options]]
title = "Mode 1"
value = "1800000"

[[action.params.options]]
title = "Mode 2"
value = "2200000"

[[action.rows]]
text = "Applies to CPU0 only"
italic = true

[[group]]
title = "Maintenance"

[[action]]
title = "Clear cache"
confirm = true
warn = "Cache will be wiped!"
script = "sync; echo 3 > /proc/sys/vm/drop_caches"
auto-off = true

# Page menu (3-dot) and FAB - collected wherever they appear
[[menu]]
handler = "echo Menu: $key"

[[menu.items]]
title = "Refresh"
type = "refresh"

[[menu.items]]
title = "Performance Mode"
type = "checkbox"
get = "getprop sys.perf.mode"
script = "setprop sys.perf.mode $state"

[[fab]]
[[fab.items]]
title = "Flash zip"
type = "file"
suffix = "zip"
script = "sh $state"

24. Tips & pitfalls

• Use [[node]] for repeatable entries; a single [node] table is also accepted by the parser for one entry. Do not mix the two forms as if they were separate entries for the same key.
• Groups are flat - never use dotted [[group.action]] nesting (those children are silently ignored). Declare children flat, right after their [[group]].
• [[toml]] is a reserved marker for inline-TOML detection (config-sh) - do not use it as a node table name.
• Use selective refresh via reload = "id1,id2" instead of reloading the entire page after action execution.

25. Changelog - recently added fields

Fields marked with the badge throughout this guide are summarized here, grouped by section, for quick reference when upgrading an existing config.

• Corrected Boolean parsing scope: ordinary Bool fields do not automatically become shell expressions.
• Documented the built-in {TEXT_ROOT} variable.
• Corrected key default semantics and the single-table / array-of-tables distinction.
• Clarified config-sh inline-TOML detection and dynamic picker option fallback.
• Corrected optional script/get/set/rows markings and expanded dependency aliases/callback behavior.
• Added action shell-by / shell-value / shell-mode: pick hidden / bg-task / log from param values at click time (rules left to right), with shell kept as the fallback.
• Naming unification (old names still work): bg-image/bg-image-sh = background image everywhere (nodes, text, rows; legacy node bg/bg-sh), bg-color = background color (legacy row bg), confirm = Bool everywhere with confirm-text for the message (legacy row string confirm still works).
• Added the [[end]] marker (§ groups): closes the current [[group]] so the following nodes render on the page without a group wrapper. Optional - a new [[group]] still closes the previous one.
• Added load-toml / load-toml-sh directives (§2.7): merge a TOML fragment (file or shell output) into the document before parsing, in the same step as load-key, so @name substitution also applies to it.
• Added load-text / load-text-sh directives (§2.7): inline key text ("""...""" block or script output) applied after load-key, so it adds missing keys and overrides same-name ones; several lines allowed.
• Added fab-spin for [[fab.items]]: the FAB icon spins only when it is true — while the item's script runs or the page reloads (refresh/reload/reload-page). The old automatic spin on page reload is removed.