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 theschema 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-idis hexadecimal, asgame getshows it:00000001through7FFFFFFF, with an optional0xprefix. For other title IDs, pass the SCID.- Reads of a title bound to another title’s configuration use the primary title’s SCID.
config saveandconfig publishby 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-idto 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-configurationskips the question. A write by--sciddoesn’t ask. config saveandconfig publishwrite the seller and SCID they used to stderr. Read commands do with--verbose.
--title-id instead:
Output
Everyxbl 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 withstatus, 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, whichconfig 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:
ValidationInfo reports FilesNotChangedCommit, and the command exits 0.
config download and config save examples
Download the latest draft sandbox documents into xbox-config:
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:
--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:
--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 inachievementChanges.added. - At a terminal without
--validate-only, the list comes before the question, as shown in Confirmation.
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 inValidationResult.
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.
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:
SourceVersion as --configset to publish the version you validated,
without a prompt:
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
-
Find the sandboxes you can reach:
-
See where working and published configuration stand:
-
Download the draft document set, which also saves
SANDBOX1.etag: -
Edit the documents in
xbox-config, then validate them: -
Save them:
-
Publish them in SANDBOX1:
-
Check the publish, and repeat until its status is
SuccessorFailed:
