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 the SynapseCTRL CLI 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 resolve device "Naga"
SynapseCTRL resolve profile "Naga" "Siege"
SynapseCTRL switch "Naga" "Siege"

The resolver commands accept either names or stable IDs and return the resolved object, making name ↔ ID lookup explicit for scripts and integrations.

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

SynapseCTRL devices --json
SynapseCTRL resolve profile "Naga" "Siege" --json

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

For high-frequency local integrations, SynapseCTRL also includes a persistent NDJSON stdio bridge:

SynapseCTRL bridge --stdio

The bridge keeps one Synapse connection/state watcher alive and can emit profile/device/Synapse availability events. It is intended for applications that own the bridge as a child process, such as Stream Deck plugins.

Optional HTTP / REST API

A conventional REST API is available as an optional dependency, so bridge-only users do not need to install a web stack.

Install it with:

uv tool install "SynapseCTRL[http]"

or:

python -m pip install "SynapseCTRL[http]"

Then run:

SynapseCTRL serve

The default API listens only on:

http://127.0.0.1:8765

It uses Starlette + Uvicorn and reuses the same persistent SynapseService core as bridge mode. See the HTTP / REST API guide for endpoints and security guidance.

Documentation

• Getting Started — install the package and required hook, verify SynapseCTRL works, and make your first switch
• Documentation home — find setup, CLI, SDK, bridge, HTTP, architecture, troubleshooting, and developer references
• CLI & JSON — terminal use and one-shot scripting
• Persistent Bridge — long-lived stdio protocol and events
• HTTP / REST API — optional Starlette/Uvicorn server and endpoints
• 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:
    device = synapse.resolve_device("Naga")
    profile = synapse.resolve_profile(device.id, "Siege")
    print(device.name, device.id)
    print(profile.name, profile.id)

    synapse.switch_profile(device.id, profile.id)

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.