Skip to content

Command Reference

ppkantorski edited this page Apr 21, 2026 · 87 revisions

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.


Table of Contents

  1. Flow Control
  2. Filesystem Commands
  3. INI Commands
  4. JSON Commands
  5. Hex Editing Commands
  6. Mod Conversion Commands
  7. System Commands
  8. UI & Display Commands
  9. Command Modes
  10. Grouping Modes
  11. Source Functions
  12. Placeholder Variables
  13. Symbol Placeholders

Flow Control

try: Block

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 missing

on: / off: Blocks

Used 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 off

erista: / mariko: Blocks

Conditionally 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/

Filesystem Commands

mkdir / make

Creates a directory, including all intermediate directories.

mkdir <DIRECTORY_PATH>

copy / cp

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.

move / mv

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>

rename

Alias for move. Behaves identically.

rename <SOURCE_PATH> <DESTINATION_PATH>

delete / del

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 to null*/*null are treated as dangerous and return a failed command without executing.

mirror_copy / mirror_cp

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>

mirror_delete / mirror_del

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>

download

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>

download-no-retry

Same as download but makes zero retry attempts on failure.

download-no-retry <FILE_URL> <DESTINATION_PATH>

unzip

Extracts a ZIP archive to the specified destination, preserving the archive's directory structure.

unzip <ZIP_FILE_PATH> <DESTINATION_PATH>

touch

Creates an empty file at the specified path if it does not already exist.

touch <FILE_PATH>

compare

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>

flag

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>

dot-clean

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>

path_exists

Returns command success if the specified path exists, failure otherwise. Intended for use inside try: blocks.

path_exists <PATH>

!path_exists

The inverse of path_exists — returns command success if the path does not exist.

!path_exists <PATH>

INI Commands

set-ini-val / set-ini-value

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>

set-ini-key

Renames a key within a section.

set-ini-key <FILE_PATH> <SECTION> <CURRENT_KEY> <NEW_KEY>

add-ini-section

Adds a new section to an INI file. Creates the file if it does not exist.

add-ini-section <FILE_PATH> <SECTION>

rename-ini-section

Renames an existing section.

rename-ini-section <FILE_PATH> <CURRENT_SECTION> <NEW_SECTION>

remove-ini-section

Removes an entire section from an INI file.

remove-ini-section <FILE_PATH> <SECTION>

remove-ini-key

Removes a key-value pair from a section.

remove-ini-key <FILE_PATH> <SECTION> <KEY>

set-ini-val-matching-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>

remove-ini-key-matching-key

In every section that contains <PATTERN_KEY>, removes <DESIRED_KEY>.

remove-ini-key-matching-key <FILE_PATH> <PATTERN_KEY> <DESIRED_KEY>

JSON Commands

set-json-val / set-json-value

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>

set-json-key

Renames a key in a JSON file.

set-json-key <JSON_PATH> <CURRENT_KEY> <NEW_KEY>

Hex Editing Commands

hex-by-offset

Writes hex data at an absolute byte offset within a file.

hex-by-offset <FILE_PATH> <OFFSET> <HEX_DATA>

hex-by-custom-offset

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>

hex-by-custom-decimal-offset

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.

hex-by-custom-rdecimal-offset

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]

hex-by-swap

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]

hex-by-string

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]

hex-by-decimal

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_SIZE must also be provided.

hex-by-rdecimal

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]

hex-by-pattern

Replaces all data matching a hex wildcard pattern with replacement hex data.

hex-by-pattern <FILE_PATH> <HEX_PATTERN_TO_REPLACE> <HEX_DATA_REPLACEMENT>

Mod Conversion Commands

pchtxt2ips

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>

pchtxt2cheat

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.


System Commands

reboot

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 .ultra extension, any reboot command automatically triggers the Ultrahand Updater payload (/config/ultrahand/payloads/ultrahand_updater.bin) to safely apply the update before rebooting.

shutdown

Shuts down the system or all connected Bluetooth controllers.

shutdown
shutdown controllers

backlight

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.

volume

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}

set-region

Sets the system region. Requires a reboot to apply. Case-insensitive.

set-region <REGION>

<REGION> is one of: JPN, USA, EUR, AUS, HTK, CHN.

open

Opens an overlay from a package command, optionally passing launch arguments.

open <PATH_TO_OVERLAY_FILE> [LAUNCH_ARG_1] [LAUNCH_ARG_2] ...

exec

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.

exit

Closes Ultrahand. Optionally navigates to the Overlays or Packages menu on next open.

exit
exit overlays
exit packages

UI & Display Commands

notify / notification

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.

notify-now / notification-now

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]

API (External) Notifications

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.

set-footer

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>

refresh

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.

refresh-to

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.

back

Simulates a B button press, navigating back one level.

back

logging

Enables command and error logging for the current package execution. Logs are written to log.txt in the package folder.

logging

clear

Clears Ultrahand-internal caches or log files.

clear log
clear hex_sum_cache

Command Modes

The ;mode= header defines how a list item behaves and is rendered.

;mode=default

Standard execution. The command runs immediately when the user presses A.

[Reboot]
reboot

;mode=toggle

A 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 off

Note: ;mode=hold is no longer a valid mode. Use ;hold=true with default, option, or slot instead.

;mode=option

Displays a dropdown list of options. The selected option is shown as the footer.

[*Graphics Quality]
;mode=option
list_source '(Low, Medium, High, Ultra)'

;mode=slot

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(*)}

;mode=trackbar

A continuous slider between a minimum and maximum value.

[Brightness]
;mode=trackbar
;min_value=0
;max_value=100
;units=%
backlight {value}

;mode=step_trackbar

A slider with a fixed number of discrete steps.

[CPU Profile]
;mode=step_trackbar
;min_value=0
;max_value=5
;steps=6

;mode=named_step_trackbar

A 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)'

;mode=table

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}'

;mode=forwarder

Points to another package's .ini file, opening it as a sub-menu.

[*Advanced Options]
;mode=forwarder
package_source './include/advanced.ini'

;mode=text

Displays static or dynamic text content.


Grouping Modes

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

Source functions define where list data is pulled from and act as dynamic input providers for commands and placeholders.

list_source

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.

list_file_source

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>

list

Inline directive for defining a list from a literal string within a command context.

list '(Item 1, Item 2, Item 3)'

list_file

Inline directive for reading a list from a text file within a command context.

list_file <PATH_TO_TEXT_FILE>

file_source

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.

filter

Inline directive that excludes specific paths from the results of the enclosing file_source resolution.

filter <PATH_TO_FILTER_TXT>

ini_file_source

Uses section names from an INI file as the list values.

ini_file_source <PATH_TO_INI_FILE>

ini_file

Reads a value from an INI file, making it available via {ini_file(<SECTION>, <KEY>)}.

ini_file <PATH_TO_INI_FILE>

json_source

Inline directive for defining a JSON object from a literal string.

json_source '[{"key":"value"}, ...]' <KEY>

Use {json_source(<KEY>)} to retrieve values.

json_file_source

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

json

Inline directive for defining a JSON mapping from a literal string.

json '{"key1":"value1","key2":"value2"}'

Use {json(<KEY>)} to retrieve values.

json_file

Inline directive for reading JSON data from a file within a command context.

json_file <PATH_TO_JSON_FILE>

hex_file

Inline directive for reading and parsing hex data from a binary file.

hex_file <PATH_TO_FILE>

package_source

Forwards execution to another package's INI file. Used with ;mode=forwarder.

package_source '<PATH_TO_PACKAGE_INI_FILE>'

Placeholder Variables

Placeholders are resolved at runtime and inserted into command arguments. They use {...} syntax. Placeholders support nesting (e.g. {math({index}+1)}).

Device Information

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

Trackbar / List State

Placeholder Description
{value} Current value of the active trackbar/slider.
{index} Current index of the active selection or list.

Source Accessors

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.

String Manipulation

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.

Numeric & Encoding Conversions

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.

Math & Logic

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

Time

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

Symbol Placeholders

These render as graphical button/UI symbols rather than text.

Controller Buttons

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

System Buttons

Placeholder Symbol
{POWER} Power button
{HOME} Home button
{CAPTURE} Capture button

Directional Arrows

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

UI Icons

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.

Clone this wiki locally