DeckSurf - The Open Stream Deck CLI & Tooling

Lightweight and open way to manage your Stream Deck device.

• Installation
• Prerequisites
• How It Works
• Available CLI Commands
• Included Plugin: Barn
  • LaunchApplication
  • ShowCPUUsage
  • SnakeGame
• Building a Plugin
  • Plugin Interface
  • Command Interface
  • Key SDK Types
  • Plugin Deployment
• Supported Devices
• FAQ

DeckSurf is distributed as a .NET global tool. Install it with:

dotnet tool install -g DeckSurf

Once installed, the deck command is available from any terminal. To update to the latest version:

dotnet tool update -g DeckSurf

The tool includes the Barn plugin out of the box, so you can start using commands like LaunchApplication, ShowCPUUsage, and SnakeGame immediately.

• .NET 10 SDK
• A supported Elgato Stream Deck device (XL, XL 2022, Plus, Original, Original 2019, MK.2, Mini, Mini 2022, Neo)
• Windows: The Elgato Stream Deck software must be closed before running DeckSurf (it holds exclusive USB access)
• macOS: USB entitlements (com.apple.security.device.usb) are required
• Linux: udev rules must be configured for Stream Deck USB access

To get started, it's necessary to create a new profile, with a set of commands that will be associated with a button on the Stream Deck. To do that, you can use the write command in the DeckSurf CLI.

Usage:
  deck write [options] 

Options:
  -d, --device-index <device-index> (REQUIRED)  Zero-based index of the connected device. [default: -1]
  -k, --key-index <key-index> (REQUIRED)        Zero-based index of the key to configure. [default: -1]
  -n, --plugin <plugin> (REQUIRED)              Plugin ID (e.g., DeckSurf.Plugin.Barn). [default: ]
  -c, --command <command> (REQUIRED)            Command class name within the plugin. [default: ]
  -i, --image-path <image-path> (REQUIRED)      Path to the default image for the button. [default: ]
  -a, --action-args <action-args> (REQUIRED)    Arguments passed to the command. [default: ]
  -p, --profile <profile> (REQUIRED)            Profile name. Created if it does not exist. [default: ]
  -?, -h, --help                                Show help and usage information

The following arguments are used, and are required:

The created profile will be located in %LOCALAPPDATA%\Den.Dev\DeckSurf\Profiles\{PROFILE_NAME}. The settings are stored in a profile.json file within the profile folder.

DeckSurf ships with DeckSurf.Plugin.Barn, a built-in plugin that demonstrates the plugin system and provides useful commands out of the box. All Barn commands are compatible with every supported Stream Deck model.

Launches an application when the mapped button is pressed. On activation, it automatically extracts the file icon from the target executable and displays it on the button (Windows only). If a custom --image-path is provided in the profile, that image is used instead.

Usage example:

deck write -d 0 -k 5 -n DeckSurf.Plugin.Barn -c LaunchApplication -i "" -a "C:\Windows\System32\notepad.exe" -p myprofile

The --action-args (-g) value is the full path to the executable to launch.

Displays a live-updating system-wide CPU usage percentage on the mapped button. The display refreshes every 2 seconds. On Windows, the percentage is rendered as red text on a black background. On macOS and Linux, the button color shifts from green (low usage) through yellow to red (high usage).

Usage example:

deck write -d 0 -k 10 -n DeckSurf.Plugin.Barn -c ShowCPUUsage -i "" -a "" -p myprofile

No arguments are required for this command.

A fully playable game of snake that runs on the Stream Deck button grid. The snake moves automatically once per second, and you steer it by pressing buttons on the device. Press a button above or below the snake's head to change vertical direction, or left/right to change horizontal direction. The snake wraps around the edges of the grid.

Usage example:

deck write -d 0 -k 0 -n DeckSurf.Plugin.Barn -c SnakeGame -i "" -a "" -p myprofile

The game uses the device's full button grid (e.g., 8x4 on the XL). Snake segments are displayed as white buttons and empty space is black.

DeckSurf uses a plugin architecture powered by the DeckSurf SDK. Plugins are .NET class libraries that implement the IDeckSurfPlugin and IDeckSurfCommand interfaces.

Each plugin must implement IDeckSurfPlugin:

using DeckSurf.SDK.Interfaces;
using DeckSurf.SDK.Models;

public class Plugin : IDeckSurfPlugin
{
    public PluginMetadata Metadata => new()
    {
        Author = "Your Name",
        Id = "DeckSurf.Plugin.YourPlugin",
        Version = "1.0.0",
        Website = "https://example.com"
    };

    public List<Type> GetSupportedCommands()
    {
        return new List<Type>() { typeof(YourCommand) };
    }
}

Each command implements IDeckSurfCommand (which extends IDisposable):

using DeckSurf.SDK.Interfaces;
using DeckSurf.SDK.Models;

[CompatibleWith(DeviceModel.XL)]
class YourCommand : IDeckSurfCommand
{
    public string Name => "Your Command";
    public string Description => "Description of the command.";

    public void ExecuteOnActivation(CommandMapping mappedCommand, IConnectedDevice mappedDevice)
    {
        // Called when the command is loaded and the device is initialized.
    }

    public void ExecuteOnAction(CommandMapping mappedCommand, IConnectedDevice mappedDevice, int activatingButton = -1)
    {
        // Called when the mapped button is pressed.
    }

    public void Dispose()
    {
        // Clean up any resources (timers, handles, etc.)
    }
}

Plugin DLLs must follow the naming convention DeckSurf.Plugin.*.dll and be placed in a plugins/{PluginName}/ subdirectory relative to the deck executable.

The Stream Deck Plus and Neo also support LCD screen output via IConnectedDevice.SetScreen().

The Stream Deck is a great piece of hardware, but the official software is closed-source and opaque. I created DeckSurf to build an open, hackable alternative — by reverse engineering the USB HID protocol that the Stream Deck uses, I wanted to give developers and tinkerers full control over their devices without relying on proprietary tooling. The goal is an open ecosystem where anyone can extend, automate, and integrate their Stream Deck however they see fit.

No - not in any capacity. Use at your own leisure and risk.

This repository generally should be a good starting point, but you can also go to https://deck.surf for latest links and relevant information.

Starting with DeckSurf SDK 0.0.7, the underlying SDK supports Windows, macOS, and Linux. Cross-platform support in the CLI tooling is a work in progress.

Not yet - it's just a CLI and a .NET SDK. In the future, I expect to also create a more visual approach to managing the content, that is easier for folks that don't want to fiddle with the terminal.