Skip to main content
The xbl command family is Experimental. Its CLI interface might change or be removed based on feedback. xbox xbl manages XBOX services configuration — working and published configuration state, configuration documents, publishing, and configuration schemas — as well as achievement images. To list the sandboxes configuration commands target, use xbox sandbox list. These commands work with the same configuration that Partner Center edits. For what each XBOX services feature does and how to configure it, see Portal configuration overview in the XBOX developer documentation.

Shared behavior

Seller and sandbox

Every command except the schema commands takes --seller-id. Without it, a command uses XBOX_SELLER_ID or the seller saved with xbox context set, and then your only seller; if you have several, pass --seller-id. config status and config publish take --sandbox-id from XBOX_SANDBOX_ID or the saved sandbox-id when you leave it out. config download and config save need --sandbox-id on the command line for sandbox documents.

Title targeting

config list, config status, config publish, and sandbox-scoped config download and config save take the title’s service configuration identifier (SCID) with --scid, or its XBOX title ID with --title-id, but not both. With neither, they use XBOX_TITLE_ID or the saved title-id; see Context. --scid ignores both.
  • --title-id is hexadecimal, as game get shows it: 00000001 through 7FFFFFFF, with an optional 0x prefix. For other title IDs, pass the SCID.
  • Reads of a title bound to another title’s configuration use the primary title’s SCID.
  • config save and config publish by a bound title’s ID are refused, even with --validate-only (bound_title_requires_scid). The error names the primary title and SCID; rerun with that --scid.
  • Saving or publishing by --title-id to configuration that other titles are bound to changes it for all of them. At a terminal, the CLI lists the bound titles and asks first; without one, it fails. --allow-shared-configuration skips the question. A write by --scid doesn’t ask.
  • config save and config publish write the seller and SCID they used to stderr. Read commands do with --verbose.
These commands save a title ID, then use it to read, download, and validate that title’s configuration in XDKS.1. The last one names the title with --title-id instead:

Output

Every xbl command accepts --output table as well as json (the default) and json-compact. Each command’s options table lists its table columns.

Errors

A failed request exits 1 and writes a JSON error to stderr with status, title, detail, and code when the service sends one. Branch on status or code, not on the wording of detail. A 429 error includes retryAfterSeconds; see Rate limits. When XBOX services validation rejects the configuration, the error lists each message under validation:
config save and config publish without --validate-only say whether a failed change could have been applied: On exit 3, don’t resubmit. stderr prints a read-only command to check with: for a save, config download --view draft, to compare with the files you saved; for a publish, config status.

config

Inspect, download, save, and publish XBOX services configuration for one SCID. A sandbox holds a working configuration, which config save changes, and a published configuration, which players and test accounts see once config publish makes the working configuration live.

config list and config status

Both commands report the latest working and published versions, each version’s commit time, and whether the working version has unpublished changes. A published commit time is the commit time of the published version, not when the publish finished. config list returns an array with one object per sandbox. config status returns one object for one sandbox, and adds its last publish under lastPublish, or null when there’s none to report. For --sandbox-id ALL, lastPublish is always null, because the title-wide configuration in ALL goes live through a publish to HIDDEN.

config list options

config status options

Both commands’ tables have the columns SANDBOX, WORKING, WORKING COMMIT, PUBLISHED, PUBLISHED COMMIT, and UNPUBLISHED. config status adds PUBLISH STATUS, the last publish’s status.

config list and config status examples

config download and config save

Download, validate, and save XBOX services configuration document sets. A document set belongs to a sandbox (the default, which needs a SCID or title and --sandbox-id) or to the account (--type account, which takes no SCID, title, or sandbox). config download saves the document set’s ETag next to the documents, as <sandbox>.etag, or Account.etag for account scope; on Windows the file is hidden. config save reads the ETag file next to the first file --file matches, and rewrites it after a save. If the configuration changed since you downloaded it, the save fails; pass --force to save over those changes, or --etag to supply an ETag yourself. config save doesn’t ask before it saves, and --confirm doesn’t apply to it. Run it with --validate-only first.

config download options

config save options

When XBOX services can’t save the documents (CanCommit false with --validate-only, otherwise Committed false), the command still writes the result to stdout, writes each validation message to stderr, leaves the ETag file unchanged, and exits 1:
Documents that match the latest working ones aren’t a failure: nothing is saved, ValidationInfo reports FilesNotChangedCommit, and the command exits 0.

config download and config save examples

Download the latest draft sandbox documents into xbox-config:
After you edit the documents, validate them all, or only the two you changed:
Save them with a message:
Download one document as it was in published version 7:
Download the account’s draft documents:

config publish

Publish a working version of XBOX services configuration to a sandbox’s published configuration. Publishing is asynchronous: start it with config publish, then run config status for the destination sandbox until lastPublish.status is Success or Failed.

Source selection

--sandbox-id is the destination. The source is a working version of the source sandbox, which defaults to the destination: When the source sandbox has unpublished changes, its latest working version isn’t what’s live there. A cross-sandbox publish without --configset then warns, and names the version that’s live:
To promote exactly what’s live in the source, run with --validate-only first and add the --configset it suggests. In the JSON output, SourceVersion is the working version used, sourceHasUnpublishedChanges says whether it differs from what’s live in the source, and sourceLiveVersion is the version that’s live there, when one is found. A title-wide publish, --sandbox-id HIDDEN, always publishes the latest working configuration in ALL, so it takes no --source-sandbox-id or --configset. To see which version goes live, run config status --sandbox-id ALL first and read workingVersion.

Confirmation

config publish asks before it publishes in these cases: At a terminal it describes the publish and asks. Without a terminal it refuses and exits 1. --confirm (--yes, -y) skips the question, and --validate-only never asks. See Safety and destructive operations. Before it asks about a RETAIL publish, it validates the publish and lists the achievements it adds. If you answer yes, it publishes the working version it validated, so what goes live is what was listed:
When that validation fails, it publishes nothing and doesn’t ask. So at a terminal, a RETAIL publish by --title-id to configuration other titles are bound to needs --allow-shared-configuration. With --confirm there’s no list, so run --validate-only first to see it.

Achievements a RETAIL publish adds

Once achievements are live in RETAIL, they can’t be removed, and their unlock rules and gamerscore can’t change. So a RETAIL publish says which achievement IDs it adds that RETAIL doesn’t have yet:
  • With --validate-only, the list goes to stderr, and the JSON output carries it in achievementChanges.added.
  • At a terminal without --validate-only, the list comes before the question, as shown in Confirmation.
A publish that adds none says so. Other sandboxes don’t list achievements.

Republishing

config publish publishes only changes. When nothing changed since the destination’s last successful publish, no publish starts, and the result’s Status is AlreadyPublished. After a publish fails, running config publish again retries it. Sometimes XBOX locks RETAIL for a product, and a RETAIL to RETAIL publish then fails with retail_locked. To publish anyway, add --republish: it forces the selected configuration, by default RETAIL’s latest working configuration, onto RETAIL. Publishing to RETAIL from another sandbox, such as CERT, also clears the lock, but it replaces RETAIL’s working documents with that sandbox’s. --republish publishes in full, even when nothing changed. It can’t be combined with --validate-only.

Diagnostics

Validation diagnostics from XBOX services, such as the warning for a first RETAIL publish without an embargo, go to stderr, one per line. The JSON output keeps them in ValidationResult.
When validation fails, config publish exits 1 and lists each message under validation, as shown in Errors.

Cross-sandbox publishing replaces global title storage files

Publishing from one sandbox to another makes the destination’s global title storage files an exact copy of the source’s. Files only the destination has are deleted, and can’t be recovered.
Global files are the files every player of the game reads, such as news feeds and maps: The copy takes whatever the source holds when the publish runs. Players’ own data isn’t touched, and a same-sandbox publish leaves global files alone. To keep a destination file, add it to the source sandbox before publishing. Every cross-sandbox publish writes this warning to stderr, including with --validate-only, and includes it in the confirmation question:

config publish options

config publish examples

Validate a publish to SANDBOX1 without publishing:
Publish SANDBOX1’s latest working configuration, so it’s live in SANDBOX1:
Publish SANDBOX1’s latest working version to SANDBOX2. This also replaces SANDBOX2’s global title storage files with SANDBOX1’s:
Publish working version 42 of SANDBOX1 to SANDBOX2:
Validate a publish from CERT to RETAIL, which lists the achievements it adds:
Then pass the output’s SourceVersion as --configset to publish the version you validated, without a prompt:
Publish SANDBOX1 again although nothing changed:
Check the publish to SANDBOX2:

schema

Discover and download XBOX services configuration document schemas.

schema list options

schema get options

schema get writes one JSON object:

schema download options

Each schema is saved as <type>_<version>.xsd, with the type in lowercase, and the command prints the saved paths. With --dest -, it writes the raw XSD to stdout instead, and --output doesn’t apply.

schema examples


A typical configuration round trip

  1. Find the sandboxes you can reach:
  2. See where working and published configuration stand:
  3. Download the draft document set, which also saves SANDBOX1.etag:
  4. Edit the documents in xbox-config, then validate them:
  5. Save them:
  6. Publish them in SANDBOX1:
  7. Check the publish, and repeat until its status is Success or Failed:
Last modified on November 18, 2026