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

# Usar a XBOX CLI a partir de agentes

> Como um agente de IA executa a XBOX CLI, desde o login e a escolha de um destino até a leitura da saída e a obtenção de aprovação antes de alterar qualquer coisa.

A XBOX CLI (`xbox`) foi criada para ser executada por agentes de IA e scripts, além de por pessoas. Seus
comandos recebem argumentos explícitos, seus comandos de dados gravam JSON e seus erros vão para stderr
com um código de saída diferente de zero. Esta página é para agentes e para as pessoas que os configuram: como
entrar, escolher sobre o que um comando atua, ler a saída e encontrar a API certa, e o que
perguntar antes de alterar qualquer coisa.

## Antes de alterar qualquer coisa

O usuário conectado geralmente tem direitos de administrador em títulos e vendedores de produção, e nada no
lado do servidor impede uma chamada equivocada. [Segurança e operações destrutivas](https://docs.xbox.com/pt-BR/tools/xbox-cli/safety.md) lista
o que a CLI pergunta e o que ela não pergunta. O restante cabe a você:

* Trate uma operação do PlayFab como somente leitura apenas se o nome dela começar com `Get`, `List` ou
  `Search`. Trate todas as outras operações, e todos os comandos `xbox` que criam, alteram ou
  excluem algo, como uma alteração de produção.
* Antes de uma alteração de produção, mostre o comando ao usuário e diga em uma frase o que ele
  altera e em qual título ou vendedor, incluindo se esse destino vem do contexto
  salvo. Execute-o somente depois que o usuário disser sim, mesmo que seu runtime execute `xbox` sem
  perguntar. Um sim abrange apenas as chamadas que você mostrou.
* Passe o título ou o vendedor como sinalizador em todas as alterações de produção. O contexto salvo é compartilhado por
  todas as sessões do usuário do SO; portanto, ele pode mudar entre o sim do usuário e a sua chamada.
* Pergunte antes de `xbox pc sandbox set`, que troca a sandbox para todos no PC, e
  antes de `xbox pc sandbox launch-apps`, que fecha a Microsoft Store e o aplicativo XBOX.
* Não adicione `--confirm` (ou `--yes`) em vez de perguntar. A CLI não consegue saber quem o adicionou.
* Antes de pedir para publicar em RETAIL com `xbox xbl config publish`, execute-o com
  `--validate-only` e mostre ao usuário as conquistas listadas. Em seguida, publique com
  `--configset` definido como o `SourceVersion` da saída JSON. As conquistas em RETAIL não podem ser
  removidas; consulte
  [Conquistas que uma publicação em RETAIL adiciona](https://docs.xbox.com/pt-BR/tools/xbox-cli/commands/xbl.md#achievements-a-retail-publish-adds).
* Se uma alteração de produção falhar e o resultado dela for desconhecido, ela pode ter sido aplicada. Leia
  o estado afetado antes de tentar novamente; consulte
  [Uma gravação interrompida informa que seu resultado é desconhecido](https://docs.xbox.com/pt-BR/tools/xbox-cli/safety.md#an-interrupted-write-reports-that-its-outcome-is-unknown).
* Não mexa no contexto salvo, a menos que o usuário peça para alterá-lo. `xbox context set`,
  `xbox context unset` e `xbox context profile delete` alteram os padrões de todas as
  sessões.

## Entrar

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

`auth status` sai com o código 0 e informa `{"signedIn":false}` quando ninguém está conectado; portanto,
tome decisões com base em `signedIn`. Um código de saída diferente de zero significa que não foi possível verificar, e o erro está em stderr.
As chamadas ao PlayFab falham, a menos que o usuário conectado tenha a permissão Admin no título. Consulte
[Autenticação](https://docs.xbox.com/pt-BR/tools/xbox-cli/authentication.md).

## Escolher o título ou o vendedor

Passe o título ou o vendedor como sinalizador, como `--playfab-title-id ABC123`. Sem ele, um
comando usa uma variável de ambiente `XBOX_` ou um valor salvo com `xbox context set`; consulte
[Contexto](https://docs.xbox.com/pt-BR/tools/xbox-cli/commands/context.md) para saber qual prevalece. Execute `xbox context get --output json-compact` para
ver o que está salvo e confirme o título com o usuário uma vez antes de chamar qualquer coisa
substancial.

## Ler a saída

Combine `--data-only` e `--output json-compact` para obter somente o conteúdo, em uma única linha:

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

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

Uma chamada com falha sai com código diferente de zero e grava o erro em stderr. Com `--data-only`, stdout fica
vazio em caso de erro; portanto, verifique o código de saída antes de analisar stdout.

`playfab file upload`, `download` e `delete` não gravam nada em stdout, e as mensagens deles em stderr
podem mudar; portanto, verifique o código de saída. Consulte [Arquivos](https://docs.xbox.com/pt-BR/tools/xbox-cli/commands/playfab/file.md#output).

A Ajuda marca os comandos **Experimental**, cuja interface pode mudar. Consulte
[Comandos experimentais](https://docs.xbox.com/pt-BR/tools/xbox-cli/cli-command-lifecycle.md).

### Limites de taxa

Quando um serviço do XBOX responde com HTTP 429, aguarde antes de tentar novamente; a CLI não tenta novamente
por você. Quando o serviço especifica uma espera, o erro informa quantos segundos, e os erros estruturados
também a incluem como `retryAfterSeconds`. Um 429 com o código de erro `rate_limited` significa que você enviou
solicitações demais em pouco tempo; portanto, diminua o ritmo.

## Encontrar a API do PlayFab certa

`xbox playfab api <api-path>` chama qualquer operação de API do PlayFab. O caminho é
`/<Prefix>/<Operation>`, como `/MultiplayerServer/ListBuildSummariesV2`, e o corpo da
solicitação é o objeto de solicitação JSON da operação. O PlayFab documenta ambos:

* As [especificações Swagger do PlayFab](https://github.com/PlayFab/API_Specs/tree/master/Swagger/PlayFab)
  são legíveis por máquina. Cada arquivo lista suas operações por caminho, com os esquemas de solicitação e
  de resposta e os campos obrigatórios. Os arquivos têm os nomes dos grupos de API do PlayFab, não
  do primeiro segmento do caminho; portanto, pesquise a operação nos `paths` dos arquivos: `/Catalog`
  e `/Inventory` estão em `Economy.swagger.json`, e `/Match`, `/Lobby` e
  `/MultiplayerServer` estão em `Multiplayer.swagger.json`. O campo `security` de cada operação
  nomeia a credencial que ela aceita: `SecretKey`, `EntityToken`, `SessionTicket` ou `None`
  para operações que não precisam de credencial, como chamadas de login de jogadores. Algumas operações também
  listam os tipos de token de entidade permitidos na descrição.
* A [referência da API REST do PlayFab](https://learn.microsoft.com/rest/api/playfab/) abrange as
  mesmas operações para pessoas.

A CLI faz as chamadas com as credenciais do Microsoft Entra ID do usuário em vez de uma chave secreta de título ou de um
token de entidade de título; portanto, as operações que precisam de um `SessionTicket` de jogador, ou que aceitam somente tokens de entidade de jogador ou de
servidor de jogo, não são autorizadas. Quando uma chamada falha, a resposta de erro geralmente nomeia o problema, como
`InvalidParameter` ou `MissingParameter`. Consulte [Integração com a API do PlayFab](https://docs.xbox.com/pt-BR/tools/xbox-cli/playfab-api.md) para
saber mais.

No Git Bash no Windows, defina `MSYS_NO_PATHCONV=1` para o comando, porque, caso contrário, o Git Bash
converte o caminho da API em um caminho do Windows antes que a CLI o receba. Consulte
[Executar a partir do Git Bash no Windows](https://docs.xbox.com/pt-BR/tools/xbox-cli/commands/playfab/api.md#running-from-git-bash-on-windows).

## Manter segredos fora dos logs

* Quando o corpo de uma solicitação puder conter segredos, passe-o com `--body-file` em vez de `--body`, para que
  ele fique fora do histórico do shell e das listagens de processos. `playfab mps certificate upload` e
  `playfab mps secret upload` recusam `--body`, porque o corpo deles sempre contém um segredo.
* Mantenha segredos fora dos arquivos de configuração e das variáveis de ambiente. `ClientId`, `TenantId`
  e os escopos OAuth são identificadores, não segredos.
* As respostas do PlayFab podem conter dados de jogadores, de inventário ou de economia. Ocultar, reter e
  controlar o acesso a tudo o que um agente registra em log é responsabilidade do proprietário do agente.

## Confira também

* [Comandos](https://docs.xbox.com/pt-BR/tools/xbox-cli/commands.md): a referência completa de comandos
* [Segurança e operações destrutivas](https://docs.xbox.com/pt-BR/tools/xbox-cli/safety.md): o que pergunta primeiro e o que faz mais do que o nome diz


## Related topics

- [XBOX CLI](https://docs.xbox.com/pt-BR/tools/xbox-cli/index.md)
- [Segurança e operações destrutivas](https://docs.xbox.com/pt-BR/tools/xbox-cli/safety.md)
- [Usar agentes de codificação de IA com o GDK](https://docs.xbox.com/pt-BR/build/gdk-and-engines/guides/use-ai-coding-agents-with-the-gdk.md)
- [Implantando layouts de controles por toque usando a CLI do TAK](https://docs.xbox.com/pt-BR/build/core-features/common/game-streaming/building-touch-layouts/game-streaming-touch-deploying-touch-layout.md)
- [Usar os serviços do XBOX em um playtest](https://docs.xbox.com/pt-BR/tools/xbox-cli/xbox-services-in-a-playtest.md)
