Skip to content

docs(cli): clarify AddBranch shared settings #3

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
phil-scott-78 merged 2 commits into from
Jan 6, 2026
Merged

docs(cli): clarify AddBranch shared settings #3

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
0b196c6
docs(cli): clarify AddBranch shared settings
meiranzheng Dec 30, 2025
b9cf1cd
docs(cli): explain AddBranch<TSettings> requirement
meiranzheng Dec 31, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
11 changes: 9 additions & 2 deletions Spectre.Docs.Cli.Examples/DemoApps/CommandHierarchies/Main.cs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -72,6 +72,13 @@ public class RemoteRemoveSettings : RemoteSettings
public string Name { get; init; } = string.Empty;
}

/// <summary>
/// Settings for listing remotes.
/// </summary>
public class RemoteListSettings : RemoteSettings
{
}

internal class RemoteAddCommand : Command<RemoteAddSettings>
{
protected override int Execute(CommandContext context, RemoteAddSettings settings, CancellationToken cancellation)
Expand All @@ -94,9 +101,9 @@ protected override int Execute(CommandContext context, RemoteRemoveSettings sett
}
}

internal class RemoteListCommand : Command<RemoteSettings>
internal class RemoteListCommand : Command<RemoteListSettings>
{
protected override int Execute(CommandContext context, RemoteSettings settings, CancellationToken cancellation)
protected override int Execute(CommandContext context, RemoteListSettings settings, CancellationToken cancellation)
{
System.Console.WriteLine("Listing remotes...");
if (settings.Verbose)
Expand Down
11 changes: 7 additions & 4 deletions Spectre.Docs/Content/cli/how-to/working-with-multiple-command-hierarchies.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -15,7 +15,7 @@ A git-style CLI with nested `remote` subcommands—`add`, `remove`, and `list`

## Create a Command Branch

Use `AddBranch<TSettings>("name", ...)` to define a parent command with nested subcommands:
Use `AddBranch` to define a parent command with nested subcommands. Use the generic overload when you want shared settings/options for the branch:

```csharp:xmldocid,bodyonly
M:Spectre.Docs.Cli.Examples.DemoApps.CommandHierarchies.Demo.RunAsync(System.String[])
Expand All @@ -30,13 +30,16 @@ Define a base settings class for the branch, then inherit from it in subcommand
```csharp:xmldocid
T:Spectre.Docs.Cli.Examples.DemoApps.CommandHierarchies.RemoteSettings
T:Spectre.Docs.Cli.Examples.DemoApps.CommandHierarchies.RemoteAddSettings
T:Spectre.Docs.Cli.Examples.DemoApps.CommandHierarchies.RemoteListSettings
```

The `--verbose` flag is now available on all remote subcommands: `myapp remote add origin https://... --verbose`.
The `--verbose` flag is now available on all remote subcommands, and can be specified either before or after the subcommand name: `myapp remote --verbose add origin https://...` or `myapp remote add origin https://... --verbose`.

Rule: when you use `AddBranch<TSettings>`, each subcommand's settings type should inherit from `TSettings`. Even if a subcommand doesn't add any extra arguments/options (like `list`), give it a dedicated settings type (for example, `RemoteListSettings : RemoteSettings`).

## Nest Multiple Levels

For complex CLIs, branches can contain other branches:
For complex CLIs, branches can contain other branches (use the non-generic overload when you just want grouping):

```csharp
config.AddBranch("cloud", cloud =>
Expand All @@ -54,4 +57,4 @@ This creates deeply nested commands like `myapp cloud storage upload`.
## See Also

- <xref:cli-app-configuration> - Basic command registration
- <xref:cli-commands-arguments> - Settings class patterns
- <xref:cli-commands-arguments> - Settings class patterns