CLI reference

Kyaraben can be fully configured through its config file and controlled via command-line.

The config file

Kyaraben stores its configuration at ~/.config/kyaraben/config.toml. The config file and the UI are kept synchronized: changes made in the UI are written to the file, and changes made to the file are reflected in the UI.

Most users do not need to edit the config file directly. It is there for users who prefer text editors or want to version-control their setup.

Example

[global]
collection = "~/Emulation"

[systems]
snes = ["retroarch:bsnes"]
psx = ["duckstation"]
gamecube = ["dolphin"]
ps2 = ["pcsx2"]

[emulators.duckstation]
version = "v0.1-10655"

[frontends.esde]
enabled = true

[sync]
enabled = true

[global]

Key	Type	Default	Description
collection	string	~/Emulation	Path to the collection
headless	bool	false	Sync-only mode: creates directories, skips emulators

[graphics]

Key	Type	Default	Description
shaders	string	manual	Global shader setting: recommended, on, off, or manual

When set to recommended, shaders are enabled only for emulators where they work well. Per-emulator overrides in [emulators.<id>] take precedence.

[savestate]

Key	Type	Default	Description
resume	string	manual	Global resume setting: recommended, on, off, or manual

When set to recommended, auto-resume (autosave on exit, autoload on launch) is enabled only for emulators that support it reliably. Per-emulator overrides in [emulators.<id>] take precedence.

[systems]

Maps system IDs to lists of emulator IDs. Each system can have one or more emulators enabled.

[systems]
snes = ["retroarch:bsnes"]
psx = ["duckstation"]

[emulators.<id>]

Optional per-emulator configuration:

[emulators.duckstation]
version = "v0.1-10655"
shaders = "on"
resume = "on"

• version: Pin to a specific version. When omitted, uses the latest supported.
• shaders: Enable managed CRT/LCD shaders. Values: on, off, manual. When omitted, follows the global [graphics] setting.
• resume: Enable auto-resume (autosave on exit, autoload on launch). Values: on, off, manual. When omitted, follows the global [savestate] setting.

[frontends.<id>]

Frontend configuration:

[frontends.esde]
enabled = true

[sync]

Synchronization configuration.

[sync]
enabled = true
autostart = true

[sync.syncthing]
listen_port = 22100
discovery_port = 21127
gui_port = 8484
relay_enabled = true

[sync.ignore]
patterns = [
  "**/shader_cache/**",
  "**/logs/**",
]

When autostart is enabled, Syncthing starts automatically when you log in. On Steam Deck, this works in both Desktop Mode and Game Mode.

See kyaraben sync for available commands.

Commands

The CLI is intentionally minimal. The config file is the interface for advanced users. The UI is for users who prefer not to edit files. The CLI is the glue: initialize, apply, check status.

kyaraben apply

Reads the config, installs emulators, generates emulator configs, and creates the folder structure. If there are conflicts with your existing configuration, kyaraben apply asks for confirmation before overwriting.

$ kyaraben apply

Applying kyaraben configuration...

Using ~/Emulation (existing data preserved)
Installing emulators (this may take a while on first run)...
Adding to application menu...
Configuring emulators...
  Installed to: ~/.local/state/kyaraben/packages/...

  Applied: ~/.config/retroarch/retroarch.cfg
  Applied: ~/.config/duckstation/settings.ini
  Applied: ~/.config/mgba/config.ini
  Applied: ~/.config/PCSX2/inis/PCSX2.ini

Done!

Your collection is ready at: ~/Emulation
Place your ROMs in the appropriate subdirectories.

Use --dry-run to preview config changes without applying them.

kyaraben status

Shows the current state: which emulators are installed, their versions, and where files are stored.

$ kyaraben status

Config: ~/.config/kyaraben/config.toml
Collection: ~/Emulation (initialized)

Enabled systems: PlayStation, Super Nintendo, Game Boy Advance, Nintendo DS

Managed emulators:
  DuckStation          v0.1-10861
  RetroArch (bsnes)    1.22.2
  mGBA                 0.10.5
  melonDS              1.1

Paths:
  DuckStation (psx)
    ROMs:          ~/Emulation/roms/psx
    BIOS:          ~/Emulation/bios/psx
    Saves:         ~/Emulation/saves/psx
    Savestates:    ~/Emulation/states/duckstation
    Screenshots:   ~/Emulation/screenshots/psx
  ...

Last applied: 2026-02-07 23:13:59

Provision status: 1 system(s) missing required files (run 'kyaraben doctor')

kyaraben doctor

Checks BIOS and firmware file status for all enabled systems.

$ kyaraben doctor

Checking provisions...

  DuckStation (psx)
    ✗ scph5501.bin (USA) - MISSING (required)
    - scph5500.bin (Japan) - not found (optional)
    - scph5502.bin (Europe) - not found (optional)
    Expected location: ~/Emulation/bios/psx

  RetroArch (bsnes) (snes)
    No provisions required.

  melonDS (nds)
    - bios7.bin (ARM7) - not found (optional)
    - bios9.bin (ARM9) - not found (optional)
    - firmware.bin (Firmware) - not found (optional)
    Expected location: ~/Emulation/bios/nds

Summary:
  1 required file(s) missing
  5 optional file(s) missing

kyaraben init

Creates a default config.toml with popular systems enabled:

$ kyaraben init

Created configuration at ~/.config/kyaraben/config.toml

Enabled 13 systems with default emulators.
Run 'kyaraben apply' to install emulators and create directories.

Options:

• -d, --collection <PATH>: set the collection path (default: ~/Emulation)
• -f, --force: overwrite existing configuration
• --headless: create a headless configuration for sync hubs (no emulators)

With --headless, kyaraben apply creates directories for all systems but does not install emulators. See headless server guide for setup instructions.

kyaraben uninstall

Removes Kyaraben-managed files. Never touches the Collection .

$ kyaraben uninstall

This will remove:

  ~/.local/state/kyaraben (packages, manifest, state)

  Kyaraben installation:
    ~/.local/bin/kyaraben-ui
    ~/.local/bin/kyaraben
    ~/.local/share/applications/kyaraben.desktop

  Desktop entries:
    ~/.local/share/applications/kyaraben/duckstation.desktop
    ~/.local/share/applications/kyaraben/retroarch.desktop
    ~/.local/share/applications/kyaraben/mgba.desktop

  Icons:
    ~/.local/share/icons/hicolor/256x256/apps/kyaraben-duckstation.png
    ~/.local/share/icons/hicolor/scalable/apps/kyaraben-retroarch.svg
    ~/.local/share/icons/hicolor/256x256/apps/kyaraben-mgba.png

  Managed config files:
    ~/.config/retroarch/retroarch.cfg
    ~/.config/duckstation/settings.ini
    ~/.config/mgba/config.ini

This will NOT remove:
  ~/Emulation (your ROMs, saves, BIOS)
  ~/.config/kyaraben (your kyaraben config)

Proceed? [y/N]

kyaraben update

Checks for and installs CLI updates. The desktop app updates separately through its own mechanism.

$ kyaraben update

Current version: v0.9.0
Checking for updates...

New version available: v0.9.1
Downloading...
Updated to v0.9.1

If already up to date:

$ kyaraben update

Current version: v0.9.1
Checking for updates...
Already up to date.

kyaraben sync

Manage save synchronization. See app reference for an overview.

Enabling synchronization

Edit ~/.config/kyaraben/config.toml:

[sync]
enabled = true

Then run kyaraben apply to install Syncthing.

kyaraben sync pair [CODE]

Pair two devices. Without a code, this device generates a pairing code. With a code, this device joins the device that generated it.

Installs and starts the synchronization service automatically if it is not already running.

$ kyaraben sync pair
Installing synchronization service...
Pairing code: K7X9M2
Waiting for devices... (expires in 5 minutes)

Paired with steamdeck-kyaraben

On the second device:

$ kyaraben sync pair K7X9M2
Connecting...
Paired with desktop-kyaraben

kyaraben sync pair --device-id

Show the full 56-character device ID instead of a pairing code. Use this when the relay server is unavailable:

$ kyaraben sync pair --device-id
Device ID: LGFPDIT7-SKNNJVJZ-A4FC7QNC-...

# On the other device, join using the full device ID
$ kyaraben sync pair LGFPDIT7-SKNNJVJZ-A4FC7QNC-...

This works across any network via Syncthing’s relay servers.

kyaraben sync status

Shows synchronization state, connected devices, per-folder progress, and conflict counts.

$ kyaraben sync status

Sync: enabled
Status: synced
Device ID: LGFPDIT7-SKNNJVJZ-A4FC7QNC-...
UI: http://127.0.0.1:8484

Paired devices:
  steamdeck-kyaraben                 connected

Synced folders:
  ROMs                 idle
  Saves                idle
    2 conflict file(s)
  States               idle
  Screenshots          idle

When conflicts exist, the overall status shows conflict and each affected folder lists its conflict count. See resolving conflicts for how to handle them.

kyaraben sync add-device <DEVICE-ID>

Add a device by its 56-character Syncthing device ID. Use this for manual pairing without the interactive flow.

kyaraben sync remove-device <ID-or-NAME>

Remove a paired device by its device ID or friendly name.

Sync configuration

Syncthing runs as a systemd user service with its own configuration, separate from any existing Syncthing installation.

Setting	Default
Config directory	~/.local/state/kyaraben/syncthing/
Listen port	22100
Discovery port	21127
GUI port	8484
Relay servers	Enabled
Device name	<hostname>-kyaraben

Override ports in ~/.config/kyaraben/config.toml:

[sync.syncthing]
listen_port = 22100
discovery_port = 21127
gui_port = 8484
relay_enabled = true
global_discovery_enabled = false

Ignore patterns

Kyaraben ignores regenerable data by default:

**/shader_cache/**
**/cache/**
**/*.tmp
.DS_Store
Thumbs.db

Add custom patterns in ~/.config/kyaraben/config.toml:

[sync.ignore]
patterns = [
  "**/shader_cache/**",
  "**/logs/**",
]

Patterns use Syncthing’s ignore syntax. Prefix with ! to un-ignore.

Ignore patterns are local to each device:

• Ignored on primary: files won’t be sent to any secondary
• Ignored on secondary: files won’t be received on that device, but other devices still synchronize them

This lets you skip large files on a device with limited storage (like a Steam Deck) while keeping them on others.

Example: exclude large ROM formats

If you only want to synchronize smaller ROMs and skip disc-based games:

[sync.ignore]
patterns = [
  # Skip disc images (PS1, PS2, GameCube, Wii, etc.)
  "roms/**/*.iso",
  "roms/**/*.chd",
  "roms/**/*.cso",
  "roms/**/*.rvz",
  "roms/**/*.wbfs",
  # Skip optical formats
  "roms/**/*.bin",
  "roms/**/*.cue",
]

Example: skip EmulationStation DE videos

Scraped videos can be several gigabytes per system. To synchronize box art and screenshots but skip videos:

[sync.ignore]
patterns = [
  "frontends/esde/media/**/videos/**",
]

Or skip all media and only synchronize gamelists (metadata):

[sync.ignore]
patterns = [
  "frontends/esde/media/**",
]

Sync troubleshooting

Pairing code rejected

Codes expire after 5 minutes. Cancel pairing on the primary and start a new session.

Devices paired but not synchronizing

1. Check kyaraben sync status shows “connected”
2. If a firewall is blocking connections, see Syncthing’s firewall documentation

kyaraben import scan

Analyzes an existing ROM collection and shows what can be imported into Kyaraben’s structure. This is a read-only operation that does not move or modify any files.

$ kyaraben import scan ~/Games/Emulation

Back up your collection before copying anything.

Existing collection: /home/user/Games/Emulation
Kyaraben collection: /home/user/Emulation

Overall: +0 in Kyaraben, +2.3 GB to import

===========================================================================
PlayStation
===========================================================================

ROMs                                               +0  +1.8 GB

  Found at:        /home/user/Games/Emulation/roms/psx
                   47 files, 1.8 GB
  Kyaraben expects: /home/user/Emulation/roms/psx
                   (not found)

  Missing from Kyaraben (47 files, 1.8 GB):
    Final Fantasy VII (USA).chd
    Metal Gear Solid (USA) (Disc 1).chd
    ... and 45 more

Use this command when migrating from another emulation setup (like EmuDeck) or consolidating files from multiple locations.

Options:

• --esde <PATH>: specify the ES-DE data directory. Defaults to ~/ES-DE if it exists.
• --format <text|json>: output format. Defaults to text.

The JSON format is useful for scripting:

$ kyaraben import scan ~/Games --format json | jq '.summary.totalOnlyInSource'
2463187456