Skip to main content
This is unreleased documentation for the next Zaparoo Core release.
For up-to-date documentation, see the latest version (Stable).
Version: Next

Terminal UI

The Zaparoo Core terminal UI, or TUI, is Core's local menu interface. Use it when you are on the device running Core and want to check status, write a token, manage media, or change settings without opening the Zaparoo App, Web UI, or command line.

The TUI is built into Core on MiSTer, Batocera, Linux, SteamOS, Bazzite, ChimeraOS, LibreELEC, and RePlayOS. Windows runs Core from the system tray instead and uses the App or Web UI for settings.

Opening the TUI​

Start Core from the launcher, script, or executable documented for your platform. For example, MiSTer users open Zaparoo from the Scripts menu, and Batocera users open it from the Ports system in EmulationStation.

On Linux, SteamOS, Bazzite, ChimeraOS, LibreELEC, and RePlayOS, running the zaparoo binary with no flags opens the TUI and starts the service if it is not already running. Use the relevant platform guide for install paths and startup behavior.

Service or daemon modes skip the TUI. See the command line reference for platform flags.

Main screen​

The main screen shows the local Core service status, device IP address, the running version and update state, Web UI address, connected reader status, and the most recent scanned token.

While the service is starting, the status reads STARTING. If it is not running, or it started and stopped on a problem it could not fix (NOT WORKING), most actions are disabled, the status shows the last error from the log, and the Settings button becomes Logs so you can view or upload the log for support.

Exiting the TUI may leave the Core service running in the background, depending on how Core was started on that platform.

Main actions​

ActionWhat it does
Search mediaSearches indexed media and writes the selected result to a token.
Custom writeWrites custom ZapScript to a token.
Manage mediaUpdates the media index and runs metadata scraping.
SettingsOpens Core settings, backups, Zaparoo Online, TUI settings, reader settings, audio settings, paired clients, and logs.
ProfilesCreates, switches, and manages device profiles and their switch cards.
ExitCloses the TUI.

Managing media​

Open Manage media to update the media index, scrape metadata, or resume/cancel media jobs.

Managing profiles​

Open Profiles to create or switch device profiles, set profile roles and playtime limit overrides, reset lost switch cards, or write a switch card. The first profile is an administrator and requires a PIN.

Use Settings > Profiles to require an active personal profile before launching media. Use Settings > Clients to pair or revoke remote clients, assign member or admin access, and require encrypted remote connections.

Writing tokens​

The TUI can write tokens from Search media or Custom write.

Search results use the TUI write_format setting:

  • zapscript writes the ZapScript generated by Core. This is the default.
  • path writes the media path directly.

Search results load more entries automatically as you approach the end of the list without clearing existing results or moving your selection.

Custom writes parse the ZapScript before writing and show an error for unknown command names.

Backups and Zaparoo Online​

Open Settings > Backup to create, inspect, restore, or delete device backups. Supported devices can also link a Zaparoo Online account, upload cloud snapshots, choose an automatic schedule, and restore compatible snapshots from other devices on the account.

Settings > Online shows account-link status and available online services. Linking displays a URL and one-time code to approve from another device, then offers to turn on every online feature at once. The online toggles stay disabled until the device is linked, and the All online features switch turns them all on or off together, including cloud backup only when the account has Warp. The Play history sync toggle separately controls whether retained and future play sessions are uploaded; account linking alone leaves history local. The Remote control toggle works the same way, and the Remote status line under it shows whether Zaparoo Online can currently send commands to this device; see remote control. The Library sync toggle syncs favorites, likes, play later, decks, and the list of games on this device with the account; see Library sync.

Reload Core​

After editing settings, mappings, or custom launcher files outside the terminal UI, open Settings > Advanced > Reload Core. Core reloads those files, refreshes supported platform launcher data such as MiSTer RBF files and Batocera's EmulationStation system configuration, then reports whether the reload succeeded.

Some settings still require a full service restart.

TUI settings​

TUI-specific settings live in tui.toml next to config.toml. You can change them from Settings > TUI, or edit the file manually. The settings are listed below.

The TUI settings menu includes:

  • theme
  • write_format
  • mouse
  • crt_mode
  • on_screen_keyboard

crt_mode and on_screen_keyboard default to true on MiSTer and false elsewhere.

Logs​

Open Settings > Logs to view recent Core log output, refresh the view, or upload the log for support. It also works from the Logs button shown while Core is not running.

Some platforms also show a Copy action that copies the log to a platform-specific location.