# Command Line

kat5200 can be started with options that override the saved configuration for
that run, load a ROM or state directly, or recover from a bad video setup.

```text
kat5200 [options] [ <rom_file> ]
```

A bare (non-option) argument is treated as a ROM image to attach and launch —
handy for file-manager associations and front ends. `kat5200 --help` prints the
full option list; the man page (`man kat5200`) documents mapping values and the
input configuration syntax in detail.

Options set on the command line apply on top of the saved `kat5200.conf` at
startup. They are not written back to the configuration unless you later press a
**Save** button in the GUI.

## General options

| Option | Description |
|--------|-------------|
| `--help`, `-h` | Print the option summary and exit. |
| `--version`, `-V` | Print version information (including library versions) and exit. |
| `--reset_config` | Reset the configuration and profiles to defaults, then exit. Same effect as **Factory Reset** in [Misc → Configuration](options/misc.md#configuration). |
| `--config <file>` | Use an alternate configuration file (and its directory). |
| `--debug` | Start the emulation in the [debugger](options/misc.md#debugger). |
| `--state <file>` | State file to load at startup. |
| `--quick_state <1-9>` | Numbered quick-state slot to load at startup. If both `--state` and `--quick_state` are given, the quick state wins. |
| `--start_with {file_browser\|rom_list\|last_rom}` | What to open at launch, overriding the saved **Start With** setting. |
| `--throttle <percent>` | Emulation speed; `100` is normal, `0` runs as fast as possible. |
| `--sio_patch {true\|false}` | Enable/disable the SIO patch for fast disk loading. |
| `--basic_enable {true\|false}` | Enable/disable BASIC on the 8-bit computers. |
| `--machine {5200\|800\|xl\|xe}` | The machine type to emulate. |
| `--mapping <value>` | Cartridge mapping for the ROM being loaded (`auto` or a specific type; see the man page for values). |

## Video options

| Option | Description |
|--------|-------------|
| `--safe` | Boot with the SDL default renderer and shaders disabled — use this to recover from a bad video configuration. Session-only; never saved. |
| `--backend <name\|default>` | SDL renderer backend (alias `--video.renderer_name`). `default` lets SDL choose. Overrides `--safe` if both are given. |
| `--shader <name\|dir\|none>` | Shader bundle by list name or directory, or `none` to disable (alias `--video.shader`). Overrides `--safe` if both are given. |
| `--video.fullscreen {true\|false}` | Full-screen mode. |
| `--video.fixed_window {true\|false}` | Disallow window resizing. |
| `--video.width` / `--video.height` | Window size in pixels. |
| `--video.x` / `--video.y` | Window position on the desktop. |
| `--video.wide_playfield {true\|false}` | Show the extra emulated edge pixels. |
| `--video.gui_scale <0\|25..300>` | GUI scale percent; `0` = auto. |
| `--video.window_scaling {letterbox\|stretch\|fit_window}` | Window scaling mode. |
| `--video.texture_scaling {pixelated\|smooth}` | Texture scaling mode. |
| `--video.palette <profile\|file>` | Palette profile or palette file to load. |
| `--video.vsync {true\|false}` | Vertical sync. |
| `--video.ntsc_artifacts {true\|false}` | NTSC artifacting filter. |
| `--video.ntsc_setup.<param> <-1.0..1.0>` | NTSC filter fine adjustment; `<param>` is one of `hue`, `saturation`, `contrast`, `brightness`, `sharpness`, `burst_phase`, `hue_warping`. |

## Sound options

| Option | Description |
|--------|-------------|
| `--sound.enable {true\|false}` | Master audio switch. |
| `--sound.frequency <hz>` | Sample frequency (e.g. `44100`). |
| `--sound.samples <n>` | Sample buffer size in samples. |
| `--sound.buffer_size <n>` | Internal buffer adjustment size. |
| `--sound.gain <0..150>` | Output volume percent (`100` = normal). |

## Machine options

| Option | Description |
|--------|-------------|
| `--machine.tv_standard {pal\|ntsc}` | TV standard. |
| `--machine.ram <kb>` | RAM amount in kilobytes. |
| `--machine.bios <file>` | BIOS file to use. |
| `--machine.profiles_dir <dir>` | ROM-profiles directory for the current machine type (give it after `--machine`). |

## Input options

Player bindings and UI shortcuts can also be set from the command line with the
`--input.game.*` and `--input.misc.*` families — for example
`--input.game.p0.type Joystick` or `--input.misc.fullscreen <binding>`. These
use the same keys as the configuration file; run `kat5200 --help` for the list
and see the man page for the binding syntax. For interactive setup, the
[Input](options/input.md) tab's capture flow is much easier.

## Examples

```bash
# Launch a cartridge image directly
kat5200 ~/roms/5200/Gorf.bin

# Resume from quick-state slot 3
kat5200 --quick_state 3

# Recover from a bad shader / renderer configuration
kat5200 --safe

# One-off PAL 800 session with BASIC, without touching saved settings
kat5200 --machine 800 --basic_enable true --machine.tv_standard pal
```
