Automation Examples

Automation Examples

⚠️ Stability disclaimer — read this first. Everything on this page drives Sucrose's internal IPC command protocol, not a stable, supported public command line. The Portal and Launcher build these commands for you automatically; the format, command names, and argument order are implementation details that can change between versions without notice, and there is no compatibility guarantee. Treat these examples as advanced/experimental. If a command stops working after an update, the protocol changed — that is expected. For the formal reference, see Command-Reference.

This page collects practical, copy-pasteable automation recipes built on the command bus that Sucrose.Commandog.exe dispatches. Every command is a single specially-encoded string of the form ✔Command✖value✖value, where ✔ is U+2714 (HEAVY CHECK MARK) and ✖ is U+2716 (HEAVY MULTIPLICATION X). The most realistic automation use cases are configuring auto-start-on-logon, reloading the wallpaper, and triggering the cycling reload. For the complete list of commands and their arguments, read Command-Reference first; for how the dispatcher works, see Commandog-Dispatcher.

Contents

• Prerequisites and caveats
• Emitting the marker characters correctly
• Example: auto-start Sucrose on logon (Task Scheduler)
• Example: remove or toggle the logon task
• Example: reload the wallpaper
• Example: cycling reload
• Example: open the Portal on a specific settings page
• Example: launch a background service or helper
• Example: diagnose the parser with the Test command
• See also

Prerequisites and caveats

• The dispatcher executable is Sucrose.Commandog.exe. It lives under %LocalAppData%\Sucrose in its own sibling folder (…\Sucrose.Commandog\Sucrose.Commandog.exe). See Data-Locations for the exact install layout.
• Commandog reads its own argument string, performs one action, and immediately exits (Environment.Exit(0)). It is not a daemon; each command is a fresh process launch.
• Command names are case-insensitive (RestartLive == restartlive). The ✔ start marker and at least one ✖-separated value are both required, or the input is ignored.
• The placeholders below (<PortalPath>, <UpdatePath>, etc.) are full paths to the corresponding Sucrose executables. In normal operation the UI fills these in; if you script them, point them at the real .exe paths under %LocalAppData%\Sucrose.
• There is no documented stdout contract. Apart from the diagnostic Test command, Commandog produces no machine-readable output — do not parse its console for status.

Emitting the marker characters correctly

The hardest part of scripting these commands is producing the literal Unicode markers ✔ (U+2714) and ✖ (U+2716) as UTF-8, not their ASCII look-alikes. Commandog sets its console to UTF-8 on startup, so the bytes must arrive as UTF-8.

In PowerShell, build the markers from their code points so you never have to paste the glyphs:

# Build the marker characters from code points (avoids copy/paste mistakes)
$check = [char]0x2714   # ✔  StartCommand
$x     = [char]0x2716   # ✖  ValueSeparator

# Helper: run a Commandog command from an array of parts.
# parts[0] is the command name; the rest are values.
function Invoke-SucroseCommand {
    param(
        [Parameter(Mandatory)] [string] $CommandogPath,
        [Parameter(Mandatory)] [string[]] $Parts
    )
    $check = [char]0x2714
    $x     = [char]0x2716
    $arg   = $check + ($Parts -join $x)
    Start-Process -FilePath $CommandogPath -ArgumentList $arg
}

Make sure your console and any file you save the script to are UTF-8 encoded, or the markers can be mangled before they reach the process.

Example: auto-start Sucrose on logon (Task Scheduler)

Sucrose's preferred auto-start mechanism is a Windows Task Scheduler task named Autorun for Sucrose (in the \Sucrose\ task folder), triggered at logon for the current user. The Scheduler command with the Create sub-command creates it; the second value is the application path the task should run.

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

Driven from PowerShell with the helper above:

$commandog = "$env:LocalAppData\Sucrose\Sucrose.Commandog\Sucrose.Commandog.exe"
$appToRun  = "$env:LocalAppData\Sucrose\Sucrose.Launcher\Sucrose.Launcher.exe"

Invoke-SucroseCommand -CommandogPath $commandog -Parts @('Scheduler','Create', $appToRun)

The resulting task uses a LogonTrigger, has no execution time limit, and does not stop on battery. This is the same mechanism the Portal uses when you choose the Scheduler startup mode (see Theme-Tray-Startup). Because it is a scheduled task — not a registry Run entry — you manage it in Task Scheduler, not in msconfig/Run; see Troubleshooting-Settings-Startup-GPU.

Example: remove or toggle the logon task

To temporarily turn auto-start off without deleting the task, use Disable; re-enable with Enable; remove it entirely with Delete:

✔Scheduler✖Disable
✔Scheduler✖Enable
✔Scheduler✖Delete

$commandog = "$env:LocalAppData\Sucrose\Sucrose.Commandog\Sucrose.Commandog.exe"

# Turn auto-start off (keeps the task)
Invoke-SucroseCommand -CommandogPath $commandog -Parts @('Scheduler','Disable')

# Turn it back on
Invoke-SucroseCommand -CommandogPath $commandog -Parts @('Scheduler','Enable')

# Remove it completely
Invoke-SucroseCommand -CommandogPath $commandog -Parts @('Scheduler','Delete')

The Run-key alternatives exist too (Startup per-user, StartupM machine-wide, StartupP priority/approved), but the Scheduler task is what the UI uses by default. See Command-Reference for those signatures.

Example: reload the wallpaper

RestartLive is the wallpaper reload: it stops the live engine and its subprocess, kills Sucrose.Backgroundog.exe, restarts the wallpaper, waits ~1500 ms, and retries if it did not come back. It takes one value, conventionally Unknown.

✔RestartLive✖Unknown

$commandog = "$env:LocalAppData\Sucrose\Sucrose.Commandog\Sucrose.Commandog.exe"
Invoke-SucroseCommand -CommandogPath $commandog -Parts @('RestartLive','Unknown')

This is exactly what the Launcher tray "Reload" action emits. Use it after editing settings or assets that the engine reads only at startup.

Example: cycling reload

Cycyling (note the spelling in code) performs the cycling reload used by the slideshow feature: it stops the live engine and subprocess, restarts the wallpaper, waits ~1500 ms, and retries once if needed. It does not consume a value beyond the required one, so pass a placeholder:

✔Cycyling✖Unknown

$commandog = "$env:LocalAppData\Sucrose\Sucrose.Commandog\Sucrose.Commandog.exe"
Invoke-SucroseCommand -CommandogPath $commandog -Parts @('Cycyling','Unknown')

For the user-facing slideshow configuration (interval, random vs. sequential, exclusion list), see Wallpaper-Cycling.

Example: open the Portal on a specific settings page

The Interface command opens the Portal. With a second value (an ArgumentCommandType member) it jumps straight to a settings page:

✔Interface✖<PortalPath>
✔Interface✖<PortalPath>✖GeneralSetting

$commandog = "$env:LocalAppData\Sucrose\Sucrose.Commandog\Sucrose.Commandog.exe"
$portal    = "$env:LocalAppData\Sucrose\Sucrose.Portal\Sucrose.Portal.exe"

# Just open the Portal
Invoke-SucroseCommand -CommandogPath $commandog -Parts @('Interface', $portal)

# Open the Portal directly on the General settings page
Invoke-SucroseCommand -CommandogPath $commandog -Parts @('Interface', $portal, 'GeneralSetting')

Valid page targets are OtherSetting, SystemSetting, GeneralSetting, PersonalSetting, WallpaperSetting, and PerformanceSetting (plus the hidden DonateSetting). Each maps to a page documented under Settings-Overview.

Example: launch a background service or helper

Several commands exist mainly to launch a service .exe. These pass the target executable path as the value:

✔Backgroundog✖<BackgroundogPath>
✔Reportdog✖<ReportdogPath>
✔Property✖<PropertyPath>

$commandog    = "$env:LocalAppData\Sucrose\Sucrose.Commandog\Sucrose.Commandog.exe"
$backgroundog = "$env:LocalAppData\Sucrose\Sucrose.Backgroundog\Sucrose.Backgroundog.exe"

# Start the system-status / audio service on demand
Invoke-SucroseCommand -CommandogPath $commandog -Parts @('Backgroundog', $backgroundog)

Note that Backgroundog-Service auto-exits when there is no live wallpaper, so starting it manually only makes sense while a wallpaper is running. Property opens the per-wallpaper property editor for the currently selected wallpaper (use PropertyA with a second value to target a specific theme) — see Property-Service and Customizing-Wallpaper.

Example: diagnose the parser with the Test command

Test is a built-in diagnostic: it prints Test Values: and then, for each value, detects its type (bool, then int, else string) and echoes the parsed value. Use it to confirm your markers and encoding are reaching Commandog intact:

✔Test✖true✖42✖hello

$commandog = "$env:LocalAppData\Sucrose\Sucrose.Commandog\Sucrose.Commandog.exe"
Invoke-SucroseCommand -CommandogPath $commandog -Parts @('Test','true','42','hello')

If Test does not echo your values, the ✔/✖ markers were not delivered as UTF-8 — revisit Emitting the marker characters correctly.

📷 Screenshot needed: The Sucrose.Commandog.exe console window output after running ✔Test✖true✖42✖hello, showing the Test Values: line and the three parsed values.

See also

• Command-Reference — the authoritative table of all 31 commands, their arguments, and the wire format
• Commandog-Dispatcher — how the dispatcher parses, routes, and exits
• Wallpaper-Cycling — the user-facing slideshow that the Cycyling command backs
• Theme-Tray-Startup — startup modes (None/Normal/Priority/Scheduler) that map to startup commands
• IPC — the separate Pipe/Signal/Transmission live-data channels
• Data-Locations — where the executables and data live on disk