refactor(cli): use --output-file in ado template

[AlessandroPomponio]

@AlessandroPomponio I noticed that ado template now is different. It has --output instead of --output-file, and autogenerated file names. It's probably worth changing it so everything is the same unless strong reason why it should be different?

Originally posted by @michael-johnston in #865 (comment)

---

Technical Analysis

Current Behavior

The ado template command uses --output (short: -o) with the following behavior:

• If not specified: Auto-generates a filename like {resource_type}_template_{random}.yaml
• If a directory is provided: Creates the auto-generated filename inside that directory
• If a file path is provided: Uses that file path

Code location: orchestrator/cli/commands/template.py:111-121

output: Annotated[
    pathlib.Path | None,
    typer.Option(
        "--output",
        "-o",
        help="Path in which to output the template. "
        "If unset, a name will be autogenerated.",
        show_default=False,
        writable=True,
    ),
] = None

Expected Behavior (Consistent with Other Commands)

All other ado CLI commands that write output use --output-file (with no short form) with the following behavior:

• If not specified: Write to stdout
• If specified: Write to the specified file path

Note: The -o short form is reserved for --output which specifies output format (json, yaml, table, etc.), not file paths.

Examples of consistent commands:

• ado get - uses --output-file (no short form)
  • Also has --output/-o for format selection
• ado show entities - uses --output-file (no short form)
• ado show results - uses --output-file (no short form)
• ado show requests - uses --output-file (no short form)
• ado show summary - uses --output-file (no short form)

Proposed Changes

1. Rename flag: Change --output/-o to --output-file (with no short form)
2. Change default behavior: Output to stdout when --output-file is not specified
3. Remove auto-generation: Remove the auto-generated filename logic (lines 166-172 in template.py)
4. Update help text: Change help text to match other commands: "Write output to the specified file instead of stdout."

Implementation Details

The current code (lines 166-172):

autogenerated_name = pathlib.Path(
    f"{resource_type.value}_template_{get_random_name_extension()}.yaml"
)
if output is None:
    output = autogenerated_name
elif output.is_dir():
    output /= autogenerated_name

Should be replaced with logic that writes to stdout when output_file is None.

Benefits

• Consistency: Aligns with all other ado CLI commands
• Unix philosophy: Follows standard CLI patterns where output goes to stdout by default
• Composability: Allows piping output to other commands (e.g., ado template space | grep experiment)
• Predictability: Users familiar with other ado commands will know what to expect
• No naming conflicts: Frees up -o for potential future use with output format selection