Skip to content

docs: fix and fill gaps in the kubectl-ate CLI reference - #814

Open
botengyao wants to merge 1 commit into
agent-substrate:mainfrom
botengyao:cli-docs
Open

docs: fix and fill gaps in the kubectl-ate CLI reference#814
botengyao wants to merge 1 commit into
agent-substrate:mainfrom
botengyao:cli-docs

Conversation

@botengyao

Copy link
Copy Markdown
Contributor

Follow-up to #561, doc-only — happy to open an issue if preferred.

#561 fixed the kubectl ate logs examples that omitted the required -a/--atespace. Two more documented commands have the same problem:

  • cmd/kubectl-ate/README.md, the --trace example: kubectl ate get actor my-counter-1 --trace
  • demos/parking/README.md: kubectl ate get actors

Both fail with --atespace is required when getting actors / specify --atespace <name> to list one atespace, or -A/--all-atespaces for all.

While in the CLI README, three gaps that a first-time reader hits:

  • The get actor STATUS column lists 4 states; the API defines 8. Added STATUS_PAUSING, STATUS_PAUSED, STATUS_CRASHED, STATUS_DELETING (all reachable — the control plane sets each of them today).
  • pause actor was undocumented. Added it alongside suspend, with a note on the distinction that matters in practice: suspend uploads the snapshot so the actor can resume anywhere, pause keeps it on the node VM and biases the next resume back to that node.
  • top was undocumented, even though the get workers section already pointed at "the same flags as top workers". Added a section with the flags and the output columns, plus a note that it needs metrics-server.

Plus a typo in hack/update/proto-fmt.sh ("wince" → "since").

  • Tests pass
  • Appropriate changes to documentation are included in the PR

Two more documented commands fail the way agent-substrate#561 fixed: the `--trace`
example in the CLI README and `get actors` in the parking demo both omit
`-a/--atespace`, which those commands require.

Also in the CLI README:

- The actor STATUS column listed 4 of the 8 states the API defines,
  missing PAUSING, PAUSED, CRASHED, and DELETING.
- `pause actor` was undocumented, even though pause vs suspend (node-local
  vs uploaded snapshot) is the distinction users most need spelled out.
- `top` was undocumented, while the `get workers` section already referred
  to "the same flags as `top workers`" — a dangling reference.

Plus a typo in hack/update/proto-fmt.sh.
@botengyao
botengyao marked this pull request as ready for review August 8, 2026 20:23
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant