Skip to main content
When a request fails, the CLI prints the API’s error: a stable code, a message, and usually a one-line hint. This page maps each code to what you should try, then covers problems that come from the CLI itself rather than the API.

Error codes

The CLI surfaces the same error envelope and retry rules as the API.

Authentication and access

Request problems

Limits and versions

Common issues

userplay: command not found after installing Your global npm bin directory is not on your PATH. Reopen your terminal, or re-run npm i -g @userplaylabs/cli and check where npm put it with npm bin -g. Still unauthorized right after logging in USERPLAY_API_KEY in your environment outranks the account you logged in as. If it holds an old key, that old key is the one being sent.
Every write is blocked USERPLAY_READONLY is set. It refuses any non-GET request before it leaves your machine.
A write in a script exits with “Aborted” Production writes ask for confirmation, and a script has no terminal to answer with, so the prompt fails closed. Pass --yes:
Commands are hitting the wrong API Each account carries the API URL it logged in against. Check where you are pointed, then switch or re-point:
Where state lives covers overriding the URL per command.

Still stuck

Send us the command you ran and the error you got:

Errors

The envelope, and how to branch on a code in your own client.

Global options

The agent-mode failure contract a script can parse.

Authentication

Accounts, keys in CI, and where credentials are stored.

Rate limits

The per-key budget behind a 429 in the terminal.