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-automation 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-automation. 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 behavior

-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.

Headless operation

To run dosbox-automation without a display (e.g., for automated testing or batch processing), set the SDL_VIDEODRIVER environment variable to dummy:

SDL_VIDEODRIVER=dummy dosbox --exit -c "dir c:\"

This disables all graphical output while the emulation continues to run normally.

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.