Support named resource command options

[David Fowler (davidfowl)]

Description

Resource command inputs were previously forwarded as ordered positional values, which made optional inputs difficult to use without providing every earlier value. This change makes resource command inputs feel like normal CLI options: command metadata is used to parse the command tail as named options with System.CommandLine, and the CLI sends the existing named JSON object payload over the backchannel.

This also adds command-specific --help for resource commands. The help output shows each command input, whether it is required, default values, choice values, and how to use -- when a resource command option name collides with an Aspire CLI option.

User-facing usage

The Stress playground now exposes resource command inputs as named options. For example, a command with text, number, boolean, choice, and secret inputs shows command-specific help:

$ aspire resource argument-commands echo-arguments --help
Common dashboard/API command with text, number, boolean, choice, and secret argument inputs.

Usage:
  aspire resource argument-commands echo-arguments [command-options] [options]
  aspire resource argument-commands echo-arguments -- [command-options]

Command options:
  --message <value>  Text value to echo. Required.
  --repeat <value>  How many times to echo the message. Default: 1.
  --shout  Uppercase the echoed message. Default: false.
  --flavor <value>  Choice argument used to verify select input rendering. Allowed values: vanilla, chocolate, strawberry. Default: vanilla.
  --secret <value>  Secret text input. The command only returns its length.

Options:
  --apphost <apphost>  The path to the Aspire AppHost project file or a directory to search
  -?, -h, --help       Show help and usage information

Those options can be invoked by name instead of position:

$ aspire resource argument-commands echo-arguments --message "hello named options" --repeat 2 --shout false --flavor chocolate --secret s3cr3t
Executing command 'echo-arguments' on resource 'argument-commands'...
✅ Command 'echo-arguments' executed successfully on resource 'argument-commands'.
{
  "Message": "hello named options",
  "Repeat": 2,
  "Shout": false,
  "Flavor": "chocolate",
  "SecretLength": 6,
  "Echoed": [
    "hello named options",
    "hello named options"
  ]
}

Named options also allow later optional inputs to be supplied without filling every earlier optional input. This Stress command provides required values plus --item20, while omitting --item04 through --item19:

$ aspire resource argument-commands argument-stress-test --run-id pr-description --iterations 1 --enabled true --item01 one --item02 two --item03 three --item20 twenty
Executing command 'argument-stress-test' on resource 'argument-commands'...
✅ Command 'argument-stress-test' executed successfully on resource 'argument-commands'.
{
  "PropertyCount": 7,
  "StringCharacters": 31,
  "NumberCount": 1,
  "BooleanCount": 1,
  "PropertyNames": [
    "runId",
    "iterations",
    "enabled",
    "item01",
    "item02",
    "item03",
    "item20"
  ]
}

Validation:

• ./dotnet.sh test --project tests/Aspire.Cli.Tests/Aspire.Cli.Tests.csproj --no-launch-profile -- --filter-class "*.ResourceCommandTests" --filter-class "*.ResourceCommandHelpParserTests" --filter-not-trait "quarantined=true" --filter-not-trait "outerloop=true"
• Stress playground smoke-tested command-specific help, named required inputs, omitted optional inputs, late optional inputs, positional rejection, and invalid number rejection.

Dependencies: N/A

Fixes # (issue)

Checklist

• Is this feature complete?
  • Yes. Ready to ship.
  • No. Follow-up changes expected.
• Are you including unit tests for the changes and scenario tests if relevant?
  • Yes
  • No
• Did you add public API?
  • Yes
    • If yes, did you have an API Review for it?
      • Yes
      • No
    • Did you add <remarks /> and <code /> elements on your triple slash comments?
      • Yes
      • No
  • No
• Does the change make any security assumptions or guarantees?
  • Yes
    • If yes, have you done a threat model and had a security review?
      • Yes
      • No
  • No

[github-actions]

🚀 Dogfood this PR with:

⚠️ WARNING: Do not do this without first carefully reviewing the code of this PR to satisfy yourself it is safe.

curl -fsSL https://raw.githubusercontent.com/microsoft/aspire/main/eng/scripts/get-aspire-cli-pr.sh | bash -s -- 16903

Or

• Run remotely in PowerShell:

iex "& { $(irm https://raw.githubusercontent.com/microsoft/aspire/main/eng/scripts/get-aspire-cli-pr.ps1) } 16903"

[Copilot]

Pull request overview

Updates the Aspire CLI resource command to parse resource command inputs as named options using live command metadata, and adds command-specific --help output for those inputs.

Changes:

• Parse resource command “tail” tokens as metadata-driven named options and forward them as a named JSON object payload.
• Add a custom help action for aspire resource <resource> <command> --help that renders command-input options (required/default/allowed values + -- collision guidance).
• Expand unit coverage with new help-parser tests and updated resource command tests + snapshot.

Show a summary per file

File	Description
src/Aspire.Cli/Commands/ResourceCommand.cs	Implements metadata lookup, named-option parsing, and custom command-specific help rendering.
src/Aspire.Cli/Commands/ResourceCommandHelpParser.cs	Adds a testable parser for detecting command-specific help requests and extracting the apphost path.
tests/Aspire.Cli.Tests/Commands/ResourceCommandTests.cs	Updates and adds tests for named-option parsing, validation behavior, collisions, and help output.
tests/Aspire.Cli.Tests/Commands/ResourceCommandHelpParserTests.cs	Adds unit tests for the help-request parsing logic.
tests/Aspire.Cli.Tests/Snapshots/ResourceCommandTests.ResourceCommand_CommandSpecificHelpForAllArgumentTypesMatchesSnapshot.verified.txt	Adds snapshot coverage for command-specific help output across argument shapes.

Copilot's findings

• Files reviewed: 5/5 changed files
• Comments generated: 3

[David Fowler (davidfowl)]

Thanks for the summary. This is an informational PR overview and does not require any code changes.

[James Newton-King (JamesNK)]

Testing command. I noticed without the resource name the error is duplicated.

And when the resource name is specified then it complains about the resource name again, not the missing command name.

[David Fowler (davidfowl)]

Fixing.

[David Fowler (davidfowl)]

Fixed in 5c35a17. I reproduced the missing-argument output and changed resource validation so aspire resource reports only The 'resource' argument is required. and aspire resource myresource reports only The 'command' argument is required., while the usage still shows <resource> <command> as required. Added tests for both cases.

[James Newton-King (JamesNK)]

NullReferenceException from testing:

[2026-05-09 04:58:36.472] [INFO] [Program] Version: 13.4.0-dev
[2026-05-09 04:58:36.473] [INFO] [Program] Build ID: 42.42.42.42424
[2026-05-09 04:58:36.473] [INFO] [Program] Working directory: C:\Development\Source\aspire
[2026-05-09 04:58:36.473] [INFO] [Program] Log file: C:\Users\jamesnk\.aspire\logs\cli_20260509T045836_cdb8b24f.log
[2026-05-09 04:58:36.473] [INFO] [Program] CLI process ID: 26196
[2026-05-09 04:58:36.519] [DBUG] [Host] Hosting starting
[2026-05-09 04:58:36.622] [DBUG] [Host] Hosting started
[2026-05-09 04:58:36.716] [DBUG] [Features] Feature defaultWatchEnabled = False (default: False)
[2026-05-09 04:58:36.716] [DBUG] [Features] Feature execCommandEnabled = False (default: False)
[2026-05-09 04:58:36.716] [DBUG] [Features] Feature experimentalPolyglot:go = False (default: False)
[2026-05-09 04:58:36.716] [DBUG] [Features] Feature experimentalPolyglot:java = False (default: False)
[2026-05-09 04:58:36.716] [DBUG] [Features] Feature experimentalPolyglot:python = False (default: False)
[2026-05-09 04:58:36.716] [DBUG] [Features] Feature experimentalPolyglot:rust = False (default: False)
[2026-05-09 04:58:36.716] [DBUG] [Features] Feature nugetSignatureVerificationEnabled = True (default: True)
[2026-05-09 04:58:36.716] [DBUG] [Features] Feature showAllTemplates = False (default: False)
[2026-05-09 04:58:36.716] [DBUG] [Features] Feature showDeprecatedPackages = False (default: False)
[2026-05-09 04:58:36.716] [DBUG] [Features] Feature stagingChannelEnabled = False (default: False)
[2026-05-09 04:58:36.716] [DBUG] [Features] Feature updateNotificationsEnabled = True (default: True)
[2026-05-09 04:58:36.801] [INFO] [Program] Command: aspire resource test-resource ss
[2026-05-09 04:58:36.801] [DBUG] [Program] Parsing arguments: resource test-resource ss
[2026-05-09 04:58:36.810] [DBUG] [Program] Executing command: aspire resource
[2026-05-09 04:58:36.813] [DBUG] [AuxiliaryBackchannelMonitor] Current command is not MCP start command. Auxiliary backchannel monitoring disabled.
[2026-05-09 04:58:36.839] [DBUG] [AuxiliaryBackchannelMonitor] Socket created: C:\Users\jamesnk\.aspire\cli\backchannels\auxi.sock.3e792bcc6fc4640b.267c6ad91293.39116
[2026-05-09 04:58:36.846] [INFO] [AuxiliaryBackchannelMonitor] Connecting to auxiliary socket: C:\Users\jamesnk\.aspire\cli\backchannels\auxi.sock.3e792bcc6fc4640b.267c6ad91293.39116
[2026-05-09 04:58:36.898] [DBUG] [AuxiliaryBackchannelMonitor] Connected to auxiliary backchannel at C:\Users\jamesnk\.aspire\cli\backchannels\auxi.sock.3e792bcc6fc4640b.267c6ad91293.39116
[2026-05-09 04:58:36.999] [DBUG] [AuxiliaryBackchannelMonitor] AppHost capabilities: aux.v1, aux.v2
[2026-05-09 04:58:37.001] [INFO] [AuxiliaryBackchannelMonitor] Successfully connected to AppHost at C:\Users\jamesnk\.aspire\cli\backchannels\auxi.sock.3e792bcc6fc4640b.267c6ad91293.39116. Hash: 3e792bcc6fc4640b, AppHost Path: C:\Development\Temp\cli-init\no-dashboard\apphost.cs, AppHost PID: 39116, CLI PID: 30896, In Scope: False, Supports V2: True
[2026-05-09 04:58:37.029] [INFO] [Stdout] ℹ️ No running AppHosts found in the current directory. Select from all running AppHosts.
[2026-05-09 04:58:37.059] [INFO] [Stdout] Selection prompt: Select an AppHost to connect to:
[2026-05-09 04:58:37.951] [INFO] [Stdout] Selection result: C:\Development\Temp\cli-init\no-dashboard\apphost.cs
[2026-05-09 04:58:37.952] [INFO] [Stdout] ✅ Using AppHost: C:\Development\Temp\cli-init\no-dashboard\apphost.cs
[2026-05-09 04:58:37.954] [DBUG] [AuxiliaryBackchannelMonitor] Getting resource snapshots
[2026-05-09 04:58:37.998] [DBUG] [ResourceCommand] Executing command 'ss' on resource 'test-resource'
[2026-05-09 04:58:38.000] [DBUG] [AuxiliaryBackchannelMonitor] Executing command 'ss' on resource 'test-resource'
[2026-05-09 04:58:38.018] [DBUG] [AuxiliaryBackchannelMonitor] Command 'ss' on resource 'test-resource' completed with success=False
[2026-05-09 04:58:38.022] [FAIL] [Program] An unexpected error occurred.
System.NullReferenceException: Object reference not set to an instance of an object.
   at Aspire.Cli.Commands.ResourceCommandHelper.AppendValidationErrors(String errorMessage, ResourceCommandArgumentValidationError[] validationErrors) in c:\Development\Source\aspire\src\Aspire.Cli\Commands\ResourceCommandHelper.cs:line 168
   at Aspire.Cli.Commands.ResourceCommandHelper.ExecuteGenericCommandAsync(IAppHostAuxiliaryBackchannel connection, IInteractionService interactionService, ILogger logger, String resourceName, String commandName, JsonNode arguments, CancellationToken cancellationToken) in c:\Development\Source\aspire\src\Aspire.Cli\Commands\ResourceCommandHelper.cs:line 103
   at Aspire.Cli.Commands.ResourceCommand.ExecuteAsync(ParseResult parseResult, CancellationToken cancellationToken) in c:\Development\Source\aspire\src\Aspire.Cli\Commands\ResourceCommand.cs:line 121
   at Aspire.Cli.Commands.BaseCommand.<>c__DisplayClass14_0.<<-ctor>b__0>d.MoveNext() in c:\Development\Source\aspire\src\Aspire.Cli\Commands\BaseCommand.cs:line 53
--- End of stack trace from previous location ---
   at System.CommandLine.Invocation.InvocationPipeline.InvokeAsync(ParseResult parseResult, CancellationToken cancellationToken)
   at Aspire.Cli.Program.Main(String[] args) in c:\Development\Source\aspire\src\Aspire.Cli\Program.cs:line 796
[2026-05-09 04:58:38.038] [FAIL] [AspireCliTelemetry] An unexpected error occurred.
System.NullReferenceException: Object reference not set to an instance of an object.
   at Aspire.Cli.Commands.ResourceCommandHelper.AppendValidationErrors(String errorMessage, ResourceCommandArgumentValidationError[] validationErrors) in c:\Development\Source\aspire\src\Aspire.Cli\Commands\ResourceCommandHelper.cs:line 168
   at Aspire.Cli.Commands.ResourceCommandHelper.ExecuteGenericCommandAsync(IAppHostAuxiliaryBackchannel connection, IInteractionService interactionService, ILogger logger, String resourceName, String commandName, JsonNode arguments, CancellationToken cancellationToken) in c:\Development\Source\aspire\src\Aspire.Cli\Commands\ResourceCommandHelper.cs:line 103
   at Aspire.Cli.Commands.ResourceCommand.ExecuteAsync(ParseResult parseResult, CancellationToken cancellationToken) in c:\Development\Source\aspire\src\Aspire.Cli\Commands\ResourceCommand.cs:line 121
   at Aspire.Cli.Commands.BaseCommand.<>c__DisplayClass14_0.<<-ctor>b__0>d.MoveNext() in c:\Development\Source\aspire\src\Aspire.Cli\Commands\BaseCommand.cs:line 53
--- End of stack trace from previous location ---
   at System.CommandLine.Invocation.InvocationPipeline.InvokeAsync(ParseResult parseResult, CancellationToken cancellationToken)
   at Aspire.Cli.Program.Main(String[] args) in c:\Development\Source\aspire\src\Aspire.Cli\Program.cs:line 796
[2026-05-09 04:58:38.040] [FAIL] [Program] Exit code: 1 (exception)
[2026-05-09 04:58:38.054] [DBUG] [Host] Hosting stopping
[2026-05-09 04:58:38.056] [DBUG] [Host] Hosting stopped

[David Fowler (davidfowl)]

Fixed in 7034f40. The failed command response path now treats null ValidationErrors the same as an empty list, and I applied the same guard to the MCP resource-command tool because it had the same assumption.

Why the earlier tests missed it: the fake and constructor-created responses used the CLR default ValidationErrors = [] or explicitly populated validation errors. James's repro came from the wire shape where the backchannel response can deserialize validationErrors: null/missing as null, so the failure-without-validation-errors path was not represented. Added regression tests for both the CLI helper and MCP tool with ValidationErrors = null.

[James Newton-King (JamesNK)]

Not sure if it is related to this change, but arguments without a command name causes the command to use the first argument name as the command name:

And:

[David Fowler (davidfowl)]

I can keep fixing these anyways, I’m touching this code (well the agent is…)

[James Newton-King (JamesNK)]

This error message doesn't seem ideal:

--mm ss should be grouped together?

This is what I see with an unknown argument in a different command:

[James Newton-King (JamesNK)]

The names don't match up here. I specified --timeout-seconds and the validation mentions timeoutSeconds

[James Newton-King (JamesNK)]

This one might be tricky. Validation of choices when the choice is a dependent value:

If I given an invalid choice for a choice that is preloaded then it fails with a good error message:

But if I do the same thing for a dependent choice, that loads its values when the first input is set, then it is allowed through:

It should only allow values in the choice:

[github-actions]

Re-running the failed jobs in the CI workflow for this pull request because 1 job was identified as retry-safe transient failures in the CI run attempt.
GitHub was asked to rerun all failed jobs for that attempt, and the rerun is being tracked in the rerun attempt.
The job links below point to the failed attempt jobs that matched the retry-safe transient failure rules.

• Tests / Hosting-1 / Hosting-1 (windows-latest) - Job-level runner or infrastructure failure matched the transient allowlist.

[David Fowler (davidfowl)]

arguments without a command name causes the command to use the first argument name as the command name

Fixed in 2a041bcd1. Option-shaped tokens in the <resource>/<command> slots are now treated as missing positional arguments, so aspire resource myresource --selector value reports the missing command instead of treating --selector as the command name. Added regression tests for both missing-resource and missing-command option cases.

--mm ss should be grouped together?

Fixed in 89becbd55. Unknown command options now group the option token with its value for the error message, so the output matches the other command behavior more closely.

I specified --timeout-seconds and the validation mentions timeoutSeconds

Fixed in 89becbd55. Validation error argument names are now formatted back to CLI option spelling, so timeoutSeconds displays as --timeout-seconds.

Validation of choices when the choice is a dependent value

Fixed in e317270ae. Non-interactive resource command execution/validation now loads dependent dynamic choice options before built-in validation, and the new regression test verifies an invalid dependent choice is rejected without executing the command.

[github-actions]

Re-running the failed jobs in the CI workflow for this pull request because 1 job was identified as retry-safe transient failures in the CI run attempt.
GitHub was asked to rerun all failed jobs for that attempt, and the rerun is being tracked in the rerun attempt.
The job links below point to the failed attempt jobs that matched the retry-safe transient failure rules.

• Tests / Hosting-1 / Hosting-1 (windows-latest) - Job-level runner or infrastructure failure matched the transient allowlist.

[github-actions]

🎬 CLI E2E Test Recordings — 77 recordings uploaded (commit 23fd809)

View all recordings

Status	Test	Recording
❔	AddPackageInteractiveWhileAppHostRunningDetached	▶️ View Recording
❔	AddPackageWhileAppHostRunningDetached	▶️ View Recording
❔	AgentCommands_AllHelpOutputs_AreCorrect	▶️ View Recording
❔	AgentInitCommand_DefaultSelection_InstallsSkillOnly	▶️ View Recording
❔	AgentInitCommand_MigratesDeprecatedConfig	▶️ View Recording
❔	AspireAddPackageVersionToDirectoryPackagesProps	▶️ View Recording
❔	AspireInitSingleFileAppHostRunsViaDotnetRunAppHost	▶️ View Recording
❔	AspireUpdateRemovesAppHostPackageVersionFromDirectoryPackagesProps	▶️ View Recording
❔	Banner_DisplayedOnFirstRun	▶️ View Recording
❔	Banner_DisplayedWithExplicitFlag	▶️ View Recording
❔	Banner_NotDisplayedWithNoLogoFlag	▶️ View Recording
❔	CertificatesClean_RemovesCertificates	▶️ View Recording
❔	CertificatesTrust_WithNoCert_CreatesAndTrustsCertificate	▶️ View Recording
❔	CertificatesTrust_WithUntrustedCert_TrustsCertificate	▶️ View Recording
❔	ConfigSetGet_CreatesNestedJsonFormat	▶️ View Recording
❔	CreateAndRunAspireStarterProject	▶️ View Recording
❔	CreateAndRunAspireStarterProjectWithBundle	▶️ View Recording
❔	CreateAndRunEmptyAppHostProject	▶️ View Recording
❔	CreateAndRunJavaEmptyAppHostProject	▶️ View Recording
❔	CreateAndRunJsReactProject	▶️ View Recording
❔	CreateAndRunPythonReactProject	▶️ View Recording
❔	CreateAndRunTypeScriptEmptyAppHostProject	▶️ View Recording
❔	CreateAndRunTypeScriptStarterProject	▶️ View Recording
❔	CreateJavaAppHostWithViteApp	▶️ View Recording
❔	CreateTypeScriptAppHostWithViteApp_UsesConfiguredToolchain	▶️ View Recording
❔	DashboardRunWithOtelTracesReturnsNoTraces	▶️ View Recording
❔	DeployK8sBasicApiService	▶️ View Recording
❔	DeployK8sWithGarnet	▶️ View Recording
❔	DeployK8sWithMongoDB	▶️ View Recording
❔	DeployK8sWithMySql	▶️ View Recording
❔	DeployK8sWithPostgres	▶️ View Recording
❔	DeployK8sWithRabbitMQ	▶️ View Recording
❔	DeployK8sWithRedis	▶️ View Recording
❔	DeployK8sWithSqlServer	▶️ View Recording
❔	DeployK8sWithValkey	▶️ View Recording
❔	DeployTypeScriptAppToKubernetes	▶️ View Recording
❔	DescribeCommandResolvesReplicaNames	▶️ View Recording
❔	DescribeCommandShowsRunningResources	▶️ View Recording
❔	DetachFormatJsonProducesValidJson	▶️ View Recording
❔	DetachFormatJsonProducesValidJsonWhenRestartingExistingInstance	▶️ View Recording
❔	DoListStepsShowsPipelineSteps	▶️ View Recording
❔	DocsCommand_RendersInteractiveMarkdownFromLocalSource	▶️ View Recording
❔	DoctorCommand_DetectsDeprecatedAgentConfig	▶️ View Recording
❔	DoctorCommand_TypeScriptAppHostReportsMissingConfiguredToolchain	▶️ View Recording
❔	DoctorCommand_WithSslCertDir_ShowsTrusted	▶️ View Recording
❔	DoctorCommand_WithoutSslCertDir_ShowsPartiallyTrusted	▶️ View Recording
❔	GlobalMigration_HandlesCommentsAndTrailingCommas	▶️ View Recording
❔	GlobalMigration_HandlesMalformedLegacyJson	▶️ View Recording
❔	GlobalMigration_PreservesAllValueTypes	▶️ View Recording
❔	GlobalMigration_SkipsWhenNewConfigExists	▶️ View Recording
❔	GlobalSettings_MigratedFromLegacyFormat	▶️ View Recording
❔	InitTypeScriptAppHost_AugmentsExistingViteRepoAtRoot	▶️ View Recording
❔	InteractiveCSharpInitCreatesExpectedFiles	▶️ View Recording
❔	InvalidAppHostPathWithComments_IsHealedOnRun	▶️ View Recording
❔	LatestCliCanStartStableChannelAppHost	▶️ View Recording
❔	LatestCliCanStartStableChannelTypeScriptAppHost	▶️ View Recording
❔	LegacySettingsMigration_AdjustsRelativeAppHostPath	▶️ View Recording
❔	LogsCommandShowsResourceLogs	▶️ View Recording
❔	OtelLogsReturnsStructuredLogsFromStarterAppCore	▶️ View Recording
❔	PsCommandListsRunningAppHost	▶️ View Recording
❔	PsFormatJsonOutputsOnlyJsonToStdout	▶️ View Recording
❔	PublishWithConfigureEnvFileUpdatesEnvOutput	▶️ View Recording
❔	PublishWithDockerComposeServiceCallbackSucceeds	▶️ View Recording
❔	PublishWithoutOutputPathUsesAppHostDirectoryDefault	▶️ View Recording
❔	RestoreGeneratesSdkFiles	▶️ View Recording
❔	RestoreGeneratesSdkFiles_WithConfiguredToolchain	▶️ View Recording
❔	RestoreRefreshesGeneratedSdkAfterAddingIntegration	▶️ View Recording
❔	RestoreSupportsConfigOnlyHelperPackageAndCrossPackageTypes	▶️ View Recording
❔	RunFromParentDirectory_UsesExistingConfigNearAppHost	▶️ View Recording
❔	SecretCrudOnDotNetAppHost	▶️ View Recording
❔	SecretCrudOnTypeScriptAppHost	▶️ View Recording
❔	StagingChannel_ConfigureAndVerifySettings_ThenSwitchChannels	▶️ View Recording
❔	StartAndWaitForTypeScriptSqlServerAppHostWithNativeAssets	▶️ View Recording
❔	StopAllAppHostsFromAppHostDirectory	▶️ View Recording
❔	StopNonInteractiveSingleAppHost	▶️ View Recording
❔	StopWithNoRunningAppHostExitsSuccessfully	▶️ View Recording
❔	UnAwaitedChainsCompileWithAutoResolvePromises	▶️ View Recording

---

_{📹 Recordings uploaded automatically from CI run #25594430544}

[aspire-repo-bot]

Pull request created: #898

Generated by PR Documentation Check

[aspire-repo-bot]

📝 Documentation has been drafted in microsoft/aspire.dev#898 targeting main.

Updated aspire resource CLI reference page to document named command options and command-specific help introduced by #16903. Targeting main because release/13.4 does not exist on microsoft/aspire.dev.\n\n- src/frontend/src/content/docs/reference/cli/commands/aspire-resource.mdx — updated synopsis, added "Command inputs as named options" section with help output example and -- collision guidance, added new usage examples.

Note

This draft PR needs human review before merging.