> ## 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.

# 패키지

> Partner Center 게임의 패키지를 나열하고 가져오며, 빌드를 플레이테스트에 사용할 수 있는지 확인하고, 업로드 방법을 알아봅니다.

패키지는 Partner Center가 받아서 처리한 게임의 빌드입니다. `package` 명령은 게임의 패키지를 나열하고
가져오므로, 패키지가 [플레이테스트](https://docs.xbox.com/ko/tools/xbox-cli/commands/playtest.md)에 사용할 준비가 되었는지 확인할 수
있습니다. 패키지를 업로드하려면 [패키지 업로드](#uploading-packages)를 참조하세요.

이러한 명령은 실험적 기능입니다. 옵션과 출력이 변경될 수 있습니다.
[실험적 명령](https://docs.xbox.com/ko/tools/xbox-cli/cli-command-lifecycle.md)을 참조하세요. 이러한 명령에는 게임에 대한 Partner
Center의 패키지 읽기 권한이 필요하며, 이 권한은 개발자 역할에 포함되어 있습니다.

## 명령

| 명령 | 설명 |
| - | - |
| `package list` | 게임의 Main 분기에 있는 패키지를 나열합니다. |
| `package get <package-id>` | 패키지 하나를 가져옵니다. |

## 인수 및 옵션

| 인수 또는 옵션 | 적용 대상 | 필수 | 설명 |
| - | - | - | - |
| `<package-id>` | `get` | 예 | `package list`에서 얻은 패키지 ID입니다. |
| `--store-id <id>` | 모두 | 둘 중 하나 | 게임의 Store ID이며, 예를 들면 `9N0000000000`입니다. |
| `--xbox-title-id <id>` | 모두 | 둘 중 하나 | 게임의 PlayFab 타이틀 ID가 아닌 XBOX 타이틀 ID이며, 예를 들면 `1234ABCD`입니다. 타이틀 ID에 게임이 여러 개 있으면 명령이 `--store-id`를 요청합니다. |
| `--seller-id <id>` | 모두 | 아니요 | Partner Center 판매자 ID입니다. |
| `--base-url <url>` | 모두 | 아니요 | 요청의 기본 URL이며, `XboxPartner:BaseUrl` 구성 키를 재정의합니다. |
| `--output <format>` | 모두 | 아니요 | `json`(기본값), `json-compact` 또는 `table`. |

판매자는 `--seller-id` 또는 저장된 판매자에서 가져옵니다. [컨텍스트](https://docs.xbox.com/ko/tools/xbox-cli/commands/context.md)를
참조하세요. 판매자가 지정되지 않으면 명령은 유일한 판매자를 사용하며, 여러 판매자에 속해 있으면
`--seller-id`를 요청합니다. `--xbox-title-id`에는 항상 판매자가 필요합니다.

## 패키지 나열

```bash theme={null}
xbox package list --store-id 9N0000000000 --output json-compact
```

`package list`는 게임의 Main 분기 ID와, 서비스가 반환하는 모든 필드가 포함된 `packages` 배열을 씁니다.
`package get`은 같은 형식으로 패키지 하나를 씁니다. 다음은 발췌입니다.

```json theme={null}
{
  "packageSetId": "22222222-3333-4444-5555-666666666666",
  "packages": [
    {
      "id": "11111111-2222-3333-4444-555555555555",
      "version": "1.0.0.0",
      "platform": "PC",
      "packageType": "Msixvc",
      "processingState": "Processed",
      "isAvailableForPlaytest": true,
      "validationItems": [],
      "fileName": "Nod.Arena_1.0.0.0_x64.msixvc",
      "createdAt": "2026-11-04T18:00:00Z"
    }
  ]
}
```

다음이 모두 참이면 패키지를 플레이테스트에 사용할 준비가 된 것입니다.

* `processingState`가 `Processed`입니다. 상태는 `PendingUpload`에서 `Uploaded`와 `Processing`을 거쳐
  `Processed` 또는 `ProcessFailed`로 바뀝니다.
* Partner Center가 패키지를 처리하는 동안 발견한 문제인 `validationItems`에 심각도가 `Error`인 항목이
  없습니다.
* `isAvailableForPlaytest`가 `true`입니다.

`--output table`에는 `PACKAGE ID`, `VERSION`, `PLATFORM`, `STATE`, `PLAYTEST`, `CREATED` 열이 있습니다.
유효성 검사 결과는 표시되지 않으므로 JSON에서 `validationItems`를 확인하세요.

## 패키지 업로드

CLI는 패키지를 업로드하지 않습니다. XBOX Game Development Kit(GDK)의 `makepkg`로 업로드하세요.
[makepkg 참조](https://learn.microsoft.com/gaming/gdk/docs/features/common/packaging/deployment/makepkg)를
참조하고, CI(연속 통합)에서 업로드하는 경우
[Package Uploader](https://learn.microsoft.com/gaming/gdk/docs/features/common/packaging/package-uploader)를
참조하세요. 그런 다음 `package list`를 실행하여 패키지가 준비되었는지 확인하세요.

## 오류

오류는 `--output`과 관계없이 상관 관계 ID와 함께 텍스트로 stderr에 출력됩니다. `--verbose`는 응답 본문을
추가합니다. 실패하면 `1`로 종료됩니다.

| 오류 | 해결 방법 |
| - | - |
| HTTP 401 | `xbox auth login`으로 다시 로그인하세요. |
| HTTP 403, `package_permission_denied` | 이 판매자의 게임에 대한 패키지 읽기 권한이 없습니다. Partner Center 계정 관리자에게 개발자 역할을 요청하거나, 게임이 다른 판매자에 속해 있으면 `--seller-id`를 전달하세요. |
| HTTP 403, `identity_override_not_authorized` | 해당 판매자에 속해 있지 않습니다. 판매자를 확인하고 `xbox seller list`로 자신의 판매자를 찾으세요. |
| HTTP 400, `seller_selection_required` | 여러 판매자에 속해 있습니다. `--seller-id`를 전달하세요. |
| HTTP 404, `game_not_found` | 판매자에게 해당 Store ID를 가진 게임이 없습니다. `--store-id`와 `--seller-id`를 확인하세요. |

## 예제

```bash theme={null}
xbox package list --store-id 9N0000000000
xbox package list --xbox-title-id 1234ABCD --seller-id 1234567 --output table
xbox package get 11111111-2222-3333-4444-555555555555 --store-id 9N0000000000
```


## Related topics

- [패키지](https://docs.xbox.com/ko/publishing/game-publishing/concepts/game-package-management.md)
- [패키지 고급 설정](https://docs.xbox.com/ko/publishing/game-publishing/how-to/how-to-manage-advanced-settings-for-packages.md)
- [Publisher Content 패키지](https://docs.xbox.com/ko/build/core-features/common/packaging/packaging-publisher-content.md)
- [패키지(클래식 환경)](https://docs.xbox.com/ko/publishing/game-publishing/concepts/packages-overview.md)
- [게임 패키지의 패키지 플라이트 구성 방법](https://docs.xbox.com/ko/publishing/game-publishing/how-to/how-to-package-flights-for-xvc-packages.md)
