Skip to content

Add bounded listings and discoverable named configurations #701

Description

@rhoopr

Problem

kei has bounded diagnostic detail, but agents cannot control or continue most listings.

status, verify, and reconcile cap detail at 200 rows, and sync report JSON records omitted failure counts. However:

  • capped output has no cursor or supported continuation path
  • list albums and list libraries have no explicit bound or filter
  • manifest exports the complete catalog
  • agents must remember arbitrary --config paths because configs are not named or discoverable

#589 tracks a future local catalog query command. This issue should define shared bounds and configuration discovery that the query command can reuse rather than duplicating its query scope.

Proposed change

Add consistent controls for bounded reads:

  • --limit on list and detail-returning commands
  • deterministic ordering
  • a cursor or other explicit continuation mechanism where a complete traversal is useful
  • structured shown, truncated, continuation, and narrowing hints
  • filters only where they map to facts kei already owns

Build lightweight named configuration discovery on the existing TOML model:

  • list and show named configurations
  • select one with a stable root option such as --profile <name>
  • define precedence between explicit per-run arguments, environment, selected profile, and defaults
  • surface available names through agent-context

This does not need a second configuration format. A profile can remain a named pointer to a normal kei TOML file.

Acceptance criteria

  • List-style commands have a documented default bound and --limit.
  • Capped structured output tells the caller how to continue or narrow the next request.
  • Ordering and continuation are deterministic across repeated reads of unchanged state.
  • Explicit full exports remain possible for manifest.
  • Named configurations can be listed, inspected, and selected without remembering filesystem paths.
  • Existing --config behavior remains supported, with documented precedence.
  • Add first local catalog query command #589 can reuse the same pagination, filtering, and output conventions.
  • Behavioral tests cover bounds, continuation, profile precedence, missing profiles, and unchanged human defaults.

Relevant owners: src/cli.rs, src/commands/, src/config.rs, state queries, and CLI/behavioral tests.

Reference: 10 Principles for Agent-Native CLIs

Metadata

Metadata

Assignees

No one assigned

    Labels

    P4 laterValid work that is deliberately not near-termenhancementinfraRuntime, services, reporting, metrics, distribution, and internal structure

    Projects

    No projects

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions