Using -Args with -Command does not work as documented

The powershell command line docs suggest that the “-Command” option may be used with the “-args” option to pass extra arguments to a script block. However, this does not work as described.

Recommend updating the command line documentation to document the actual behavior of -Command, which does not support an -args option.

Usage: pwsh[.exe] [-Login] [[-File] <filePath> [args]]
                  [-Command { - | <script-block> [-args <arg-array>]
                                | <string> [<CommandParameters>] } ]

Steps to reproduce

powershell.exe -Command "{ echo $args[1] }" -args one two three

Expected behavior

print two

Actual behavior

error:

aaronla@aaronla-r:scratch$ dotnet pwsh -command "{ echo $args[1] }" -args one two three
ParserError:
Line |
   1 |  { echo $args[1] } -args one two three
     |                    ~~~~~
     | Unexpected token '-args' in expression or statement.

Environment data

aaronla@aaronla-r:PowerApps-CoreServices$ dotnet pwsh -command echo $PSVersionTable

Name                           Value
----                           -----
PSVersion                      7.0.3
PSEdition                      Core
GitCommitId                    7.0.3
OS                             Microsoft Windows 10.0.19043
Platform                       Win32NT
PSCompatibleVersions           {1.0, 2.0, 3.0, 4.0…}
PSRemotingProtocolVersion      2.3
SerializationVersion           1.1.0.1
WSManStackVersion              3.0

[ghost]

Thanks for clarifying @rjmholt. The docs make it seem like it’s a command line argument, but now I see what you mean – it’s more intended as a powershell function argument to be used from within powershell, and not to be used at the command line / StartProcess / exec.

[rjmholt]

Given the discussion in the issue, I think the docs already cover this case and have marked it resolved. If there are changes you’d like to see in the documentation, please open an issue in https://github.com/MicrosoftDocs/PowerShell-Docs.

<div> GitHub</div><div>MicrosoftDocs/PowerShell-Docs</div><div>The official PowerShell documentation sources. Contribute to MicrosoftDocs/PowerShell-Docs development by creating an account on GitHub.</div>