dualshock-tool: CLI vs Browser for DualShock Diagnostics (2026)

The phrase dualshock-tool does not point to one piece of software. It points to a small ecosystem of open-source command-line utilities hosted on GitHub, each of which talks to a Sony controller through the USB HID protocol.

The three most active projects are nondebug/dualsense (a JavaScript and Python reference implementation of the DualSense HID protocol), chrippa/ds4drv (a Linux DualShock 4 userspace driver), and the ds4-tool family of small Windows binaries that ship alongside DS4Windows. They are diagnostic and protocol-research tools, not consumer products.

The reason these tools exist is the truth most "how to test your controller" blogs skip. Sony has never shipped a calibration GUI for any DualShock or DualSense controller. Out-of-warranty diagnostic work fell to the open-source community, and the community built it as a CLI because the first goal was protocol reverse engineering, not user experience.

A typical session looks like this. You clone the repo, install Python 3.10 with hidapi bindings, attach the controller by USB-C, and run a script that writes a vibration report to output report ID 0x02. The motors spin and you have proven the controller's rumble path is alive.

That is useful if you are debugging firmware behaviour or building your own integration. It is overkill if you just want to know whether your left stick is drifting.

There are exactly three things a CLI dualshock-tool gets you that the browser does not, and being honest about this matters more than pretending the CLI is obsolete.

Raw HID feature reports. The W3C Gamepad API only exposes the standardized input layer (axes and buttons). It does not expose vendor-specific HID feature reports. On a DualSense, those reports include things like internal temperature, battery cell voltage, and the controller's MAC address. A CLI can request feature report 0x05 and parse the bytes directly; the browser cannot.

Output reports to the controller. The Gamepad API is read-only. It can read state, but until very recently no browser could write back. CLI tools write vibration patterns, set the lightbar colour, and configure DualSense haptic triggers by sending output reports. The WebHID API is changing this on Chrome and Edge, and JoyCheck uses WebHID for rumble where available, but coverage is not universal yet.

Scripted automation. A CLI is shell-scriptable. You can run a regression suite that hammers the trigger 10,000 times and logs the analog values to CSV. That is hard to do in a browser tab that sleeps when backgrounded. For QA work in controller manufacturing or for protocol research, a CLI is the right tool.

Beyond those three, almost every diagnostic question a regular owner has about a DualShock or DualSense can be answered faster in a browser.

The job most people who type "dualshock-tool" into Google actually have is: "is my controller drifting, and should I repair or replace?" That is a diagnostic question, not a protocol question. It does not need raw HID output reports. It needs the input layer the W3C Gamepad API already exposes.

JoyCheck reads navigator.getGamepads() inside a requestAnimationFrame loop and displays the four stick axes and every button to three decimal places. For a DualShock 4 or DualSense, the four axes are left X, left Y, right X, right Y, in the range -1.0 to +1.0.

A new stick centres inside ±0.005, a worn stick sits outside ±0.03.

Zero install. Works over Bluetooth on macOS, Windows, Linux, ChromeOS, and recent iPadOS. No sudo, no Python venv, no driver, and the whole flow takes 30 seconds.

For the write side (vibration tests, lightbar control), JoyCheck uses WebHID where the browser supports it, which covers Chrome and Edge on desktop. On Firefox and Safari the read-only diagnostic still runs; the write path is what you lose. For pure stick-drift answers, that does not matter.

When you plug in a DualShock 4 or DualSense, the operating system enumerates it as a USB HID gamepad. The browser sees the same enumeration and exposes a Gamepad object to JavaScript through navigator.getGamepads(), per the W3C Gamepad API specification and the matching MDN Gamepad API reference.

The object has four properties that diagnostic tools care about. axes is the array of analog values, and buttons is the array of button states with pressed booleans and value floats.

mapping is either "standard" (the W3C standard layout, which DualShock controllers report under) or empty, and timestamp is a DOMHighResTimeStamp of the last state change.

The DualSense reports input at approximately 250 Hz over USB and 125 Hz over Bluetooth, per protocol traces published with the nondebug/dualsense reference implementation and corroborated by iFixit teardowns. The browser samples at the render rate (60 Hz on most displays, 120 Hz on a 120 Hz monitor). For diagnostic visibility that is plenty, because the eye cannot resolve sub-frame drift visually.

The single thing the API gives you that the controller itself does not is the raw, pre-deadzone value. Games apply a deadzone of 0.15 to 0.25 before they react; if your stick idles at 0.04, the game silently ignores it. JoyCheck shows you the 0.04, so you can decide.

If you have decided the CLI is what you actually want, here is the shape of a typical install. We use nondebug/dualsense as the example because it is the cleanest reference and works on macOS, Linux, and Windows.

1. Install Python 3.10 or newer. macOS users typically use Homebrew (brew install python@3.11). Linux users use the distro package manager. Windows users install from python.org and tick "Add to PATH".
2. Clone the repo. git clone https://github.com/nondebug/dualsense.git && cd dualsense.
3. Install the HID bindings. pip install hid (or pip install hidapi, depending on platform). On macOS you may also need brew install hidapi. On Linux you need libhidapi-libusb0 and a udev rule so non-root users can claim the device.
4. Run the Python read script. python3 read.py will dump the parsed HID input report to stdout while the controller is plugged in over USB-C.
5. Run the vibration script. A short Python snippet that opens the HID device with hid.device(), then writes a 78-byte output report to ID 0x02 with the rumble intensity bytes in positions 4 and 5. The motors spin until you send a zeroed report.

If you want the ds4drv flow instead (Linux only, exposes DualShock 4 as a uinput joystick), the install is sudo apt install ds4drv on Debian-based distros, then sudo ds4drv to run the daemon. It does not have a Mac or Windows port.

If you are on Windows and want a binary you do not have to compile, the DS4Windows installer ships several small CLI utilities alongside the main GUI for vibration testing and battery polling.

Realistically, getting any of these running for the first time takes 20 to 40 minutes if you have not used Python or a build toolchain recently. JoyCheck takes 30 seconds. That is the trade-off.

Whichever tool you use, the drift you measure is, in nearly every case, a hardware wear problem. The cause varies by stick technology and so does the prognosis.

If your CLI or browser readout shows persistent drift outside the warranty period, and the controller is a standard DualSense or DualShock 4, the stick module is wearing. The replacement parts are about €15 to €25 and the iFixit DualSense guide and iFixit DualShock 4 guide are rated moderate difficulty. Or you replace the controller.

The DualSense Edge ships with TMR sticks specifically because of the drift complaints that hit DualShock 4 and base DualSense. If you have an Edge showing measurable drift, that is unusual and worth a warranty conversation with Sony PlayStation support directly.

There is a category of failure where neither the browser tool nor the CLI tool will save you, and naming it up front saves people an evening of pointless debugging.

• Bluetooth pairing failures. Re-pair through your OS. The Bluetooth SIG standard handles pairing flows; controllers do not.
• Charging port issues. Visible only in USB charging behaviour. A diagnostic tool reads the input; it does not test the power path.
• Vibration motor failure. Testable via rumble (CLI or WebHID), not fixable in software. Stick-module-level replacement.
• DualSense mic or speaker. Separate audio subsystem on the controller. Different diagnostic path.
• Stick centering after a calibration offset. The HID protocol Sony ships does not have a calibration-offset command. There is no way for a CLI tool to "set the centre" the way Microsoft's Xbox Accessories app does for the Xbox Elite Series 2. Drift is a hardware problem with a hardware solution.

If the controller reports accurate values to your diagnostic tool and the game still misbehaves, the problem is upstream: a driver, a Steam Input override, or a game-side deadzone setting. Test on a second machine to isolate.

You do not need to read 2,000 more words to decide. Use this.

• Want to know if your stick is drifting? Browser. Open JoyCheck, connect, watch the numbers.
• Want to test buttons or trigger pressure? Browser. Same flow.
• Want to test rumble? Browser on Chrome or Edge (WebHID). CLI elsewhere.
• Want to test DualSense adaptive triggers or haptic feedback? Browser on Chrome or Edge, CLI as fallback.
• Want to read battery voltage or internal temperature? CLI.
• Building a controller QA pipeline? CLI, scripted.
• Reverse engineering an undocumented HID report? CLI.

The CLI dualshock-tool ecosystem is alive because protocol-level work needs it. The browser is alive because the other 95% of the time the protocol layer is not what the user needs to see.

1. W3C, "Gamepad API specification": w3.org/TR/gamepad
2. Mozilla Developer Network, "Gamepad API reference": developer.mozilla.org
3. nondebug/dualsense, DualSense HID protocol reference (GitHub): github.com/nondebug/dualsense
4. WICG, "WebHID API specification": wicg.github.io/webhid
5. iFixit, DualSense and DualShock 4 repair guides: ifixit.com
6. PlayStation, "DualSense Edge wireless controller": playstation.com
7. PlayStation, "Hardware support": playstation.com/support
8. USB Implementers Forum, "HID information": usb.org/hid
9. Microsoft, "Xbox Accessories app": apps.microsoft.com