Command Reference

Command Reference

⚠️ Stability disclaimer — read this first. What follows is Sucrose's internal IPC command protocol, not a stable, supported public command line. End users never type these strings; the Portal, Launcher tray, engines, and helper services build and emit them automatically. The wire format, the command names, the argument order, and the set of commands are implementation details that can change between versions without notice. There is no compatibility guarantee. Use this page to understand how Sucrose's processes talk to each other and for advanced automation at your own risk — do not build production tooling on top of it.

Sucrose is a multi-process application. One of the two ways its processes coordinate is the command bus: a one-shot, process-launch-based string protocol routed by Sucrose.Commandog.exe (the "Commandog" dispatcher). A command is not a long-lived connection — it is literally "run (or pass arguments to) an executable with a specially-encoded argument string." This page documents the wire format, the full CommandType set, the ArgumentCommandType settings-page targets, and the SchedulerCommandType auto-start sub-commands. For the live data channels (Pipe/Signal/Transmission) that carry audio and system data, see IPC. For who runs the parser, see Commandog-Dispatcher.

Contents

• The wire format
• How a command is parsed
• Typed value parsing
• CommandType — the full command table
• ArgumentCommandType — settings-page targets
• SchedulerCommandType — auto-start-on-logon
• Who emits commands
• Special command notes
• See also

The wire format

Commandog does not use ordinary --flag value syntax. It uses a custom delimited string built from two special Unicode marker characters defined in Sucrose.Memory.Manage.Readonly.General:

Constant	Value	Code point	Role
StartCommandChar	✔	U+2714 (HEAVY CHECK MARK)	Marks the start of a command string
StartCommand	"✔"	U+2714	String form of the start marker
ValueSeparatorChar	✖	U+2716 (HEAVY MULTIPLICATION X)	Separates the command name and each value
ValueSeparator	"✖"	U+2716	String form of the separator

The layout is:

✔<CommandName>✖<Value0>✖<Value1>✖<Value2>...

A complete example, emitted by an engine to reload the wallpaper:

✔RestartLive✖Unknown

Encoding gotcha. The markers are the literal Unicode characters ✔ (U+2714) and ✖ (U+2716) — not ASCII letters, not the words "check"/"x". Anything reproducing a command externally must emit these exact code points (UTF-8). Commandog sets Console.InputEncoding and Console.OutputEncoding to UTF-8 on startup so the markers survive the process boundary.

How a command is parsed

The dispatcher (Sucrose.Commandog/Helper/Arguments.cs) parses an incoming command like this:

1. Recombine the raw arguments with string.Join(" ", args).
2. Require the combined string to start with ✔ and to contain ✖. If either check fails, the input is ignored.
3. Strip the leading ✔ (take Combined[1..]), then Split('✖').
4. The first segment is the command Name; the remaining segments are the Values. At least one value is required (total parts ≥ 2).
5. Enum.TryParse<CommandType>(Name, ignoreCase: true, …) — command names are case-insensitive (RestartLive, restartlive, and RESTARTLIVE all parse the same).
6. A switch on the parsed CommandType performs the action.

Commandog itself does almost no work — it parses the command and either launches the right executable (via Sucrose.Shared.Space.Helper.Processor.Run, a ShellExecute wrapper) or calls a shared helper. It then always Environment.Exit(0) in its finally block, so it is genuinely short-lived. See Commandog-Dispatcher for the full lifecycle.

Typed value parsing

Each value is converted to the type the command expects by Parse.ArgumentValue<T>:

Requested type	Conversion
int	int.TryParse
bool	bool.TryParse
any enum	Enum.Parse (e.g. SchedulerCommandType, ArgumentCommandType)
anything else	returned as the raw string

The diagnostic Test command instead uses Miscellaneous.GetType(string), which sniffs bool first, then int, otherwise falls back to string.

CommandType — the full command table

The CommandType enum (src/Shared/Sucrose.Shared.Dependency/Enum/CommandType.cs) defines 31 commands. The table below lists every member in enum order, the values it consumes (in order), and what the matching switch case does. "Run(x)" is Processor.Run (ShellExecute); many commands simply open a path or URL.

#	Command	Values (in order)	Action
1	Log	[0]=path	Processor.Run(path) — open a log file/folder.
2	Kill	[0]=processName	Processor.Kill(name) — kill all processes by name.
3	Live	[0]=path	Processor.Run(path) — start the live wallpaper engine.
4	Test	[0..]=values	Prints Test Values:, then for each value detects its type and writes the parsed value to the console. Diagnostic only.
5	Temp	[0], [1]	Temporary.Delete(v0, v1) — clear temp/cache.
6	Wiki	[0]=url	Processor.Run(url) — open the wiki URL.
7	Reset	[0]	Reset.Start(v0) — reset settings/app.
8	Bundle	[0]=path	Processor.Run(path) — run the downloaded bundle/installer .exe.
9	Update	[0]=updateExe, optional [1]	If more than one value: Run(v0, v1) (hidden, with arg); else Run(v0). Launches Sucrose.Update.exe.
10	Import	[0], [1]	Import.Start(v0, v1) — import a theme/package.
11	Export	[0], [1]	Export.Start(v0, v1) — export a theme.
12	Report	[0]=url	Processor.Run(url) — open the report page.
13	Publish	[0]=url	Processor.Run(url) — open the publish page.
14	Startup	[0]=name, [1]=path, [2]=bool	WindowsStartup.SetStartup(name, path, enable) — per-user Run-key startup.
15	Cycyling	(none used)	Stop live + stop subprocess, Run.Start(), wait 1500 ms; if Live.Run() is false, Run.Start() again. The wallpaper cycling reload. (Spelled "Cycyling" in code.)
16	Property	[0]=path	Processor.Run(path) — launch Sucrose.Property.exe (no theme arg; edits the currently selected wallpaper).
17	StartupM	[0], [1], [2]=bool	WindowsStartupMachine.SetStartup(...) — machine-wide startup.
18	StartupP	[0], [1]=bool	WindowsStartupPriority.SetStartup(...) — startup priority/approved.
19	Official	[0]=url	Processor.Run(url).
20	Watchdog	[0]=watchdogExe, [1]=encodedPayload	If exactly two values: Run(v0, v1) (hidden). Launches Sucrose.Watchdog.exe with the Base64 crash payload.
21	Interface	[0]=portalExe, optional [1]=settingType	If more than one value: Run(v0, v1); else Run(v0). Opens the Portal, optionally on a specific settings page (see ArgumentCommandType).
22	PropertyA	[0], [1]	Run(v0, v1) — launch Sucrose.Property.exe with an argument (a specific selected theme).
23	Reportdog	[0]=reportdogExe	Run(v0, string.Empty) — launch Sucrose.Reportdog.exe.
24	Scheduler	[0]=SchedulerCommandType, [1]=appPath (Create only)	Routes to a Task Scheduler operation — see SchedulerCommandType.
25	Repository	[0]=url	Processor.Run(url).
26	Versioning	[0]=folder, [1]=version, [2]=bool	Delete.Folder(folder, version, bool) — delete old-version folders (used by the Launcher "Version" command).
27	Discussions	[0]=url	Processor.Run(url).
28	RestartLive	(none used)	Stop live + subprocess, kill Sucrose.Backgroundog.exe, Run.Start(), wait 1500 ms, retry if not running. The wallpaper reload command.
29	Backgroundog	[0]=backgroundogExe	Run(v0, string.Empty) — launch the background system-status/audio service.
30	QuotingGoogle	[0]=url	Processor.Run(url).
31	QuotingTranslate	[0]=url	Processor.Run(url).

🖼️ Diagram needed: A flow showing an emitter (Portal/Launcher/engine) building a ✔Command✖value string → spawning Sucrose.Commandog.exe → Commandog parsing the string → switch dispatching to either Processor.Run/Processor.Kill or a shared helper → the target .exe launching.

ArgumentCommandType — settings-page targets

When the Interface command opens the Portal on a specific settings page, the second value is an ArgumentCommandType member (parsed as an enum). These map to the Portal settings pages:

Member	Opens
OtherSetting	Settings-Other
DonateSetting	The Donate page (built but hidden/disabled — not documented in this wiki)
SystemSetting	Settings-System
GeneralSetting	Settings-General
PersonalSetting	Settings-Personal
WallpaperSetting	Settings-Wallpaper
PerformanceSetting	Settings-Performance

Example: the Launcher tray "Settings" action emits

✔Interface✖<PortalPath>✖GeneralSetting

which opens the Portal directly on the General settings page.

SchedulerCommandType — auto-start-on-logon

The Scheduler command manages a Windows Task Scheduler task — Sucrose's preferred auto-start-on-logon mechanism (distinct from the Run-key Startup/StartupM/StartupP commands). The first value is a SchedulerCommandType member:

Member	Routes to	Notes
Create	Scheduler.CreateTask(Values[1])	Creates the task; Values[1] is the application path to run.
Enable	Scheduler.EnableTask()	Enables the existing task.
Delete	Scheduler.DeleteTask()	Deletes the task (use this to fully remove auto-start).
Disable	Scheduler.DisableTask()	Disables the task without deleting it.

The task itself (Sucrose.Commandog/Helper/Scheduler.cs + Sucrose.Memory/Manage/Readonly/Scheduler.cs):

Property	Value
Task name	Autorun for Sucrose
Task description	Sucrose Wallpaper Engine
Task folder	\Sucrose\ (root folder named Sucrose)
Trigger	LogonTrigger, scoped to the current user (WindowsIdentity.GetCurrent().Name)
Action	ExecAction(Application)
StopIfGoingOnBatteries	false
DisallowStartIfOnBatteries	false
ExecutionTimeLimit	TimeSpan.Zero (no limit)

Backed by the Microsoft.Win32.TaskScheduler library. Because Sucrose starts via a scheduled task rather than a registry Run entry, you will not find it in the typical HKCU\…\Run startup list — see Troubleshooting-Settings-Startup-GPU.

Example — create the logon task:

✔Scheduler✖Create✖<full path to the app to run>

Example — remove the logon task:

✔Scheduler✖Delete

Who emits commands

Commands are emitted by the UI and services, never by the user directly. Representative emitters (src/Shared/Sucrose.Shared.Launcher/Command/*.cs and others):

Emitter	Command emitted	Purpose
Launcher tray → Reload (Reload.cs)	✔RestartLive✖Unknown	Reload the wallpaper
Launcher tray → Update (Update.cs)	✔Update✖<UpdatePath>	Launch the updater
Launcher tray → Settings (Setting.cs)	✔Interface✖<PortalPath>✖GeneralSetting	Open Portal on General settings
Launcher tray → Interface (Interface.cs)	✔Interface✖<PortalPath>	Open the Portal
Launcher tray → Property (Property.cs)	✔Property✖<PropertyPath>	Open the per-wallpaper property editor
Launcher tray → Reportdog (Reportdog.cs)	✔Reportdog✖<ReportdogPath>	Launch the report uploader
Launcher → Version cleanup (Version.cs)	✔Versioning✖<%LocalAppData%\Sucrose>✖<entryVersion>✖false	Delete old-version folders
Crash path (Sucrose.Shared.Space.Helper.Watchdog.cs)	✔Watchdog✖<WatchdogPath>✖<Base64 payload>	Show the crash dialog / write the report
Updater (Sucrose.Update/View/MainWindow.xaml.cs)	✔Bundle✖<installerPath>	Launch the downloaded installer
Engine (Sucrose.Shared.Engine/Event/Handler.cs)	✔RestartLive✖Unknown	Reload after an engine-side event

Some Launcher commands (Close.cs, Engine.cs, Report.cs) act locally — they kill processes or show a dialog directly and do not go through Commandog. Feedback.cs is fully commented out (no feedback dialog ships).

Special command notes

• Reload vs. Cycle vs. Restart. RestartLive is the reload (it also kills Sucrose.Backgroundog.exe); Cycyling (note the spelling) is the cycling reload used by Wallpaper-Cycling; both go through Commandog.
• Service launchers. Backgroundog, Watchdog, Reportdog, and Property exist mainly to launch the corresponding service .exe. Backgroundog auto-exits when there is no live wallpaper (after a few retries), so it is started on demand via ✔Backgroundog✖….
• The Watchdog payload is Base64. The Watchdog command's second value is a Base64-encoded Application✖SerializedException✖Show✖LogPath block — see Crash-Reporting.
• Internal enums. Both CommandType and the live-channel CommunicationType enums are declared internal. They are not exposed as a public API.
• The command bus is not the data channel. Despite the "command" wording, this protocol is unrelated to the Pipe/Signal/Transmission live-data channels documented in IPC.

See also

• Automation-Examples — practical, copy-pasteable command examples (with the same disclaimer)
• Commandog-Dispatcher — how the dispatcher parses and routes a command
• IPC — the Pipe/Signal/Transmission live-data channels (a separate mechanism)
• Architecture-Overview — the multi-process design these commands coordinate
• Theme-Tray-Startup — startup modes that map to the Startup/Scheduler commands
• Troubleshooting-Settings-Startup-GPU — why auto-start lives in Task Scheduler, not the registry Run key