audience commands list and get a
seller’s audiences, create known-user audiences, and rename one or replace its members. To let an
audience join a playtest, pass its id to playtest create or playtest update; see
Choosing audiences.
audience is Experimental: its commands, options, and output might change or be removed. See
Experimental commands. Listing and getting audiences needs Partner
Center’s customer groups Read permission for the seller, and creating and updating them needs
Write.
Commands
The CLI can’t delete an audience or change its type; do that in Partner Center.
Arguments and options
Output
audience get writes one audience:
audience list writes an audiences array of the same objects, without members, and
{"audiences":[]} when there are none. create and update write the audience as get does.
With --output table, every command shows ID, NAME, and TYPE columns, where TYPE is
groupType. Members are in JSON output only.
Creating an audience
--members-file, the audience has no members. Each run creates a new audience, even when
one with the same name exists.
Updating an audience
Pass--name, --members-file, or both; what you leave out is kept. This renames an audience:
testers.txt:
Members files
A members file is UTF-8 text with one email address per line, up to 1000 members:Exit codes
create and update send their request once. After exit 3, check before you run the command
again:
- After
create, run thexbox audience list --namecommand that stderr shows. A match is only a hint, because names don’t have to be unique, and runningcreateagain can create a second audience. - After
update, runxbox audience get <audience-id>to check its name and members.
Errors
Errors go to stderr as text, whatever--output is, with the correlation ID, guidance for the
HTTP status, and the service’s error detail when there is one. --verbose adds the service’s
response, which can include members. Scripts should branch on the exit code, not the wording.
A 403 can mean a missing permission, that you don’t belong to the seller, or that playtests
aren’t enabled for it. On list and get, a refusal can instead appear as a 502; check the error
detail for the cause. Creating and updating audiences is rolling out and might not be available
to you yet; until it is, create and update fail without changing anything.
