Shinyspace

Connecting Matter devices via CLI

2026-04-21

Today my first Matter compatible device arrived: a smart plug. For reasons explained maybe at the end, I wanted to control it from my linux commandline and for that I picked "chip-tool" to do it.

Step 1: Compile chip-tool

chip-tool does not provide binary release builds and Archlinux does not have an official package in the repositories. However, some cool person published a PKGBUILD in the AUR that makes it very easy to compile on archlinux:

yay chip-tool (takes a while to compile)

the resulting binary works well on both my desktop PC that compiled it and on my minipc server.

Step 2: Certificates

Matter (or at least chip-tool) verifies that a device really is what it claims to be, using Certificates to do that. For these to work, the proper trust root certs need to be available. in my case I downloaded them through the repository: https://github.com/project-chip/connectedhomeip

takes a while to clone the entire repo, i'm sure theres quicker ways if i ever set this up again/properly. After downloading, you can specify the proper location when running chip-tool (i only needed it during pairing): --paa-trust-store-path /root/connectedhomeip/credentials/production/paa-root-certs/

Step 3: Bluetooth

My smart plug is a Wifi matter device - this is on one hand nice because i did not need a "thread bridge" or similar. On the other hand, it does need to connect to the wifi before becoming useful, and to do that you need bluetooth (low energy, ble). My server has an Intel AX200 wifi card that also has bluetooth, so on archlinux i was able to set it up:

Step 4: Pairing

first, i recommend finding the QR code string for the full pairing info. i use a qr scanner app on my phone. you'll get something like this: MT:Y.K9042C00KA0648G00
then we can run chip-tool payload parse-setup-payload "MT:Y.K9042C00KA0648G00" which gives us our PIN and our Discriminator (full lenght) that we'll use for pairing.

Note: there is also a numeric pairing code printed on the plug, but that one only gave me a shortened discriminator, which did not work in my attempt.

Next, we can use chip-tool to pair our device: ./chip-tool pairing ble-wifi 1 "WIFI_SSID" "WIFI_PASSWORD" "<pin>" "<discriminator>" --paa-trust-store-path /root/connectedhomeip/credentials/production/paa-root-certs/

where that first 1 is the ID we are assigning to the device, so if you have more than one device change this each time.

If that succeeds, great! you can now use the device! if not:
in my case, i tried a 5ghz wifi at first, which the device seemingly does not support. using the 2.4ghz wifi worked.

Step 5: Using the device

here's the commands i've successfully ran:

./chip-tool onoff on 1 1
./chip-tool onoff toggle 1 1
./chip-tool onoff read on-off 1 1

where the first "1" is for the device id we set while pairing, and the second "1" is supposedly the "functionality", in a smart plug just the power on/off functionality.

The read on-off command prints a LOT of output, i'm not sure yet how to properly parse it to use it in scripts.

Bonus: Why chip-tool

For any reasonable human being, either Home Assistant or one of the smarthome apps by Google/Apple would be the way to go. For me personally, Google and Apple aren't an option, and Home Assistant, bluntly said, is "bloat" (sorry). I'm not going to run an entire "Home Assistant Operating System" to turn a lamp on or off. a minimum of 2GB ram for it too? not for me.

Home assistant is great, i'm sure. comes with handy mobile apps too to control your lights, and can do WAYYY more than turn lights on or off. I'm just put off by the entire architecture of it. If at all possible, i try to find services that are a simple Go binary you can put wherever and run it, and boom the service works. HA appears to be somewhat of a mess of things, a big python codebase that in effect just wraps CHIP as well in the end.

if there was some simple open source mobile app that could control matter devices, i'd check it out. but i'm not sure if matter devices can do "scheduled on/off" without a central control, and i'm happy to do a bit of work to let my own server handle it in a way i enjoy.