cli/configure-machines: fix broken add-resource example, model triplets, and CLI ref link#5022
Merged
shannonbradshaw merged 1 commit intoviamrobotics:mainfrom Apr 26, 2026
Conversation
✅ Deploy Preview for viam-docs ready!
To edit notification comments on pull requests, go to your Netlify project configuration. |
viambot
added
the
safe to build
shannonbradshaw
force-pushed
the
configure-machines-correctness
branch
from
7463762 to
9a7e375
Compare
Verified every CLI invocation against the v0.123.0 binary's --help and
the rdk source at upstream/main (bb5e7153). Findings:
Breaking — examples that error out as documented
- add-resource example was missing --resource-subtype (or --api). The
action returns "cannot add a resource of unknown subtype" without one
of these flags (rdk/cli/client.go:1386). Added the flag, plus a second
example for module-provided resources, plus a note about --api for
custom subtypes.
- Four of the six model triplets in the "Common model triplets" table
do not exist in the registry (verified via Typesense search):
viam:camera:webcam → built-in is `webcam` (rdk:builtin:webcam)
viam:motor:gpio → built-in is `gpio`
viam:arm:fake → built-in is `fake`
viam:motor:fake → built-in is `fake`
Replaced the table with correct names and added a Subtype column so
the example pairs `--model-name` with `--resource-subtype` correctly.
Kept the two real module triplets (viam:raspberry-pi:rpi5,
viam:ultrasonic:sensor).
- Reframed the "format" sentence: built-ins use a single name, registry
modules use the three-part triplet (cite: rdk/resource/model.go:16-22).
The original "namespace:module-name:model-name" framing was wrong for
built-ins.
Broken link
- "CLI reference" link pointed to /cli/ (the section landing page,
redirects to /cli/overview/) instead of /cli/reference/. Updated to
/cli/reference/#machines-aliases-robots-robot-machine, anchor verified
in the built HTML.
Coverage gap
- Page introduces multi-part machines in §1 but never showed how to
create or delete a part. Added a short "Add or delete a part" section
using the verified machines part create/delete commands, linked to
/hardware/multi-machine/.
No-change findings (verified, page is correct):
- machines list output format ("(id: X) (main part id: Y)") matches
rdk/cli/client.go:747.
- machines create output ("created new machine with id <id>") matches
rdk/cli/client.go:875.
- "Connected machines pick up configuration changes automatically"
matches the 10s default config refresh interval (rdk/config/config.go:696).
- machines update flags (--new-name, --new-location) match the binary.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
shannonbradshaw
force-pushed
the
configure-machines-correctness
branch
from
9a7e375 to
5da26f8
Compare
|
🔎💬 Inkeep AI search and chat service is syncing content for source 'Viam Docs' |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Playbook 1 correctness assessment of
docs/cli/configure-machines.md. Every CLI invocation on the page was verified against the v0.123.0 binary's--helpand the rdk source atupstream/main(bb5e7153). Three breaking issues, one broken link, and one coverage gap fixed.Breaking issues fixed
add-resourceexample would error out as written. The page showed:The action requires
--apior--resource-subtypeand returnscannot add a resource of unknown subtypewithout one (rdk/cli/client.go:1386). Added--resource-subtypeto the example, plus a second example for module-provided resources, plus a note about--apifor custom subtypes.Four of six model triplets in the "Common model triplets" table do not exist in the registry. Verified via Typesense search of the registry index:
viam:camera:webcam— built-in iswebcam(rdk:builtin:webcam)viam:motor:gpio— built-in isgpioviam:arm:fake— built-in isfakeviam:motor:fake— built-in isfakeReplaced the table with correct model names and added a Subtype column so each example pairs
--model-namewith--resource-subtypecorrectly. Kept the two real module triplets (viam:raspberry-pi:rpi5,viam:ultrasonic:sensor).Triplet format description was wrong for built-ins. The page said the format is
namespace:module-name:model-nameand applied that framing to built-ins. Built-ins use a single name (whichviam-serverexpands tordk:builtin:<name>); the three-part triplet is the registry-module form. Fixed (cite:rdk/resource/model.go:16-22).Broken link
/cli/(the section landing page that redirects to/cli/overview/) instead of/cli/reference/. Updated to/cli/reference/#machines-aliases-robots-robot-machine, anchor verified in built HTML.Coverage gap
machines part create/machines part deletecommands, linked to/hardware/multi-machine/.What was verified and is correct (no change)
machines listoutput format(id: X) (main part id: Y)matchesrdk/cli/client.go:747.machines createoutput (created new machine with id <id>) matchesrdk/cli/client.go:875.rdk/config/config.go:696).machines update --machine --new-name --new-locationflags match the v0.123.0 binary.resource update,resource enable,resource disable,machines part fragments add | remove,machines delete,machines part restart— all flags and behaviors match the binary.make build-prod: clean.Test plan
prettier --write: cleanvale docs/cli/configure-machines.md: 0 errors, 0 warningsmarkdownlint-cli2: 0 errorsmake build-prod: clean/cli/reference/#machines-aliases-robots-robot-machine)