-
-
Notifications
You must be signed in to change notification settings - Fork 43
Command Reference
Current as of: Ultrahand Overlay v2.4.1
This page is the complete scripting reference for Ultrahand packages. It covers every command, flow-control construct, command mode, source function, and placeholder variable available to package authors. For package structure, headers, and configuration, see the Package Reference.
- Flow Control
- Filesystem Commands
- INI Commands
- JSON Commands
- Hex Editing Commands
- Mod Conversion Commands
- System Commands
- UI & Display Commands
- Command Modes
- Grouping Modes
- Source Functions
- Placeholder Variables
- Symbol Placeholders
Begins a conditional block. commandSuccess is reset to true at the try: label. Any command in the block that fails causes all remaining commands in that block to be skipped. A new try: label starts a fresh block. The overall command sequence continues regardless of whether a block succeeded or failed.
[Try Example]
try:
copy /source/file.txt /dest/file.txt
set-footer Copied!
try:
!path_exists /source/file.txt
set-footer Source missingUsed in ;mode=toggle commands to specify what executes when the toggle turns on or off.
[Toggle Example]
;mode=toggle?on
on:
backlight on
off:
backlight offConditionally executes commands based on the hardware generation of the device. All commands after the label run only on that hardware variant.
[Hardware-Specific]
erista:
copy /source/erista_file.bin /dest/
mariko:
copy /source/mariko_file.bin /dest/Creates a directory, including all intermediate directories.
mkdir <DIRECTORY_PATH>
Copies a file or directory. Supports wildcard patterns (*).
copy <SOURCE_PATH> <DESTINATION_PATH>
copy <SOURCE_PATH> <DESTINATION_PATH> -filter <PATH_TO_FILTER_TXT>
-filter accepts a path to a text file containing a newline-separated list of files/folders to exclude from wildcard resolution. Relative paths (./, ../) are supported within filter files.
Moves or renames a file or directory. Supports wildcard patterns.
move <SOURCE_PATH> <DESTINATION_PATH>
move <SOURCE_PATH> <DESTINATION_PATH> -filter <PATH_TO_FILTER_TXT>
Alias for move. Behaves identically.
rename <SOURCE_PATH> <DESTINATION_PATH>
Deletes a file or directory. Supports wildcard patterns.
delete <FILE_OR_DIRECTORY_PATH>
delete <FILE_OR_DIRECTORY_PATH> -filter <PATH_TO_FILTER_TXT>
Wildcard Safety: Patterns with multiple consecutive wildcards (e.g.
**) or patterns resolving tonull*/*nullare treated as dangerous and return a failed command without executing.
Mirrors the contents of a source directory into a destination, copying only the files that exist in the source. The destination defaults to sdmc:/ if omitted.
mirror_copy <SOURCE_PATH>
mirror_copy <SOURCE_PATH> <DESTINATION_PATH>
Deletes files from the destination that exist in the source directory. The destination defaults to sdmc:/ if omitted.
mirror_delete <SOURCE_PATH>
mirror_delete <SOURCE_PATH> <DESTINATION_PATH>
Downloads a file from a URL to a local path. Performs a one-time NTP sync to pool.ntp.org on first call after startup to prevent SSL failures from clock desynchronization.
download <FILE_URL> <DESTINATION_PATH>
Same as download but makes zero retry attempts on failure.
download-no-retry <FILE_URL> <DESTINATION_PATH>
Extracts a ZIP archive to the specified destination, preserving the archive's directory structure.
unzip <ZIP_FILE_PATH> <DESTINATION_PATH>
Creates an empty file at the specified path if it does not already exist.
touch <FILE_PATH>
Compares two file lists (or wildcard-resolved path lists) and writes the results — files present in both — to an output file.
compare <PATH_1> <PATH_2> <OUTPUT_PATH>
Creates empty text files named after each file/folder matched by the source pattern, placed in the output directory.
flag <INPUT_PATH_WILDCARD_PATTERN> <OUTPUT_DIRECTORY>
Removes all macOS metadata files (files beginning with ._) and all .DS_Store files from a directory and all of its subdirectories.
dot-clean <DIRECTORY_PATH>
Returns command success if the specified path exists, failure otherwise. Intended for use inside try: blocks.
path_exists <PATH>
The inverse of path_exists — returns command success if the path does not exist.
!path_exists <PATH>
Creates or updates a key-value pair in a section of an INI file. Creates the file and/or section if they do not exist.
set-ini-val <FILE_PATH> <SECTION> <KEY> <VALUE>
Renames a key within a section.
set-ini-key <FILE_PATH> <SECTION> <CURRENT_KEY> <NEW_KEY>
Adds a new section to an INI file. Creates the file if it does not exist.
add-ini-section <FILE_PATH> <SECTION>
Renames an existing section.
rename-ini-section <FILE_PATH> <CURRENT_SECTION> <NEW_SECTION>
Removes an entire section from an INI file.
remove-ini-section <FILE_PATH> <SECTION>
Removes a key-value pair from a section.
remove-ini-key <FILE_PATH> <SECTION> <KEY>
In every section that contains <PATTERN_KEY>, sets <DESIRED_KEY> to <DESIRED_VALUE>. An empty <PATTERN_KEY> string matches all sections.
set-ini-val-matching-key <FILE_PATH> <PATTERN_KEY> <DESIRED_KEY> <DESIRED_VALUE>
In every section that contains <PATTERN_KEY>, removes <DESIRED_KEY>.
remove-ini-key-matching-key <FILE_PATH> <PATTERN_KEY> <DESIRED_KEY>
Sets a value in a JSON file by key. Creates the file and/or key if they do not exist.
set-json-val <JSON_PATH> <KEY> <VALUE>
Renames a key in a JSON file.
set-json-key <JSON_PATH> <CURRENT_KEY> <NEW_KEY>
Writes hex data at an absolute byte offset within a file.
hex-by-offset <FILE_PATH> <OFFSET> <HEX_DATA>
Writes hex data at an offset relative to a custom search pattern. The offset can be a decimal integer or a hex value prefixed with #.
hex-by-custom-offset <FILE_PATH> <CUSTOM_PATTERN> <OFFSET> <HEX_DATA>
Writes a decimal value (auto-converted to hex) at an offset relative to a custom pattern.
hex-by-custom-decimal-offset <FILE_PATH> <CUSTOM_PATTERN> <OFFSET> <DECIMAL_DATA> [BYTE_GROUP_SIZE]
BYTE_GROUP_SIZE defaults to 2 (1 byte) and auto-scales with value magnitude. Set explicitly when the decimal value is 0.
Same as hex-by-custom-decimal-offset but writes in reverse byte order (little-endian).
hex-by-custom-rdecimal-offset <FILE_PATH> <CUSTOM_PATTERN> <OFFSET> <RDECIMAL_DATA> [BYTE_GROUP_SIZE]
Replaces one hex pattern with another. Optionally targets a specific occurrence; if omitted, all instances are replaced.
hex-by-swap <FILE_PATH> <HEX_TO_REPLACE> <HEX_REPLACEMENT> [OCCURRENCE]
Replaces a string pattern with another string. Both are auto-converted to hex before editing.
hex-by-string <FILE_PATH> <STRING_TO_REPLACE> <STRING_REPLACEMENT> [OCCURRENCE]
Replaces a decimal value with another. Values are converted to hex before editing.
hex-by-decimal <FILE_PATH> <DECIMAL_TO_REPLACE> <DECIMAL_REPLACEMENT> [BYTE_GROUP_SIZE] [OCCURRENCE]
When specifying
[OCCURRENCE],BYTE_GROUP_SIZEmust also be provided.
Same as hex-by-decimal but operates in reverse byte order (little-endian).
hex-by-rdecimal <FILE_PATH> <DECIMAL_TO_REPLACE> <DECIMAL_REPLACEMENT> [BYTE_GROUP_SIZE] [OCCURRENCE]
Replaces all data matching a hex wildcard pattern with replacement hex data.
hex-by-pattern <FILE_PATH> <HEX_PATTERN_TO_REPLACE> <HEX_DATA_REPLACEMENT>
Converts a .pchtxt mod file into an .ips patch binary. Also creates an empty title ID text file alongside the IPS mod for mod manager compatibility.
pchtxt2ips <PCHTXT_FILE_PATH> <OUTPUT_DIRECTORY>
Converts and installs a .pchtxt mod as an Atmosphere cheat, automatically placing it in the correct directory for the running game. The game's title ID must be present in the pchtxt.
pchtxt2cheat <SOURCE_PATH> [CHEAT_NAME]
[CHEAT_NAME] is optional. If omitted, the cheat name is derived from the source file.
Restarts the system. Supports multiple reboot targets.
reboot
reboot hekate
reboot UMS
reboot boot <NAME_OR_INDEX>
reboot ini <NAME_OR_INDEX>
reboot <PATH_TO_PAYLOAD_BINARY>
Boot and ini entries reference entries within hekate_ipl.ini. UMS must be uppercase. hekate is case-insensitive.
Atmosphere Updater: When Atmosphere files (
atmosphere/package3,atmosphere/stratosphere.romfs) have been staged for an update with a.ultraextension, anyrebootcommand automatically triggers the Ultrahand Updater payload (/config/ultrahand/payloads/ultrahand_updater.bin) to safely apply the update before rebooting.
Shuts down the system or all connected Bluetooth controllers.
shutdown
shutdown controllers
Controls the screen backlight in handheld mode.
backlight on
backlight off
backlight <PERCENTAGE>
backlight auto on
backlight auto off
<PERCENTAGE> is an integer 0–100. backlight auto on/off controls the system's auto-brightness feature.
Sets the system master volume. Accepts values from 0 to 150. Values above 100 utilize the bundled audio mastervolume patch for amplification beyond the normal maximum.
volume <PERCENTAGE>
Example — Volume Slider:
[Volume Level]
;mode=trackbar
;min_value=0
;max_value=150
;units=%
;on_every_tick=true
volume {value}Sets the system region. Requires a reboot to apply. Case-insensitive.
set-region <REGION>
<REGION> is one of: JPN, USA, EUR, AUS, HTK, CHN.
Opens an overlay from a package command, optionally passing launch arguments.
open <PATH_TO_OVERLAY_FILE> [LAUNCH_ARG_1] [LAUNCH_ARG_2] ...
Executes a named entry from a package INI file on the interpreter thread.
exec <ENTRY_NAME>
exec <ENTRY_NAME> <PATH_TO_INI_FILE>
When PATH_TO_INI_FILE is omitted, commands are pulled from boot_package.ini in the current package's folder.
Closes Ultrahand. Optionally navigates to the Overlays or Packages menu on next open.
exit
exit overlays
exit packages
Queues a notification toast that appears as an on-screen overlay.
notify <MESSAGE> [FONT_SIZE] [TEXT_ALIGNMENT] [SPLIT_TYPE] [DURATION_MS] [TITLE] [SHOW_TIME] [APP_NAME]
| Parameter | Type | Default | Description |
|---|---|---|---|
MESSAGE |
string | (required) | Notification text. Up to 4 lines can be displayed. |
FONT_SIZE |
integer (1–34) | 24 (with title), 26 (without) | Font size for the message text. |
TEXT_ALIGNMENT |
left, center, right
|
center (no title), left (with title) |
Text alignment. |
SPLIT_TYPE |
word, char
|
word |
How text wraps across lines. |
DURATION_MS |
integer (≥500) | 4000 |
Display duration in milliseconds. 0 keeps it visible until dismissed. |
TITLE |
string | (none) | Optional notification title. |
SHOW_TIME |
true, false
|
true |
Shows a timestamp alongside the title. Requires a title. |
APP_NAME |
string | (none) | Associates the notification with an icon at /config/ultrahand/assets/notifications/{APP_NAME}.rgba. Pass "" for title to use APP_NAME without a title. |
All [] parameters are optional and interpreted based on their value and position.
Same as notify but always displays immediately in slot 0 at highest priority, bypassing the queue. Default duration is 3000 ms.
notify-now <MESSAGE> [FONT_SIZE] [TEXT_ALIGNMENT] [SPLIT_TYPE] [DURATION_MS] [TITLE] [SHOW_TIME] [APP_NAME]
External programs and sys-modules can trigger notifications by writing a JSON file to:
/config/ultrahand/notifications/{APP_ID}-{UNIQUE_ID}.notify
JSON Format:
{
"text": "This is a notification.",
"font_size": 24,
"split_type": "word",
"alignment": "left",
"duration": 4000,
"title": "My App",
"show_time": "true",
"priority": 20
}All fields except "text" are optional. Notifications can be filtered per app by creating /config/ultrahand/flags/notifications/{APP_ID}.flag. Notification icons must be 50×50 px RGBA and go at /config/ultrahand/assets/notifications/{APP_ID}.rgba.
Sets the footer label for the current command item, writing the value to config.ini. If the value contains the word null, the command is marked as failed and no change is made.
set-footer <TEXT>
Triggers a reload of the current package page, the active theme, the current package data, or the wallpaper.
refresh
refresh theme
refresh package
refresh wallpaper
When called without arguments, the page refreshes and the cursor returns to the top.
Refreshes the current page and moves the cursor to the item matching the specified name and optional value.
refresh-to <ITEM_NAME> [ITEM_VALUE] [EXACT_MATCH]
EXACT_MATCH is true by default. When false, checks if the value is contained within the item text rather than requiring an exact match.
Simulates a B button press, navigating back one level.
back
Enables command and error logging for the current package execution. Logs are written to log.txt in the package folder.
logging
Clears Ultrahand-internal caches or log files.
clear log
clear hex_sum_cache
The ;mode= header defines how a list item behaves and is rendered.
Standard execution. The command runs immediately when the user presses A.
[Reboot]
rebootA two-state ON/OFF toggle. Use toggle?on or toggle?off to set the initial default state. Pair with on: and off: blocks.
[Auto Brightness]
;mode=toggle?on
on:
backlight auto on
off:
backlight auto offNote:
;mode=holdis no longer a valid mode. Use;hold=truewithdefault,option, orslotinstead.
Displays a dropdown list of options. The selected option is shown as the footer.
[*Graphics Quality]
;mode=option
list_source '(Low, Medium, High, Ultra)'Similar to option but uses a distinct display symbol. Use set-footer {list_source(*)} to write the active selection to the footer.
[*Save Slot]
;mode=slot
list_source '(Slot A, Slot B, Slot C)'
set-footer {list_source(*)}A continuous slider between a minimum and maximum value.
[Brightness]
;mode=trackbar
;min_value=0
;max_value=100
;units=%
backlight {value}A slider with a fixed number of discrete steps.
[CPU Profile]
;mode=step_trackbar
;min_value=0
;max_value=5
;steps=6A step trackbar where each step has a named label drawn from a list_source or list_file_source. Does not use ;min_value=, ;max_value=, ;units=, or ;steps=.
[Performance Mode]
;mode=named_step_trackbar
list_source '(Eco, Normal, Boost, Turbo)'Renders a structured display table. Tables support live placeholder polling when ;polling=true.
[System Info]
;mode=table
;alignment=left
;polling=true
'Atmosphere'='{ams_version}'
'HorizonOS'='{hos_version}'Points to another package's .ini file, opening it as a sub-menu.
[*Advanced Options]
;mode=forwarder
package_source './include/advanced.ini'Displays static or dynamic text content.
The ;grouping= header controls how file_source results are grouped into section headers. Only valid on commands that use file_source.
| Value | Behaviour |
|---|---|
default |
No grouping. Items are listed without section headers. |
split |
Groups by the parent folder name of each matched file. |
split2 |
Groups by the portion of the parent folder name before the first - separator; the portion after becomes the item label. |
split3 |
Groups by the portion of the filename before the first - separator; the portion after becomes the item label. |
split4 |
Groups by the grandparent folder name (two levels up). |
split5 |
Same split logic as split2 but applied to file_source types where split2 is not applicable. |
[*Patch List]
;mode=option
;grouping=split2
file_source './pchtxts/*/*.pchtxt'Source functions define where list data is pulled from and act as dynamic input providers for commands and placeholders.
Defines an inline list for option, slot, named_step_trackbar, or other list-based modes.
list_source '(Value A, Value B, Value C)'Use {list_source(<INDEX>)} to reference a specific item by zero-based index. Use {list_source(*)} to reference the currently selected item.
Reads entries from a plain text file (one entry per line). Also compatible with tables, where it renders each line as a row.
list_file_source <PATH_TO_TEXT_FILE>
Inline directive for defining a list from a literal string within a command context.
list '(Item 1, Item 2, Item 3)'
Inline directive for reading a list from a text file within a command context.
list_file <PATH_TO_TEXT_FILE>
Iterates over files matching a wildcard pattern, exposing each matched file as a source value. In on: / off: toggle sections, evaluates file existence to determine toggle state.
file_source <WILDCARD_PATH_PATTERN>
Additional variables available within file_source contexts:
| Variable | Description |
|---|---|
{file_name} |
The filename (without extension) of the current matched file. |
{folder_name} |
The name of the parent folder of the current matched file. |
{sourced_path} |
The full resolved path of the current matched file. |
Inline directive that excludes specific paths from the results of the enclosing file_source resolution.
filter <PATH_TO_FILTER_TXT>
Uses section names from an INI file as the list values.
ini_file_source <PATH_TO_INI_FILE>
Reads a value from an INI file, making it available via {ini_file(<SECTION>, <KEY>)}.
ini_file <PATH_TO_INI_FILE>
Inline directive for defining a JSON object from a literal string.
json_source '[{"key":"value"}, ...]' <KEY>
Use {json_source(<KEY>)} to retrieve values.
Reads a JSON file as the data source. Optionally filters by a specific key.
json_file_source <PATH_TO_JSON_FILE> [JSON_KEY]
Additional variables: {jsonPath}, {jsonKey}.
Inline directive for defining a JSON mapping from a literal string.
json '{"key1":"value1","key2":"value2"}'
Use {json(<KEY>)} to retrieve values.
Inline directive for reading JSON data from a file within a command context.
json_file <PATH_TO_JSON_FILE>
Inline directive for reading and parsing hex data from a binary file.
hex_file <PATH_TO_FILE>
Forwards execution to another package's INI file. Used with ;mode=forwarder.
package_source '<PATH_TO_PACKAGE_INI_FILE>'
Placeholders are resolved at runtime and inserted into command arguments. They use {...} syntax. Placeholders support nesting (e.g. {math({index}+1)}).
| Placeholder | Description |
|---|---|
{ram_vendor} |
RAM vendor name. |
{ram_model} |
RAM model number. |
{ams_version} |
Atmosphere version (e.g. 1.7.1). |
{hos_version} |
Horizon OS version (e.g. 18.1.0). |
{cpu_speedo} |
CPU speedo fuse value. |
{cpu_iddq} |
CPU IDDQ fuse value. |
{gpu_speedo} |
GPU speedo fuse value. |
{gpu_iddq} |
GPU IDDQ fuse value. |
{soc_speedo} |
SOC speedo fuse value. |
{soc_iddq} |
SOC IDDQ fuse value. |
{title_id} |
Title ID of the currently running game. Returns null when idle. |
{build_id} |
Build ID of the currently running game. |
{local_ip} |
Local IP address of the device. |
{backlight} |
Current handheld backlight level. |
{volume} |
Current system master volume level. |
{package_version} |
Version string of the current package (from the package header). |
| Placeholder | Description |
|---|---|
{value} |
Current value of the active trackbar/slider. |
{index} |
Current index of the active selection or list. |
| Placeholder | Description |
|---|---|
{list_source(<INDEX>)} |
Fetches an item from the current list_source by zero-based index. |
{list_source(*)} |
Returns the currently selected item from the active list_source. |
{json(<KEY>)} |
Fetches a value from the current inline JSON source by key. |
{json_source(<KEY>)} |
Fetches a value from the current json_source by key. |
{ini_file(<SECTION>, <KEY>)} |
Returns the value for a key in a section of the current INI source. |
| Placeholder | Description |
|---|---|
{slice(<STRING>, <START>, <END>)} |
Returns a substring from START to END (exclusive). |
{split(<STRING>, <PATTERN>, <INDEX>)} |
Splits a string by a delimiter and returns the part at INDEX. |
{length(<STRING>)} |
Returns the character count of the string. Leading/trailing whitespace is trimmed. |
| Placeholder | Description |
|---|---|
{decimal_to_hex(<DECIMAL>)} |
Converts a decimal integer to a hex string. |
{decimal_to_hex(<DECIMAL>, <BYTE_GROUP_SIZE>)} |
Same, with explicit byte group size. |
{ascii_to_hex(<ASCII>)} |
Converts an ASCII string to its hex representation. |
{hex_to_rhex(<HEX>)} |
Reverses byte order of a hex string (big-endian ↔ little-endian). |
{hex_to_decimal(<HEX>)} |
Converts a hex string to its decimal representation. |
{base64_decode(<ENCODED_STRING>)} |
Decodes a Base64-encoded string. |
| Placeholder | Description |
|---|---|
{math(<EXPRESSION>)} |
Evaluates a mathematical expression. Supports +, -, *, /, %, and parentheses. |
{math(<EXPRESSION>, true)} |
Same, but forces integer output. |
{random(<START>, <END>)} |
Returns a random integer between START and END (inclusive). |
| Placeholder | Description |
|---|---|
{timestamp} |
Returns the current Unix timestamp as a string. |
{timestamp(<FORMAT>)} |
Returns the current time formatted per a strftime format string (e.g. {timestamp(%Y-%m-%d)}, {timestamp(%s.%f)} for fractional seconds). |
These render as graphical button/UI symbols rather than text.
| Placeholder | Symbol |
|---|---|
{A}, {B}, {X}, {Y}
|
Face buttons |
{L}, {R}, {ZL}, {ZR}
|
Shoulder / trigger buttons |
{DUP}, {DDOWN}, {DLEFT}, {DRIGHT}
|
D-Pad directions |
{LS}, {RS}
|
Left stick / right stick clicks |
{PLUS}, {MINUS}
|
Plus and Minus buttons |
| Placeholder | Symbol |
|---|---|
{POWER} |
Power button |
{HOME} |
Home button |
{CAPTURE} |
Capture button |
| Placeholder | Symbol |
|---|---|
{UP_ARROW}, {DOWN_ARROW}, {LEFT_ARROW}, {RIGHT_ARROW}
|
Cardinal arrows |
{RIGHT_UP_ARROW}, {RIGHT_DOWN_ARROW}, {LEFT_UP_ARROW}, {LEFT_DOWN_ARROW}
|
Diagonal arrows |
| Placeholder | Symbol |
|---|---|
{REFRESH_SYMBOL} |
Refresh/reload icon |
{WARNING_SYMBOL} |
Warning/caution icon |
{INFO_SYMBOL} |
Information icon |
For package structure, headers, boot/exit hooks, and configuration options, see the Package Reference.
For the latest updates and community packages, visit github.com/ppkantorski/Ultrahand-Overlay.
Notice: Documentation is currently a work-in-progress. For clean examples, look at some of the more well-crafted Ultrahand Packages out there for guidance.

