Skip to content

feat: kosli list environments: add pagination and filtering flags #934

@dangrondahl

Description

@dangrondahl

Problem

kosli list environments currently calls GET /api/v2/environments/{org} with no query parameters and renders the full, unpaginated array. This doesn't scale for orgs with many environments and ignores the pagination/filtering parameters the API now exposes.

API parameters now available

From https://app.kosli.com/api/v2/openapi.jsonGET /environments/{org}:

Parameter Type Notes
page int (≥1) Page number
per_page int (1–50) Page size
sort enum EnvironmentSortField, default name
sort_direction enum asc / desc, default asc
space_id []string Filter by space; repeatable (OR)
name string Case-insensitive substring match
type []enum Filter by env type (K8S, ECS, ...); repeatable
tag []string Filter by key or key:value; repeatable

Proposed CLI changes

Add flags to kosli list environments mirroring the API:

  • --page (int, default 1)
  • --page-size (int, default e.g. 25; max 50)
  • --sort (string)
  • --sort-direction (string, asc|desc)
  • --space-id (stringSlice, repeatable)
  • --name (string)
  • --type (stringSlice, repeatable)
  • --tag (stringSlice, repeatable)

Pass these through as query parameters on the GET request. Default behaviour becomes paginated.

Breaking change consideration

Today the command returns all environments in one call. Introducing default pagination changes behaviour for users who rely on getting the full list (e.g. piping JSON to jq). Options:

  1. Ship as breaking change under CLI V3 and document migration: use --page to iterate, or a future --all flag.
  2. Add --all flag that auto-paginates and concatenates, for parity with current behaviour.

Definition of Done

  • Flags added to cmd/kosli/listEnvironments.go and wired into the request URL
  • Table and JSON output handle paginated response shape (EnvironmentListResponse) as well as legacy array shape, or commit fully to paginated shape under V3
  • Integration tests cover: default pagination, --page/--page-size, each filter flag, sort
  • kosli list environments --help documents new flags
  • Migration note in V3 changelog / MIGRATING-v3.md

References

  • Current command: cmd/kosli/listEnvironments.go

Metadata

Metadata

Assignees

No one assigned

    Labels

    breakingIssues or PRs that is deemed to introduce breaking changesenhancementNew feature or request

    Type

    No type
    No fields configured for issues without a type.

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions