Skip to content

Releases

XBOX CLI v0.4.2

Choose a tag to compare

@tbradshaw tbradshaw released this 15 Nov 16:13
3ed7566

Testing your game with playtests

  • New xbox playtest commands list, get, and compare a game's playtests, and create, update, publish, and delete them. create, update, publish, and delete are Experimental. See Playtest, and Your first playtest for a walkthrough.
  • playtest create and playtest update choose who can join with --audience-id, and which builds players get with --pc-package-id and --console-package-id.
  • Before it asks to publish, playtest publish checks 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 delete waits until the playtest is deleted, as playtest publish waits until it's scheduled or live. --no-wait returns as soon as the request is queued.
  • playtest create --idempotency-key makes 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 audience commands 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 list and xbox package get commands show a game's packages, and whether a build can be used in a playtest. See Package.

Configuring and publishing XBOX services

  • The xbox xbl configuration commands have new names; see Breaking changes below.
  • xbl config commands can name a game by its XBOX title ID with --title-id, or the saved title-id context, instead of its service configuration identifier (SCID). When other titles share the configuration, saving or publishing by title ID asks first, and --allow-shared-configuration skips the question.
  • Before it asks you to confirm a publish to RETAIL, xbl config publish lists the achievements the publish adds, because achievements can't be removed once they're live. --validate-only to RETAIL lists them too.
  • xbl config status includes the result of the last publish, in lastPublish.

Automating with service principals

  • New Experimental xbox playfab service-principal commands let a studio administrator grant a Microsoft Entra ID service principal access to PlayFab titles, so a continuous integration (CI) pipeline can run xbox playfab commands. 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 130 without an error. A change stopped before its request was sent says that nothing changed.
  • xbox game get with 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 xbl configuration commands are renamed: configuration list is config list, configuration get is config status, document download is config download, document commit is config save, and publish start is config publish. publish status is removed; its result is the lastPublish field of config status. See XBOX services configuration.
  • xbl config download requires --view, and working is renamed draft: pass --view draft or --view published.
  • xbl schema get no longer lists or downloads schemas: use xbl schema list for types and versions, and xbl schema download to save XSD files, or --dest - to print one. schema get now shows one version's type, version, and namespace.
  • The xbl config and xbl schema commands no longer accept one-letter option names, except -o for --output and -y for --yes. Use the full names, such as --type and --scid.
  • xbox playfab title-data get no 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:DependencyTracingEnabled and Telemetry:DependencyTraceSamplingRatio settings are removed. See Telemetry.

Fixed

  • xbox upgrade no longer fails with HTTP 301: GitHub release metadata is unavailable.
  • On Linux, when ~/.local/share doesn't exist, the CLI no longer keeps its state, including its token cache, in an XboxDevCLI folder in the current directory. If an earlier version left XboxDevCLI/xboxdevcli_tokencache.bin in a folder you ran it from, delete it.

See Known issues for the problems this release still has.

XBOX CLI v0.2.1

Choose a tag to compare

@tbradshaw tbradshaw released this 07 Nov 03:01
8a0ce4c

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.json or appsettings.{environment}.json. Its settings are built into the executable, and you change them with XBOX_ environment variables, such as XBOX_AZUREAD__CLIENTID, or with command options. Each zip now holds only the executable, LICENSE, and NOTICE.md. If you changed a value in one of those files, set its XBOX_ variable instead; see Upgrading from a release that read appsettings.json.
  • --config-env is retired. Passing it is an error that points to XBOX_ environment variables.
  • sandbox list writes a JSON object with a sandboxes array, as game list does, 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__VALUE because an earlier error message suggested it, remove it. PlayFab commands fail until you do, with an error that names it.
  • auth status reports 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 create fails, 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 the game list command to check before trying again.
  • When you create XBOX test accounts in a terminal without --security-question or --security-answer-file, test-account batch create offers a numbered list of security questions. Enter keeps the default, What is your favorite hobby?.
  • game, sandbox, test-account, and xbl commands never follow an HTTP redirect, so a request that creates something is never sent twice. test-account batch create, update, and delete report a redirect as an unknown outcome, with exit code 3.

Configuring and publishing

  • xbl commands that wait on one request, such as xbl configuration get, xbl publish start, and xbl document commit, show what they're waiting for on one line of stderr, such as Publishing 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 status no longer needs --collection-id for the default collection. Pass the entity that gave the items as --entity-id and --entity-type.

Sign-in and errors

  • Commands that run offline, such as xbox info and xbox 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

Choose a tag to compare

@tbradshaw tbradshaw released this 03 Nov 02:33
6b4a56d

Breaking changes

  • The xbl commands' --sandbox option is now --sandbox-id, and xbl publish start's --source-sandbox is now --source-sandbox-id, matching game create and test-account batch create. The xbl sandbox options no longer have the -s and -d short aliases; -s is still --scid, and -d is still --dest.
  • The saved context key is now sandbox-id, and its environment variable is XBOX_SANDBOX_ID. A sandbox saved with xbox context set sandbox or set in XBOX_SANDBOX is no longer read; save it again with xbox context set sandbox-id <id>, or set XBOX_SANDBOX_ID. Only xbl configuration get, xbl publish start, and xbl publish status read it; other commands that take --sandbox-id need it on the command line.

Setting up and testing your game

  • game list and game get show their progress on one line of stderr while they read a large catalog, such as Reading games... 1646 found, 25 pages, 84s, and xbl achievement-image upload shows 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 create shows the password requirements before it asks for one, and rejects an empty password before submitting anything.
  • game commands 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 to game list instead of printing a command that wouldn't work.

Errors and rate limits

  • When an XBOX service request returns HTTP 429 with a Retry-After header, the error says how many seconds to wait, and structured errors include it as retryAfterSeconds. A 429 with the code rate_limited says 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 xbl is described as managing XBOX services configuration.

Privacy and notices

  • The repository includes a privacy notice, PRIVACY.md, and NOTICE.md lists the third-party packages the CLI ships, with their licenses.
  • Each release's zip includes LICENSE and NOTICE.md beside the executable, with the notices of the .NET runtime it bundles.

XBOX CLI v0.1.28

Choose a tag to compare

@tbradshaw tbradshaw released this 31 Oct 04:40
bc0a5fe

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