Skip to content

Add concrete examples to all --help screens#1549

Merged
garrytrinder merged 9 commits intomainfrom
copilot/add-examples-to-help-screens
Feb 26, 2026
Merged

Add concrete examples to all --help screens#1549
garrytrinder merged 9 commits intomainfrom
copilot/add-examples-to-help-screens

Conversation

Copy link
Contributor

Copilot AI commented Feb 25, 2026

  • Create DevProxy/Commands/HelpExamples.cs - helper class with custom help action that appends examples after default help output
  • Add examples to DevProxyCommand.cs (root command) and install the custom help action
  • Add examples to CertCommand.cs
  • Add examples to ConfigCommand.cs
  • Add examples to JwtCommand.cs (jwt create subcommand)
  • Add examples to StdioCommand.cs
  • Add examples to OutdatedCommand.cs
  • Add examples to MsGraphDbCommand.cs
  • Build and verify help output for all commands
  • Fix description alignment to column 52 across all examples
Original prompt

This section details on the original issue you should resolve

<issue_title>Add concrete examples to all --help screens</issue_title>
<issue_description>Parent: #1534

Problem

No --help screen in Dev Proxy includes concrete usage examples. Every command shows only option descriptions. For example, jwt create --help shows:

--claims    Claims to add to the token. Specify once for each claim in the format "name:value".

But an agent doesn't know whether to write:

  • --claims "name:value"
  • --claims name:value
  • --claims name:value --claims other:value
  • --claims name:value other:value

An example removes all ambiguity instantly.

Rationale

AI agents pattern-match from examples more reliably than from abstract flag descriptions. Research on LLM tool use consistently shows that concrete invocation examples are the highest-signal input for correct command composition. This is the single highest-ROI change for agent discoverability.

Proposed solution

Add 3-5 examples to each command's --help output using System.CommandLine's AddHelpText or equivalent mechanism.

Root command

Examples:
  devproxy                                            Start with default config
  devproxy -c myconfig.json                           Start with custom config
  devproxy -u "https://api.example.com/*"             Watch specific URLs
  devproxy --port 9000 --record                       Custom port, record requests
  devproxy --output json                              JSON output for scripts/agents

cert

Examples:
  devproxy cert ensure                                Install and trust certificate
  devproxy cert remove --force                        Remove certificate (no prompt)

config

Examples:
  devproxy config new                                 Create default devproxyrc.json
  devproxy config new myconfig.json                   Create named config file
  devproxy config get <config-id>                     Download config from gallery
  devproxy config open                                Open config in default editor

jwt create

Examples:
  devproxy jwt create                                 Create token with defaults
  devproxy jwt create -n "John Doe" -r admin -r user  Token with name and roles
  devproxy jwt create -s "read" -s "write" -a myapp   Token with scopes/audience
  devproxy jwt create --claims "dept:eng" --claims "level:5"  Custom claims

stdio

Examples:
  devproxy stdio npx -y @devproxy/mcp                 Proxy MCP server stdio
  devproxy stdio node server.js                        Proxy Node.js app stdio
  devproxy stdio -c myconfig.json node app.js          With custom config

outdated

Examples:
  devproxy outdated                                   Check for updates (human output)
  devproxy outdated --short                           Version number only

Affected code

  • All files in DevProxy/Commands/ — add help text examples to each command
    </issue_description>

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


💡 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.

Co-authored-by: waldekmastykarz <11164679+waldekmastykarz@users.noreply.github.com>
Copilot AI changed the title [WIP] Add concrete examples to all --help screens Add concrete examples to all --help screens Feb 25, 2026
Co-authored-by: waldekmastykarz <11164679+waldekmastykarz@users.noreply.github.com>
Copy link
Contributor Author

Copilot AI commented Feb 25, 2026

Just as a heads up, I was blocked by some firewall rules while working on your feedback. Expand below for details.

Warning

Firewall rules blocked me from connecting to one or more addresses (expand for details)

I tried to connect to the following addresses, but was blocked by firewall rules:

  • aka.ms
    • Triggering command: /home/REDACTED/work/dev-proxy/dev-proxy/DevProxy/bin/Debug/net10.0/devproxy /home/REDACTED/work/dev-proxy/dev-proxy/DevProxy/bin/Debug/net10.0/devproxy --help (dns block)
    • Triggering command: /usr/bin/dotnet dotnet DevProxy/bin/Debug/net10.0/devproxy.dll --help (dns block)

If you need me to access, download, or install something from one of these locations, you can either:

@waldekmastykarz waldekmastykarz marked this pull request as ready for review February 25, 2026 14:08
@waldekmastykarz waldekmastykarz requested a review from a team as a code owner February 25, 2026 14:08
Copilot AI review requested due to automatic review settings February 25, 2026 14:08
Copy link
Contributor

Copilot AI left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Pull request overview

This PR adds concrete usage examples to help screens across Dev Proxy commands to improve discoverability for AI agents and human users. The implementation introduces a new HelpExamples helper class that extends System.CommandLine's help system by appending examples after the default help output.

Changes:

  • Created HelpExamples.cs infrastructure using ConditionalWeakTable and custom HelpOption.Action
  • Added 3-5 examples to each command's help screen (root, cert, config, jwt create, stdio, outdated, msgraphdb)
  • Examples show concrete command invocations with aligned descriptions at column 52

Reviewed changes

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

Show a summary per file
File Description
DevProxy/Commands/HelpExamples.cs New helper class implementing custom help action to append examples after default help output using ConditionalWeakTable pattern
DevProxy/Commands/DevProxyCommand.cs Added root command examples and installed HelpExamples infrastructure on RootCommand
DevProxy/Commands/CertCommand.cs Added examples for cert ensure and cert remove subcommands
DevProxy/Commands/ConfigCommand.cs Added examples for config new, get, and open subcommands
DevProxy/Commands/JwtCommand.cs Added examples for jwt create with various option combinations
DevProxy/Commands/StdioCommand.cs Added examples for stdio command with different executable types
DevProxy/Commands/OutdatedCommand.cs Added examples for outdated command with and without --short option
DevProxy/Commands/MsGraphDbCommand.cs Added example for msgraphdb command

Copy link
Contributor

@garrytrinder garrytrinder left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Tested: builds clean, examples present in all commands (root, cert, config, jwt create, stdio, outdated, msgraphdb). Merge conflict with main resolved (ExitCodeHelpAction + HelpExamples coexist). LGTM.

@garrytrinder garrytrinder enabled auto-merge (squash) February 26, 2026 11:55
@garrytrinder garrytrinder merged commit 389af3c into main Feb 26, 2026
4 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Add concrete examples to all --help screens

4 participants