Clarify experimental meaning on ls subcommand

[noahsilas]

Goals

1. Help users understand the meaning of the "Experimental" annotation on the ls subcommand.

Non-goals

Background

Running turbo --help shows this entry in the commands list:

ls            EXPERIMENTAL: List packages in your monorepo

The documentation for that command (https://turborepo.dev/docs/reference/ls) shows an "Experimental" badge only on the --output flag. It has seemingly been there for two years (since #9063).

Proposal

Is this subcommand stable enough to rely on generally? Is the "experimental" aspect here purely related to one of the output formats? Updating the documentation to make this clearer would help me decide when it is appropriate to use this subcommand.

[MILLERMARRU]

Worth flagging directly since I can't fully resolve it either: your finding that the CLI --help text and the docs page disagree looks accurate. What I can confirm is that the current /docs/reference/ls page describes --output as having the format options json and pretty, without the docs page itself carrying an overall "experimental" badge on the command in what's currently published, which lines up with your observation that only --output was ever marked that way, two years ago in #9063.

I don't have a way to confirm from outside whether that reflects an intentional, completed stabilization that the turbo --help banner text just never got updated to match, or whether the command has quietly stayed experimental in practice and the docs badge was just dropped without the underlying status changing. Given the two-year gap and that the docs no longer show the badge, my best guess is the help text is stale rather than the stabilization being incomplete, but I'd treat that as a guess, not a confirmed answer.

Given that ambiguity, I'd frame the ask to the team as two questions rather than one: is ls (the command, not just --output) considered stable enough to script against today, and separately, should the CLI's own --help output be updated to stop showing EXPERIMENTAL if the answer is yes. That's a cleaner ask than "clarify the docs," since it pins down exactly what's inconsistent (help text vs. docs page) rather than leaving it open to interpretation.