Startup options

You can start ssp.exe with the following options (switches).

What are startup options?

This is a feature that lets you change settings when starting Windows software.
For details, look up terms such as runtime options, command-line options, and startup options.

How to use

There are several ways to use them.
For example, you can use them from the Command Prompt or the Run dialog.
Here, we’ll explain how to create a shortcut dedicated to these options.

  1. Create a shortcut to ssp.exe.
    Example: Right-click ssp.exe → Create shortcut
  2. Open the properties of the shortcut you created.
    Example: Right-click the shortcut → Properties
  3. After confirming that the path to ssp.exe is in the “Target” field of the properties, enclose the entire path in “""”.
  4. Add one half-width space after the enclosed path, then enter the startup option below.
    Example: "C:/User/Document/略/SSP/ssp.exe" --random
  5. Click OK to close the properties, then give the shortcut an easy-to-understand name.
    Example: SSP-Random startup
  6. When you run that shortcut, SSP will start with the options applied, unlike when you start ssp.exe normally.

List of options

We recommend using the --オプション名 format for each option. For backward compatibility, short options in the /x / -x format can still be used.

For options that take a value, separate the option name and value with a half-width space, as in --オプション名 値. If the value contains spaces, enclose it in “""”.

Starting with 2.8.97, the --オプション名=値 format is also accepted as an alternative (for example: --sstp-listen=9900). This page uses space-separated values by default. Note that the = format cannot be used with short options in the /x format.

--option options

You can specify multiple --option options separated by commas (for example: --option bootunlock,standalone).

Switch Function
--option nobootcheck
(legacy: /o nobootcheck)
Disable abnormal termination checks
--option layered
(legacy: /o layered)
Enable translucent windows
--option region
(legacy: /o region)
Disable translucent windows (region mode)
--option bootunlock
(legacy: /o bootunlock)
Skip the multiple-instance check
--option standalone
(legacy: /o standalone)
If SSP.exe is already running, this disables the mechanism that delegates tasks such as installing or launching a ghost to the running SSP.exe, and always launches ghosts or performs installations itself.
You can run multiple instances of SSP.exe without any warnings by combining this with the multiple-instance check bypass, as in --option bootunlock,standalone.
--option kiosk
(legacy: /o kiosk)
Enable KIOSK mode. It behaves as follows. [2.6.54~]
Enables --option bootunlock,standalone
Always sets alignmenttodesktop to free
Does not accept mouse or keyboard input
Does not interfere with the multiple-instance check in any way
Does not display notification area or taskbar icons
Does not save settings managed by SSP for ghosts or shells
Does not display a window indicating that it is running
Does not show error notifications
--option readonly
(legacy: /o readonly)
Enable read-only mode. [2.8.96 and later]
Starts without making any persistent changes to the user environment. Use this when you want to try out SSP without changing your settings, or temporarily run SSP on someone else’s PC.
The on-screen behavior and interactions with ghosts are unchanged. Unlike KIOSK mode, this mode does not block input or restrict display. It is independent of KIOSK mode, so you can use both modes together, as in --option kiosk,readonly.

It behaves as follows.
Enables --option bootunlock,standalone (because delegating tasks to a running instance of SSP could cause that instance to write settings)
Does not interfere with the multiple-instance check in any way
Does not save any settings for Preferences, ghosts, shells, balloons, or plugins
Does not save startup history, usage statistics, cache, cookies, vanish records, SSTP settings, POP settings, or Ukagaka messenger information and logs
Does not save Calendar schedules (schedule.ics)
Does not share save data (it neither exports data to the cloud nor restores data from the cloud to the local device)
Does not write to the registry. It does not associate files, create shortcuts, register jump lists, or add items to “Recent Items”
Does not change the desktop wallpaper or background color
Does not empty the Recycle Bin
Does not delete a ghost’s folder when the ghost vanishes
Does not automatically update SSP, ghosts, balloons, plugins, or language resources. It also does not perform manual network updates or install NARs
Does not install initial_install.nar
Does not perform NTP time sync using SNTP

You can change settings as usual, but the changes are not written back to files when you exit, so they will not be carried over to the next startup.
Temporary files required for operation (in the temporary folder) are still created as usual and are discarded when you exit.
--option dontloadmodule
(legacy: /o dontloadmodule)
Do not load SHIORI/MAKOTO/PLUGIN/HEADLINE/CALENDAR modules
--option dpiaware
(legacy: /o dpiaware)
Start with DPI Awareness Mode set to Per-Monitor V2
--option callghost
(legacy: /o callghost)
When used with --install, automatically call the ghost after installation is complete.
--option deletesource
(legacy: /o deletesource)
When used with --install, delete the NAR after it is successfully installed.

General options

Switch Function
--fmo-name FMO名
(old: /f FMO名)
Force the FMO name to be written to the specified name.
--random
(old: /r)
Start a random ghost regardless of the settings.
--ghost フォルダ名/ゴースト名
(old: /g フォルダ名/ゴースト名)
Start the specified ghost. Separate multiple ghosts with spaces to start them together. If specified when starting SSP, the first specified ghost will start as the first ghost pair.
Since 2.8.99, if you specify an absolute path to a ghost folder when starting SSP (for example, ssp.exe --ghost "C:\Users\user\Desktop\myGhost"), and that ghost is not in the ghost search folders, its parent folder (in this example, C:\Users\user\Desktop\) will be temporarily added to the ghost search folders for that launch only, and the ghost will start. This applies only to folders that contain ghost\master\descript.txt.
Folders added temporarily are not saved in the settings. They are shown as "(temporary)" on the folder settings screen, where you cannot edit or delete them. They are also not offered as possible ghost installation locations. If you explicitly add the same folder from the folder settings screen, it will be saved as a regular ghost search folder.
This process is not performed if SSP is already running (that is, if the request is passed to the running instance of SSP).
--help
(old: /?)
Open the startup options help page in a browser.
--help ファイル名
(old: /? ファイル名)
Open the help page for the specified file name in a browser.
--ukagaka-link x-ukagaka-link:URL
(old: /m x-ukagaka-link:URL)
Perform the same action as when opening x-ukagaka-link:URL. If specified when starting SSP, execution will wait until the first ghost pair has started.
--install NARファイル名
(old: /i NARファイル名)
Install a NAR. If another instance of SSP is running, it will handle the installation; otherwise, this instance will perform the installation and then continue starting up.
Separate multiple NAR files with spaces to install them in order.
The instance handling the installation can also proceed if a warning dialog says that no ghost is installed (the "Please do something about this" dialog) is open.
Also, if you specify --option callghost in this case, the startup continuation button in the warning dialog will be automatically clicked, and startup will continue.
--ssf SSFファイル名
(old: /s SSFファイル名)
Run an SSF file. If specified when starting SSP, execution will wait until the first ghost pair has started.
--windowmode モード [省略可] 2.8.78 and later: Start in the experimental "Window mode". Ghosts start in a window that acts as a single virtual screen, making capture operations easier and preventing them from affecting the entire desktop.
2.8.86 and later: You can specify a mode. The available modes are listed below. If omitted, the previous setting is used (the default is shared).
shared: Combine all running ghosts into one window.
perghost: Use a separate window for each ghost.
Since 2.8.86, the Window mode state is saved as a setting, so SSP will start in the previous state even if you omit this option. To turn it off, change the setting from "Settings" in the right-click menu or from "Streaming" in Preferences.
--sstp-listen 待ち受け先 Temporarily specify the SSTP server's listening addresses for this launch. [2.8.97 and later]
The saved SSTP server listening settings will not be loaded; the server will listen only at the specified addresses.
The listening settings for this launch are not saved. The SSTP server list in Preferences is displayed for viewing only; you cannot add or remove entries or enable or disable them.
This option is intended for setting up a test instance of SSP that will not interfere with other running instances, in combination with --option readonly.

You can specify multiple listening addresses, separated by commas. Use the following formats.
Port number: Listen on the IPv4 and IPv6 loopback addresses (127.0.0.1 and ::1). Example: 9801
localhost:port number: Same as specifying only the port number.
IPv4 address:port number: Listen only on the specified address. Specify 0.0.0.0 to listen on all IPv4 interfaces. Example: 192.168.0.5:9801
[IPv6 address]:port number: Enclose the IPv6 address in []. Specify [::] to listen on all IPv6 interfaces. Example: [::1]:9801
none: Do not listen at all. This is also the behavior if no listening address is specified.

Specify addresses numerically (hostnames cannot be used, except for localhost).
Listening addresses with an incorrect format or that fail to listen will be ignored and recorded in the error log. The saved settings will not be restored in this case.
Note that specifying an address other than a loopback address allows SSTP connections from other PCs.

Example: ssp.exe --option readonly --sstp-listen 9900,[::1]:9901
--guifont フォント名 [2.8.75以降] Specify the font used in the GUI. This does not replace every instance of text; some menus and title bars, for example, are unchanged for now.

Offline Surface Dump

Switch Function
--offline-dump folder path Starts in offline dump mode. Loads surfaces.txt from the specified ghost folder, dumps the surface images, and exits immediately without actually starting the ghost. SHIORI/MAKOTO/PIRO are not loaded. No window or message loop is created.
Specify the ghost folder path as the argument (a trailing \ is optional).
Since 2.8.98, relative paths specified for offline dump options (this option, --dump-output-dir, and --dump-error-log) are resolved relative to the current directory when SSP is started.

Example: ssp.exe --offline-dump "C:\SSP\ghost\myGhost" --dump-surface-list "0,1" --dump-output-dir "C:\dump"
--dump-shell folder name or name [optional] Use with --offline-dump. Specify the shell to dump by its folder name (that is, a relative path under shell) or by its name. If omitted, the default shell specified in descript.txt (usually master) is used.
Since 2.8.98, if the specified shell cannot be found, SSP does not dump the default shell. Instead, it records an Error in the error log and outputs nothing.
--dump-scope (scope ID) [optional] Use with --offline-dump. Specify the scope ID for the dumped images. Defaults to 0 if omitted.
--dump-surface-list list [optional] Use with --offline-dump. Specify the surfaces to dump as a comma-separated list. The surface number prefix (surface) is optional. You can also use the extended format for specifying surface IDs in surfaces.txt.
Example: --dump-surface-list "0,1,10"
If this option is omitted, no surface dump is performed (you can combine it with --dump-error-log to output only parse errors).
Since 2.8.98, the prefix can be omitted for each element, not just the first ("0,surface1", for example). Also, if a surface specified by a single number rather than a range does not exist, a Warning is recorded in the error log (missing numbers within a specified range are not recorded).
--dump-output-dir directory [optional] Use with --offline-dump. Specify the directory where the dumped images are saved. If omitted, the current directory is used (before 2.8.97, no dump was performed if this option was omitted).
--dump-output-prefix prefix [optional] Use with --offline-dump. Specify the part of the output file name that appears before the surface number. This replaces the default string "surface" (it is not added to it). Defaults to "surface" if omitted.
Example: With --dump-output-prefix "x_", surface 0 is saved as x_0.png (not x_surface0.png).
--dump-error-log file path [optional] Use with --offline-dump. Write the error log from loading the shell (such as parse errors in surfaces.txt) to the specified path.
You can run error checking without dumping by omitting --dump-surface-list and specifying only this option.
Example: ssp.exe --offline-dump "C:\SSP\ghost\myGhost" --dump-error-log "C:\dump\error.csv"

Output format: UTF-8 CSV with a BOM (CRLF line endings). Each line is one entry, each field is enclosed in ", and any " within a field is escaped as "".
"時刻","ゴースト名","レベル","内容"
Time: In HH:MM:SS format.
Level: One of Info / Notice / Warning / Error / Critical / System.
Content: The log message. Since 2.8.94, SERIKO-related logs include the source file (relative to the ghost folder) and line number, as in [SERIKO] shell\master\surfaces.txt:Line=12:Surface=10 .... Logs for duplicate definitions also include the location of the earlier definition as (filename:Line=n).
Since 2.8.94, when this option is specified, up to 10000 log entries are retained, and similar log entries are not consolidated into summary lines (level System), so no logs are lost.
If there are no log entries, no file is created (any existing file at the same path is neither overwritten nor deleted).

Exit code: Since 2.8.94, the process exits with a code corresponding to the most severe level among the recorded logs.
0: No logs, or Info/Notice only
1: Warning present (no Error/Critical)
2: Error present (no Critical)
3: Critical present
If the ghost itself fails to load (for example, if descript.txt in the specified folder cannot be read), no log is output and the exit code is 0.
--dump-surface-option option [optional] [since 2.8.57] Specify options for the offline dump feature. The following options are available.
backlog: Crop the same area (around the face) as the backlog feature. However, the image is output as-is, without scaling or compositing.
collision: Draw the shapes and names of collision regions in the output. This is the same as displaying collision regions in the developer palette, except that names are always displayed and no outline rectangles are drawn for the surface bounds, active areas, or overlap regions.[since 2.8.98]
Since 2.8.98, you can specify multiple options separated by commas (for example, --dump-surface-option backlog,collision).
If collision is not specified with this option, collision regions are not drawn, regardless of the user setting for displaying collision regions in the developer palette.
--dump-bind dressup specification [optional] [since 2.9.05] Use with --offline-dump. Specify the dressup state for the dump.
You can specify multiple entries separated by semicolons, in the format "category name,part name,ON/OFF". This works the same as \![bind]: turning a part ON in an exclusive category turns the other parts in that category OFF.
If the part name is blank or __ALL__, all parts in the category are affected.
Use 1 or true for ON, and 0 or false for OFF. If omitted, ON is assumed (unlike \![bind], which toggles the state when omitted).
Example: --dump-bind "頭,帽子;服,制服;アクセサリ,__ALL__,0"

The starting state is each part's default as specified in the shell's descript.txt (sakura.bindgroup*.default); the user's last dressup state (the saved value in shell\profile) is not used. Only the specified parts are changed from that starting state.
Dressup is applied to the scope specified by --dump-scope.
If a specified category or part does not exist, a Warning is logged, and only that entry is ignored while the dump continues (--dump-error-log exits with code 1).
Whitespace before or after category and part names is not removed, so do not add spaces after commas.
--dump-animation animation ID [optional] [since 2.9.05] Use with --offline-dump. Play the specified animation as with \i[ID] and output the image for each frame as a numbered sequence. You can specify only one ID (in addition to a number, you can use a name assigned to the animation in surfaces.txt, just as with \i[ID]).
For each surface, an image identical to a regular dump (the state after one cycle of the runonce animation) is first output as surface0.png. Then, each time the specified animation advances to the next pattern, an image is output in a zero-based, four-digit sequence: surface0_0000.png, surface0_0001.png, and so on. The --dump-output-prefix and --dump-surface-option settings also apply to the numbered images.
Example: ssp.exe --offline-dump "C:\SSP\ghost\myGhost" --dump-surface-list "0" --dump-animation 10 --dump-output-dir "C:\dump"

Animations such as runonce and always run as they would in a regular dump, with the specified animation overlaid on top. Only the patterns of the specified animation are included in the numbered sequence; the number of images does not increase when an always animation advances.
The dump ends when the specified animation reaches its last pattern (for always animations, after one cycle). It also ends if another animation stops it or if it is stopped by an exclusive animation.
Other animations started by start, alternativestart, or parallelstart are not included in the numbered sequence. A Warning is logged if the specified animation contains any of these patterns (output continues).
Patterns in the start and stop families do not change the image, so they are not counted as frames in the sequence.
If the specified ID does not exist for that surface, or cannot be played because it is disabled by dressup or blocked by an exclusive animation, a Warning is logged and only the regular single image is output for that surface.
The sequence is limited to 10000 images (up to _9999). If this limit is reached, a Warning is logged and output stops.

Offline tools

Switch Function
--offline-tool type [2.9.01 and later] Starts in offline tool mode. Creates a NAR, update definition file, or archive from the folder specified by --target-dir without starting a ghost, then exits immediately. No ghost events occur, and no window or message loop is created.
This performs the same operations as the Sakura Script commands \![execute,createnar] / \![execute,createupdatedata] / \![execute,compressarchive], but the output destination is not restricted (for example, to folders managed by SSP), so you can specify any location.
Specify one of the following types (uppercase and lowercase are not distinguished).

nar: Creates a NAR file. Exclusions specified by nonar in developer_options.txt, .narignore, and so on are applied in the same way as for normal NAR creation. If there is no install.txt directly in the folder, the type and name are identified from descript.txt (or ghost\master\descript.txt), and an install.txt file is created in the target folder before the files are included. The operation fails if the type and name cannot be identified.
updatedata: Creates an update definition file. If the file name specified by --output ends in .dau, it creates a single specified file in the same format as updates2.dau; otherwise, it uses the updates.txt format. It does not create or delete updates2.dau or updates.txt directly in the target folder or in ghost\master. Exclusions specified by noupdate in developer_options.txt, .updateignore, and so on are applied in the same way as usual.
archive: Compresses the target folder as is. Exclusion rules such as .narignore are not read (hidden files and hidden folders are not included). The format is determined by the extension specified by --output: .7z uses the 7z format, and all other extensions use the zip format.

For all types, if the output file already exists, it is overwritten. If the output destination is inside the target folder, that file itself is not included. The output folder must already exist.
If relative paths are specified for --target-dir or --output, they are resolved relative to the current directory when SSP was started.

Exit codes:
0: Success
1: Invalid arguments (unknown type, --target-dir or --output omitted, or --target-dir does not exist or is not a folder)
2: Creation failed (the output destination cannot be written to, the NAR type and name cannot be identified, updatedata encountered an unreadable file or a folder hierarchy that is too deep (over 32 levels), and so on). A partially created file may remain even when the operation fails.

Example: ssp.exe --offline-tool nar --target-dir "C:\src\myGhost" --output "C:\out\myGhost.nar"
Example: ssp.exe --offline-tool updatedata --target-dir "C:\src\myGhost" --output "C:\out\updates2.dau"
Example: ssp.exe --offline-tool archive --target-dir "C:\src\data" --output "C:\out\data.7z" --password "pass"
--target-dir folder path [2.9.01 and later] Must be used with --offline-tool. Specifies the folder to process (the trailing \ is optional). For a NAR or update definition file, specify the root folder of the ghost or other item (the folder containing descript.txt, install.txt, or the ghost folder).
--output file path [2.9.01 and later] Must be used with --offline-tool. Specifies the path of the file to create.
--password password [optional] [2.9.01 and later] Use with --offline-tool nar or archive. Creates an AES-encrypted ZIP using the specified password (for the 7z format, 7z encryption is used). This option is ignored for updatedata.
The password remains visible in the command line, so handle it with care.

Other

Switch Function
initial_install.nar This is not a startup option, but if you place a NAR file named initial_install.nar in the same folder as ssp.exe, it will be silently installed over the existing files (without a confirmation dialog) when SSP starts. After installation is complete, initial_install.nar is automatically deleted. This can be used when distributing SSP with ghosts or other items included. [2.7.52 and later]