> ## Documentation Index
> Fetch the complete documentation index at: https://docs.xbox.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 설치

> Windows, Linux 또는 macOS용 CLI를 다운로드하고 설치합니다.

Windows에서는 WinGet으로, Linux 또는 macOS에서는 설치 스크립트로, 모든 플랫폼에서는
릴리스 보관 파일에서 XBOX CLI를 설치합니다. 대신 소스에서 빌드하려면
[소스에서 빌드](https://github.com/xbox/cli/blob/v0.4.2/docs/contributing/building-from-source.md)를 참조하세요.

## Windows: WinGet으로 설치

Windows에서는 Windows 패키지 관리자인 [WinGet](https://learn.microsoft.com/windows/package-manager/winget/)으로
CLI를 설치합니다.

```powershell theme={null}
winget install xbox
xbox --version
```

WinGet은 `xbox`를 `PATH`에 추가하며, 관리자 권한이 필요하지 않습니다. 설치 후 터미널에서
`xbox`를 찾을 수 없으면 새 터미널을 열거나, IDE의 통합 터미널을 사용하는 경우 IDE를
다시 시작하세요.

CLI를 업데이트하려면 다음을 실행합니다.

```powershell theme={null}
winget upgrade Microsoft.Gaming.XBOXDeveloperCLI
```

제거하려면 다음을 실행합니다.

```powershell theme={null}
winget uninstall Microsoft.Gaming.XBOXDeveloperCLI
```

제거해도 저장된 설정과 로그인 데이터는 `%LOCALAPPDATA%\XboxDevCLI`에 남아 있습니다. WinGet
설치는 이 페이지의 ZIP 단계가 아니라 WinGet으로만 업데이트하세요.
[다음 단계](#next-steps)로 계속 진행하세요.

## Linux 및 macOS: 스크립트로 설치

Linux x64 또는 macOS에서 설치 스크립트는 최신 릴리스를
`~/.local/opt/xboxdevcli`에 다운로드하고, 셸의 시작 파일에서 해당 디렉터리를 `PATH`에 추가합니다.
`curl` 및 `unzip`이 필요합니다.

```bash theme={null}
curl -fsSL https://raw.githubusercontent.com/xbox/cli/main/install.sh | sh
```

스크립트는 변경한 시작 파일을 출력합니다. 새 터미널을 열고 `xbox --version`으로 버전을
확인하세요. CLI를 업데이트하려면 스크립트를 다시 실행합니다. 제거하려면
`~/.local/opt/xboxdevcli`와 스크립트가 해당 시작 파일에 추가한 줄을 삭제합니다.

## 릴리스 다운로드

WinGet이 없는 Windows PC처럼 WinGet과 설치 스크립트가 적합하지 않은 경우
릴리스 보관 파일에서 설치합니다.

[GitHub 릴리스 페이지](https://github.com/xbox/cli/releases/latest)에서 운영 체제와 CPU에 맞는
보관 파일을 다운로드합니다.

| 플랫폼 | 자산 | 바이너리 |
| - | - | - |
| Windows x64 | `xbox-win-x64.zip` | `xbox.exe` |
| Linux x64 | `xbox-linux-x64.zip` | `xbox` |
| Apple 실리콘의 macOS | `xbox-osx-arm64.zip` | `xbox` |
| Intel의 macOS | `xbox-osx-x64.zip` | `xbox` |

Linux x64 바이너리에는 glibc 2.27 이상이 필요합니다. macOS 바이너리는 Microsoft가 서명하고
Apple이 공증합니다. .NET을 설치할 필요가 없습니다.

플랫폼별 단계에 나와 있는 것처럼 전체 보관 파일을 새 전용 디렉터리에 추출하고, 해당 디렉터리를 `PATH`에
추가합니다. 디렉터리에 이미 설치가 있는 경우 대신
[ZIP 설치 업데이트](#update-a-zip-installation)를 따르세요.

## Windows(PowerShell)

1. 보관 파일을 추출하고 추출된 실행 파일을 확인합니다.

   ```powershell theme={null}
   $cliDir = Join-Path $env:LOCALAPPDATA 'Programs\XboxDevCLI'
   Expand-Archive -LiteralPath "$HOME\Downloads\xbox-win-x64.zip" -DestinationPath $cliDir
   & "$cliDir\xbox.exe" --version
   ```

2. 디렉터리를 `PATH`에 추가합니다. Windows 검색에서 **계정의 환경 변수
   편집**을 엽니다. **사용자 변수**에서 **Path**를 편집하고, **새로 만들기**를 선택한 다음,
   `C:\Users\<you>\AppData\Local\Programs\XboxDevCLI`와 같은 디렉터리를 입력합니다.

3. 새 터미널을 열고 버전을 확인합니다.

   ```powershell theme={null}
   xbox --version
   ```

## Linux 및 macOS(Bash 또는 Zsh)

1. 보관 파일을 추출하고 추출된 실행 파일을 확인합니다. 이 예에서는 Linux x64를 사용합니다.
   macOS에서는 Apple 실리콘의 경우 `xbox-osx-arm64.zip`을, Intel의 경우 `xbox-osx-x64.zip`을 사용하세요.

   ```bash theme={null}
   cli_dir="$HOME/.local/opt/xboxdevcli"
   mkdir -p "$cli_dir"
   unzip "$HOME/Downloads/xbox-linux-x64.zip" -d "$cli_dir"
   chmod u+x "$cli_dir/xbox"
   "$cli_dir/xbox" --version
   ```

2. 디렉터리를 `PATH`에 추가합니다. macOS의 기본 셸인 Zsh의 경우 `~/.zshrc`에, Bash의 경우
   `~/.bashrc`에 다음 줄을 추가합니다.

   ```bash theme={null}
   export PATH="$HOME/.local/opt/xboxdevcli:$PATH"
   ```

3. 새 터미널을 열고 버전을 확인합니다.

   ```bash theme={null}
   xbox --version
   ```

## 설치 확인

`xbox --version`은 다운로드한 릴리스의 버전을 태그의 선행 `v` 없이 표시합니다.
이전 버전이 표시되면 `PATH`에서 다른 `xbox` 복사본이 먼저 발견되는 것입니다. PowerShell에서는
`Get-Command xbox -All`로, Bash 또는 Zsh에서는 `type -a xbox`로 해당 복사본을 찾아 `PATH`에서
제거하세요.

## 업데이트 확인

`xbox upgrade`는 최신 릴리스가 있는지와 설치 방법을 알려 줍니다.
[Upgrade](https://docs.xbox.com/ko/tools/xbox-cli/commands/upgrade.md)를 참조하세요.

```bash theme={null}
xbox upgrade
```

WinGet 설치를 업데이트하려면 `winget upgrade Microsoft.Gaming.XBOXDeveloperCLI`를 실행합니다. 스크립트
설치를 업데이트하려면 [설치 스크립트](#linux-and-macos-install-with-a-script)를 다시
실행합니다. ZIP 설치를 업데이트하려면 다음 섹션을 따르세요.

## ZIP 설치 업데이트

저장된 설정과 로그인 데이터는 설치와 별도로 저장되므로 그대로 유지됩니다.
[값이 저장되는 위치](https://docs.xbox.com/ko/tools/xbox-cli/commands/context.md#where-values-are-saved)를 참조하세요.

1. `xbox upgrade`가 표시하는 릴리스 페이지나
   [GitHub 릴리스 페이지](https://github.com/xbox/cli/releases/latest)에서 새 릴리스의 보관 파일을 다운로드하고
   새 디렉터리에 추출합니다.
2. 실행 중인 `xbox` 프로세스를 모두 닫습니다.
3. 이전 설치 디렉터리를 같은 경로에서 새 디렉터리로 바꾸거나,
   [Windows(PowerShell)](#windows-powershell) 또는
   [Linux 및 macOS(Bash 또는 Zsh)](#linux-and-macos-bash-or-zsh)에서와 같이 `PATH` 항목을 새 디렉터리로 변경합니다.
4. 새 터미널을 열고 `xbox --version`에 새 버전이 표시되는지 확인합니다.

새 버전이 작동할 때까지 이전 디렉터리를 `PATH`에서 제외한 상태로 보관하세요. 로그인이 만료된 경우
`xbox auth login`을 다시 실행하세요.

## 다음 단계

* [시작하기](https://docs.xbox.com/ko/tools/xbox-cli/getting-started.md): 로그인하고, Partner Center 판매자를 선택하고, 해당 판매자의
  게임을 나열합니다.
* [명령](https://docs.xbox.com/ko/tools/xbox-cli/commands.md): 전체 명령 참조입니다.
* [원격 분석](https://docs.xbox.com/ko/tools/xbox-cli/telemetry.md): CLI가 수집하는 항목과 수집을 끄는 방법입니다.


## Related topics

- [설치 기여 지정](https://docs.xbox.com/ko/services/playfab/api-references/rest/client/advertising/attribute-install.md)
- [스트리밍 설치: 상태](https://docs.xbox.com/ko/build/core-features/common/packaging/packaging-installstatus.md)
- [무인 설치 URI(API 콘텐츠)](https://docs.xbox.com/ko/reference/deviceportal/unattendedsetup/atoc-rest-unattendedsetup.md)
- [스트리밍 설치용 도구](https://docs.xbox.com/ko/build/core-features/common/packaging/deployment/atoc-deployment-tools.md)
- [스트리밍 설치: 디버깅](https://docs.xbox.com/ko/build/core-features/common/packaging/packaging-debugging.md)
