Installation

Roleplay requires Node.js 20 or newer.

Install Globally

npm install -g @roleplay-sh/cli
roleplay --help

The included local runner is packaged as the roleplay CLI. Public installation remains available for setup and smoke tests, but meaningful workbench usage starts with a workspace, project, and project API key.

Run Without Installing

npx @roleplay-sh/cli --help

You can also use pnpm dlx in CI:

corepack pnpm dlx @roleplay-sh/cli --help

Set Up A Project

From the repository where your agent lives:

roleplay setup

roleplay setup guides Workbench URL, project ID, provider, judge mode, target, and safe placeholders. For non-interactive setup, use:

roleplay init

These commands create:

.roleplay/
  config.json
  scenarios/
  runs/

It also creates starter scenarios when they do not already exist.

Environment Variables

Create or update .env with any values your agent and Roleplay need.

# Optional credentials used by your own HTTP or CLI target.
AGENT_API_KEY=

# Workbench upload settings. Fill these only after onboarding creates a project and API key.
ROLEPLAY_CLOUD_URL=https://app.roleplay.sh
ROLEPLAY_PROJECT_ID=
ROLEPLAY_API_KEY=
ROLEPLAY_AGENT_NAME=

# Bring-your-own provider for real adaptive runs.
ROLEPLAY_LLM_PROVIDER=<provider>
ROLEPLAY_JUDGE_MODE=hybrid
ROLEPLAY_JUDGE_PROVIDER=<provider>
ROLEPLAY_<PROVIDER>_API_KEY=

# Built-in attack-pack target. Set exactly one.
ROLEPLAY_TARGET_URL=
ROLEPLAY_TARGET_COMMAND=

Use provider-specific key variables only for the provider you choose. ROLEPLAY_LLM_API_KEY is also supported for generic and OpenAI-compatible provider setups.

Verify Local Setup

roleplay doctor

If you are checking the workbench locally:

roleplay doctor --cloud --cloud-url http://127.0.0.1:3000

With project credentials from a real workbench project:

ROLEPLAY_CLOUD_URL=https://app.roleplay.sh \
ROLEPLAY_PROJECT_ID=<project-id> \
ROLEPLAY_API_KEY=<project-api-key> \
roleplay doctor --cloud

Local Development From Source

If you are working inside the Roleplay repository:

corepack enable
pnpm install
pnpm build
pnpm dev --help

Use source commands only when developing Roleplay itself. Public user docs use the installed roleplay CLI.