feat: agent-native CLI fixes (F1, F7, F8)#190
Merged
AlephNotation merged 5 commits intomainfrom May 8, 2026
Merged
Conversation
Addresses F1 from AGENT_NATIVE_AUDIT.md.
Addresses F8 from AGENT_NATIVE_AUDIT.md. Aligns with the canonical get/list/create/update/delete vocabulary already used by 'repo get' and 'tag get'. The 'info' alias is preserved for backwards compatibility.
Addresses F7 from AGENT_NATIVE_AUDIT.md.
Adds --limit (default 50; 0=unbounded) and --offset to every list-style
command on top of the F1 --json flag layout:
vers status, vers alias (no arg), vers commit list, vers repo list,
vers repo tag list, vers tag list, vers env list
Output shapes:
- JSON, not truncated: bare items array (backwards-compat).
- JSON, truncated: envelope with items, total, limit, offset, truncated,
next_offset, and hint.
- Text/quiet: data on stdout, single-line truncation hint on stderr.
env list special-cases the historical map shape ({KEY: VALUE, ...}) when
not truncated and switches to an ordered envelope ({items: [{key, value}]})
when truncated, since Go map iteration is unstable.
Pagination is currently client-side because the SDK does not yet expose
typed Limit/Offset query params. Inline TODO comments at every call site
mark where to plumb the flags through once the SDK supports them.
a876215 to
858a439
Compare
This was referenced May 8, 2026
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
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.
Three top-priority agent-native-CLI fixes, sourced from Trevin Chow's 10 Principles for Agent-Native CLIs and Cloudflare's Wrangler vocabulary rules. Implemented by three Opus 4.7 subagents in parallel git worktrees, then merged onto this integration branch.
What changed
--format json→--json(canonical Cloudflare/Wrangler vocabulary)19 cobra
--format stringflags now have a sibling--jsonBoolVar. The old--formatflag is preserved as a hidden, deprecated alias for backwards compat.presenters.ParseFormat(quiet, json, format)centralizes precedence:quiet > json > format > default.--formatvalues now error with an enumerated message instead of silently falling through:vers status --format jsonstill works but emitsFlag --format has been deprecated, use --json insteadto stderr (cobraMarkDeprecated).vers info→vers get(verb consistency)repo getandtag getalready use the canonical verb. The top-levelvers infowas the inconsistent outlier. Renamedcmd/info.go→cmd/get.goviagit mv;infois preserved as a cobra alias so existing scripts and integration tests keep working.Pagination + truncation hints on every list command
Added
--limit N(default 50;0= unbounded) and--offset Ntostatus,commit list,repo list,repo tag list,tag list,env list, andalias(no-arg list mode).JSON output shapes:
{ "items": [...], "total": 11, "limit": 3, "offset": 0, "truncated": true, "next_offset": 3, "hint": "showing 3 of 11 — use --limit=N (0 for all) or --offset=3 for the next page" }Text/quiet modes print the truncation hint to stderr so stdout stays clean for piping. New
internal/presenters/pagination.goexposesPageInfo,ApplyPaging,PrintListJSON,PrintTruncationHint. Unit tested with 10 sub-cases.Caveats and follow-ups
vers-sdk-gov0.1.0-alpha.32 does not yet exposeLimit/Offsetquery params (the response shapes include them). Inline// TODO:comments at every call site mark the migration path.env listJSON shape changes only when truncated:{items: [{key, value}, ...]}to preserve order across pages. Bare object map is preserved when not truncated. MCP/agent consumers depending strictly on the map form will see the new shape only on the truncated branch.test/single-action/fail on both this branch andmain(verified via stash). Failures are unrelated to this PR —TestCommitAndListrejectsvers commit <vm-id>because cobra treats the positional VM-ID as an unknown subcommand. Worth a separate finding/fix.Validation
make build— cleango vet ./...— cleango test ./internal/... ./cmd/...— all packages pass (including newformat_test.goandpagination_test.gocases)--json,--limit/--offset, deprecation warnings, and theinfoalias all behave correctly.