[Alex (Alexkuva)]

What does this PR change?

• YAML output is the document --output json prints: same keys, same order, same values. It printed Go field names (externalcustomerid), every absent field as null, and typed values such as a grant's value as {}.
• YAML input is read as the JSON it stands for. A YAML --file or --payload lost every field whose name has more than one word (externalCustomerId, default_variant) without an error, so the request went out incomplete. A key the request has no field for now stops the command and is named. JSON input is unchanged.
• licenses create has no --version. It was required and never sent: the API numbers the versions itself and refuses one it is sent. On licenses update the flag stays, optional, as a check the API makes.
• Three flags that did nothing are removed: components update --previous-component-id (the API refuses the field on update), instances audit-trails --offset and instances list --include-deleted (the API declares neither).
• An inline instances update keeps the instance's metadata. It sent "metadata": {}, which cleared it. It now reads the instance and sends its metadata back unless --metadata-json gives another; --metadata-json '{}' clears it.
• README: the --output default for each kind of command, the two entitlement update commands described as each behaves, the exit codes of destructive commands, the rules for --file and --payload. The example --event-name instance.updated becomes INSTANCE_UPDATED. Installation and Development are untouched (feat: install scripts, Linux packages, a container image and automated releases #2 rewrites them).

Why?

YAML is the default output of every command that returns one resource, and it could not be read. YAML input lost data silently. Four flags were accepted and had no effect, one update cleared data it was not asked to touch, and the README described defaults and update behaviour the code does not have.

For scripts (nothing is released yet): the keys of YAML output change; licenses create --version and the three removed flags now exit 2; a YAML yes or no is no longer read as a boolean.

One point to decide. JSON input still skips a key it does not know, which is what lets get --output json | update --file - work. YAML input now refuses one, so the same write-back in YAML stops on the first read-only field (createdAt). Refusing catches a snake_case key written by hand, the failure this fixes; skipping would make the two formats agree. Accepting a resource's read-only fields in both formats would give both, and needs a map from each request to its resource.

Testing

• Each fix has a test that fails on main and passes here: 18 tests added, 15 of which fail on main; the other three pin behaviour kept as is.
• go build ./..., go vet ./..., go test -race -shuffle=on ./... and golangci-lint run are clean.
• Each defect was reproduced, and its fix checked, with the built binary against a local stub server. No real API was called.
• feat: install scripts, Linux packages, a container image and automated releases #2 merges cleanly onto this branch. With feat: usage report transaction IDs, usage history and exports #3 there is one conflict, the README's --output sentence, which both rewrite: keep this one and add ndjson.

Checklist

• I have read CONTRIBUTING.md.
• Every commit in this PR includes a valid DCO Signed-off-by line.
• I have the right to submit all material in this PR.
• I have not included secrets or confidential data.
• I have updated tests where appropriate.
• I have updated documentation where appropriate.
• I have preserved required third-party licenses and attributions.

🤖 Generated with Claude Code · ✅ Tested and approved by Alex (@Alexkuva), maintainer