Standardize CLI flag descriptions across commands

[Copilot]

Multiple CLI flags had inconsistent descriptions across commands, causing user confusion about flag purposes and behavior.

Changes

Standardized Flags

--repo (7 commands)

• add: "Source repository containing workflows (owner/repo format)"
• logs/run/enable/disable: "Target repository (owner/repo format)"
• pr transfer, trial: Unchanged (already appropriate)

--json (4 commands)

• All commands: "Output results in JSON format"

--force (3 contexts)

• new/add: "Overwrite existing files without confirmation"
• compile: "Force overwrite of existing dependency files (e.g., dependabot.yml)"
• update: "Force update even if no changes are detected"

--dir (2 contexts)

• compile/update: "Workflow directory (default: .github/workflows)"
• add: "Subdirectory under .github/workflows/ (e.g., 'shared' creates .github/workflows/shared/)"

Contextually Different (Preserved)

--engine

• compile/add/update/run/trial: "Override AI engine (claude, codex, copilot, custom)"
• logs: "Filter logs by engine type (claude, codex, copilot)"

--timeout

• logs: "Download timeout in seconds (0 = no timeout)"
• trial: "Execution timeout in minutes (default: 30)"

Minor Fixes

• --auto-merge-prs, --stop-after, --no-stop-after: Removed redundant "added"/"updated" qualifiers

Files Modified

• cmd/gh-aw/main.go
• pkg/cli/{add_command,audit,logs,trial_command,update_command,status}.go
• pkg/cli/logs_test.go

Original prompt

---

This section details on the original issue you should resolve

<issue_title>[cli-consistency] Inconsistent flag descriptions across commands</issue_title>
<issue_description>## Issue Description

Type: Flag Description Inconsistency
Priority: Medium

Multiple CLI flags have inconsistent descriptions when used across different commands, which can confuse users about the flag's actual purpose.

Affected Flags

1. --repo flag (7 different descriptions)

Used in 7 commands with varying descriptions:

• "Install and use workflows from specified repository (org/repo)"
• "Repository to download logs from (owner/repo format)"
• "Repository to run the workflow in (owner/repo format)"
• "Repository to enable workflows in (owner/repo format)"
• "Target repository (owner/repo format). Defaults to current repository"
• "Repository to disable workflows in (owner/repo format)"
• "Alias for --host-repo"

Suggested Fix: Standardize to context-appropriate but consistent wording:

• For add/update commands: "Source repository containing workflows (owner/repo format)"
• For run/enable/disable/logs commands: "Target repository (owner/repo format)"
• For pr transfer: "Target repository (owner/repo format). Defaults to current repository"
• For trial command: Keep "Alias for --host-repo" since it's a specific alias

2. --json flag (4 different descriptions)

• "Output audit report as JSON instead of formatted console tables"
• "Output status in JSON format"
• "Output validation results as JSON"
• "Output logs data as JSON instead of formatted console tables"

Suggested Fix: Standardize to: "Output results in JSON format"

3. --engine flag (2 different descriptions)

• "Filter logs by agentic engine type (claude, codex, copilot)"
• "Override AI engine (claude, codex, copilot, custom)"

Suggested Fix: Keep both as they serve different purposes:

• For compile/add/update/run/trial: "Override AI engine (claude, codex, copilot, custom)"
• For logs command only: "Filter logs by engine type (claude, codex, copilot)"

4. --force flag (3 different descriptions)

• "Overwrite existing workflow files"
• "Force overwrite of existing files (e.g., dependabot.yml)"
• "Force update even if no changes detected"

Suggested Fix: Standardize to context-appropriate wording:

• For add/new commands: "Overwrite existing files without confirmation"
• For compile command (dependabot): "Force overwrite of existing dependency files (e.g., dependabot.yml)"
• For update command: "Force update even if no changes are detected"

5. --timeout flag (2 different descriptions)

• "Maximum time in seconds to spend downloading logs (0 = no timeout)"
• "Timeout in minutes for workflow execution (default: 30)"

Suggested Fix: Keep different as they have different units and purposes, but clarify:

• For logs command: "Download timeout in seconds (0 = no timeout)"
• For trial command: "Execution timeout in minutes (default: 30)"

6. --dir flag (2 different descriptions)

• "Relative directory containing workflows (default: .github/workflows)"
• "Specify subdirectory under .github/workflows/ (e.g., 'shared' for .github/workflows/shared/)"

Suggested Fix: Standardize based on context:

• For compile command: "Workflow directory (default: .github/workflows)"
• For add command: "Subdirectory under .github/workflows/ (e.g., 'shared' creates .github/workflows/shared/)"

7. Minor Inconsistencies

The following flags have minor inconsistencies that should also be addressed:

• --auto-merge-prs: Difference between "workflow execution" vs "trial execution"
• --logical-repo: Different phrasing for the same concept
• --no-stop-after: "added" vs "updated" workflow
• --stop-after: "added" vs "updated" workflow
• --use-local-secrets: "workflow" vs "trial" execution

Impact

Users may be confused about:

1. What a flag does when seeing different descriptions in help text
2. Whether the same flag behaves differently across commands
3. The correct format for flag values

Files Affected

• cmd/gh-aw/main.go
• pkg/cli/add_command.go
• pkg/cli/audit.go
• pkg/cli/logs.go
• pkg/cli/trial_command.go
• pkg/cli/update_command.go
• And others

Recommendation

Review and standardize flag descriptions to ensure:

1. Flags that do the same thing use identical descriptions
2. Flags that behave differently in different contexts have clear, contextually appropriate descriptions
3. Format hints and defaults are consistently mentioned

AI generated by CLI Consistency Checker</issue_description>

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

• Fixes [cli-consistency] Inconsistent flag descriptions across commands #4385

---

💬 We'd love your input! Share your thoughts on Copilot coding agent in our 2 minute survey.

[Copilot]

Pull Request Overview

This PR standardizes CLI flag descriptions across multiple commands to improve user clarity and consistency. The changes address inconsistent wording for the same flags used in different contexts, making it easier for users to understand flag purposes and expected values.

• Standardizes --repo, --json, --force, --dir, --engine, and --timeout flag descriptions
• Maintains contextual differences where appropriate (e.g., different timeout units for different commands)
• Removes redundant qualifiers like "added" and "updated" from workflow-related flags

Reviewed Changes

Copilot reviewed 8 out of 8 changed files in this pull request and generated no comments.

Show a summary per file

File	Description
cmd/gh-aw/main.go	Updates flag descriptions for --force, --dir, --json, --repo in compile, new, enable, disable, and run commands
pkg/cli/add_command.go	Standardizes --repo, --force, --dir, --no-stop-after, and --stop-after descriptions
pkg/cli/audit.go	Updates --json flag description to standard format
pkg/cli/logs.go	Standardizes --engine, --repo, --json, and --timeout descriptions
pkg/cli/logs_test.go	Updates test assertion to match new --engine flag description
pkg/cli/status.go	Updates --json flag description to standard format
pkg/cli/trial_command.go	Standardizes --timeout and --auto-merge-prs descriptions
pkg/cli/update_command.go	Updates --force, --dir, --no-stop-after, and --stop-after descriptions

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[github-actions]

✅ Agentic Changeset Generator completed successfully.