Saltar al contenido principal
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 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.
  • 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.
  • 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

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.

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 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:
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. La Ayuda marca los comandos Experimental, cuya interfaz puede cambiar. Consulta Comandos experimentales.

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

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

Última modificación el 19 de noviembre de 2026