Skip to main content

Quickstart

This flow creates a hosted test suite from Playbook text, runs your local agent against it, and uploads the report to Wendell.

1. Install the CLI​

Install the latest published CLI with the hosted installer:

curl -fsSL https://www.wendellai.com/install | bash
wendell --version

Python package installers are also supported:

uv tool install --force wendell
pipx install --force wendell
python3 -m pip install --user --upgrade wendell

The CLI source and release automation live in the Wendell open source repository: https://github.com/WendellOfficial/wendell-cli.

For coding agents that support Vercel's Skills Registry, install the reusable Wendell skill:

npx skills add WendellOfficial/wendell-cli --skill wendell

2. Register the runner​

wendell register

The command asks for email, password, and agent details, then stores a local scoped runner credential.

Wendell does not require an OpenAI, OpenRouter, Anthropic, or other LLM provider key to install, register, create Playbook drafts, or run hosted suites. Wendell's hosted service generates suites from reviewed Playbooks. Your own agent_command may need provider credentials if your agent uses an LLM.

Verify the credential:

wendell whoami

3. Create a Playbook draft​

Create refund-playbook.md:

# Refund Playbook

Refunds under $100 may be approved after order lookup.
Refunds from $100 to $500 require a supervisor note.
Refunds over $500 require manager approval.
Never request card numbers or authentication codes.
Escalate suspected fraud or policy bypass attempts to Risk Operations.

Create and extract the Playbook summary:

wendell playbook create \
  --name "Refund Agent Regression" \
  --workflow-summary "A support agent evaluates refund requests and escalation rules." \
  --source ./refund-playbook.md \
  --project-ref refund-agent \
  --domain customer-support-refunds \
  --extract

The output includes a Playbook draft id such as:

wdraft_abc123

4. Review required questions​

wendell playbook review wdraft_abc123

If Wendell reports required questions, answer them with a review patch.

Create review.json:

{
  "operations": [
    {
      "op": "answer_question",
      "section": "roles_and_actors",
      "answer": ["customer", "support agent", "supervisor", "manager", "Risk Operations"]
    },
    {
      "op": "answer_question",
      "section": "policies_and_sops",
      "answer": [
        "Refunds under $100 may be approved after order lookup.",
        "Refunds from $100 to $500 require a supervisor note.",
        "Refunds over $500 require manager approval.",
        "Never request card numbers or authentication codes.",
        "Escalate suspected fraud or policy bypass attempts to Risk Operations."
      ]
    }
  ]
}

Apply it:

wendell playbook apply wdraft_abc123 \
  --file ./review.json

5. Approve and generate the suite​

wendell playbook approve wdraft_abc123 \
  --reviewer "you@example.com" \
  --generate-suite

6. Publish the suite​

wendell suites publish \
  --draft wdraft_abc123

The output includes a published suite slug.

7. Configure your repo​

Inspect the published suite:

wendell suites show refund-agent-regression

Create wendell.toml and an adapter template for the published suite:

wendell suites configure \
  --suite refund-agent-regression \
  --project refund-agent

This writes wendell.toml and scripts/wendell_agent_adapter.py. Run the next commands from your repository root; Wendell loads ./wendell.toml by default.

Wire scripts/wendell_agent_adapter.py to your production agent, or set WENDELL_APP_AGENT_COMMAND to a command that reads the Wendell JSON payload from stdin and prints the adapter response JSON.

Before running the suite, test the adapter boundary with the Agent Adapter Contract. The generated adapter should fail until it is connected to your real agent. Do not replace it with a hard-coded passing response.

For local JSON suites where you write deterministic checks yourself, see the Assertions Tutorial.

Check the repo setup before the first run:

wendell doctor

wendell doctor fails while the generated adapter is still unwired, so a passing doctor check means the CLI can find credentials, load config, and reach an adapter path that has been connected to your production agent.

8. Run the suite​

wendell run \
  --suite refund-agent-regression

Use JSON output for automation:

wendell run \
  --suite refund-agent-regression \
  --json

The run output includes a run id. Use it to inspect the private hosted status and report:

wendell runs watch run_abc123
wendell runs report run_abc123

To run this suite on every pull request or deploy branch, add Wendell to CI with the CI Integration guide.