Skip to content

🔥🔥🔥 You are viewing a development version of the website. Things will blow up. 🔥🔥🔥

Regular users, please follow the exit signs.

# Command-line usage

## Simple usage

The simplest way to launch a game is to pass its path directly to DOSBox Staging. It’s smart enough to figure out what to do: if you pass a directory, it’s mounted as the C: drive; if you pass an executable, its parent directory is mounted and the program runs automatically.

    dosbox /path/to/game/
    dosbox /path/to/game/GAME.EXE
    dosbox disk.img

## Preferred usage

While this might be alright for some quick testing, a much better way is to organise games into subfolders and put a `dosbox.conf` local configuration into each which contains your game-specific settings and tweaks.

Config files can be layered with `--conf`; later files override earlier ones. This way you can inject extra settings into your DOSBox session, overriding values from the local config:

    dosbox --conf extra.conf

For quick one-off tweaks without editing any files, use `--set`. If you want to set multiple settings, no problem — just provide multiple `--set` arguments:

    dosbox --set machine=ega --set cpu_cycles=5000

Of course, you can combine these techniques:

    dosbox --conf extra.conf --set cpu_cycles=25000

See Config layering for more info.

## Discovery

Several `--list-*` options are handy for discovering what’s available on your system: shaders, keyboard layouts, country codes, and code pages.

## Command-line reference

##### PATH

  - If `PATH` is a directory, it’s mounted as the C: drive.
  - If it’s a bootable disk image (IMA or IMG file), it’s booted.
  - If it’s a CD-ROM image (e.g., an ISO file), it’s mounted as the D: drive.
  - If it’s a DOS executable (a file with BAT, COM, or EXE extension), its parent directory is mounted as C: and the executable is run. When the executable exits, DOSBox Staging quits.

### Configuration

##### `--conf <config_file>`

  Start with the options specified in `<config_file>`. Multiple `--conf` options can be specified; settings from later files override earlier ones.

  Example: `--conf base.conf --conf game.conf`

##### `--set <setting>=<value>`

  Override a configuration setting. Multiple `--set` options can be specified. These take highest priority over all config files.

  Example: `--set mididevice=fluidsynth --set soundfont=gm.sf2`

##### `--printconf`

  Print the location of the primary configuration file and exit.

##### `--editconf`

  Open the primary configuration file in the default text editor in the terminal (e.g., the one set via `$EDITOR`).

##### `--eraseconf`

  Delete the primary configuration file.

##### `--noprimaryconf`

  Don’t load the primary configuration file if it exists, and don’t create and load it if it doesn’t exist.

##### `--nolocalconf`

  Don’t load the local `dosbox.conf` configuration file from the current working directory.

##### `--working-dir <path>`

  Set the working directory for DOSBox Staging. DOSBox will act as if started from this directory. If a local `dosbox.conf` configuration exists in this folder, it will be loaded after the primary config.

### Startup behaviour

##### `-c <command>`

  Run the specified DOS command before handling `PATH`. Multiple `-c` options can be specified.

##### `--noautoexec`

  Don’t run DOS commands from any autoexec sections.

##### `--exit`

  Exit after running `-c` commands and `[autoexec]` sections.

##### `--fullscreen`

  Start in fullscreen mode.

##### `--lang <lang_file>`

  Start with the specified language file. Set to `auto` to detect the language from the host OS (this is the default).

##### `--machine <type>`

  Emulate a specific machine type. The machine type affects both the emulated video and sound hardware. See machine for further details.

### Discovery

##### `--list-countries`

  List all supported countries with their numeric codes, for use with the country config setting.

##### `--list-layouts`

  List all supported keyboard layouts with their codes, for use with the keyboard_layout config setting.

##### `--list-code-pages`

  List all bundled code pages (screen fonts).

##### `--list-shaders`

  List all available shaders and their paths, for use with the shader config setting.

### Mapper

##### `--startmapper`

  Launch the key mapper GUI directly. See Keyboard shortcuts.

##### `--erasemapper`

  Delete the default mapper file.

### Security & networking

##### `--securemode`

  Enable secure mode, which disables the `MOUNT` and `IMGMOUNT` commands.

##### `--socket <num>`

  Run nullmodem on the specified socket number.

### Help

##### `-h`, `-?`, `--help`

  Print the help message and exit.

##### `-V`, `--version`

  Print version information and exit.