The manual

The command line

Use omacrt to control the television, launch media and manage the collection from a terminal. The Omarchy panel calls these same commands. On other Hyprland desktops, use them directly or bind them to keys.

The commands can also be used in scripts.

Output format

Command output uses these elements:

• the head is the mark and, in the self test only, the wordmark beside it
• a field is a label and a value: OUTPUT, DAC, LIBRARY
• a lamp is the green or red block beside a field that is up or down
• a check is a row tagged OK, WARN or FAIL
• a step is one labelled line printed as something happens: audio:, launcher:, mode:

doctor and setup accept keyboard input and redraw in place. Other commands print their output once. All commands leave output in terminal scrollback; none clears the terminal or uses the alternate screen.

When output is piped or redirected, the commands use plain text. NO_COLOR, TERM=dumb and --plain also select this format. The text and exit codes remain compatible with scripts written before the visual output was added.

The television

omacrt on [ntsc|pal]     modeline, sync, audio to the set, launcher
omacrt off               launcher closed, audio back, output disabled
omacrt toggle            one or the other
omacrt boot              login reset: output off, audio back to the desktop
omacrt status [--json]   output, mode, converter, audio, launcher, library, BIOS
omacrt mode ntsc|pal|film|480i|576i [--lines N] [--hz H] [--shift-x X] [--shift-y Y] [--keep]
omacrt restart           off and on again, in one word
omacrt watchdog          put the display back if it dies

on runs these steps in order:

1. It applies the modeline to the leased connector through Hyprland's own configuration API.
2. It waits a second for the converter to lock, then selects the composite sync mode over the I2C bus.
3. It switches the graphics card's audio to the converter and points the launcher's streams at that sink.
4. It tells Hyprland that a fullscreen window is taking over, and pins the launcher to that output.
5. It starts the launcher with the keyboard.

off reverses these steps. Add boot to your Hyprland autostart if you want login to turn off the television output and return audio to the desktop.

mode ntsc --lines 224 keeps the line rate and refresh rate while centring 224 active lines in the frame. This preserves the vertical line count of a Super Nintendo game. See How a game gets its mode.

mode --keep gives the television the timing that it has now, with only the given shift changed. The pause menu uses it to move a picture while a game runs.

watchdog runs while the tube is on and puts the display back if the process dies. on starts it and off stops it, so it is rarely typed.

Launching games and video

omacrt play <title|path> [--force]   out of the index, or a file
omacrt watch <file|url> [--later]    a film or a link, now or into Videos
omacrt focus                         give the tube the keyboard again
omacrt-pick [system]                 a picker on the desktop, the game on the tube

play searches for an exact title, then a title beginning with the search text, then a title containing it. Shorter matches come first. It prints the selected game. If another game is running, the command refuses to launch unless you use --force to stop it first.

omacrt-pick opens a fuzzy-search picker and passes the selection to play. The Omarchy menu’s Play a game entry uses it. On another desktop, you can bind it to a key.

Launcher commands

omacrt shell start|stop|restart|focus
omacrt shell screen <name>     home games videos youtube music favorites recent
                               frame ambient monitor processes settings picture
                               style pads diagnostics about power
omacrt shell key <input>...    home up down left right fire back fav alt start
                               search osk del next prev first last
omacrt shell type <text>       into the search bar
omacrt game key <key> [ms]     a key inside the running game, held that long

The launcher accepts commands through a named pipe. Tests and recorded tours use this interface to navigate the menus. A running game retains the physical keyboard and pad; launcher-pipe commands do not reach it.

Use a screen name to open a page directly. The desktop menu uses this method.

omacrt game quit stops the running emulator process. It does not press a key. An exit key went through the core first, and a core that reads the keyboard kept it: ScummVM closed itself and left RetroArch on an empty menu.

Pads

omacrt pads [--json]                 the order, and what is connected
omacrt pads devices                  what the kernel shows, in RetroArch's
                                     enumeration order, with each index
omacrt pads mapping [--json]         what SDL makes of each pad, and whether
                                     the letters on its face are crossed
omacrt pads move <port> up|down      one port along
omacrt pads forget <port>            off the list
omacrt pads identify <port>          shake it

The order lives in pads.toml and one writer holds it at a time. While the launcher is running, these commands ask it to make the change, because it owns the file. With nothing running, they edit the file directly. Pads and input explains what the order decides.

The collection

omacrt library [--json]                    systems, counts and sources
omacrt library scan [DIR...] [--progress]  index everything under a folder
omacrt library cores [--json]              the core each system needs, and its package
omacrt library set SYS core=X|dir=D        change a system's core or folder
omacrt library set SYS shift_x=N|shift_y=N the position of a system's picture
omacrt library covers [SYS...] [--limit N] box art, matched by title
omacrt library arcade                      MAME's machine list, for the arcade filters
omacrt library hiscore [SET...]            the record each arcade game keeps
omacrt library cheevos                     the RetroAchievements account and its progress
omacrt library games [--system S] [--limit N]
omacrt library discover | roots add|remove DIR | assign DIR SYSTEM | unknown | systems
omacrt bios [--json]                       what each core expects, and what is missing
omacrt bios import DIR [--all]             copy them out of another collection
omacrt bios discover [--json]              folders on the disks that hold BIOS files

scan takes folders in any layout and remembers them as roots. With no arguments it rescans them and looks for mounted disks that look like collections. unknown lists what it could not place and assign teaches it. cores names the package a missing core comes from, which lets the library overlay offer to install it.

covers downloads libretro thumbnails in advance. It matches the exact filename first, then searches a title index using the region order in settings. If an arcade set has no thumbnail, covers downloads its flyer from the Arcade Database. The launcher also fetches missing covers as needed.

hiscore reads the high score tables that MAME and FinalBurn Neo save, and prints the top score of each set. A dash shows a set whose table the launcher cannot read. cheevos tells you if the RetroAchievements account works, and lists your progress.

The photo frame

omacrt frame check       is the server there, does it take the key
omacrt frame fill [N]    prepare N photographs ahead of an evening
omacrt frame clear       throw the prepared ones away

Configure the Immich server address and API key in ~/.config/omacrt/immich.toml. OmaCRT passes the key to curl through standard input, keeping it out of the process list. If this file is missing, the frame reports that it needs configuration. Other features remain available.

Screenshots and recordings

omacrt shot out.png           one frame out of the launcher's own framebuffer
omacrt record start out.mp4   and stop, for a film of it

These commands capture the launcher’s 320 by 240 framebuffer before it reaches the cable. They do not photograph or record the physical television.

Audio and converter controls

omacrt audio crt|desktop|all|apps   where the sound goes
omacrt audio volume N               the set's own volume, up to 150
omacrt dac status|reset|watch       the converter, and whether it has lock
omacrt dac listen                   every loss of lock, timestamped, no reset
omacrt dac csync and|xor|separate   how the two sync signals are combined

audio crt routes OmaCRT’s streams to the television. all makes it the default sink for all audio and remembers the previous default. dac csync configures the tested converter. The converter explains this setting and converters that use no control bus.

Status and diagnostics

omacrt status [--json]      the machine, in one sheet
omacrt version              which build this is
omacrt doctor [--fix]       what is wrong, and what has been left behind
omacrt doctor --plain       the lines, with no picture
omacrt config               the settings as they are
omacrt config set KEY VALUE one key of crt.toml, comments kept

Run status for a summary of the connector, reported display name, mode, line rate, converter lock, audio route, launcher and collection size.

Run doctor to check the graphics driver, connector leasing, systemd and debugfs. These checks work without a television attached. With hardware connected, it also shows the modeline diagram, output map and converter lock. Use --fix to clean up orphan emulators, stale watchdog pidfiles and partially downloaded cache files.

Without Omarchy, the report labels desktop integration as Hyprland and skips the bar-plugin check.

Configuration and data files

config set updates one key while preserving comments. Before saving a file from a newer build, OmaCRT keeps a versioned copy containing any keys this build cannot read. Persistent files are saved through a temporary file and a rename, with the previous version kept as .bak.