Does Terramate intend to add native pagination options like `--limit` and `--offset` to the `terramate list` command?

Answer

As of the newest publicly available Terramate release (up to mid‑2024), the terramate list command does not include native pagination flags such as --limit or --offset. No official roadmap entry or open pull request implements these options, and the documentation makes no mention of a forthcoming pagination feature.

Why Pagination Matters

• Large projects can contain thousands of stacks; pulling the full list into a script can be slow and memory‑heavy.
• Without a stable ordering, manual pagination (e.g., piping to head or jq) can produce duplicate or missing entries when the underlying filesystem order changes.
• Depth‑first traversal is used internally, and the order differs between case‑sensitive and case‑insensitive filesystems, so the same project may list stacks in a different sequence on Windows vs. Linux.

Risks to Automation Scripts

• Scripts that rely on external tools for pagination may inadvertently skip or double‑count stacks if the list order shifts between runs.
• When operating across multiple operating systems, inconsistent traversal can break idempotent workflows that assume deterministic stack ordering.
• In high‑throughput environments, the overhead of processing the entire list each time can become a bottleneck.

What Would Native Pagination Need?

If Terramate were to add --limit and --offset in the future, it would almost certainly need to expose a stable sort key (e.g., stack path or name) to guarantee repeatable results. Documentation would have to describe the ordering semantics to avoid ambiguity for users.

How to Verify the Current State

1. Open a terminal in a project directory and run:

   terramate list --help
   

   Check the output for any --limit or --offset flags. If they are absent, the CLI does not support pagination.

2. Inspect the official documentation (e.g., docs.terramate.io) or the terramate GitHub repository’s release notes. Search for tags such as "pagination" or "list" to see if a new feature has been announced.

3. If you need pagination now, consider one of the following workarounds:

   • terramate list | head -n 100 – simple line‑based slicing.
   • terramate list | jq '.[] | select(.path | startswith("/desired/prefix"))' – JSON filtering for more complex criteria.

   These external tools add processing overhead but are the current practical solution.

Next Steps for Users

• If pagination is critical for your workflow, file a feature request on the Terramate GitHub issues page.
• Keep your CLI and documentation up to date; new releases may introduce pagination without prior announcement.
• When scripting, always capture the full list once and then apply pagination logic in your own code to avoid repeated full traversals.

Assumptions & Uncertainty

These conclusions are based on the state of Terramate up to June 2024. Product plans may evolve, and a future release could add pagination without a prior public announcement. Therefore, the verification steps above should be repeated whenever you upgrade your CLI or consult the latest documentation.