Standardize trial command help text with Examples section

[Copilot]

The trial command help text embedded 14 examples in the Long description rather than using the standard "Examples:" section format used by all other CLI commands.

Changes

• pkg/cli/trial_command.go: Refactored help text to move examples to dedicated "Examples:" section
  • Extracted 14 examples from prose into standard format
  • Reorganized into: basic usage (4), repository modes (3), advanced options (7)
  • Condensed Long description to focus on repository modes explanation

Before

Long: `Trial one or more agentic workflows...

Single workflow:
  gh aw trial githubnext/agentics/weekly-research
  Outputs: stdout + local trials/...

Multiple workflows (for comparison):
  gh aw trial githubnext/agentics/daily-plan...

After

Long: `Trial one or more agentic workflows...

Repository modes:
- Default mode (no flags): Creates a temporary...
- --logical-repo REPO: Simulates execution...

Examples:
  gh aw trial githubnext/agentics/weekly-research          # Trial single workflow
  gh aw trial githubnext/agentics/daily-plan githubnext/agentics/weekly-research  # Trial multiple workflows

All 24 CLI commands now use consistent Examples formatting.

Original prompt

---

This section details on the original issue you should resolve

<issue_title>[Code Quality] Add usage examples to CLI commands missing help text examples</issue_title>
<issue_description>## Description

Currently 14 of 23 CLI command files (61%) include example usage in their help text. The remaining 9 commands lack examples, making them harder to discover and use correctly. Adding examples to all commands improves usability and reduces the learning curve.

Suggested Changes

Add example usage to these commands:

1. compile_command.go - Most frequently used, needs examples for:

   • Single workflow compilation
   • Batch compilation with --all
   • Compilation with validation flags

2. trial_command.go - Complex command needing examples for:

   • Basic trial run
   • Trial with environment variables
   • Trial with specific repository context

3. actions_build_command.go - Developer tool needing examples

4. codemod_slash_command.go - Needs codemod examples

5. generate_action_metadata_command.go - Needs generation examples

6. list_command.go - Needs listing examples

7. Other commands - Review and add as needed

Example format to follow:

Examples:
  gh aw compile workflow-name          # Compile single workflow
  gh aw compile --all                   # Compile all workflows
  gh aw compile workflow -v             # Verbose output

Files Affected

Commands missing examples:

• pkg/cli/compile_command.go (HIGH PRIORITY - most used)
• pkg/cli/trial_command.go (HIGH PRIORITY - complex usage)
• pkg/cli/actions_build_command.go
• pkg/cli/codemod_slash_command.go
• pkg/cli/generate_action_metadata_command.go
• pkg/cli/list_command.go
• Others TBD after review

Success Criteria

• All 23 CLI commands have at least 3 usage examples
• Examples cover common use cases (basic, intermediate, advanced)
• Examples follow consistent format matching existing commands
• Examples tested and verified working
• gh aw --help output improved for all commands
• Example coverage increased from 61% to 100%

Source

Extracted from analysis of current CLI codebase showing 14/23 commands with examples.

Related to User Experience Analysis discussion github/gh-aw#14234 recommendation: "Add more practical examples to CLI commands"

Priority

Medium - Improves discoverability and usability but existing commands work. Focus on high-usage commands first (compile, trial).

AI generated by Discussion Task Miner - Code Quality Improvement Agent

• expires on Feb 8, 2026, 1:29 AM UTC

Comments on the Issue (you are @copilot in this section)

• Fixes [Code Quality] Add usage examples to CLI commands missing help text examples #14251

---

💡 You can make Copilot smarter by setting up custom instructions, customizing its development environment and configuring Model Context Protocol (MCP) servers. Learn more Copilot coding agent tips in the docs.