RETROARCH(6)

👑 RETROARCH(6) 👑

okay so bestie, we're in the System Manager's Manual: retroarch section, page 6, and this is the whole vibe of retroarch. Buckle up, she's a long one. 💅

---

✨ NAME ✨

retroarch — the reference frontend for the libretro API. periodt. 👑

---

✨ SYNOPSIS ✨

retroarch [rom file(s)] [OPTIONS]...

like. that's it. that's the whole shape of it. rom files go in, options go in, magic comes out. 🦋

---

✨ DESCRIPTION ✨

so retroarch is the reference frontend for the libretro API, which is a whole thing. let me break it down.

libretro is basically an abstraction of a game system — like, it's the concept of "a game system" without the console part attached. and literally any frontend can implement it. it's not locked to one thing, it's not gatekept, it's giving open energy. ✨

the libretro API itself? it's designed for games, emulators and multimedia. so yeah, games, but also everything adjacent. it's versatile like that.

and retroarch — what does she actually do? she focuses on exposing needed functionality for the game system through command line and configuration files. that's the whole job. she's the interface, she hands you the controls, she doesn't overcomplicate it. 😌

oh and also — she features a simple built-in UI. so if you don't wanna live in the terminal forever, you don't have to. she's got range. 💖

---

✨ EXAMPLE COMMANDLINE ✨

okay real examples, because reading is one thing and doing is another. 🌸

🎀 Load content, using a specific libretro core and config file 🎀

retroarch --config ~/.config/retroarch/retroarch.cfg --libretro /path/to/libretro/core.so /path/to/rom.rom --verbose

see how she's pointing at a config file, then a core, then the rom, then asking for --verbose? iconic sequencing. no notes. 💅

🎀 No command line options will start RetroArch in menu mode 🎀

retroarch

literally just. type it. that's all. no options, no arguments, and she opens up in menu mode. lowkey the easiest way in. 🫶

🎀 Start RetroArch in menu mode, with verbose logging 🎀

retroarch --menu --verbose

same energy, but she's telling you everything while she does it. verbose logging hits different when something's being weird. 🔥

---

✨ Menu ✨

this one's a mini-section so listen up:

Menu refers to the built-in GUI system for RetroArch. and here's the important part — it is aimed at being controlled with a gamepad only. 🎮

so like. keyboard people, don't come for her. she was built for the controller. that's the design choice. respect it. 💅

---

✨ DEFAULT CONTROLS ✨

bestie this is the whole section, don't blink: by default, only keyboard input is accepted.

that's it. that's the default. keyboard in, everything else is a you problem until you change it. 😭

---

✨ GENERAL OPTIONS ✨

• [rom file] — bestie if you don't drop a rom file path on the command line, retroarch is gonna try to load a core with no rom at all. which… only works with some libretro cores, so don't be surprised. retroarch runs uncompressed content by default, but it can uncompress stuff in .zip/deflate format if that support got compiled in. which content types work totally depends on the libretro implementation you're using. iykyk 💅
• --help, -h — prints the help text. that's it. that's the whole job. 🫶
• --menu — starts you directly in the in-game menu if it's enabled. does not need content or a libretro implementation to be set — you can load those later from inside the menu. and fun fact: if you pass no arguments to retroarch at all, it's literally equivalent to calling retroarch with this as the only argument. 🌸
• --features — prints the available features that got compiled into RetroArch, then exits. a little peek behind the curtain ✨
• -L PATH, --libretro PATH — path to the libretro implementation you wanna use. this option overrides anything in a config file. heads up though: it's only available if RetroArch was compiled with dynamic libretro loading. 👑
• --save PATH, -s PATH — overrides the path used for save ram (*.srm). (deprecated!) if you don't use this flag, the save ram path gets inferred from the rom path name and dropped in the same directory as the rom file, with the extension swapped out for .srm. if PATH is a directory, RetroArch treats it as the save file directory, and the save file name gets inferred from the rom name.
• --savestate PATH, -S PATH — overrides the path used for save states. (also deprecated!) without this flag, the save state path gets inferred from the rom path name, put in the same directory as the rom file, with the extension replaced by .state. if PATH is a directory, RetroArch treats it as the save state directory, and the state file name gets inferred from the rom name.

⚠️ lowkey important: save states are bound to the libretro implementation you're using. switch to a different libretro and you could invalidate that save state file. no take-backs. 💀

• --fullscreen, -f — always starts RetroArch in fullscreen. completely disregards whatever your configuration file says. main character energy, no notes 🌈
• --config PATH, -c PATH — sets the configuration file path. retroarch uses this path to load the config file. if it's not defined, retroarch goes hunting through platform-specific paths to find the config file. /etc/retroarch.cfg (when installed), or retroarch.cfg in the source tarball, serves as a skeleton configuration file. /etc/retroarch.cfg should really only be a skeleton config, okay? 🎀

Unix-like systems will look in $XDG_CONFIG_HOME/retroarch/retroarch.cfg first. if $XDG_CONFIG_HOME isn't defined, it's assumed to be $HOME/.config as per specification. then it tries $HOME/.retroarch.cfg. if both paths fail, RetroArch will try to create a new, default config file in $XDG_CONFIG_HOME/retroarch/retroarch.cfg (or the $HOME/.config default for $XDG_CONFIG_HOME). if all of that fails, default settings get assumed. and if RetroArch does create a new default config file, it'll attempt to load the skeleton config file /etc/retroarch.cfg and use that as a basis — which lets distributions set up default paths for libretro cores and similar things. also: a config file does not need to define every possible option, only the ones you actually wanna override. 💜

If config_save_on_exit = true is set in the config file, RetroArch will overwrite the config file on exit. settings can be changed from within the menu. but beware bestie — if RetroArch overwrites a config file, formatting, comments, etc. will be lost. if RetroArch creates a default config file, it'll have config_save_on_exit set automatically. 🙈

Windows will look in retroarch.cfg in the same folder where retroarch.exe resides. a default config file will also be created in the same manner as Unix. 🦋

• --appendconfig PATH — appends a different set of config files to the config file loaded in -c (or the default). multiple config files are delimited by ','. every config file gets appended in order, where the key-value pairs of the next config file take priority over the old ones. stacked configs, slay ✨
• --subsystem SUBSYSTEM — use a subsystem of the loaded libretro core. multiple content files are loaded as multiple arguments. if you need to skip content, use a blank ("") command line argument. content must be loaded in an order that depends on the particular subsystem being used — so check the verbose log output to learn how a particular subsystem wants its content loaded. 👑
• --nodevice PORT, -N PORT — disconnects an input device from port number PORT. possible values for PORT are 1 to 8. this may be needed for some odd games to run properly. if you set it explicitly here, it overrides the config file for that port. 🎮
• --dualanalog PORT, -A PORT — connects a DualAnalog controller into port PORT. possible values are 1 to 8. if you set it explicitly here, it overrides the config file for that port. 🕹️
• --device PORT:ID, -d PORT:ID — connects a generic input device ID into port PORT. possible values for port are 1 to 8. if set explicitly here, it overrides the config file for that port. ID is an unsigned number corresponding to the device for a libretro core. 💅
• --record PATH, -r PATH — activates video recording of gameplay into PATH. using a .mkv extension is recommended. the codecs used are (FFV1 or H264 RGB lossless (x264))/FLAC, which is suitable for processing the material further. film it, bestie 🎬
• --recordconfig PATH — sets the path to a config file for use during recording.
• --size WIDTHxHEIGHT — lets you specify the exact output width and height of recording. this option overrides any configuration settings. the video input gets scaled with point filtering before being encoded at the correct size. 🌸
• --play-replay PATH, -P PATH — play back a movie recorded in the .replay format. the cart ROM and movie file need to correspond, and it also requires you to play back with the same libretro backend that was used for recording. no swapping, no cap 🫶
• --record-replay PATH, -R PATH — start recording a .replay video to PATH immediately after startup. hit the ground running ✨
• --sram-mode MODE, -M MODE — MODE designates how to handle SRAM. the format of the second parameter is {no,}load-{no,}save. these two boolean values tell whether SRAM loading and SRAM saving should take place. note that noload-save implies that the SRAM will be overwritten with new data. 😭
• --verbose, -v — activates verbose logging. for the girlies who need to see everything 🔍
• --host, -H — be the host of netplay. waits until a user connects. the host will always assume user 1. 👑
• --connect SERVER, -C SERVER — connect to a host of netplay. will always assume user 2. 🦋
• --frames FRAMES, -F FRAMES — sync frames to use when using netplay. more frames allow for more latency, but require more CPU power. set FRAMES to 0 to have perfect sync. 0 frames is only suitable for LAN. defaults to 0. 🌈
• --port PORT — network port used for netplay. this defaults to 55435. this option affects both TCP and UDP.
• --spectate — if netplay is used, it'll go into a spectator mode. spectator mode lets one host live stream game playback to multiple clients. essentially, clients receive a live streamed replay movie file. clients can connect and disconnect at any time, and thus cannot interact as user 2. for spectating mode to work, both host and clients need to use this flag. 💅
• --command CMD — sends a command over UDP to an already running RetroArch application, and exits. the command is formatted as "COMMAND;HOST;PORT". HOST and PORT are both optional. "COMMAND;HOST" will set PORT to the "network_cmd_port" default setting. if only "COMMAND" is used, HOST and PORT will be assumed to be "localhost" and "network_cmd_port" respectively. and the available commands get listed if "COMMAND" is invalid. 📡
• --nick NICK — pick a nickname for use with netplay. this is purely cosmetic, and only serves to help users identify each other. 💖
• --ups PATCH, -U PATCH — attempts to apply an UPS patch to the current content image. no files are altered. if this flag isn't specified, RetroArch will look for a .ups file with the same basename as the content specified. ✨
• --bps PATCH — attempts to apply a BPS patch to the current content image. no files are altered. if this flag isn't specified, RetroArch will look for a .bps file with the same basename as the content specified. 🎀
• --ips PATCH — attempts to apply a IPS patch to the current content image. no files are altered. if this flag isn't specified, RetroArch will look for a .ips file with the same basename as the content specified.

⚠️ heads up: RetroArch cannot perform any error checking on whether patching was successful, because of how IPS works. it's just like that sometimes 😭

• --xdelta PATCH — attempts to apply an Xdelta patch to the current content image. no files are altered. if this flag isn't specified, RetroArch will look for a .xdelta file with the same basename as the content specified. only available if RetroArch was built with Xdelta support. 🦋
• --no-patch — disables all kinds of content patching. periodt. 💅
• -D, --detach — detach from the current console. this is currently only relevant for Microsoft Windows. 🌸

---

🌸 ENVIRONMENT 🌸

ok so bestie</p> listen — retroarch is obsessed with these little environment variables 💖 and if you set one, it literally overrides whatever the matching config file option says. it's giving "env var said it first, periodt" 👑

---

• LIBRETRO_DIRECTORY — tells RetroArch which directory to go dig through for core and info files, and it overrides the libretro_directory configuration file option. 🦋
• LIBRETRO_ASSETS_DIRECTORY — points RetroArch at the directory where it should look for assets, and it overrides the assets_directory configuration file option. 🎀
• LIBRETRO_AUTOCONFIG_DIRECTORY — this one tells RetroArch where to find controller auto-configuration files, and it overrides the joypad_autoconfig_dir configuration file option. 🎮✨
• LIBRETRO_CHEATS_DIRECTORY — the directory where RetroArch hunts down cheat files, and it overrides the cheat_database_path configuration file option. 😈
• LIBRETRO_DATABASE_DIRECTORY — where RetroArch looks for database files, and it overrides the content_database_path configuration file option. 🗂️
• LIBRETRO_SYSTEM_DIRECTORY — the directory RetroArch searches for system files, and it overrides the system_directory configuration file option. 💜
• LIBRETRO_VIDEO_FILTER_DIRECTORY — tells RetroArch where the video filters live, and it overrides the video_filter_dir configuration file option. 🌈
• LIBRETRO_VIDEO_SHADER_DIRECTORY — where RetroArch goes looking for video shaders, and it overrides the video_shader_dir configuration file option. 🔥

---

no cap, every single one of these is a straight-up override — the env var wins, the config file option just has to sit there and take it 💅

---

and that's a wrap on the whole page, bestie!! 🫶 this was RETROARCH, version dated January 20, 2025, filed under RETROARCH(6) — you read the whole thing, which is genuinely main character energy, go take a nap and drink some water 🧚💖 ⭐