8000 Read All Attributes From a Specific Cluster · Issue #82 · p0fi/matter-cli · GitHub
[go: up one dir, main page]

Skip to content

Read All Attributes From a Specific Cluster #82

Closed

Description

@tobiasgraf

Problem Statement

Checking every attribute of a single cluster takes one command per attribute. To see what BasicInformation reports on a device, you have to know the attribute names up front and run matter @1/0 BasicInformation read <name> a dozen times.

matter @1 tree -L 4 does dump attribute values, but only for the entire device — every endpoint, every cluster. When you are debugging one cluster, that is far too much output and far too slow.

chip-tool covers this with a wildcard attribute ID: basicinformation read-by-id 0xFFFFFFFF 30 0. matter-cli has no equivalent.

Solution

Omitting the attribute reads the whole cluster.

matter @1/0 cluster read --cluster BasicInformation
matter @1/0 BasicInformation read

Both forms send a single wildcard read and print every attribute the device reports, sorted by attribute ID, with --format json|table|yaml support. The endpoint stays pinned to the target, so @1/0 reads endpoint 0 exactly as it does today.

User Stories

  1. As a device integrator, I want to read every attribute of one cluster in a single command, so that I can see the cluster's full state without knowing its attribute names in advance.
  2. As a device integrator, I want to do this by omitting the attribute rather than learning a new subcommand, so that I do not have to remember a third read-like verb.
  3. As a device integrator, I want the shorthand form (matter @1/0 BasicInformation read) to work the same way as the generic form, so that the two surfaces stay consistent.
  4. As a device integrator, I want the read to complete in one network round-trip, so that inspecting a cluster over a slow Thread or Wi-Fi link is fast.
  5. As a device integrator, I want attributes sorted by ID, so that output from two devices can be diffed line by line.
  6. As a device integrator, I want global attributes (ClusterRevision, FeatureMap, AttributeList, EventList, AcceptedCommandList, GeneratedCommandList) included, so that the output reflects what the device actually exposes rather than a filtered view.
  7. As a device integrator, I want those global attributes to sort to the bottom, so that the attributes I care about appear first without needing a filter flag.
  8. As a device integrator, I want attributes the device refuses to disclose to appear as rows marked <access denied>, so that I can tell "not permitted" apart from "not present".
  9. As a device integrator, I want one unreadable attribute not to abort the whole read, so that a single privileged attribute does not cost me the other twenty.
  10. As a script author, I want --format json to emit an array of records, so that I can pipe the result into jq.
  11. As a script author, I want values in JSON to be native types — numbers as numbers, booleans as booleans, arrays as arrays — so that I do not have to parse display strings back into types.
  12. As a script author, I want JSON values to be complete rather than truncated for display, so that long strings and list attributes like AttributeList are usable.
  13. As a script author, I want the JSON record shape to match what subscribe --format json already emits, so that code handling one attribute report handles both.
  14. As a script author, I want progress and status messages on stderr and results on stdout, so that piping produces clean, parseable output.
  15. As a script author, I want the command to exit 0 when the read succeeded even if individual attributes returned a status, so that normal clusters containing a privileged attribute do not look like failures.
  16. As a terminal user, I want a readable table by default, so that I can scan values without reaching for jq.
  17. As a terminal user, I want long values truncated in the table but not in JSON, so that the table stays aligned while machine output stays complete.
  18. As a terminal user reading one attribute, I want today's output to stay exactly as it is, so that the command I run most often does not change under me.
  19. As a terminal user reading one FeatureMap attribute, I want the feature-flag breakdown to keep working, so that I do not lose the decoded view.
  20. As a user who targets the wrong endpoint, I want a clear error naming the cluster and endpoint, so that I understand what went wrong.
  21. As a user who targets the wrong endpoint, I want the error to suggest matter @N tree, so that I know how to find the right endpoint.
  22. As a user running against an unresponsive device, I want the read to time out rather than hang forever, so that I get my shell back.
  23. As a user with the session daemon running, I want the wildcard read to reuse the daemon session, so that I do not pay for a fresh CASE handshake on the command I am running repeatedly while debugging.
  24. As a user of --format json on a single-attribute read, I want the flag to be honored, so that it stops being silently ignored.
  25. As a user piping a single-attribute read, I want the documented pipe default (JSON) to apply, so that the command behaves as the CLI documentation says.
  26. As a user reading a cluster with unknown or vendor-specific attribute IDs, I want those rows shown with a hex identifier, so that unrecognized attributes are still visible.
  27. As a maintainer, I want the wildcard read implemented so that tree -L 4 can adopt it later, so that the tree speedup becomes a small follow-up rather than a rewrite.
  28. As a maintainer, I want the record-building logic to be a pure function, so that it can be table-tested without a device.
  29. As a maintainer, I want the daemon and direct-CASE transports to produce identical records, so that behavior does not depend on whether a daemon happens to be running.
  30. As a maintainer, I want the documented CLI usage updated alongside the feature, so that the reference stays accurate.

Implementation Decisions

Command surface

  • Omitting the attribute triggers a cluster-wide read. The generic form drops its "attribute is required" error; the shorthand form's argument count relaxes from exactly one to at most one.
  • No new subcommand, no new flag, no explicit wildcard sentinel. chip-tool's 0xFFFFFFFF is a CLI-level convention for what the wire encodes as an omitted field, so it is not reproduced at the CLI layer.
  • The endpoint is not wildcardable. It comes from the resolved target exactly as it does today, so @1 still means endpoint 0. Endpoint wildcarding is a separate concern.

Wire protocol

  • A single ReadRequest carrying one attribute path with the attribute ID omitted. The Interaction Model attribute path type already models wildcards as nil pointer fields, and the read client already handles chunked ReportData and returns reports carrying their own paths.
  • The read client is not modified.

Session daemon IPC

  • The IPC attribute-path request type gains an additive boolean field indicating a wildcard attribute. It is additive JSON, so a new daemon receiving an old request is unaffected.
  • The daemon's read handler translates that flag into a wire path with a nil attribute ID. This translation moves out of the handler's inline loop into a named pure function so it can be tested directly.

Result model

  • A single record type mirroring the conventions already established by the subscribe record: numeric cluster ID, cluster name, numeric attribute ID, attribute name, native-typed value, plus an error field populated when the attribute returned a status instead of data, plus a display string excluded from JSON and YAML and used only by the table encoder.
  • Values are decoded with the existing native TLV decoder already used by subscribe, producing booleans, integers, floats, strings, arrays, and structs. This makes read --format json and subscribe --format json agree on the same data, and removes the truncation question from machine output entirely, since the display string is only ever built for the table.
  • Records are sorted by attribute ID ascending. Device report order is not relied on. Because global attributes occupy the top of the ID space, ascending sort places them last without a filtering rule.
  • No attributes are filtered out. The output reflects what the device reported.
  • Unknown attribute IDs resolve through the cluster registry, then the global attribute table, then fall back to 8000 a hex representation — the same resolution order the tree command already uses.

Rendering

  • Both transports normalize into a common report type at the existing transport boundary, then feed one shared record-building function. There is one record-building path, not one per transport.
  • Human rendering branches on result count. One record renders as today's single-attribute output, including the FeatureMap feature-flag breakdown. Multiple records render as a table with ID, attribute, and value columns.
  • --format json and --format yaml always emit an array, for both the single-attribute and wildcard cases. The shape does not depend on how many attributes were requested.
  • Table values keep the existing 40-character middle-truncation. JSON and YAML carry native values and are never truncated.
  • Progress and status output goes to stderr; results go to stdout. This follows the precedent set by subscribe.

Errors and exit codes

  • Per-attribute statuses never abort the read. They render as <access denied> or <timeout> in the table, and as a record with an error field and no value in JSON, reusing the error-formatting the tree command already applies.
  • The command exits 0 when the read transaction itself succeeded, regardless of individual attribute statuses.
  • Zero reports means the cluster is not present on that endpoint. This is an error: a message naming the cluster and endpoint, plus a next-step suggestion to run tree against the node, on stderr, exit 1. It applies in all output formats.

Timeouts

  • The read is wrapped in an overall 30-second deadline at the CLI layer. The daemon's read handler already applies a 30-second timeout, so this brings the direct-CASE path in line with the daemon rather than introducing a new number.
  • The Interaction Model client's timeout behavior is unchanged, so existing callers including tree and subscribe are unaffected.

Placement

  • The implementation stays in the existing cluster command file rather than moving to a new one.

Known consequences

  • Breaking change. Piping a single-attribute read currently emits human-readable text on stdout. It will emit JSON. This is the documented pipe default that the read command never honored, but it will break existing scripts, and must be called out in the pull request description.
  • Daemon version skew. The IPC protocol carries no version field. A daemon left running across a CLI upgrade will not recognize the new wildcard flag and will read attribute 0 instead — wrong data, no error. Stopping the session daemon is the workaround. Fixing the general problem is out of scope.
  • YAML is a stub across the whole CLI: the YAML formatter currently emits pretty-printed JSON. This feature inherits that and does not fix it.
  • Fabric filtering stays on, matching current read behavior. Wildcard reads of AccessControl or OperationalCredentials will therefore not show other fabrics' entries.

Testing Decisions

Good tests here assert external behavior — the records produced from a given set of device reports, and the paths produced from a given IPC request — not the internal steps taken to get there. The network round-trip itself is not unit-tested; it is verified by hand.

Three seams, two of them new:

  1. Record building (new, pure). Given a slice of attribute reports and a cluster, produce the sorted record slice. Table-driven subtests cover: ordering with global attributes present; name resolution for registry-known, global, and unknown attribute IDs; status-only reports mapping to error records with no value; native decoding of scalars, arrays, and structs; and display-string truncation applying to the table field while the native value stays complete. Prior art: the existing daemon/direct read-result parity tests and the existing native TLV decoder tests.

  2. Daemon path translation (new, pure). Given an IPC attribute-path request with and without the wildcard flag, produce the correct wire path. This is small but it is the only place the new flag acquires wire semantics, and daemon/direct divergence is a failure mode this repo already has regression tests for.

  3. Command construction (existing seam, no new production code). Assert the relaxed argument count, that omitting the attribute no longer errors, and that an unknown named attribute still errors. Prior art: the existing subscribe command construction and shorthand tests.

Both transports must produce identical records for equivalent input, following the pattern of the existing parity tests.

End-to-end verification is manual, against the matter.js virtual device (a project skill exists for starting one). This is the only thing that proves a real device accepts the wildcard ReadRequest, which is the design's single riskiest assumption.

Out of Scope

  • Converting tree -L 4 to use the wildcard read. It currently costs one round-trip per attribute plus one for the attribute list; the wildcard read would collapse that to one per cluster. Worth doing, but it changes tree's per-attribute timeout and error-reporting behavior and roughly doubles the diff. Separate follow-up issue.
  • Endpoint wildcarding (reading a cluster across every endpoint that hosts it).
  • Cluster wildcarding (reading every cluster on an endpoint) — that is what tree -L 4 is for.
  • Daemon IPC protocol versioning. The skew hazard above is real but general; fixing it is its own change.
  • Implementing real YAML output. The stub is CLI-wide.
  • Making fabric filtering configurable.
  • Wildcard event reads.

Further Notes

The follow-up issue for tree -L 4 should be filed once this lands, since it depends on the wildcard read existing.

Two design decisions in this spec were revised late, after discovering that the subscribe command had already solved the same problems: the native TLV decoder already exists and is tested, and the subscribe record type already encodes the "native value for JSON, display string for table" split. Reusing both was chosen over inventing a parallel vocabulary for attribute reports. Any implementation that finds itself writing a second TLV-to-native decoder has taken a wrong turn.

Activity

  1. added
    ready-for-agentReady for implementation by an agent
    enhancementImprovement to existing functionality
    cliCobra commands, flags, help, output formatting
    clustersCluster codegen, shorthand, attributes, commands
    daemonSession daemon
    on Aug 28, 2026
  2. self-assigned this
    on Aug 28, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

Labels

cliCobra commands, flags, help, output formattingclustersCluster codegen, shorthand, attributes, commandsdaemonSession daemonenhancementImprovement to existing functionalityready-for-agentReady for implementation by an agent

Projects

No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions

    0