xbox) is built to be run by AI agents and scripts as well as by people. Its
commands take explicit arguments, its data commands write JSON, and its errors go to stderr
with a nonzero exit code. This page is for agents, and for the people who set them up: how to
sign in, choose what a command acts on, read its output, and find the right API, and what to
ask before changing anything.
Before changing anything
The signed-in user usually has admin rights on production titles and sellers, and nothing on the server side stops a mistaken call. Safety and destructive operations lists what the CLI asks about and what it doesn’t. The rest is up to you:- Treat a PlayFab operation as read-only only if its name starts with
Get,List, orSearch. Treat every other operation, and everyxboxcommand that creates, changes, or deletes something, as a production change. - Before a production change, show the user the command and say in one sentence what it
changes and on which title or seller, including whether that target comes from saved
context. Run it only after they say yes, even if your runtime would run
xboxwithout asking. A yes covers only the calls you showed. - Pass the title or seller as a flag on every production change. Saved context is shared by every session of the OS user, so it can change between the user’s yes and your call.
- Ask before
xbox pc sandbox set, which switches the sandbox for everyone on the PC, and beforexbox pc sandbox launch-apps, which closes the Microsoft Store and XBOX app. - Don’t add
--confirm(or--yes) in place of asking. The CLI can’t tell who added it. - Before asking to publish to RETAIL with
xbox xbl config publish, run it with--validate-onlyand show the user the achievements it lists. Then publish with--configsetset to theSourceVersionin its JSON output. Achievements in RETAIL can’t be removed; see Achievements a RETAIL publish adds. - If a production change fails and its outcome is unknown, it might have been applied. Read the affected state before retrying; see An interrupted write reports that its outcome is unknown.
- Leave saved context alone unless the user asks you to change it.
xbox context set,xbox context unset, andxbox context profile deletechange the defaults for every session.
Signing in
auth status exits with code 0 and reports {"signedIn":false} when nobody is signed in, so
branch on signedIn. A nonzero exit means it couldn’t check, and the error is on stderr.
PlayFab calls fail unless the signed-in user has Admin permission on the title. See
Authentication.
Choosing the title or seller
Pass the title or seller as a flag, such as--playfab-title-id ABC123. Without one, a
command uses an XBOX_ environment variable or a value saved with xbox context set; see
Context for which wins. Run xbox context get --output json-compact to
see what’s saved, and confirm the title with the user once before calling anything
substantive.
Reading output
Combine--data-only and --output json-compact to get only the payload, on a single line:
--data-only, stdout is
empty on an error, so check the exit code before parsing stdout.
playfab file upload, download, and delete write nothing to stdout, and their stderr
messages might change, so check their exit code. See Files.
Help marks Experimental commands, whose interface might change. See
Experimental commands.
Rate limits
When an XBOX service answers HTTP 429, wait before trying again; the CLI doesn’t retry for you. When the service specifies a wait, the error says how many seconds, and structured errors also carry it asretryAfterSeconds. A 429 with error code rate_limited means you sent too
many requests in a short time, so slow down.
Finding the right PlayFab API
xbox playfab api <api-path> calls any PlayFab API operation. The path is
/<Prefix>/<Operation>, such as /MultiplayerServer/ListBuildSummariesV2, and the request
body is the operation’s JSON request object. PlayFab documents both:
- The PlayFab Swagger specs
are machine-readable. Each file lists its operations by path, with their request and
response schemas and required fields. The files are named for PlayFab’s API groups, not
for the path’s first segment, so search the files’
pathsfor the operation:/Catalogand/Inventoryare inEconomy.swagger.json, and/Match,/Lobby, and/MultiplayerServerare inMultiplayer.swagger.json. Each operation’ssecurityfield names the credential it accepts:SecretKey,EntityToken,SessionTicket, orNonefor operations that need no credential, such as player sign-in calls. Some operations also list their allowed entity token types in their description. - The PlayFab REST API reference covers the same operations for people.
SessionTicket, or accept only player or
game-server entity tokens, aren’t authorized. When a call fails, its error response usually names what’s wrong, such as
InvalidParameter or MissingParameter. See PlayFab API integration for
more.
In Git Bash on Windows, set MSYS_NO_PATHCONV=1 for the command, because Git Bash otherwise
converts the API path into a Windows path before the CLI receives it. See
Running from Git Bash on Windows.
Keeping secrets out of logs
- When a request body might hold secrets, pass it with
--body-filerather than--body, so it stays out of shell history and process listings.playfab mps certificate uploadandplayfab mps secret uploadrefuse--body, because their body always holds one. - Keep secrets out of configuration files and environment variables.
ClientId,TenantId, and OAuth scopes are identifiers, not secrets. - PlayFab responses can hold player, inventory, or economy data. Redacting, retaining, and controlling access to whatever an agent logs is up to the agent’s owner.
See also
- Commands: the full command reference
- Safety and destructive operations: what asks first, and what does more than its name says
