Add concrete examples to all --help screens (#1549)

* Initial plan

* Add concrete examples to all --help screens

Co-authored-by: waldekmastykarz <11164679+waldekmastykarz@users.noreply.github.com>

* Fix misaligned descriptions in help examples

Co-authored-by: waldekmastykarz <11164679+waldekmastykarz@users.noreply.github.com>

* Apply suggestion from @waldekmastykarz

* Apply suggestion from @waldekmastykarz

---------

Co-authored-by: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com>
Co-authored-by: waldekmastykarz <11164679+waldekmastykarz@users.noreply.github.com>
Co-authored-by: Waldek Mastykarz <waldek@mastykarz.nl>
Co-authored-by: Garry Trinder <garry@trinder365.co.uk>

Author: 3 people

DevProxy/Commands/CertCommand.cs

@@ -41,6 +41,11 @@ private void ConfigureCommand()
             certEnsureCommand,
             certRemoveCommand,
         }.OrderByName());
+
+        HelpExamples.Add(this, [
+            "devproxy cert ensure                                Install and trust certificate",
+            "devproxy cert remove --force                        Remove certificate (no prompt)",
+        ]);
     }
 
     private async Task EnsureCertAsync()

DevProxy/Commands/ConfigCommand.cs

@@ -108,6 +108,13 @@ private void ConfigureCommand()
             configNewCommand,
             configOpenCommand
         }.OrderByName());
+
+        HelpExamples.Add(this, [
+            "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",
+        ]);
     }
 
     private async Task DownloadConfigAsync(string configId, OutputFormat outputFormat)

DevProxy/Commands/DevProxyCommand.cs

@@ -532,6 +532,14 @@ private void ConfigureCommand()
         commands.AddRange(_plugins.SelectMany(p => p.GetCommands()));
         this.AddCommands(commands.OrderByName());
 
+        HelpExamples.Add(this, [
+            "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",
+        ]);
+        HelpExamples.Install(this);
+
         var helpOption = Options.OfType<HelpOption>().FirstOrDefault();
         if (helpOption?.Action is HelpAction helpAction)
         {

DevProxy/Commands/HelpExamples.cs

@@ -0,0 +1,48 @@
+// Licensed to the .NET Foundation under one or more agreements.
+// The .NET Foundation licenses this file to you under the MIT license.
+// See the LICENSE file in the project root for more information.
+
+using System.CommandLine;
+using System.CommandLine.Help;
+using System.CommandLine.Invocation;
+using System.Runtime.CompilerServices;
+
+namespace DevProxy.Commands;
+
+static class HelpExamples
+{
+    private static readonly ConditionalWeakTable<Command, string[]> _examples = new();
+
+    public static void Add(Command command, string[] examples)
+    {
+        _examples.AddOrUpdate(command, examples);
+    }
+
+    public static void Install(RootCommand rootCommand)
+    {
+        var helpOption = rootCommand.Options.OfType<HelpOption>().First();
+        helpOption.Action = new ExamplesHelpAction();
+    }
+
+    private sealed class ExamplesHelpAction : SynchronousCommandLineAction
+    {
+        public override int Invoke(ParseResult parseResult)
+        {
+            new HelpAction().Invoke(parseResult);
+
+            var command = parseResult.CommandResult.Command;
+            if (_examples.TryGetValue(command, out var examples))
+            {
+                var output = parseResult.Configuration.Output;
+                output.WriteLine("Examples:");
+                foreach (var example in examples)
+                {
+                    output.Write("  ");
+                    output.WriteLine(example);
+                }
+                output.WriteLine();
+            }
+            return 0;
+        }
+    }
+}

DevProxy/Commands/JwtCommand.cs

@@ -115,6 +115,13 @@ private void ConfigureCommand()
             jwtSigningKeyOption
         }.OrderByName());
 
+        HelpExamples.Add(jwtCreateCommand, [
+            "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 and audience",
+            "devproxy jwt create --claims \"dept:eng\"              Custom claims",
+        ]);
+
         jwtCreateCommand.SetAction(parseResult =>
         {
             var jwtOptions = new JwtOptions

DevProxy/Commands/MsGraphDbCommand.cs

@@ -20,6 +20,10 @@ public MsGraphDbCommand(MSGraphDb msGraphDb) :
 
     private void ConfigureCommand()
     {
+        HelpExamples.Add(this, [
+            "devproxy msgraphdb                                  Generate Microsoft Graph DB",
+        ]);
+
         SetAction(GenerateMsGraphDbAsync);
     }
 

DevProxy/Commands/OutdatedCommand.cs

@@ -36,6 +36,12 @@ private void ConfigureCommand()
             Description = "Return version only",
         };
         Add(outdatedShortOption);
+
+        HelpExamples.Add(this, [
+            "devproxy outdated                                   Check for updates (human output)",
+            "devproxy outdated --short                           Version number only",
+        ]);
+
         SetAction(async (parseResult) =>
         {
             var versionOnly = parseResult.GetValue(outdatedShortOption);

DevProxy/Commands/StdioCommand.cs

@@ -55,6 +55,12 @@ private void ConfigureCommand()
             .Select(g => g.First()));
         this.AddOptions(options.OrderByName());
 
+        HelpExamples.Add(this, [
+            "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",
+        ]);
+
         SetAction(RunAsync);
     }