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

# Uso de la XBOX CLI desde agentes

> Cómo ejecuta un agente de IA la XBOX CLI, desde iniciar sesión y elegir un destino hasta leer la salida y obtener aprobación antes de cambiar algo.

La XBOX CLI (`xbox`) está diseñada para que la ejecuten agentes de IA y scripts, además de personas. Sus
comandos aceptan argumentos explícitos, sus comandos de datos escriben JSON y sus errores van a stderr
con un código de salida distinto de cero. Esta página está dirigida a los agentes y a las personas que los configuran: cómo
iniciar sesión, elegir sobre qué actúa un comando, leer su salida y encontrar la API adecuada, y qué
preguntar antes de cambiar algo.

## Antes de cambiar algo

El usuario que ha iniciado sesión suele tener derechos de administrador en los títulos y vendedores de producción, y nada en
el lado del servidor detiene una llamada errónea. [Seguridad y operaciones destructivas](https://docs.xbox.com/es/tools/xbox-cli/safety.md) enumera
sobre qué pregunta la CLI y sobre qué no. El resto depende de ti:

* Trata una operación de PlayFab como de solo lectura únicamente si su nombre empieza por `Get`, `List` o
  `Search`. Trata cualquier otra operación, y cualquier comando `xbox` que cree, cambie o
  elimine algo, como un cambio en producción.
* Antes de un cambio en producción, muestra al usuario el comando y explica en una frase qué
  cambia y en qué título o vendedor, incluido si ese destino procede del contexto
  guardado. Ejecútalo solo después de que diga que sí, aunque tu entorno de ejecución ejecutase `xbox` sin
  preguntar. Un sí solo abarca las llamadas que mostraste.
* Pasa el título o el vendedor como marca en cada cambio en producción. El contexto guardado lo comparten
  todas las sesiones del usuario del sistema operativo, por lo que puede cambiar entre el sí del usuario y tu llamada.
* Pregunta antes de `xbox pc sandbox set`, que cambia el sandbox para todos los usuarios del PC, y
  antes de `xbox pc sandbox launch-apps`, que cierra Microsoft Store y la aplicación XBOX.
* No agregues `--confirm` (ni `--yes`) en lugar de preguntar. La CLI no puede saber quién lo agregó.
* Antes de pedir permiso para publicar en RETAIL con `xbox xbl config publish`, ejecútalo con
  `--validate-only` y muestra al usuario los logros que enumera. Después, publica con
  `--configset` establecido en el `SourceVersion` de su salida JSON. Los logros de RETAIL no se pueden
  quitar; consulta
  [Logros que agrega una publicación en RETAIL](https://docs.xbox.com/es/tools/xbox-cli/commands/xbl.md#achievements-a-retail-publish-adds).
* Si un cambio en producción falla y su resultado es desconocido, es posible que se haya aplicado. Lee
  el estado afectado antes de reintentarlo; consulta
  [Una escritura interrumpida indica que su resultado es desconocido](https://docs.xbox.com/es/tools/xbox-cli/safety.md#an-interrupted-write-reports-that-its-outcome-is-unknown).
* No modifiques el contexto guardado a menos que el usuario te lo pida. `xbox context set`,
  `xbox context unset` y `xbox context profile delete` cambian los valores predeterminados de todas
  las sesiones.

## Inicio de sesión

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

`auth status` sale con el código 0 e indica `{"signedIn":false}` cuando nadie ha iniciado sesión, así que
ramifica según `signedIn`. Un código de salida distinto de cero significa que no pudo comprobarlo, y el error está en stderr.
Las llamadas a PlayFab fallan a menos que el usuario que ha iniciado sesión tenga el permiso Admin en el título. Consulta
[Autenticación](https://docs.xbox.com/es/tools/xbox-cli/authentication.md).

## Elegir el título o el vendedor

Pasa el título o el vendedor como marca, por ejemplo `--playfab-title-id ABC123`. Sin ella, un
comando usa una variable de entorno `XBOX_` o un valor guardado con `xbox context set`; consulta
[Contexto](https://docs.xbox.com/es/tools/xbox-cli/commands/context.md) para saber cuál prevalece. Ejecuta `xbox context get --output json-compact` para
ver lo que hay guardado y confirma el título con el usuario una vez antes de llamar a algo
importante.

## Leer la salida

Combina `--data-only` y `--output json-compact` para obtener solo la carga útil, en una sola línea:

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

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

Una llamada con errores sale con un código distinto de cero y escribe su error en stderr. Con `--data-only`, stdout está
vacío cuando hay un error, así que comprueba el código de salida antes de analizar stdout.

`playfab file upload`, `download` y `delete` no escriben nada en stdout, y sus mensajes de stderr
pueden cambiar, así que comprueba su código de salida. Consulta [Archivos](https://docs.xbox.com/es/tools/xbox-cli/commands/playfab/file.md#output).

La Ayuda marca los comandos **Experimental**, cuya interfaz puede cambiar. Consulta
[Comandos experimentales](https://docs.xbox.com/es/tools/xbox-cli/cli-command-lifecycle.md).

### Límites de velocidad

Cuando un servicio XBOX responde con HTTP 429, espera antes de volver a intentarlo; la CLI no reintenta
por ti. Cuando el servicio especifica una espera, el error indica cuántos segundos, y los errores estructurados
también la incluyen como `retryAfterSeconds`. Un 429 con el código de error `rate_limited` significa que enviaste demasiadas
solicitudes en poco tiempo, así que reduce el ritmo.

## Encontrar la API de PlayFab adecuada

`xbox playfab api <api-path>` llama a cualquier operación de la API de PlayFab. La ruta es
`/<Prefix>/<Operation>`, como `/MultiplayerServer/ListBuildSummariesV2`, y el cuerpo de la
solicitud es el objeto de solicitud JSON de la operación. PlayFab documenta ambos:

* Las [especificaciones Swagger de PlayFab](https://github.com/PlayFab/API_Specs/tree/master/Swagger/PlayFab)
  son legibles por máquina. Cada archivo enumera sus operaciones por ruta, con sus esquemas de solicitud y
  respuesta y los campos obligatorios. Los archivos llevan el nombre de los grupos de API de PlayFab, no
  del primer segmento de la ruta, así que busca la operación en las `paths` de los archivos: `/Catalog`
  e `/Inventory` están en `Economy.swagger.json`, y `/Match`, `/Lobby` y
  `/MultiplayerServer` están en `Multiplayer.swagger.json`. El campo `security` de cada operación
  indica la credencial que acepta: `SecretKey`, `EntityToken`, `SessionTicket` o `None`
  para las operaciones que no necesitan credenciales, como las llamadas de inicio de sesión de jugadores. Algunas operaciones también
  enumeran en su descripción los tipos de token de entidad permitidos.
* La [referencia de la API REST de PlayFab](https://learn.microsoft.com/rest/api/playfab/) abarca las
  mismas operaciones para personas.

La CLI llama con las credenciales de Microsoft Entra ID del usuario en lugar de una clave secreta de título o un token
de entidad de título, por lo que las operaciones que necesitan un `SessionTicket` de jugador, o que solo aceptan tokens de entidad de jugador o
de servidor de juegos, no están autorizadas. Cuando una llamada falla, su respuesta de error suele indicar el problema, como
`InvalidParameter` o `MissingParameter`. Consulta [Integración de la API de PlayFab](https://docs.xbox.com/es/tools/xbox-cli/playfab-api.md) para
obtener más información.

En Git Bash en Windows, establece `MSYS_NO_PATHCONV=1` para el comando, porque, de lo contrario, Git Bash
convierte la ruta de la API en una ruta de Windows antes de que la CLI la reciba. Consulta
[Ejecución desde Git Bash en Windows](https://docs.xbox.com/es/tools/xbox-cli/commands/playfab/api.md#running-from-git-bash-on-windows).

## Mantener los secretos fuera de los registros

* Cuando el cuerpo de una solicitud pueda contener secretos, pásalo con `--body-file` en lugar de `--body`, para que
  no aparezca en el historial del shell ni en las listas de procesos. `playfab mps certificate upload` y
  `playfab mps secret upload` rechazan `--body`, porque su cuerpo siempre contiene uno.
* Mantén los secretos fuera de los archivos de configuración y de las variables de entorno. `ClientId`, `TenantId`
  y los ámbitos de OAuth son identificadores, no secretos.
* Las respuestas de PlayFab pueden contener datos de jugadores, inventario o economía. La redacción, la retención y
  el control de acceso de todo lo que registre un agente son responsabilidad del propietario del agente.

## Consulta también

* [Comandos](https://docs.xbox.com/es/tools/xbox-cli/commands.md): la referencia completa de comandos
* [Seguridad y operaciones destructivas](https://docs.xbox.com/es/tools/xbox-cli/safety.md): qué pregunta primero y qué hace más de lo que indica su nombre


## Related topics

- [XBOX CLI](https://docs.xbox.com/es/tools/xbox-cli/index.md)
- [Seguridad y operaciones destructivas](https://docs.xbox.com/es/tools/xbox-cli/safety.md)
- [Uso de agentes de codificación de IA con el GDK](https://docs.xbox.com/es/build/gdk-and-engines/guides/use-ai-coding-agents-with-the-gdk.md)
- [Información general sobre los sandboxes de los servicios de XBOX](https://docs.xbox.com/es/services/xbox-services/fundamentals/sandboxes/live-setup-sandbox.md)
- [Uso de servicios XBOX en un playtest](https://docs.xbox.com/es/tools/xbox-cli/xbox-services-in-a-playtest.md)
