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

# Configuração

> Como a CLI combina em camadas as configurações dos padrões internos, das variáveis de ambiente e das opções de linha de comando.

A XBOX CLI não precisa de arquivo de configuração. Suas configurações vêm de padrões integrados
ao executável, que você pode substituir para um shell com variáveis de ambiente ou para
um único comando com opções.

## Fontes de configuração e precedência

As configurações vêm de três fontes, e as fontes posteriores substituem as anteriores:

1. Padrões internos, compilados no executável. Consulte [Configurações](#settings).
2. Variáveis de ambiente. Consulte [Variáveis de ambiente](#environment-variables).
3. Opções de linha de comando. Consulte [Substituições por opções da CLI](#cli-option-overrides).

Uma nova versão traz os próprios padrões; portanto, não há arquivo de configurações para levar adiante.

O vendedor, o título do PlayFab, o título do XBOX e a sandbox não são configurações; consulte
[Contexto](https://docs.xbox.com/pt-BR/tools/xbox-cli/commands/context.md) para saber de onde um comando os obtém.

## Configurações

| Chave | Variável de ambiente | Opção | Padrão interno |
| - | - | - | - |
| `AzureAd:ClientId` | `XBOX_AZUREAD__CLIENTID` | `--client-id` | O próprio aplicativo do Microsoft Entra ID da CLI |
| `AzureAd:TenantId` | `XBOX_AZUREAD__TENANTID` | `--tenant-id` | `common` |
| `AzureAd:Scopes` | `XBOX_AZUREAD__SCOPES` | `--scopes` | Interno |
| `PlayFab:BaseUrlTemplate` | `XBOX_PLAYFAB__BASEURLTEMPLATE` | Nenhuma | Interno |
| `PlayFab:StudioBaseUrl` | `XBOX_PLAYFAB__STUDIOBASEURL` | Nenhuma | Interno |
| `PlayFab:MaxRequestBodyBytes` | `XBOX_PLAYFAB__MAXREQUESTBODYBYTES` | Nenhuma | `1048576` (1 MiB) |
| `PlayFab:MaxResponseBytes` | `XBOX_PLAYFAB__MAXRESPONSEBYTES` | Nenhuma | `4194304` (4 MiB) |
| `XboxPartner:BaseUrl` | `XBOX_XBOXPARTNER__BASEURL` | `--base-url`, nos comandos que a aceitam | Interno |
| `XboxPartner:TimeoutSeconds` | `XBOX_XBOXPARTNER__TIMEOUTSECONDS` | Nenhuma | `120` |
| `XblPCSandbox:Path` | `XBOX_XBLPCSANDBOX__PATH` | Nenhuma | Não definido |
| `AuditLog:Enabled` | `XBOX_AUDITLOG__ENABLED` | Nenhuma | `false` |
| `Telemetry:Enabled` | `XBOX_TELEMETRY__ENABLED` | `--disable-telemetry` define `false` | `true` |

* `AzureAd:*` configuram o login do usuário; consulte [Autenticação](https://docs.xbox.com/pt-BR/tools/xbox-cli/authentication.md#overriding-entra-id-settings).
* `PlayFab:StudioBaseUrl` é o ponto de extremidade do PlayFab para APIs de estúdio (`/Studio/*`), como
  as que [`playfab service-principal`](https://docs.xbox.com/pt-BR/tools/xbox-cli/commands/playfab/service-principal) chama.
* `XboxPartner:TimeoutSeconds` é o tempo limite de solicitação, em segundos, para comandos como
  [`game`](https://docs.xbox.com/pt-BR/tools/xbox-cli/commands/game) e precisa ser um número positivo.
* `XblPCSandbox:Path` é o `XblPCSandbox.exe` que os comandos [`pc sandbox`](https://docs.xbox.com/pt-BR/tools/xbox-cli/commands/pc)
  executam. Quando ele não está definido, a CLI procura no próprio diretório e, em seguida, em `PATH`.
* `AuditLog:Enabled` ativa o [log de auditoria](https://docs.xbox.com/pt-BR/tools/xbox-cli/audit-log.md).
* `Telemetry:*` são descritas em [Telemetria](https://docs.xbox.com/pt-BR/tools/xbox-cli/telemetry.md).

Quando `PlayFab:BaseUrlTemplate`, `PlayFab:StudioBaseUrl` ou `XboxPartner:BaseUrl` não é o
padrão interno, todos os comandos que enviam um token a esse ponto de extremidade primeiro gravam um aviso em
stderr.

## Variáveis de ambiente

A variável de uma configuração é `XBOX_` seguido da chave, com `__` (dois sublinhados) no lugar de cada `:`;
assim, `Telemetry:Enabled` é `XBOX_TELEMETRY__ENABLED`. Escreva os nomes em maiúsculas. Uma variável se aplica
ao shell que a define e a todos os comandos que esse shell inicia:

```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
```

Todas as configurações em [Configurações](#settings) têm uma variável. A CLI também lê estas:

| Variável de ambiente | Finalidade |
| - | - |
| `XBOX_PLAYFAB_TITLE_ID`, `XBOX_SELLER_ID`, `XBOX_SANDBOX_ID`, `XBOX_TITLE_ID` | Valores de contexto; consulte [Contexto](https://docs.xbox.com/pt-BR/tools/xbox-cli/commands/context.md) |
| `XBOX_PROFILE` | O [perfil](https://docs.xbox.com/pt-BR/tools/xbox-cli/commands/context.md#profiles) de onde vêm os valores salvos, quando `--profile` não é passado |
| `XBOX_TELEMETRY_OPTOUT` | Desativa a telemetria quando definida como `1`, `true` ou `yes` |
| `XBOX_AUTHENTICATION__MODE` e outras variáveis `XBOX_AUTHENTICATION__` | Login como entidade de serviço |

As configurações `XBOX_AUTHENTICATION__` são lidas somente de variáveis de ambiente, nunca de padrões
internos nem de opções. Consulte
[Autenticação de automação (entidade de serviço)](https://docs.xbox.com/pt-BR/tools/xbox-cli/authentication.md#automation-service-principal-authentication).

## Substituições por opções da CLI

As opções substituem todas as outras fontes, para um único comando.

| Opção | Chave de configuração ou comportamento |
| - | - |
| `--client-id` | `AzureAd:ClientId` para o login do usuário; recusada nos modos de entidade de serviço |
| `--tenant-id` | `AzureAd:TenantId` para o login do usuário; recusada nos modos de entidade de serviço |
| `--scopes` | `AzureAd:Scopes` |
| `--base-url` | `XboxPartner:BaseUrl`, nos comandos que a aceitam, como [`game`](https://docs.xbox.com/pt-BR/tools/xbox-cli/commands/game) e [`seller`](https://docs.xbox.com/pt-BR/tools/xbox-cli/commands/seller) |
| `--disable-telemetry` | Define `Telemetry:Enabled=false` para este comando |

Consulte [Comandos](https://docs.xbox.com/pt-BR/tools/xbox-cli/commands.md) para ver as outras opções globais.

## Configuração da telemetria

As versões oficiais coletam telemetria anônima limitada, a menos que você a desative. Para desativá-la
para um único comando:

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

Para desativá-la para um shell:

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

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

Consulte [Telemetria](https://docs.xbox.com/pt-BR/tools/xbox-cli/telemetry.md) para saber o que é coletado.

## Atualizar a partir de uma versão que lia appsettings.json

As versões anteriores liam `appsettings.json` ao lado do executável. Se você alterou um valor
nele, defina a variável `XBOX_` correspondente: por exemplo, `"AzureAd": { "ClientId": "..." }` passa a ser
`XBOX_AZUREAD__CLIENTID`. Você pode ver estas mensagens até concluir:

* `--config-env` falha com este erro. Remova a opção e defina variáveis `XBOX_` em vez disso.

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

* Enquanto houver um arquivo `appsettings*.json` ao lado do executável, os comandos gravarão esta observação em
  stderr. Exclua o arquivo.

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

* Os comandos do PlayFab falham com um erro que nomeia `XBOX_PLAYFAB__REQUESTHEADERS__0__VALUE` se uma
  mensagem de erro anterior levou você a defini-la. Remova a variável.


## Related topics

- [Configuração](https://docs.xbox.com/pt-BR/services/xbox-services/storage/title-storage/config/index.md)
- [Configuração do portal](https://docs.xbox.com/pt-BR/services/xbox-services/fundamentals/portal-config/index.md)
- [Configuração do jogo](https://docs.xbox.com/pt-BR/publishing/game-publishing/concepts/game-setup-overview.md)
- [Configuração de HTTP](https://docs.xbox.com/pt-BR/services/playfab/sdks/c/http-config.md)
- [Configuração de segmentos](https://docs.xbox.com/pt-BR/services/playfab/live-service-management/game-configuration/segmentation/segmentation-configuration.md)
