SynapseCTRL

Programmatic control for Razer Synapse 4 software profiles on Windows.

SynapseCTRL discovers connected devices, lists their software profiles, reports the active profile, and switches profiles through Synapse itself — without UI automation or fake clicks.

The source project is developed, dependency-managed, and built with uv. It is intentionally uv-first while still publishing as a normal Python package and command-line tool.

Important: SynapseCTRL requires its Synapse inspector hook before device/profile control will work. Start with the Getting Started guide.

Install

SynapseCTRL is published on PyPI. Installing it exposes synapsectrl as a terminal command, so normal usage does not require cloning the repository or running the project through Python manually.

For the CLI, an isolated uv tool install is recommended:

uv tool install synapsectrl
synapsectrl hook install

Standard pip installation also works:

python -m pip install synapsectrl
synapsectrl hook install

After either install, commands are available directly from the terminal:

synapsectrl --version
synapsectrl devices

Windows will request administrator elevation for the hook installer. Fully exit and reopen Razer Synapse afterward.

Python projects can add the SDK with:

uv add synapsectrl

What it can do

synapsectrl devices
synapsectrl profiles "Naga"
synapsectrl switch "Naga" "Siege"

For other programs, every command also supports machine-readable JSON:

synapsectrl devices --json

Python applications can use SynapseClient directly instead of spawning the CLI.

Documentation

• Getting Started — install the package and required hook, verify SynapseCTRL works, and make your first switch
• Documentation home — find setup, CLI, SDK, architecture, troubleshooting, and developer references
• CLI & JSON — scripting and cross-language integrations
• Python SDK — use SynapseCTRL directly from Python
• API reference — models, errors, selectors, and exact behavior
• Troubleshooting — doctor, update repair, and diagnostics

Quick Python example

from synapsectrl import SynapseClient

with SynapseClient() as synapse:
    devices = synapse.list_devices()
    for device in devices:
        print(device.name, device.active_profile_id)

    synapse.switch_profile("Naga", "Siege")

Use stable device IDs and profile GUIDs for unattended automation. Human-readable names are convenience selectors.

Attribution and license

SynapseCTRL is licensed under the Apache License 2.0 and ships with a NOTICE file so downstream distributions preserve project attribution as required by the license.

When integrating SynapseCTRL, it is also appreciated if your source or documentation mentions that Razer Synapse device/profile discovery and control is handled by SynapseCTRL. See Attribution.

Project status

SynapseCTRL targets Razer Synapse 4 on Windows and relies on private Synapse/Electron interfaces discovered at runtime. Synapse updates can change those interfaces, so compatibility is capability-checked rather than tied to one fixed Synapse version.

This is an independent community project and is not affiliated with or endorsed by Razer.