Problem
After commissioning, devices get generic names from their ProductName attribute (e.g. "On/Off Light"). Renaming requires a verbose cluster write:
matter cluster write --cluster basic-information --attribute node-label "Kitchen Light" @1/1
Even then, the updated label is only stored on the device — the local store Name field (used for autocomplete and @alias resolution) is never updated, so @kitchen-light wouldn't work after a rename.
Proposed Solution
Add a top-level matter rename command:
matter rename @1 "Kitchen Light"
This should:
- Update the local store — set
node.Name to the new label so autocomplete and @alias resolution work immediately.
- Write
NodeLabel (0x0005) to the device — sync the label to the Matter device's BasicInformation cluster so other controllers see it too.
- Confirm the change — print the old and new name, e.g.
Renamed @1: "On/Off Light" → "Kitchen Light".
Alias resolution after rename
Once renamed, all target forms should work interchangeably:
matter OnOff Toggle @1/1 # by node ID
matter OnOff Toggle @kitchen-light/1 # by alias (kebab-case of Name)
Edge cases to handle
- Name conflicts — warn (but don't block) if another node already has the same name.
- Empty name — reject empty strings; suggest
matter rename @1 --reset to restore the original ProductName.
- Offline device — update the local store name even if the device is unreachable (skip the
NodeLabel write with a warning).
Relevant Code
| File |
What it does |
internal/store/types.go:22-32 |
Node.Name field |
internal/store/bolt.go:165-185 |
SaveNode() — persists node including Name |
cli/target.go:112-142 |
resolveAlias() — maps name → node ID |
cli/completion/completer.go:314-317 |
Builds kebab-case alias from node.Name |
cli/commission.go:345-349 |
Sets initial Name from ProductName / VendorName |
internal/clusters/basicinformation/cluster.go:24 |
AttrNodeLabel (0x0005) |
Out of Scope
- Multiple aliases per node (a single Name is sufficient for now).
- Renaming endpoints (only node-level naming).
Problem
After commissioning, devices get generic names from their
ProductNameattribute (e.g. "On/Off Light"). Renaming requires a verbose cluster write:matter cluster write --cluster basic-information --attribute node-label "Kitchen Light" @1/1Even then, the updated label is only stored on the device — the local store
Namefield (used for autocomplete and@aliasresolution) is never updated, so@kitchen-lightwouldn't work after a rename.Proposed Solution
Add a top-level
matter renamecommand:matter rename @1 "Kitchen Light"This should:
node.Nameto the new label so autocomplete and@aliasresolution work immediately.NodeLabel(0x0005) to the device — sync the label to the Matter device's BasicInformation cluster so other controllers see it too.Renamed @1: "On/Off Light" → "Kitchen Light".Alias resolution after rename
Once renamed, all target forms should work interchangeably:
Edge cases to handle
matter rename @1 --resetto restore the originalProductName.NodeLabelwrite with a warning).Relevant Code
internal/store/types.go:22-32Node.Namefieldinternal/store/bolt.go:165-185SaveNode()— persists node including Namecli/target.go:112-142resolveAlias()— maps name → node IDcli/completion/completer.go:314-317node.Namecli/commission.go:345-349ProductName/VendorNameinternal/clusters/basicinformation/cluster.go:24AttrNodeLabel(0x0005)Out of Scope