--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.
Commands
batch create, batch update, and batch delete ask before they change anything, and are
sent once and never retried. See Safety and destructive operations.
Options for reading batches
Tags appear as
keywords in JSON output and in error codes such as
test_account_keyword_invalid. --tag matches a whole tag, not part of one.
If you can’t read every batch for the seller, you get no error: batch list returns only the
batches you created.
Expired batches
A batch is expired once itsaccessExpirationDate, the date its sandbox access ends, has
passed. A batch with no date never expires. Expiry doesn’t say whether the accounts can still
sign in.
batch list --expired reads the seller’s whole list to find the expired batches, so it’s
slower for a seller with many batches. It can’t be combined with --include-sandboxes; run
batch get on an expired batch to see its sandbox access.
Response shape
list returns:
keywordsandsandboxAccessarenullunless you pass--include-sandboxes.getalways returns them.isCompletemeans the creation job stopped, not that every account was created. Compare the number of accounts fromgetwithbatchSize, and readprogressfor the status message.createdByis a numeric Partner Center user ID.jobIdis the batch’s running job, and isnullonce the job has stopped. Update and delete jobs appear here too, but only a creation job can be followed withjob wait.
get returns the same batch object plus its accounts:
xuid, email, gamertag, and isDeleted. xuid is a string.
Errors when reading batches
batch list, batch get, and test-account get exit 1 on failure. When the service returns
a JSON error, stderr gets a JSON error with status, title, detail, code when the
response includes one, and its correlationId; most add a hint to detail. Other failures
print a line of text. Check the exit code before parsing stderr.
Looking up an account
test-account get <email> says whether the batch holding an account has expired. The email
must end with @xboxtest.com. The command searches the newest 10 batches whose email
template matches the account’s name. When it doesn’t find the account there, it says older
batches weren’t searched and prints batch list and batch get commands to check them
yourself.
It returns the following, shortened here; batch holds every batch field that batch list
returns:
expiredOn is null when the batch hasn’t expired. A deleted account is reported only when no
live copy exists, with account.isDeleted set. The command exits 0 whenever it finds the
account, expired or not, so scripts should read expired. It exits 1 when:
- The account isn’t in the batches you can see. It might belong to another seller, so try
--seller-id, or another developer created its batch and you can’t read every batch for the seller. - The email appears in more than one batch. stderr lists a
batch getcommand for each. - A request fails, as in Errors when reading batches.
Creating a batch
batch create starts a job that creates the accounts, then waits for it to stop. The accounts
count against the seller’s test account limit until the batch is
deleted.
In a terminal, the command shows the security question picker,
lists the values it will send, including the defaults for options you left out, and asks you to
confirm. It then prompts for the password and security answer, signs in, and sends
the request. --confirm (--yes, -y) skips only the confirmation.
Without a terminal, pass --password-file, --security-answer-file, and --confirm. Without
--confirm, the command prints the values, refuses, and sends nothing.
Choosing a security question
In a terminal, when you pass neither--security-question nor --security-answer-file, the
command shows a numbered picker of these questions. Enter selects the first. To choose one
without the picker, pass its text with --security-question:
- What is your favorite hobby?
- Who is your favorite athlete?
- What is your maternal grandmother’s first name?
- What was your childhood best friend’s first name?
- What was the name of your first pet?
- What is your current best friend’s first name?
- What was your favorite city to visit as a child?
What is your favorite hobby?. Ctrl+C at the picker cancels without creating anything.
Choosing a question doesn’t confirm the create.
Secrets
The password and security answer are never accepted as option values or environment variables, so they stay out of shell history, process listings, and logs. Each comes from:- Its
--password-fileor--security-answer-file. A single trailing line break is removed. -in place of a path, which reads it from stdin. Only one of the two can read stdin.- With no file option, a prompt in the terminal that doesn’t echo what you type.
Waiting and exit codes
While it waits, the command prints progress to stderr. It writes the final job to stdout, in the same shape asjob get.
When the outcome is unknown
When the CLI can’t tell whether the service created a batch, such as when the connection drops after the request is sent or the service returns a5xx error, it exits 3. It never sends the
create again. stderr prints the time the request started, in UTC, and these steps:
- Wait a few minutes; a batch still being created might not be listed yet.
- Run
xbox test-account batch list --mine --email-prefix <prefix>and look for a batch with the same email prefix and template created at or after that time. - If that batch’s
jobIdis set, follow it withxbox test-account job wait <job-id> --batch-id <batch-id>. IfjobIdisnull, the job has stopped; inspect it withxbox test-account batch get <batch-id>. - Create again only if no such batch exists.
Errors when creating
Failures write a JSON error to stderr withstatus, title, detail, and code when the
response includes one. Branch on code, not on detail.
Following a creation job
batch create prints the batch and job IDs as soon as the job is accepted. A job can run for
days, so you can stop waiting at any time and follow it later:
Both return the job:
state is running, succeeded, or failed. errorCode is test_account_job_failed when the
job failed. job wait retries temporary read failures, such as throttling or a dropped
connection.
Errors when following a job
These error codes point at the job ID,--batch-id, or --seller-id:
Updating a batch
batch update changes every account in a batch: it can give them access to more sandboxes,
take access away, move when that access expires, and add to or replace the batch’s tags. It
then waits until the batch shows the change.
In a terminal, the command first shows each requested change next to the batch’s current
value, warns when a job is still running on the batch, and asks. Pass --confirm (--yes,
-y) to skip the prompt. Without a terminal and without --confirm, it prints the changes,
refuses, and sends nothing.
Pass at least one change. A batch can have at most 20 tags.
--replace-tags and
--clear-tags keep the tag that records which tool created the batch, which doesn’t count
toward the limit. Changing sandboxes or the expiry needs access to those sandboxes;
extending the expiry needs access to every sandbox on the batch.
The command returns the batch’s values once the update completes:
state is updated once the batch shows the change, or updating with --no-wait or when
the wait ends first. When the batch already has every requested value, nothing changes:
state is unchanged, jobId is null, and the command exits 0. Update jobs can’t be
followed with job get or job wait.
Waiting and exit codes when updating
Errors when updating
A
404 or 405 with no code means updating batches isn’t available.
Deleting a batch
batch delete deletes a whole batch, then waits until it’s gone. Every account in the batch
loses its sandbox access, and its test account record is deleted. The accounts’ Microsoft
accounts and XBOX profiles aren’t closed.
In a terminal, the command first shows the batch’s email template, size, and creator, warns
when a job is still running on it, and asks. Pass --confirm (--yes, -y) to skip the
prompt. Without a terminal and without --confirm, it prints what it would delete, refuses,
and sends nothing. There’s no bulk delete; delete batches one at a time.
The command returns:
state is deleted once the batch is gone, or deleting with --no-wait or when the wait
ends first. Delete jobs can’t be followed with job get or job wait; while the delete runs,
the batch shows its jobId.
Waiting and exit codes when deleting
Errors when deleting
A
404 or 405 with no code means deleting batches isn’t available.
Table output
Every command accepts--output table. Times are shown in UTC, and summary lines go to
stderr, so stdout holds only the table.
