What you need first
- An access key. Create one under Account > Developer with Create access key. It inherits your permissions, so it can only do what your role already allows.
- The CLI installed and authenticated. See the CLI quickstart.
- Your
studioId, fromuserplay studios list.
The playbook
1
Create the draft
Run
playtests create with your type, name, and session count.minSessionDuration and sessionCooldown are in seconds. --maxPlayers makes the playtest open, capped at that number. Omit it for a roster-only playtest.Playtests
Every playtest command, argument, and flag.
Access
What
--maxPlayers sets, and what omitting it commits you to.2
Turn on the components you need
Run Each flag reveals its tab in the studio editor, where the content goes.
playtests update with a bare flag per component.These are the same master toggles as the Config tab: NDA, build distribution, key distribution, briefing, objectives, survey, screening, and recording.
Modifying a playtest
Which of these stay editable after the draft leaves your script.
Gameplay recording
The tab
--recordingEnabled reveals, and what still needs a human.3
Seed the roster
Run
playtests import-players with the group IDs you want copied in.Seeding from a raw list instead
Seeding from a raw list instead
add-players and replace-players both take an emails array, capped at 250 per call.Build a group you can reuse
Playbook: create the groups
import-players draws from.Player groups
Custom groups against backing groups, and which ones you can import.
4
Attach keys
Run one of the two key commands. Either way the keys land in the playtest’s own system vault, on its Keys tab.
- From an existing vault
- From raw values
userplay playtests import-keys copies keys across, scoped to all, available, or unredeemed.Key distribution
The system vault these keys land in, and its limits.
Migrate your key inventory
Playbook: split a large inventory across vaults first.
5
Hand it back to a human
Open the draft in the studio.
- Click Preview in the editor header and walk the flow you scripted.
- Click Publish.
Cloning instead of building from flags
duplicate copies an existing playtest’s configuration into a fresh draft, and --copyRoster brings the players along. Usually less work than rebuilding from flags.
How you know it worked
userplay playtests get <studioId> <playtestId>returns astageofdraft, with the components you enabled showing as turned on.userplay playtests list-playersreturns the roster you seeded, at the count you expected.userplay playtests key-vaultshows the playtest’s system vault holding your keys.- The draft shows up in the studio, and the editor displays exactly the tabs your toggles revealed. If a tab you expected is missing, a toggle did not take.
Related articles
Automate with the API
Keys, authentication, pagination, and getting data back out.
CLI command reference
Every command, argument, and flag.
Playtest types
What each type commits you to before you script it.
Launch a playtest
The publish step, where the script hands off to a person.