Utilities

These commands stop media, switch device profiles, log messages, run host commands, add delays, send launcher controls, and take screenshots.

stop

Stops the currently running media and returns to the menu.

Syntax

**stop

Arguments

None.

Examples

Stop whatever is currently playing and return to the menu:

**stop

Only stop if media is currently playing:

**stop?when=[[media_playing]]

Stop only background audio and close any background playlist, leaving the game in the main slot running:

**stop?slot=background

---

profile

Switches the device to a personal profile using its generated switch ID.

Syntax

**profile:<switch-id>

Arguments

switch-id (required) The switch ID generated by Core for the profile. Open the profile in the terminal UI to reveal or reset it. Selecting Write Card creates this command automatically.

Examples

Switch to a profile:

**profile:corn-arm-truck

Switch profiles before launching a game:

**profile:corn-arm-truck||SNES/Super Mario World.sfc

This command does not ask for the profile PIN. Anyone who knows the switch ID can activate the profile, so keep it private when the profile has limits or administrative access.

---

profile.clear

Deactivates the active personal profile and returns the device to its shared profile.

Syntax

**profile.clear

Arguments

None.

Examples

Return to the shared profile:

**profile.clear

---

playtime.extend

Grants extra time to the playtime session currently being limited, authorized by an administrator profile's switch ID. The game keeps running and no configured limit changes.

Syntax

**playtime.extend:<amount>?profile=<switch-id>

Arguments

amount (required) A duration to add to the session, such as 15m or 1h30m, or today to waive the session limit until the next local midnight. The daily limit is never affected.

Advanced arguments

Argument	Type	Default	Description
profile	string	-	Required. The switch ID of an administrator profile, which permits the grant. It never chooses who receives the time.

Examples

Add 15 minutes to the current session:

**playtime.extend:15m?profile=corn-arm-truck

Waive the session limit for the rest of the day:

**playtime.extend:today?profile=corn-arm-truck

The time goes to whoever is being limited when the card is scanned. Core only accepts the command from a physical reader and only as the sole command on the token. A single grant is between 1 minute and 24 hours, and a session can accumulate up to 24 hours. Like a profile card, the switch ID is a key; keep the card private.

---

echo

Outputs a message to the Zaparoo Core log file.

Syntax

**echo:<message>

Arguments

message (required) The text to output. Multiple arguments are joined with , and logged at "info" level.

Examples

Log "Token was scanned" to the Core log file:

**echo:Token was scanned

Log the current platform using an expression:

**echo:Platform is [[platform]]

---

execute

Runs a command on the host system.

Syntax

**execute:<command>

Arguments

command (required) The command to run, including any arguments. Arguments are split while respecting double and single quoted strings. The command is executed directly without a shell interpreter, so shell features like pipes, redirection, or command substitution are not supported. The command has a 2-second timeout.

Examples

Reboot the system:

**execute:reboot

Send a desktop notification on Linux systems with notify-send:

**execute:notify-send "Game started"

Security Requirement

This command requires explicitly enabling the arguments in the allow_execute config option. It is always blocked from remote sources. Currently, Zap Links are the only remote source; scripts sent through the Zaparoo App are checked against allow_execute normally.

---

write

Stages text to be written to the next writable card scanned by a reader.

Syntax

**write:<text>

Arguments

text (required) The text to write to the next scanned writable card. Expressions are evaluated before the write is staged.

Examples

Write the currently active media path to the next scanned card:

**write:[[active_media.path]]

Write a specific launch command to the next scanned card:

**write:Genesis/Sonic the Hedgehog.md

After scanning a token with **write:..., scan the card you want to write within one minute. The source token is ignored, so scanning the setup token again will not overwrite it. The card is not scanned as a token while the write is pending; take it off the reader once the write finishes before scanning it again.

Reader support

This command requires a writable reader that supports targeted writes, such as PN532 or supported libnfc readers.

---

delay

Pauses script execution for a specified duration, or waits until active media is ready when readiness support is available.

Syntax

**delay:<milliseconds>
**delay:media_ready

Arguments

milliseconds The number of milliseconds to pause. Must be an integer.

media_ready Wait until active media is considered ready for controls or raw input. This is useful after a launch command before sending input or a launcher control.

Examples

Pause for 500 milliseconds, or half a second:

**delay:500

Pause for 10 seconds:

**delay:10000

Launch SNES, wait 10 seconds, then press F12:

_Console/SNES||**delay:10000||**input.keyboard:{f12}

Launch a game, wait for media readiness, then press F12:

SNES/Super Mario World.sfc||**delay:media_ready||**input.keyboard:{f12}

Blocking Command

This is a blocking command. The entire script pauses until the delay completes. media_ready waits have an internal timeout, so scripts do not wait forever if readiness cannot be detected.

---

control

Dispatches a launcher control action to the active media's launcher. This allows you to send commands to whatever is currently playing, such as pausing, saving state, or skipping tracks.

Syntax

**control:<action>

Arguments

action (required) The control action to dispatch. Available actions depend on the launcher handling the currently active media.

Defined action names include:

• toggle_pause - Pause or unpause
• pause - Pause
• resume - Resume
• save_state - Save the current state
• load_state - Load a saved state
• save_ram - Save RAM data
• toggle_menu - Toggle an in-game menu
• reset - Reset the active media
• stop - Stop the active media
• fast_forward - Fast forward
• rewind - Rewind
• next - Skip to next track or disc
• previous - Go to previous track or disc
• toggle_tray - Open or close the emulated disc tray

Advanced arguments

Argument	Type	Default	Description
slot	string	primary	Media slot to control: primary or background (audio)
seconds	number	10	Seek amount for fast_forward and rewind on audio playback

Examples

Pause or unpause the currently playing media:

**control:toggle_pause

Save the current state, such as a save state in an emulator:

**control:save_state

Pause background music without affecting the active game:

**control:pause?slot=background

Info

Media must be actively playing for this command to work. If no media is active, the command will return an error. The available actions depend on the launcher, and not all launchers support all actions.

---

screenshot

Captures the current platform display and saves the screenshot to disk.

Platform Support

Currently supported on MiSTer and RePlayOS.

Syntax

**screenshot

Arguments

None.

Examples

Capture a screenshot of the current display:

**screenshot