Repository navigation
Releases
XBOX CLI v0.4.2
Testing your game with playtests
- New
xbox playtestcommands list, get, and compare a game's playtests, and create, update, publish, and delete them.create,update,publish, anddeleteare Experimental. See Playtest, and Your first playtest for a walkthrough. playtest createandplaytest updatechoose who can join with--audience-id, and which builds players get with--pc-package-idand--console-package-id.- Before it asks to publish,
playtest publishchecks the game's XBOX services setup, such as whether its embargo date is after the playtest's end date, and lists anything to review. Use XBOX services in a playtest explains how to prepare it. playtest deletewaits until the playtest is deleted, asplaytest publishwaits until it's scheduled or live.--no-waitreturns as soon as the request is queued.playtest create --idempotency-keymakes a retry safe. When the outcome of a create is unknown, the error shows the command that retries it without creating a second playtest.- Playtest commands show a progress line with a timer on stderr while a request runs.
- New Experimental
xbox audiencecommands list, get, create, and update a seller's audiences, the groups of players or devices that Partner Center calls customer groups. See Audience. - New Experimental
xbox package listandxbox package getcommands show a game's packages, and whether a build can be used in a playtest. See Package.
Configuring and publishing XBOX services
- The
xbox xblconfiguration commands have new names; see Breaking changes below. xbl configcommands can name a game by its XBOX title ID with--title-id, or the savedtitle-idcontext, instead of its service configuration identifier (SCID). When other titles share the configuration, saving or publishing by title ID asks first, and--allow-shared-configurationskips the question.- Before it asks you to confirm a publish to RETAIL,
xbl config publishlists the achievements the publish adds, because achievements can't be removed once they're live.--validate-onlyto RETAIL lists them too. xbl config statusincludes the result of the last publish, inlastPublish.
Automating with service principals
- New Experimental
xbox playfab service-principalcommands let a studio administrator grant a Microsoft Entra ID service principal access to PlayFab titles, so a continuous integration (CI) pipeline can runxbox playfabcommands. See Service principal.
Installing and updating
- On Windows, install and update the CLI with WinGet:
winget install xbox. - On Linux and macOS, install the CLI with one command:
curl -fsSL https://raw.githubusercontent.com/xbox/cli/main/install.sh | sh. See Installation.
Safety, errors, and scripting
- Confirmation prompts stand out from the summary before them, with a blank line, and bold color in a terminal that supports it.
- Ctrl+C stops Partner Center and XBOX services commands consistently. A command that's reading or waiting exits
130without an error. A change stopped before its request was sent says that nothing changed. xbox game getwith a Store ID in place of an XBOX title ID suggests the same command with--store-id.- A numeric option that isn't a number is reported as an error, instead of crashing.
Breaking changes
- The
xbox xblconfiguration commands are renamed:configuration listisconfig list,configuration getisconfig status,document downloadisconfig download,document commitisconfig save, andpublish startisconfig publish.publish statusis removed; its result is thelastPublishfield ofconfig status. See XBOX services configuration. xbl config downloadrequires--view, andworkingis renameddraft: pass--view draftor--view published.xbl schema getno longer lists or downloads schemas: usexbl schema listfor types and versions, andxbl schema downloadto save XSD files, or--dest -to print one.schema getnow shows one version's type, version, and namespace.- The
xbl configandxbl schemacommands no longer accept one-letter option names, except-ofor--outputand-yfor--yes. Use the full names, such as--typeand--scid. xbox playfab title-data getno longer accepts--value-only. A single-key get already writes the bare value.- Telemetry sends one event for each command, with schema version 3, in place of the earlier metrics and traces, and the
Telemetry:DependencyTracingEnabledandTelemetry:DependencyTraceSamplingRatiosettings are removed. See Telemetry.
Fixed
xbox upgradeno longer fails withHTTP 301: GitHub release metadata is unavailable.- On Linux, when
~/.local/sharedoesn't exist, the CLI no longer keeps its state, including its token cache, in anXboxDevCLIfolder in the current directory. If an earlier version leftXboxDevCLI/xboxdevcli_tokencache.binin a folder you ran it from, delete it.
See Known issues for the problems this release still has.
XBOX CLI v0.2.1
macOS
The XBOX CLI now runs on macOS. Download xbox-osx-arm64.zip for Apple silicon or xbox-osx-x64.zip for Intel. Both binaries are signed by Microsoft and notarized by Apple. Follow the Linux and macOS steps in Installation to extract the archive and add xbox to your PATH.
Breaking changes
- The CLI no longer reads
appsettings.jsonorappsettings.{environment}.json. Its settings are built into the executable, and you change them withXBOX_environment variables, such asXBOX_AZUREAD__CLIENTID, or with command options. Each zip now holds only the executable,LICENSE, andNOTICE.md. If you changed a value in one of those files, set itsXBOX_variable instead; see Upgrading from a release that read appsettings.json. --config-envis retired. Passing it is an error that points toXBOX_environment variables.sandbox listwrites a JSON object with asandboxesarray, asgame listdoes, instead of a bare array. Scripts must read.sandboxes. An empty listing is{"sandboxes":[]}.- Telemetry no longer reads
APPLICATIONINSIGHTS_CONNECTION_STRING, and a release build's telemetry destination can't be changed. The opt-outs are unchanged; see Telemetry. - If you set
XBOX_PLAYFAB__REQUESTHEADERS__0__VALUEbecause an earlier error message suggested it, remove it. PlayFab commands fail until you do, with an error that names it. auth statusreports that you're signed out only when no account is cached. If the configuration, the sign-in settings, or the token cache can't be read, it exits 1 and writes the error to stderr.
Setting up and testing your game
- When
game createfails, it says whether a game could have been created. If the request wasn't sent, or the service refused it, no game was created, and it's safe to fix the problem and run it again. After a server error, a timeout, or a dropped connection, the outcome is unknown, and the command prints thegame listcommand to check before trying again. - When you create XBOX test accounts in a terminal without
--security-questionor--security-answer-file,test-account batch createoffers a numbered list of security questions. Enter keeps the default,What is your favorite hobby?. game,sandbox,test-account, andxblcommands never follow an HTTP redirect, so a request that creates something is never sent twice.test-account batch create,update, anddeletereport a redirect as an unknown outcome, with exit code 3.
Configuring and publishing
xblcommands that wait on one request, such asxbl configuration get,xbl publish start, andxbl document commit, show what they're waiting for on one line of stderr, such asPublishing from STAGE.0 to RETAIL... 12s. The line is drawn only when stderr is a terminal, and is erased before the result or error is written.
Running your game live
playfab economy inventory operation statusno longer needs--collection-idfor the default collection. Pass the entity that gave the items as--entity-idand--entity-type.
Sign-in and errors
- Commands that run offline, such as
xbox infoandxbox upgrade, no longer refuse--client-id,--tenant-id, or a service-principal profile. - A warning about a changed service endpoint appears only for the services the command calls.
- An error a command expects is reported as one message on stderr, never a stack trace.
XBOX CLI v0.1.30
Breaking changes
- The
xblcommands'--sandboxoption is now--sandbox-id, andxbl publish start's--source-sandboxis now--source-sandbox-id, matchinggame createandtest-account batch create. Thexblsandbox options no longer have the-sand-dshort aliases;-sis still--scid, and-dis still--dest. - The saved context key is now
sandbox-id, and its environment variable isXBOX_SANDBOX_ID. A sandbox saved withxbox context set sandboxor set inXBOX_SANDBOXis no longer read; save it again withxbox context set sandbox-id <id>, or setXBOX_SANDBOX_ID. Onlyxbl configuration get,xbl publish start, andxbl publish statusread it; other commands that take--sandbox-idneed it on the command line.
Setting up and testing your game
game listandgame getshow their progress on one line of stderr while they read a large catalog, such asReading games... 1646 found, 25 pages, 84s, andxbl achievement-image uploadshows its upload the same way. The line is drawn only when stderr is a terminal, and is erased before the result or error is written.test-account batch createshows the password requirements before it asks for one, and rejects an empty password before submitting anything.gamecommands remove control characters from the job and correlation IDs they print, so a malformed ID can't disrupt your terminal or logs. The JSON on stdout keeps the ID as the service returned it. If an ID can't be printed safely, the recovery message points togame listinstead of printing a command that wouldn't work.
Errors and rate limits
- When an XBOX service request returns HTTP 429 with a
Retry-Afterheader, the error says how many seconds to wait, and structured errors include it asretryAfterSeconds. A 429 with the coderate_limitedsays that you sent too many requests in a short time. See Rate limits. - Errors, warnings, and Help refer to the service consistently and describe failures in plain terms.
- Docs and Help call XBOX's online services XBOX services, and
xblis described as managing XBOX services configuration.
Privacy and notices
- The repository includes a privacy notice,
PRIVACY.md, andNOTICE.mdlists the third-party packages the CLI ships, with their licenses. - Each release's zip includes
LICENSEandNOTICE.mdbeside the executable, with the notices of the .NET runtime it bundles.
XBOX CLI v0.1.28
The first public release of the XBOX Developer CLI, xbox: a technical preview that brings building, releasing, and operating XBOX games together in one command-line tool, with one sign-in, one set of commands, and consistent output. Use it in your terminal, in scripts and CI pipelines, or from AI agents.
What you can do
- Set up your games: find the sellers you work with, and list, get, and create games.
- Test: create and manage sandboxes and test accounts, and switch the sandbox a Windows PC uses.
- Configure and publish: download, validate, and commit your game's service configuration, publish it between sandboxes, and manage achievement images.
- Run your live game with cross-platform services: work with title data, player data, files, inventory, API access, multiplayer servers, CloudScript, groups, experiments, player accounts, and privacy exports. When there's no dedicated command yet, call any PlayFab API directly.
One experience
- Sign in once with your developer account through Microsoft Entra ID, or as a service principal for unattended jobs.
- Set your targets once: save your seller, title, and sandbox, in named profiles, and every command uses them.
- Script it: data commands write JSON to stdout, with
--output tableon commands that offer a table view, and diagnostics go to stderr. - Change production safely: the most destructive operations, such as deleting a title's resources, require
--confirm, and an opt-in local audit log records the operations the CLI performs.
Get started
Download the zip for your platform below, extract the whole archive, and add its folder to your PATH. No separate .NET runtime is required. Follow Installation, then Getting started to sign in and list your games.
Official release builds send limited anonymous usage telemetry to Microsoft. Opt out with XBOX_TELEMETRY_OPTOUT=1; see Telemetry.
Report bugs and request features in GitHub Issues, or run xbox feedback to open a bug report with your environment details.