8000 [release/v7.2.14] Update man page to match current help for pwsh (#19… · PowerShell/PowerShell@ef4fd9a · GitHub
[go: up one dir, main page]
Skip to content

Commit ef4fd9a

Browse files
daxian-dbwdaxian-dbw
authored
[release/v7.2.14] Update man page to match current help for pwsh (#19993) (#20240)
1 parent 5ccd7c9 commit ef4fd9a

File tree

1 file changed

+159
-51
lines changed

1 file changed

+159
-51
lines changed

‎assets/pwsh.1.ronn

Lines changed: 159 additions & 51 deletions
Original file line numberDiff line numberDiff line change
@@ -3,11 +3,17 @@ pwsh(1) -- PowerShell command-line shell and .NET REPL
33

44
## SYNOPSIS
55

6-
`pwsh` [`-NoLogo`] [`-NoExit`] [`-NoProfile`] [`-NonInteractive`]
7-
[`-InputFormat` {Text | XML}] [`-OutputFormat` {Text | XML}]
6+
`pwsh` [`-Login`] [ [`-File`] <filePath> [args] ]
7+
[`-Command` { - | <script-block> [`-args` <arg-array>] | <string>
8+
[<CommandParameters>] } ] [`-ConfigurationFile` <filePath>]
9+
[`-ConfigurationName` <string>] [`-CustomPipeName` <string>]
10+
[`-EncodedArguments` <Base64EncodedArguments>]
811
[`-EncodedCommand` <Base64EncodedCommand>]
9-
[`-File` <filePath> <args>] [`-ExecutionPolicy` <ExecutionPolicy>]
10-
[`-Command` { `-` | <script-block> [`-args` <arg-array>] | <string> [<CommandParameters>] } ]
12+
[`-ExecutionPolicy` <ExecutionPolicy>] [`-Help`] [`-InputFormat` {Text | XML}]
13+
[`-Interactive`] [`-MTA`] [`-NoExit`] [`-NoLogo`] [`-NonInteractive`]
14+
[`-NoProfile`] [`-NoProfileLoadTime`] [`-OutputFormat` {Text | XML}]
15+
[`-SettingsFile` <filePath>] [`-SSHServerMode`] [`-STA`] [`-Version`]
16+
[`-WindowStyle` <style>] [`-WorkingDirectory` <directoryPath>]
1117

1218
## DESCRIPTION
1319

@@ -17,62 +23,164 @@ command-line shell and associated scripting language.
1723

1824
## OPTIONS
1925

20-
PowerShell accepts both `-` and `--` prefixed arguments.
26+
All parameters are case-insensitive.
27+
28+
`pwsh` accepts both `-` and `--` prefixed arguments.
29+
30+
Some parameters have abbreviated forms
31+
32+
* `-File` | `-f`:
33+
Runs the specified script in the local scope ("dot-sourced"), so that the
34+
functions and variables that the script creates are available in the current
35+
session. Enter the script file path and any parameters. File must be the last
36+
parameter in the command, because all characters typed after the File
37+
parameter name are interpreted as the script file path followed by the script
38+
parameters.
39+
40+
* `-Command` | `-c`:
41+
Executes the specified commands (and any parameters) as though they were
42+
typed at the PowerShell command prompt, and then exits, unless NoExit is
43+
specified. The value of Command can be `-`, a string or a script block. If
44+
the value of Command is `-`, the command text is read from standard input. If
45+
the value of Command is a script block, the script block must be enclosed in
46+
braces (`{}`). You can specify a script block only when running PowerShell in
47+
PowerShell. The results of the script block are returned to the parent shell
48+
as deserialized XML objects, not live objects. If the value of Command is a
49+
string, Command must be the last parameter in the command, because any
50+
characters typed after the command are interpreted as the command arguments.
51+
52+
To write a string that runs a PowerShell command, use the format:
53+
`& {<command>}` where the quotation marks indicate a string and the invoke
54+
operator (`&`) causes the command to be executed.
55+
56+
* `-ConfigurationName` | `-config`:
57+
Specifies a configuration endpoint in which PowerShell is run. This can be
58+
any endpoint registered on the local machine including the default PowerShell
59+
remoting endpoints or a custom endpoint having specific user role
60+
capabilities.
61+
62+
Example: `pwsh -ConfigurationName AdminRoles`
63+
64+
* `-CustomPipeName`:
65+
Specifies the name to use for an additional IPC server (named pipe) used for
66+
debugging and other cross-process communication. This offers a predictable
67+
mechanism for connecting to other PowerShell instances. Typically used with
68+
the **CustomPipeName** parameter on `Enter-PSHostProcess`.
69+
70+
This parameter was introduced in PowerShell 6.2.
71+
72+
For example:
73+
74+
```powershell
75+
# PowerShell instance 1
76+
pwsh -CustomPipeName mydebugpipe
77+
# PowerShell instance 2
78+
Enter-PSHostProcess -CustomPipeName mydebugpipe
79+
```
80+
81+
* `-EncodedArguments` | `-encodeda` | `-ea`:
82+
Accepts a base-64-encoded string version of command arguments.
83+
Use this parameter to submit command arguments to PowerShell that
84+
require complex quotation marks or curly braces.
2185

22-
* `-NoLogo`:
23-
Hides the copyright banner at startup.
86+
* `-EncodedCommand` | `-e` | `-ec`:
87+
Accepts a base-64-encoded string version of a command.
88+
Use this parameter to submit commands to PowerShell that
89+
require complex quotation marks or curly braces.
90+
91+
* `-ExecutionPolicy` | `-ex` | `-ep`:
92+
This parameter only applies to Windows computers. On non-Windows platforms,
93+
the parameter and the value provided are ignored.
94+
95+
* `-InputFormat` | `-inp` | `-if`:
96+
Describes the format of data sent to PowerShell.
97+
Valid values are "Text" (text strings) or "XML" (serialized CLIXML format).
98+
99+
* `-Interactive` | `-i`:
100+
Present an interactive prompt to the user. Inverse for NonInteractive
101+
parameter.
102+
103+
* `-Login` | `-l`:
104+
On Linux and macOS, starts PowerShell as a login shell, using `/bin/sh` to
105+
execute login profiles such as `/etc/profile` and `~/.profile`.
106+
107+
This parameter must come first to start PowerShell as a login shell. This
108+
parameter is ignored if it is passed in another position.
109+
110+
To set up `pwsh` as the login shell:
111+
112+
- Verify that the full absolute path to `pwsh` is listed under `/etc/shells`
113+
- This path is usually something like `/opt/microsoft/powershell/7/pwsh` on
114+
Linux or `/usr/local/bin/pwsh` on macOS
115+
- If `pwsh` isn't present in `/etc/shells`, use an editor to append the path
116+
to `pwsh` on the last line. This requires elevated privileges to edit.
117+
- Use the `chsh` utility to set your current user's shell to `pwsh`:
118+
119+
```sh
120+
chsh -s /usr/bin/pwsh
121+
```
122+
123+
* -MTA
124+
This parameter is only supported on Windows. Using this parameter on non-Windows
125+
platforms results in an error.
126+
127+
* `-NoExit` | `-noe`:
128+
Doesn't exit after running startup commands.
24129
25-
* `-NoExit`:
26-
Does not exit after running startup commands.
130+
Example: `pwsh -NoExit -Command Get-Date`
27131
28-
* `-NoProfile`:
29-
Does not load the PowerShell profile.
132+
* `-NoLogo` | `-nol`:
133+
Hides the copyright banner at startup.
30134
31-
* `-NonInteractive`:
135+
* `-NonInteractive` | `-noni`:
32136
Does not present an interactive prompt to the user.
33137
34-
* `-InputFormat`:
35-
Describes the format of data sent to PowerShell.
36-
Valid values are "Text" (text strings) or "XML" (serialized CLIXML format).
138+
* `-NoProfile` | `-nop`:
139+
Doesn't load the PowerShell profile.
37140

38-
* `-OutputFormat`:
39-
Determines how output from PowerShell is formatted.
40-
Valid values are "Text" (text strings) or "XML" (serialized CLIXML format).
141+
* `-OutputFormat` | `-o` | `-of``:
142+
Determines how output from PowerShell is formatted. Valid values are "Text"
143+
(text strings) or "XML" (serialized CLIXML format).
41144
42-
* `-EncodedCommand`:
43-
Accepts a base-64-encoded string version of a command.
44-
Use this parameter to submit commands to PowerShell that
45-
require complex quotation marks or curly braces.
145+
Example: `pwsh -o XML -c Get-Date`
146+
147+
When called within a PowerShell session, you get deserialized objects as
148+
output rather plain strings. When called from other shells, the output is
149+
F438 string data formatted as CLIXML text.
150+
151+
* `-SettingsFile` | `-settings`:
152+
Overrides the system-wide `powershell.config.json` settings file for the
153+
session. By default, system-wide settings are read from the
154+
`powershell.config.json` in the `$PSHOME` directory.
155+
156+
Note that these settings aren't used by the endpoint specified by the
157+
`-ConfigurationName` argument.
158+
159+
Example: `pwsh -SettingsFile c:\myproject\powershell.config.json`
160+
161+
* `-SSHServerMode` | `-sshs`:
162+
Used in `sshd_config` for running PowerShell as an SSH subsystem. It isn't
163+
intended or supported for any other use.
164+
165+
* -STA
166+
This parameter is only supported on Windows. Using this parameter on
167+
non-Windows platforms results in an error.
168+
169+
* `-Version` | `-v`:
170+
Displays the version of PowerShell. Additional parameters are ignored.
171+
172+
* `-WindowStyle` | `-w`
173+
Sets the window style for the session. Valid values are Normal, Minimized,
174+
Maximized and Hidden. This parameter only applies to Windows. Using this
175+
parameter on non-Windows platforms results in an error.
176+
177+
* `-WorkingDirectory` | `-wd` | `-wo`
178+
Sets the initial working directory by executing at startup. Any valid
179+
PowerShell file path is supported.
180+
181+
To start PowerShell in your home directory, use: `pwsh -WorkingDirectory ~`
46182
47-
* `-File`:
48-
Runs the specified script in the local scope ("dot-sourced"),
49-
so that the functions and variables that the script creates are available in the current session.
50-
Enter the script file path and any parameters.
51-
File must be the last parameter in the command,
52-
because all characters typed after the File parameter name are
53-
interpreted as the script file path followed by the script parameters.
54-
55-
* `-ExecutionPolicy`:
56-
Sets the default execution policy for the current session and saves it in the
57-
$env:PSExecutionPolicyPreference environment variable.
58-
This parameter does not change the PowerShell execution policy that is set in the registry.
59-
60-
* `-Command`:
61-
Executes the specified commands (and any parameters) as though they were typed at the PowerShell command prompt,
62-
and then exits, unless NoExit is specified.
63-
The value of Command can be `-`, a string or a script block.
64-
If the value of Command is `-`, the command text is read from standard input.
65-
If the value of Command is a script block, the script block must be enclosed in braces (`{}`).
66-
You can specify a script block only when running PowerShell in PowerShell.
67-
The results of the script block are returned to the parent shell as deserialized XML objects, not live objects.
68-
If the value of Command is a string, Command must be the last parameter in the command,
69-
because any characters typed after the command are interpreted as the command arguments.
70-
71-
To write a string that runs a PowerShell command,
72-
use the format: `& {<command>}` where the quotation marks indicate a string and the
73-
invoke operator (`&`) causes the command to be executed.
74-
75-
* `-Help`, `-?`, `/?`:
183+
* `-Help`, `-h`, `-?`, `/?`:
76184
Shows this message.
77185
78186
## FILES

0 commit comments

Comments
 (0)
0