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.

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. Always use double brackets [[name]] for every entry

TOML does not allow mixing [name] (single brackets, single table) and [[name]] (double brackets, array of tables) for the same key at the same position - this will cause a parse error. To be safe, always use [[name]] for any entry, even if there is currently only one entry of that type. This prevents breaking the file later when you add a second entry of the same type but forget to switch the brackets.

2.2. Node type = TOML table name

There is no separate type field. A node's type is determined by its TOML table name:

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

All node types are declared as flat [[type]] entries at the top level of the document - the dotted [[group.action]] / [[subgroup.type]] style is no longer supported. A child node simply belongs to the most recently declared [[group]] above it in the file; the parser walks the document once, in line order, and assigns each entry to the current group.

[[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 values - 3 accepted forms

Boolean fields such as confirm, readonly, auto-off accept:

Example: readonly = "test -f /sdcard/lock && echo 1" - the parser runs that command, and if it returns "1" then readonly = true.

2.6. String resource references

Any text field (title, desc, summary ...) may include a reference to the app's string resources via @string/name or @string:name. The parser resolves these automatically. 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"

3. Node type overview

Quick reference for all node types. Click a name to jump to its detailed section.

4. Shared fields (NodeInfoBase + ClickableNode + RunnableNode)

These are the fields that every node has (inherited from NodeInfoBase). All text fields accept @string/... references.

4.1. NodeInfoBase (present on every node)

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

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

5. [[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.

6. [[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 fields

6.2. 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"

7. [[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

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

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 17 for details.

9. [[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"

10. [[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'"

11. [[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

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

This is the most common display component: used in [[text]], [[action]], [[page]], [[download]] and [[action.params-rows]]. 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"

13. [[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"

14. [[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"

15. [[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"

16. [[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
• [[...items]]: the list of items shown in the menu/fab - each item uses the same fields as the old [[page.options]] (type/style/suffix/mime/path-home/multiple/get/silent/link/activity/html/config/config-sh/script/title...)

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"

[[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]]
[[fab.items]]
title = "Add rule"
type = "file"
suffix = "toml"
script = "sh $state"

17. 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

By default, when no condition matches, the param is shown. To change the default to hidden:

18. Shell-script fields - overview

In Tool-Tree, many fields accept either a static value (string/bool) or a dynamic shell script. The parser runs the script and uses its output as the value. Here is a summary of all shell-style fields:

19. resolveBoolOrShell

The resolveBoolOrShell() function parses fields that can take either a static boolean or a shell command. If the string evaluates to "true" or "1", it resolves to true. For non-boolean strings, it executes the script immediately via the root shell during parsing; if the command output equals "1", it returns true, otherwise false.

20. Pending states

To maximize performance when parsing large configuration files, the parser does not run every dynamic shell evaluation synchronously. Five queues collect the deferred work while parsing:

After the whole document is parsed, resolvePendingStates() submits ALL collected scripts in a single batch via ScriptEnvironmen.executeMultipleResultRoot() - one shell round-trip instead of N - and then distributes the results to each node before the page is displayed.

21. 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.

22. 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.

23. 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]"
"""

24. 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"

25. Tips & pitfalls

• Always use double brackets [[node]] across all declarations to prevent TOML table array parser exceptions.
• 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.