about_Pwsh — pwsh 명령줄 인터페이스 다루기

터미널에서 PowerShell을 실행할 때 어떤 옵션을 붙여야 하는지 헷갈릴 때가 많아요. 특히 스크립트를 자동화하거나 다른 셸에서 PowerShell을 호출할 때는 조용히 동작해야 하는데, 그때마다 파라미터를 외우려면 쉽지 않죠. 이 문서는 pwsh 실행 파일(PowerShell 7 이상)의 명령줄 파라미터를 하나씩 정리해 둔 공식 문서예요. 코드와 명령어, 식별자는 원문 그대로 보존했으니 그대로 복사해서 써도 됩니다.

출처: PowerShell 공식 문서 about_Pwsh

본문

이 문서가 설명하는 것

짧게 요약하면 이렇습니다. 이 문서는 pwsh 명령줄 인터페이스를 어떻게 사용하는지 설명하고, 각 명령줄 파라미터와 그 문법을 소개해요.

Windows PowerShell 5.1용 명령줄 옵션이 궁금하다면 about_PowerShell_exe 문서를 보면 됩니다.

문법 (Syntax)

pwsh의 기본 사용법은 이렇게 생겼어요.

Usage: pwsh[.exe]
    [-Login]
    [[-File] <filePath> [args]]
    [-Command { - | <script-block> [-args <arg-array>]
                  | <string> [<CommandParameters>] } ]
    [[-CommandWithArgs <string>] [<CommandParameters>]]
    [-ConfigurationFile <filePath>]
    [-ConfigurationName <string>]
    [-CustomPipeName <string>]
    [-EncodedCommand <Base64EncodedCommand>]
    [-ExecutionPolicy <ExecutionPolicy>]
    [-InputFormat {Text | XML}]
    [-Interactive]
    [-MTA]
    [-NoExit]
    [-NoLogo]
    [-NonInteractive]
    [-NoProfile]
    [-NoProfileLoadTime]
    [-OutputFormat {Text | XML}]
    [-SettingsFile <filePath>]
    [-SSHServerMode]
    [-STA]
    [-Version]
    [-WindowStyle <style>]
    [-WorkingDirectory <directoryPath>]

pwsh[.exe] -h | -Help | -? | /?

파라미터

모든 파라미터는 대소문자를 구분하지 않아요. 파라미터 하나씩 살펴볼게요.

-File | -f

File의 값이 될 수 있는 건 -이거나 파일 경로에 선택 파라미터가 붙은 형태예요. 만약 File 값이 -라면 표준 입력(standard input)에서 명령을 읽어요.

이 파라미터는 명령줄에 파라미터는 없는데 값만 있을 때 기본으로 적용되는 파라미터예요. 지정한 스크립트는 새 세션의 로컬 범위(local scope)에서 실행되는데, 이걸 "dot-sourced"라고 불러요. 그래서 스크립트가 만든 함수와 변수를 새 세션에서 그대로 쓸 수 있답니다. 스크립트 파일 경로와 파라미터를 입력하면 되고요. 여기서 File은 명령의 마지막 파라미터여야 해요. File 파라미터 이름 뒤에 입력한 모든 문자는 스크립트 파일 경로와 스크립트 파라미터로 해석되거든요.

보통 스크립트의 [switch] 파라미터는 넣거나 빼거나 둘 중 하나예요. 예를 들어 다음 명령은 Get-Script.ps1 스크립트 파일의 All 파라미터를 사용하죠: -File .\Get-Script.ps1 -All

드물긴 하지만 [switch] 파라미터에 Boolean 값을 줘야 할 때가 있어요. File 파라미터 값 안에서 [switch] 파라미터에 Boolean 값을 주려면 파라미터를 쓴 직후에 콜론과 boolean 값을 붙이면 됩니다: -File .\Get-Script.ps1 -All:$false

스크립트에 전달되는 파라미터는 현재 셸이 해석한 뒤 리터럴 문자열로 전달돼요. 예를 들어 cmd.exe 안에서 환경 변수 값을 넘기고 싶으면 cmd.exe 문법을 쓰면 됩니다: pwsh -File .\test.ps1 -TestParam %windir%

반대로 cmd.exe 안에서 pwsh -File .\test.ps1 -TestParam $Env:windir를 실행하면 스크립트는 $Env:windir라는 리터럴 문자열을 받아요. 현재 cmd.exe 셸에서는 그게 특별한 의미를 갖지 않기 때문이죠. 다만 이런 $Env:windir 스타일의 환경 변수 참조는 Command 파라미터 안에서 쓸 수 있어요. 거기서는 PowerShell 코드로 해석되거든요.

비슷하게 Batch script에서 같은 명령을 실행한다면 현재 실행 디렉터리를 나타낼 때 .\\나 $PSScriptRoot 대신 %~dp0를 쓰면 됩니다: pwsh -File %~dp0test.ps1 -TestParam %windir%. 여기서 .\\test.ps1을 쓰면 PowerShell이 리터럴 경로 .\\test.ps1을 찾지 못해 오류를 던져요.

참고 — File 파라미터는 인자 값의 배열을 받는 파라미터를 사용하는 스크립트를 지원하지 못해요. 아쉽지만 이건 네이티브 명령이 인자 값을 얻는 방식의 한계예요. 네이티브 실행 파일(예: powershell이나 pwsh)을 호출할 때는 배열을 어떻게 처리해야 할지 모르기 때문에 문자열로 넘겨지거든요.

File 값이 -라면 표준 입력에서 명령을 읽어요. 리다이렉트된 표준 입력 없이 pwsh -File -를 실행하면 일반 세션으로 시작되는데, 사실상 File 파라미터를 아예 지정하지 않은 것과 같아요. 표준 입력에서 읽을 때 입력 구문은 PowerShell 명령 프롬프트에 입력한 것처럼 한 번에 하나씩 실행됩니다. 어떤 문이 구문 분석에 실패하면 그 문은 실행되지 않아요. 프로세스 종료 코드는 입력 안에서 마지막(실행된) 명령의 상태로 결정돼요. 정상 종료면 종료 코드는 항상 0이에요. 스크립트 파일이 exit 명령으로 끝나면 프로세스 종료 코드는 exit 명령에 준 숫자 인자로 설정되죠.

-Command와 비슷하게, 스크립트 종료 오류가 나면 종료 코드는 1로 설정돼요. 다만 -Command와 달리 Ctrl+C로 실행을 중단하면 종료 코드는 0이에요. 자세한 내용은 about_Automatic_Variables 문서의 $LASTEXITCODE를 참고하세요.

참고 — PowerShell 7.2부터 File 파라미터는 Windows에서 .ps1 파일만 받아요. 다른 파일 형식을 주면 오류가 발생하죠. 이 동작은 Windows에서만 해당하고, 다른 플랫폼에서는 PowerShell이 다른 파일 형식도 실행하려고 시도해요.

-Command | -c

Command의 값이 될 수 있는 건 -, 스크립트블록, 또는 문자열이에요. 만약 Command 값이 -라면 명령 텍스트를 표준 입력에서 읽어요.

Command 파라미터는 전달된 값을 ScriptBlock 형식으로 인식할 수 있을 때만 그 스크립트블록을 실행할 수 있어요. 이게 가능한 경우는 오직 다른 PowerShell 호스트에서 pwsh를 실행할 때뿐이에요. ScriptBlock 형식은 기존 변수에 들어 있거나, 식에서 반환되거나, pwsh에 전달되기 전에 PowerShell 호스트가 중괄호({})로 감싼 리터럴 스크립트블록으로 파싱한 형태일 수 있어요.

pwsh -Command {Get-WinEvent -LogName Security}

cmd.exe에는 스크립트블록(즉 ScriptBlock 형식)이라는 게 없어요. 그래서 Command에 전달되는 값은 항상 문자열이 되죠. 문자열 안에 스크립트블록을 쓸 수는 있는데, 실행되는 대신 일반적인 PowerShell 프롬프트에 입력한 것처럼 동작해서 스크립트블록의 내용을 그대로 출력해 버려요.

Command에 전달된 문자열은 여전히 PowerShell 코드로 실행되기 때문에, cmd.exe에서 실행할 때는 사실 스크립트블록 중괄호가 애초에 필요 없는 경우가 많아요. 문자열 안에 정의한 인라인 스크립트블록을 실행하려면 call operator &를 쓰면 됩니다:

pwsh -Command "& {Get-WinEvent -LogName Security}"

Command 값이 문자열이라면 Command는 pwsh의 마지막 파라미터여야 해요. 그 뒤에 오는 모든 인자는 실행할 명령의 일부로 해석되거든요.

기존 PowerShell 세션 안에서 호출하면 결과는 라이브 개체가 아니라 역직렬화된 XML 개체로 부모 셸에 반환돼요. 다른 셸에서는 결과가 문자열로 반환되고요.

Command 값이 -라면 명령을 표준 입력에서 읽어요. 표준 입력과 함께 Command 파라미터를 쓰려면 반드시 표준 입력을 리다이렉트해야 해요. 예를 들어:

@'
"in"

"hi" |
  % { "$_ there" }

"out"
'@ | pwsh -NoProfile -Command -

이 예제는 다음과 같은 출력을 만들어요:

in
hi there
out

표준 입력에서 읽을 때 입력은 PowerShell 명령 프롬프트에 입력한 것처럼 한 번에 하나씩 파싱되어 실행돼요. 입력 코드가 올바르게 파싱되지 않으면 그 문은 실행되지 않아요. -NoExit 파라미터를 쓰지 않으면 표준 입력에서 더 읽을 입력이 없을 때 PowerShell 세션이 종료돼요.

프로세스 종료 코드는 입력 안에서 마지막(실행된) 명령의 상태로 결정돼요. $?가 $true면 종료 코드는 0, $false면 1이에요. 마지막 명령이 외부 프로그램이거나 종료 코드를 0이나 1이 아닌 값으로 명시적으로 설정한 PowerShell 스크립트라면, 그 종료 코드는 프로세스 종료 코드를 위해 1로 변환돼요. 마찬가지로 throw나 -ErrorAction Stop 같은 스크립트 종료(runspace 종료) 오류가 발생하거나 Ctrl+C로 실행을 중단하면 값 1이 반환돼요.

특정 종료 코드를 그대로 보존하려면 명령 문자열이나 스크립트블록에 exit $LASTEXITCODE를 추가하면 됩니다. 자세한 내용은 about_Automatic_Variables 문서의 $LASTEXITCODE를 참고하세요.

-CommandWithArgs | -cwa

이건 7.4에서 추가된 실험 기능으로, PowerShell 7.5-preview.5에서 공식 기능이 됐어요.

인자와 함께 PowerShell 명령을 실행하는 파라미터예요. -Command와 달리 이 파라미터는 명령이 사용할 수 있는 $args 기본 제공 변수를 채워줘요.

첫 번째 문자열은 명령이고, 공백으로 구분된 나머지 문자열은 인자예요.

예를 들어:

pwsh -CommandWithArgs '$args | % { "arg: $_" }' arg1 arg2

이 예제는 다음과 같은 출력을 만들어요:

arg: arg1
arg: arg2

참고 — 인자 파싱과 따옴표 때문에 cmd.exe나 powershell.exe에서 실행하면 위 예제가 실패해요. 그 셸들에서 실행하려면 아래처럼 쓰면 됩니다.

REM Quoting required when run from cmd.exe
pwsh -CommandWithArgs "$args | % { ""arg: $_"" }" arg1 arg2

# Quoting required when run from powershell.exe
pwsh -CommandWithArgs '"$args | % { ""arg: $_"" }"' arg1 arg2

-ConfigurationName | -config

PowerShell이 실행될 구성 엔드포인트를 지정해요. 기본 PowerShell 원격 엔드포인트나 특정 사용자 역할 기능을 가진 사용자 지정 엔드포인트처럼, 로컬 머신에 등록된 어떤 엔드포인트든 될 수 있어요.

예: pwsh -ConfigurationName AdminRoles

-ConfigurationFile

세션 구성(.pssc) 파일 경로를 지정해요. 구성 파일에 담긴 구성이 PowerShell 세션에 적용돼요.

예: pwsh -ConfigurationFile "C:\ProgramData\PowerShell\MyConfig.pssc"

-CustomPipeName

디버깅이나 기타 프로세스 간 통신에 쓰는 추가 IPC 서버(명명된 파이프, named pipe) 이름을 지정해요. 이걸로 다른 PowerShell 인스턴스에 연결하는 예측 가능한 메커니즘을 만들 수 있죠. 보통 Enter-PSHostProcess의 CustomPipeName 파라미터와 함께 써요.

이 파라미터는 PowerShell 6.2에서 도입됐어요.

예를 들어:

# PowerShell instance 1
pwsh -CustomPipeName MyDebugPipe
# PowerShell instance 2
Enter-PSHostProcess -CustomPipeName MyDebugPipe

-EncodedCommand | -e | -ec

명령의 Base64 인코딩 문자열 버전을 받아요. 복잡하거나 겹치는 따옴표가 필요한 명령을 PowerShell에 보낼 때 이 파라미터를 사용해요. Base64 표현은 UTF-16LE 인코딩 문자열이어야 해요.

예를 들어:

$command = 'dir "C:\Program Files" '
$bytes = [System.Text.Encoding]::Unicode.GetBytes($command)
$encodedCommand = [Convert]::ToBase64String($bytes)
pwsh -EncodedCommand $encodedCommand

-ExecutionPolicy | -ex | -ep

현재 세션의 기본 실행 정책을 설정하고 그 값을 $Env:PSExecutionPolicyPreference 환경 변수에 저장해요. 이 파라미터는 영구적으로 설정된 실행 정책은 바꾸지 않아요.

이 파라미터는 Windows 컴퓨터에서만 적용돼요. Windows가 아닌 플랫폼에서는 이 파라미터와 제공된 값이 무시됩니다.

-InputFormat | -inp | -if

PowerShell로 보내는 데이터의 형식을 설명해요. 유효한 값은 "Text"(텍스트 문자열) 또는 "XML"(직렬화된 CLIXML 형식)이에요.

-Interactive | -i

사용자에게 대화형 프롬프트를 보여줘요. NonInteractive 파라미터의 반대 개념이에요.

-Login | -l

Linux와 macOS에서 PowerShell을 로그인 셸로 시작해요. /etc/profile이나 ~/.profile 같은 로그인 프로필을 실행할 때 /bin/sh를 사용하죠. Windows에서는 이 스위치가 아무 일도 하지 않아요.

주의 — PowerShell을 로그인 셸로 시작하려면 이 파라미터가 반드시 첫 번째로 와야 해요. 다른 위치에 넣으면 무시돼요.

Unix 계열 운영체제에서 pwsh를 로그인 셸로 설정하는 방법을 정리할게요:

pwsh의 전체 절대 경로가 /etc/shells 아래에 있는지 확인해요

이 경로는 보통 Linux에서는 /usr/bin/pwsh, macOS에서는 /usr/local/bin/pwsh처럼 생겼어요 설치 방법에 따라서는 설치 시점에 이 항목이 자동으로 추가되기도 해요 pwsh가 /etc/shells에 없다면 편집기를 사용해 마지막 줄에 pwsh 경로를 추가하면 됩니다. 이때 수정하려면 관리자 권한이 필요해요.

chsh 유틸리티로 현재 사용자의 셸을 pwsh로 설정하세요: chsh -s /usr/bin/pwsh

경고 — pwsh를 로그인 셸로 설정하는 것은 현재 Windows Subsystem for Linux(WSL)에서 지원하지 않아요. 거기서 로그인 셸로 설정하려 하면 WSL을 대화형으로 시작하지 못하게 될 수 있습니다.

-MTA

다중 스레드 아파트(multi-threaded apartment)로 PowerShell을 시작해요. 이 스위치는 Windows에서만 사용할 수 있고, Windows가 아닌 플랫폼에서 쓰면 오류가 나요.

-NoExit | -noe

시작 명령을 실행한 뒤에도 종료하지 않아요.

예: pwsh -NoExit -Command Get-Date

-NoLogo | -nol

대화형 세션 시작 시 배너를 숨겨요.

-NonInteractive | -noni

사용자 입력이 필요 없는 세션을 만들 때 쓰는 스위치예요. 예약 작업이나 CI/CD 파이프라인에서 도는 스크립트에 유용하죠. Read-Host나 확인 프롬프트 같은 대화형 기능을 쓰려고 하면 세션이 멈추지 않고 문 종료 오류가 발생해요.

-NoProfile | -nop

PowerShell 프로필을 불러오지 않아요.

-NoProfileLoadTime

시작 시 프로필 로드 시간이 500밀리초를 넘을 때 보여주는 프로필 로드 시간 텍스트를 숨겨요.

-OutputFormat | -o | -of

PowerShell의 출력이 어떻게 포맷되는지 결정해요. 유효한 값은 "Text"(텍스트 문자열) 또는 "XML"(직렬화된 CLIXML 형식)이에요.

예: pwsh -o XML -c Get-Date

PowerShell 세션 안에서 호출하면 평범한 문자열이 아니라 역직렬화된 개체를 출력으로 받아요. 다른 셸에서 호출하면 출력은 CLIXML 텍스트로 포맷된 문자열 데이터예요.

-SettingsFile | -settings

세션에 대한 시스템 전체 powershell.config.json 설정 파일을 재정의해요. 기본적으로 시스템 전체 설정은 $PSHOME 디렉터리의 powershell.config.json에서 읽어요.

이러한 설정은 -ConfigurationName 인자로 지정한 엔드포인트에서는 사용되지 않는다는 점을 참고하세요.

예: pwsh -SettingsFile C:\myproject\powershell.config.json

-SSHServerMode | -sshs

PowerShell을 SSH 하위 시스템으로 실행할 때 sshd_config에서 사용해요. 다른 용도로 쓰는 건 의도하지도 않았고 지원하지도 않아요.

-STA

단일 스레드 아파트(single-threaded apartment)로 PowerShell을 시작해요. 이게 기본값이에요. 이 스위치는 Windows 플랫폼에서만 사용할 수 있고, Windows가 아닌 플랫폼에서 쓰면 오류가 나요.

-Version | -v

이 PowerShell 실행 파일의 버전을 보여줘요. 추가 파라미터는 무시돼요.

-WindowStyle | -w

세션의 창 스타일을 설정해요. 유효한 값은 Normal, Minimized, Maximized, Hidden이에요. 이 파라미터는 Windows에서만 적용되고, Windows가 아닌 플랫폼에서 쓰면 오류가 나요.

-WorkingDirectory | -wd | -wo

시작 시 실행해서 초기 작업 디렉터리를 설정해요. 유효한 PowerShell 파일 경로라면 무엇이든 지원돼요.

홈 디렉터리에서 PowerShell을 시작하려면 이렇게 하세요: pwsh -WorkingDirectory ~

-Help, -?, /?

pwsh에 대한 도움말을 보여줘요. PowerShell 안에서 pwsh 명령을 입력할 때는 명령 파라미터에 슬래시(/) 대신 하이픈(-)을 붙이세요.

about_Pwsh — pwsh 명령줄 인터페이스 다루기