Standardize MCP command arguments to workflow-id-or-file

[Copilot]

The MCP commands used inconsistent workflow-file terminology while other commands (logs, enable, disable, run) used workflow-id. This created confusion about expected input format.

Changes

• Command signatures: Updated all MCP subcommands from [workflow-file] to [workflow-id-or-file]

  • mcp add [workflow-id-or-file] [mcp-server-name]
  • mcp inspect [workflow-id-or-file]
  • mcp list [workflow-id-or-file]
  • mcp list-tools <mcp_server> [workflow-id-or-file]

• Help text: Added clarifying documentation to each command explaining accepted formats:

  • Workflow ID: basename without extension (weekly-research)
  • File path: relative or absolute (weekly-research.md, .github/workflows/weekly-research.md)

• Tests: Updated test assertions to match new command signatures

Implementation

All commands already use ResolveWorkflowPath() which accepts both formats. This change only updates documentation and command signatures for consistency.

- Use:   "add [workflow-file] [mcp-server-name]",
+ Use:   "add [workflow-id-or-file] [mcp-server-name]",

Original prompt

---

This section details on the original issue you should resolve

<issue_title>[cli-consistency] Inconsistent terminology: workflow-id vs workflow-file in command arguments</issue_title>
<issue_description>## Issue Description

Type: Terminology inconsistency
Priority: Low
Area: CLI command argument naming

Current Behavior

Commands use inconsistent terminology for workflow arguments:

Commands using workflow-id:

• gh aw enable [workflow-id]...
• gh aw disable [workflow-id]...
• gh aw run (workflow-id)...
• gh aw logs [workflow-id]
• gh aw update [workflow-id]...

Commands using workflow-file:

• gh aw mcp add [workflow-file] [mcp-server-name]
• gh aw mcp inspect [workflow-file]
• gh aw mcp list [workflow-file]
• gh aw mcp list-tools (mcp_server) [workflow-file]

Analysis

The inconsistency creates confusion about what users should provide:

1. workflow-id: Suggests the basename without .md extension (e.g., ci-doctor)
2. workflow-file: Suggests a file path (e.g., ci-doctor.md or .github/workflows/ci-doctor.md)

According to the root command's Long description:

Note: A workflow-id is the basename of the markdown file without the .md extension.
For example, for 'weekly-research.md', the workflow-id is 'weekly-research'.

Recommendation

Option 1 (Preferred): Standardize on workflow-id everywhere

• Use [workflow-id] for all commands that accept workflow identifiers
• Update MCP commands to use workflow-id instead of workflow-file
• This aligns with the documentation and is more concise

Option 2: Clarify when to use each term

• Use workflow-file when the command accepts file paths
• Use workflow-id when the command only accepts basenames
• Add clear documentation explaining the distinction

Suggested Changes

If choosing Option 1, update these command definitions in pkg/cli/mcp*.go:

// Before:
Use: "add [workflow-file] [mcp-server-name]"

// After:
Use: "add [workflow-id] [mcp-server-name]"

And similarly for inspect, list, and list-tools commands.

Impact

• Low user impact: Commands currently work with both formats in practice
• Documentation clarity: Would improve consistency in help text and documentation
• Learning curve: Makes it easier for users to understand the expected input format

Additional Context

The term "workflow-id" is well-established in the CLI:

• Documented in root command help
• Used by most major commands
• Matches the conceptual model (identifier vs file path)

AI generated by CLI Consistency Checker</issue_description>

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

@pelikhan Use workflow-id-or-file everywhere and make sure the commands resolve the workflow from the id/file using the same helper.

• Fixes [cli-consistency] Inconsistent terminology: workflow-id vs workflow-file in command arguments #3955

---

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

[Copilot]

Pull Request Overview

This PR standardizes the terminology used in MCP command arguments from workflow-file to workflow-id-or-file for consistency with other commands in the CLI (logs, enable, disable, run, update). The change improves documentation clarity by explicitly stating that both formats are accepted (workflow ID as basename without extension, or file path).

Key changes:

• Updated command signatures for all MCP subcommands to use [workflow-id-or-file] instead of [workflow-file]
• Added clarifying help text explaining the accepted input formats
• Updated test assertions to match new command signatures

Reviewed Changes

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

Show a summary per file

File	Description
pkg/cli/mcp_add.go	Updated command signature to add [workflow-id-or-file] [mcp-server-name] and added help text explaining accepted formats; updated error messages
pkg/cli/mcp_inspect.go	Updated command signature to inspect [workflow-id-or-file] and added help text explaining accepted formats
pkg/cli/mcp_list.go	Updated command signature to list [workflow-id-or-file] and added help text explaining accepted formats; updated Long description references
pkg/cli/mcp_list_tools.go	Updated command signature to list-tools <mcp_server> [workflow-id-or-file] and added help text explaining accepted formats
pkg/cli/mcp_list_test.go	Updated test assertion to expect new command signature list [workflow-id-or-file]
pkg/cli/mcp_list_tools_test.go	Updated test assertion to expect new command signature list-tools <mcp_server> [workflow-id-or-file]

---

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

[github-actions]

Agentic Changeset Generator triggered by this pull request.