Update cli.md

[npentrel]

No description provided.

[netlify]

✅ Deploy Preview for viam-docs ready!

Name	Link
🔨 Latest commit	56740e7
🔍 Latest deploy log	https://app.netlify.com/sites/viam-docs/deploys/67c985c0f915e10008ee504d
😎 Deploy Preview	https://deploy-preview-4031--viam-docs.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.
Lighthouse	1 paths audited Performance: 30 (🔴 down 9 from production) Accessibility: 100 (no change from production) Best Practices: 100 (no change from production) SEO: 92 (no change from production) PWA: 70 (no change from production) View the detailed breakdown and full score reports

---

To edit notification comments on pull requests, go to your Netlify site configuration.

[JessamyT]

Okay so, if you run viam machines part run -h now, you see --organization and not the other aliases. So maybe we should turn these all back to --organization as well as in the table. Or, if you want --org-id, change the table to match since right now the table says --org. I went with --org before because it was the shortest and wasn't certain how things would end up changing anyway.

[npentrel]

Ok, so that is then actually a third inconsistency but that one can be a ticket for the SDK team, the docs can already change. Unless I am wrong that the default is not org-id?

[JessamyT]

Not sure I follow. By default, do you mean the flag help spits out, which is organization for these commands?

[npentrel]

one of the aims of the project to make the cli command flags consistent was to default to one consistent flag where there are multiple different options across commands. I believe the flag name that should be used across all commands is org-id, is that correct? If so the changes I made here should happen. The help text seems to not align with the project goals. Since using org-id works, we can already change to this in the docs and then ask the sdk team to clean up the inconsistency.

[JessamyT]

So if I'm not mistaken, the SDK team chose to keep --organization as the default flag for these commands for the following reasons (which also apply to machine vs machine-id and location vs location-id):

1. If you pass --org-id=MyOrg to one command with no errors, and then you start using a different CLI command that requires --org-id=1234actualID, you get an error and become confused.
2. We could eliminate this confusion by forcing everyone to always pass the org ID instead of the org name, but there is a desire to keep the flexibility of allowing org name for some commands. Yes, this creates a different type of confusion whereby we sometimes have two similar flags such as --machine and --machine-id in the same table for different arguments of one command (e.g. viam machines), and you can pass ID to either of them, but this was deemed by the SDK team to be the lesser of the two possible confusions. This makes sense and I don't feel strongly either way.

What I think we should do is, in this PR, change the current instances of --org (including in the table) to --organization, not --org-id. This will align with the SDK decision and the help message, and avoid confusion #1.

In tables such as the machines command table, I think we should keep it as-is: It indicates that some parameters require a --machine-id flag and others require a more flexible --machine flag. For the organizations command table, it looks like all those parameters require --org-id, so we can keep those the way they are too.

[npentrel]

Let's change to --organization here and I'll bring the rest up for discussion.

[JessamyT]

LGTM

[github-actions]

🔎💬 Inkeep AI search and chat service is syncing content for source 'Viam Docs (https://docs.viam.com)'