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

# 에이전트에서 XBOX CLI 사용

> AI 에이전트가 로그인 및 대상 선택부터 출력 읽기, 변경 전 승인 받기에 이르기까지 XBOX CLI를 실행하는 방법입니다.

XBOX CLI(`xbox`)는 사람뿐만 아니라 AI 에이전트와 스크립트도 실행할 수 있도록 빌드되었습니다. 해당
명령은 명시적 인수를 받고, 데이터 명령은 JSON을 작성하며, 오류는 0이 아닌 종료 코드와 함께
stderr로 전달됩니다. 이 페이지는 에이전트와 에이전트를 설정하는 사람을 위한 것으로,
로그인하는 방법, 명령의 작업 대상을 선택하는 방법, 출력을 읽는 방법, 올바른 API를 찾는 방법, 그리고
변경하기 전에 확인해야 할 사항을 설명합니다.

## 변경하기 전에

로그인한 사용자는 일반적으로 프로덕션 타이틀과 판매자에 대한 관리자 권한을 가지고 있으며,
서버 측에서는 잘못된 호출을 막지 않습니다. [안전 및 파괴적 작업](https://docs.xbox.com/ko/tools/xbox-cli/safety.md)에는
CLI가 확인을 요청하는 항목과 요청하지 않는 항목이 나와 있습니다. 나머지는 에이전트의 책임입니다.

* PlayFab 작업은 이름이 `Get`, `List` 또는 `Search`로 시작하는 경우에만 읽기 전용으로
  취급하세요. 그 밖의 모든 작업과 무언가를 만들거나, 변경하거나, 삭제하는 모든 `xbox` 명령은
  프로덕션 변경으로 취급하세요.
* 프로덕션 변경 전에 사용자에게 명령을 보여 주고, 무엇을 어떤 타이틀 또는 판매자에서
  변경하는지(해당 대상이 저장된 컨텍스트에서 오는지 여부 포함) 한 문장으로 설명하세요.
  런타임이 확인 없이 `xbox`를 실행할 수 있더라도 사용자가 승인한 후에만 실행하세요.
  승인은 보여 준 호출에만 적용됩니다.
* 모든 프로덕션 변경에서 타이틀 또는 판매자를 플래그로 전달하세요. 저장된 컨텍스트는 해당 OS 사용자의
  모든 세션에서 공유되므로 사용자의 승인과 에이전트의 호출 사이에 변경될 수 있습니다.
* PC의 모든 사용자에 대해 샌드박스를 전환하는 `xbox pc sandbox set`과
  Microsoft Store 및 XBOX 앱을 닫는 `xbox pc sandbox launch-apps` 전에는 확인을 요청하세요.
* 확인 요청 대신 `--confirm`(또는 `--yes`)을 추가하지 마세요. CLI는 누가 이를 추가했는지 알 수 없습니다.
* `xbox xbl config publish`로 RETAIL에 게시하도록 요청하기 전에 `--validate-only`와 함께
  실행하고 나열된 업적을 사용자에게 보여 주세요. 그런 다음 JSON 출력의 `SourceVersion`으로
  `--configset`을 설정하여 게시하세요. RETAIL의 업적은 제거할 수 없습니다.
  [RETAIL 게시로 추가되는 업적](https://docs.xbox.com/ko/tools/xbox-cli/commands/xbl.md#achievements-a-retail-publish-adds)을 참조하세요.
* 프로덕션 변경이 실패하고 결과를 알 수 없는 경우 변경이 적용되었을 수 있습니다. 다시 시도하기 전에
  영향을 받는 상태를 읽으세요.
  [중단된 쓰기는 결과를 알 수 없다고 보고함](https://docs.xbox.com/ko/tools/xbox-cli/safety.md#an-interrupted-write-reports-that-its-outcome-is-unknown)을 참조하세요.
* 사용자가 요청하지 않는 한 저장된 컨텍스트를 변경하지 마세요. `xbox context set`,
  `xbox context unset` 및 `xbox context profile delete`는 모든 세션의 기본값을
  변경합니다.

## 로그인

```bash theme={null}
xbox auth login                          # once, in the system browser
xbox auth status --output json-compact   # {"signedIn":true,"username":"...",...}
```

`auth status`는 로그인한 사용자가 없으면 코드 0으로 종료하고 `{"signedIn":false}`를 보고하므로
`signedIn`을 기준으로 분기하세요. 0이 아닌 종료 코드는 확인할 수 없었음을 의미하며, 오류는 stderr에 있습니다.
로그인한 사용자에게 타이틀에 대한 Admin 권한이 없으면 PlayFab 호출이 실패합니다.
[인증](https://docs.xbox.com/ko/tools/xbox-cli/authentication.md)을 참조하세요.

## 타이틀 또는 판매자 선택

`--playfab-title-id ABC123`처럼 타이틀 또는 판매자를 플래그로 전달하세요. 플래그가 없으면
명령은 `XBOX_` 환경 변수 또는 `xbox context set`으로 저장된 값을 사용합니다. 어느 쪽이 우선하는지는
[컨텍스트](https://docs.xbox.com/ko/tools/xbox-cli/commands/context.md)를 참조하세요. 저장된 내용을 확인하려면
`xbox context get --output json-compact`를 실행하고, 실질적인 호출을 하기 전에 사용자와
타이틀을 한 번 확인하세요.

## 출력 읽기

`--data-only`와 `--output json-compact`를 함께 사용하면 페이로드만 한 줄로 가져올 수 있습니다.

```bash theme={null}
xbox --playfab-title-id ABC123 --data-only --output json-compact playfab api /Admin/GetTitleData
```

```json theme={null}
{"Data":{"MyKey":"my-value"}}
```

실패한 호출은 0이 아닌 코드로 종료하고 오류를 stderr에 작성합니다. `--data-only`를 사용하면 오류 시 stdout이
비어 있으므로 stdout을 구문 분석하기 전에 종료 코드를 확인하세요.

`playfab file upload`, `download` 및 `delete`는 stdout에 아무것도 작성하지 않으며 stderr
메시지는 변경될 수 있으므로 종료 코드를 확인하세요. [파일](https://docs.xbox.com/ko/tools/xbox-cli/commands/playfab/file.md#output)을 참조하세요.

도움말은 인터페이스가 변경될 수 있는 **Experimental** 명령을 표시합니다.
[실험적 명령](https://docs.xbox.com/ko/tools/xbox-cli/cli-command-lifecycle.md)을 참조하세요.

### 속도 제한

XBOX 서비스가 HTTP 429로 응답하면 잠시 기다린 후 다시 시도하세요. CLI는 자동으로 다시 시도하지
않습니다. 서비스가 대기 시간을 지정하면 오류에 몇 초인지 표시되며, 구조화된 오류에도
`retryAfterSeconds`로 포함됩니다. 오류 코드 `rate_limited`가 있는 429는 짧은 시간에 너무
많은 요청을 보냈다는 의미이므로 속도를 늦추세요.

## 올바른 PlayFab API 찾기

`xbox playfab api <api-path>`는 모든 PlayFab API 작업을 호출합니다. 경로는
`/MultiplayerServer/ListBuildSummariesV2`와 같은 `/<Prefix>/<Operation>`이며, 요청
본문은 작업의 JSON 요청 개체입니다. PlayFab은 두 가지를 모두 문서화합니다.

* [PlayFab Swagger 사양](https://github.com/PlayFab/API_Specs/tree/master/Swagger/PlayFab)은
  컴퓨터가 읽을 수 있는 형식입니다. 각 파일에는 요청 및 응답 스키마와 필수 필드와 함께
  작업이 경로별로 나열되어 있습니다. 파일 이름은 경로의 첫 번째 세그먼트가 아니라 PlayFab의 API 그룹을
  기준으로 지정되므로, 파일의 `paths`에서 작업을 검색하세요. `/Catalog`
  및 `/Inventory`는 `Economy.swagger.json`에 있고, `/Match`, `/Lobby` 및
  `/MultiplayerServer`는 `Multiplayer.swagger.json`에 있습니다. 각 작업의 `security` 필드는
  허용되는 자격 증명을 지정합니다. `SecretKey`, `EntityToken`, `SessionTicket` 또는 플레이어 로그인 호출처럼
  자격 증명이 필요 없는 작업의 경우 `None`입니다. 일부 작업은 설명에 허용되는 엔터티 토큰 유형도
  나열합니다.
* [PlayFab REST API 참조](https://learn.microsoft.com/rest/api/playfab/)는 사람을 위해
  동일한 작업을 다룹니다.

CLI는 타이틀 비밀 키 또는 타이틀 엔터티 토큰 대신 사용자의 Microsoft Entra ID 자격 증명으로 호출하므로,
플레이어 `SessionTicket`이 필요하거나 플레이어 또는 게임 서버 엔터티 토큰만 허용하는 작업은
권한이 부여되지 않습니다. 호출이 실패하면 오류 응답에 일반적으로 `InvalidParameter` 또는
`MissingParameter`처럼 문제가 무엇인지 표시됩니다. 자세한 내용은 [PlayFab API 통합](https://docs.xbox.com/ko/tools/xbox-cli/playfab-api.md)을
참조하세요.

Windows의 Git Bash에서는 명령에 `MSYS_NO_PATHCONV=1`을 설정하세요. 그렇지 않으면 Git Bash가
CLI에 전달하기 전에 API 경로를 Windows 경로로 변환합니다.
[Windows의 Git Bash에서 실행](https://docs.xbox.com/ko/tools/xbox-cli/commands/playfab/api.md#running-from-git-bash-on-windows)을 참조하세요.

## 로그에 비밀이 남지 않도록 하기

* 요청 본문에 비밀이 포함될 수 있는 경우 `--body` 대신 `--body-file`로 전달하여
  셸 기록과 프로세스 목록에 남지 않도록 하세요. `playfab mps certificate upload` 및
  `playfab mps secret upload`는 본문에 항상 비밀이 포함되므로 `--body`를 거부합니다.
* 구성 파일과 환경 변수에 비밀을 두지 마세요. `ClientId`, `TenantId`
  및 OAuth 범위는 비밀이 아니라 식별자입니다.
* PlayFab 응답에는 플레이어, 인벤토리 또는 경제 데이터가 포함될 수 있습니다. 에이전트가 로그에 기록하는
  내용의 수정, 보존 및 액세스 제어는 에이전트 소유자의 책임입니다.

## 참고 항목

* [명령](https://docs.xbox.com/ko/tools/xbox-cli/commands.md): 전체 명령 참조
* [안전 및 파괴적 작업](https://docs.xbox.com/ko/tools/xbox-cli/safety.md): 먼저 확인을 요청하는 항목과 이름이 나타내는 것보다 더 많은 작업을 수행하는 항목


## Related topics

- [XBOX CLI](https://docs.xbox.com/ko/tools/xbox-cli/index.md)
- [안전 및 파괴적 작업](https://docs.xbox.com/ko/tools/xbox-cli/safety.md)
- [GDK에서 AI 코딩 에이전트 사용](https://docs.xbox.com/ko/build/gdk-and-engines/guides/use-ai-coding-agents-with-the-gdk.md)
- [XBOX Development Kit 관리용 DevKit Agent](https://docs.xbox.com/ko/tools/tools-console/devkitagent/devkitagent-overview.md)
- [명령](https://docs.xbox.com/ko/tools/xbox-cli/commands.md)
