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

# 구성

> CLI가 기본 제공 기본값, 환경 변수 및 명령줄 옵션의 설정을 계층화하는 방법입니다.

XBOX CLI에는 구성 파일이 필요하지 않습니다. 설정은 실행 파일에 기본 제공된
기본값에서 가져오며, 환경 변수를 사용하여 셸에 대해 재정의하거나 옵션을 사용하여
단일 명령에 대해 재정의할 수 있습니다.

## 구성 원본 및 우선순위

설정은 세 가지 원본에서 가져오며, 나중 원본이 앞선 원본을 재정의합니다.

1. 실행 파일에 컴파일된 기본 제공 기본값. [설정](#settings)을 참조하세요.
2. 환경 변수. [환경 변수](#environment-variables)를 참조하세요.
3. 명령줄 옵션. [CLI 옵션 재정의](#cli-option-overrides)를 참조하세요.

새 릴리스에는 자체 기본값이 포함되므로 이어서 가져갈 설정 파일이 없습니다.

판매자, PlayFab 타이틀, XBOX 타이틀 및 샌드박스는 설정이 아닙니다. 명령이 이러한 값을 가져오는 위치는
[컨텍스트](https://docs.xbox.com/ko/tools/xbox-cli/commands/context.md)를 참조하세요.

## 설정

| 키 | 환경 변수 | 옵션 | 기본 제공 기본값 |
| - | - | - | - |
| `AzureAd:ClientId` | `XBOX_AZUREAD__CLIENTID` | `--client-id` | CLI 자체의 Microsoft Entra ID 애플리케이션 |
| `AzureAd:TenantId` | `XBOX_AZUREAD__TENANTID` | `--tenant-id` | `common` |
| `AzureAd:Scopes` | `XBOX_AZUREAD__SCOPES` | `--scopes` | 기본 제공 |
| `PlayFab:BaseUrlTemplate` | `XBOX_PLAYFAB__BASEURLTEMPLATE` | 없음 | 기본 제공 |
| `PlayFab:StudioBaseUrl` | `XBOX_PLAYFAB__STUDIOBASEURL` | 없음 | 기본 제공 |
| `PlayFab:MaxRequestBodyBytes` | `XBOX_PLAYFAB__MAXREQUESTBODYBYTES` | 없음 | `1048576`(1MiB) |
| `PlayFab:MaxResponseBytes` | `XBOX_PLAYFAB__MAXRESPONSEBYTES` | 없음 | `4194304`(4MiB) |
| `XboxPartner:BaseUrl` | `XBOX_XBOXPARTNER__BASEURL` | `--base-url`(이 옵션을 허용하는 명령에서) | 기본 제공 |
| `XboxPartner:TimeoutSeconds` | `XBOX_XBOXPARTNER__TIMEOUTSECONDS` | 없음 | `120` |
| `XblPCSandbox:Path` | `XBOX_XBLPCSANDBOX__PATH` | 없음 | 설정되지 않음 |
| `AuditLog:Enabled` | `XBOX_AUDITLOG__ENABLED` | 없음 | `false` |
| `Telemetry:Enabled` | `XBOX_TELEMETRY__ENABLED` | `--disable-telemetry`가 `false`로 설정 | `true` |

* `AzureAd:*`는 사용자 로그인을 구성합니다. [인증](https://docs.xbox.com/ko/tools/xbox-cli/authentication.md#overriding-entra-id-settings)을 참조하세요.
* `PlayFab:StudioBaseUrl`은 [`playfab service-principal`](https://docs.xbox.com/ko/tools/xbox-cli/commands/playfab/service-principal)이
  호출하는 API와 같은 스튜디오 API(`/Studio/*`)의 PlayFab 엔드포인트입니다.
* `XboxPartner:TimeoutSeconds`는 [`game`](https://docs.xbox.com/ko/tools/xbox-cli/commands/game)과 같은 명령의 요청 시간 제한(초)이며,
  양수여야 합니다.
* `XblPCSandbox:Path`는 [`pc sandbox`](https://docs.xbox.com/ko/tools/xbox-cli/commands/pc) 명령이 실행하는
  `XblPCSandbox.exe`입니다. 설정되지 않은 경우 CLI는 자체 디렉터리를 찾은 다음 `PATH`에서 찾습니다.
* `AuditLog:Enabled`는 [감사 로그](https://docs.xbox.com/ko/tools/xbox-cli/audit-log.md)를 켭니다.
* `Telemetry:*`는 [원격 분석](https://docs.xbox.com/ko/tools/xbox-cli/telemetry.md)에 설명되어 있습니다.

`PlayFab:BaseUrlTemplate`, `PlayFab:StudioBaseUrl` 또는 `XboxPartner:BaseUrl`이 기본 제공
기본값이 아니면, 해당 엔드포인트로 토큰을 보내는 모든 명령이 먼저 stderr에 경고를
작성합니다.

## 환경 변수

설정의 변수는 `XBOX_`와 해당 키로 구성되며, 각 `:`는 `__`(밑줄 두 개)로 바뀝니다.
따라서 `Telemetry:Enabled`는 `XBOX_TELEMETRY__ENABLED`입니다. 이름은 대문자로 작성하세요. 변수는
해당 변수를 설정한 셸과 해당 셸이 시작하는 모든 명령에 적용됩니다.

```bash theme={null}
# Linux / macOS
export XBOX_XBOXPARTNER__TIMEOUTSECONDS=300
xbox game list
```

```powershell theme={null}
# Windows PowerShell
$env:XBOX_XBOXPARTNER__TIMEOUTSECONDS = "300"
xbox game list
```

[설정](#settings)의 모든 설정에는 변수가 있습니다. CLI는 다음 변수도 읽습니다.

| 환경 변수 | 용도 |
| - | - |
| `XBOX_PLAYFAB_TITLE_ID`, `XBOX_SELLER_ID`, `XBOX_SANDBOX_ID`, `XBOX_TITLE_ID` | 컨텍스트 값. [컨텍스트](https://docs.xbox.com/ko/tools/xbox-cli/commands/context.md)를 참조하세요. |
| `XBOX_PROFILE` | `--profile`이 전달되지 않은 경우 저장된 값을 가져올 [프로필](https://docs.xbox.com/ko/tools/xbox-cli/commands/context.md#profiles) |
| `XBOX_TELEMETRY_OPTOUT` | `1`, `true` 또는 `yes`로 설정하면 원격 분석을 끕니다. |
| `XBOX_AUTHENTICATION__MODE` 및 기타 `XBOX_AUTHENTICATION__` 변수 | 서비스 주체 로그인 |

`XBOX_AUTHENTICATION__` 설정은 환경 변수에서만 읽으며, 기본 제공 기본값이나 옵션에서는
읽지 않습니다.
[자동화(서비스 주체) 인증](https://docs.xbox.com/ko/tools/xbox-cli/authentication.md#automation-service-principal-authentication)을 참조하세요.

## CLI 옵션 재정의

옵션은 명령 하나에 대해 다른 모든 원본을 재정의합니다.

| 옵션 | 구성 키 또는 동작 |
| - | - |
| `--client-id` | 사용자 로그인의 `AzureAd:ClientId`. 서비스 주체 모드에서는 거부됨 |
| `--tenant-id` | 사용자 로그인의 `AzureAd:TenantId`. 서비스 주체 모드에서는 거부됨 |
| `--scopes` | `AzureAd:Scopes` |
| `--base-url` | [`game`](https://docs.xbox.com/ko/tools/xbox-cli/commands/game) 및 [`seller`](https://docs.xbox.com/ko/tools/xbox-cli/commands/seller)처럼 이 옵션을 허용하는 명령의 `XboxPartner:BaseUrl` |
| `--disable-telemetry` | 이 명령에 대해 `Telemetry:Enabled=false`를 설정합니다. |

다른 전역 옵션은 [명령](https://docs.xbox.com/ko/tools/xbox-cli/commands.md)을 참조하세요.

## 원격 분석 구성

공식 릴리스는 사용자가 끄지 않는 한 제한된 익명 원격 분석을 수집합니다. 명령 하나에 대해
끄려면 다음을 실행합니다.

```bash theme={null}
xbox --disable-telemetry auth status
```

셸에 대해 끄려면 다음을 실행합니다.

```bash theme={null}
export XBOX_TELEMETRY_OPTOUT=1
```

```powershell theme={null}
$env:XBOX_TELEMETRY_OPTOUT = "1"
```

수집되는 항목은 [원격 분석](https://docs.xbox.com/ko/tools/xbox-cli/telemetry.md)을 참조하세요.

## appsettings.json을 읽던 릴리스에서 업그레이드

이전 릴리스는 실행 파일 옆에 있는 `appsettings.json`을 읽었습니다. 이 파일에서 값을 변경했다면
대신 해당 `XBOX_` 변수를 설정하세요. 예를 들어 `"AzureAd": { "ClientId": "..." }`는
`XBOX_AZUREAD__CLIENTID`가 됩니다. 전환을 마칠 때까지 다음 메시지가 표시될 수 있습니다.

* `--config-env`가 다음 오류와 함께 실패합니다. 이 옵션을 제거하고 대신 `XBOX_` 변수를 설정하세요.

  ```text theme={null}
  --config-env is no longer supported because settings files are no longer read. Set XBOX_ environment variables instead, such as XBOX_AZUREAD__CLIENTID.
  ```

* `appsettings*.json` 파일이 실행 파일 옆에 있는 동안 명령이 stderr에 다음 메모를
  작성합니다. 파일을 삭제하세요.

  ```text theme={null}
  Note: '<file>' is no longer read. Settings come from the built-in defaults, XBOX_ environment variables, and command options. Delete the file to hide this note.
  ```

* 이전 오류 메시지에 따라 `XBOX_PLAYFAB__REQUESTHEADERS__0__VALUE`를 설정한 경우 PlayFab 명령이
  해당 변수 이름을 명시하는 오류와 함께 실패합니다. 변수를 제거하세요.


## Related topics

- [구성](https://docs.xbox.com/ko/services/xbox-services/fundamentals/identity/privileges/config/index.md)
- [포털 구성](https://docs.xbox.com/ko/services/xbox-services/fundamentals/portal-config/index.md)
- [일정 구성](https://docs.xbox.com/ko/publishing/game-publishing/concepts/availability/availability-schedule.md)
- [HTTP 구성](https://docs.xbox.com/ko/services/playfab/sdks/c/http-config.md)
- [포털 구성 개요](https://docs.xbox.com/ko/services/xbox-services/fundamentals/portal-config/live-portal-config-overview.md)
