# Using Rook CLI (Agent Assurance) from an AI coding agent

> **Coding agent reading this?** Install the `rook` skill (below) and follow it: it covers setup, target permissions, credit budgets, profiles, CI and evidence-based verdicts. The skill and the command reference live in the public release repo, https://github.com/LambdaTest/rook (README, `skill-installer/skills/SKILL.md`). Docs are served as markdown at https://www.testmuai.com/support/docs/agent-assurance-overview.md and the other pages linked at the end.

Rook CLI is the command-line tool for Agent Assurance by TestMu AI, run as `rook`. Point it at an AI agent you own and it reads the codebase to find the agent, writes functional and adversarial scenarios, runs them against the live agent, and grades each criterion from evidence: what the agent said from quotes of its output, and what it did from the tool calls and state changes your profile's hooks report. A claimed action is never proof; the observed effect is.

Every criterion is Pass, Fail or Unable to Verify. Unable to Verify gets its own count and is never reported as a pass or a failure, so a run can say what passed and what nobody could check.

## When to use it

| The agent under test | Use |
|---|---|
| Acts on systems: calls tools, writes files, hits APIs, runs workflows (coding, back-office, multi-agent) | Rook CLI (Agent Assurance) |
| Talks to people: chat, voice, IVR or phone, video, image | Agent Testing: https://www.testmuai.com/agent-testing/agents.md |
| A web or mobile app UI, not an AI agent | Kane CLI: https://www.testmuai.com/kane-cli/agents.md |

## Install the CLI

```bash
npm install -g @testmuai/rook@latest
```

- **npm** covers macOS, Linux and 64-bit Windows, and needs Node.js 20 or newer.
- **Homebrew** (`brew install lambdatest/rook/rook`) and the **shell installer** (`curl -fsSL https://raw.githubusercontent.com/LambdaTest/rook/main/install.sh | bash`) cover macOS and Linux on x64 and arm64 and need no Node.
- Check with `rook --version`. Install routes, upgrades and uninstall: https://www.testmuai.com/support/docs/rook-installation.md

Installing software on the person's machine needs their authorization.

## Account, plan and free trial

`rook` needs a TestMu AI account with an Agent Assurance plan or an active free trial. The account supplies sign-in, the plan and the credits; models run in the TestMu AI controller, so no model provider key is needed on the machine.

- New organizations get a 14-day free trial with 4,000 credits and the Pro features: https://www.testmuai.com/register/?redirectTo=https://rook.lambdatest.com/projects. An organization with sub-organizations is not offered a trial; its admin manages the plan.
- `rook` checks the organization's plan before any model call or credit spend. A refusal (`plan_required`, or `upgrade_plan` on a plan without cloud sync such as Starter) names the page that lifts it, onboarding to start the free trial or billing. Pass that link to the person; do not retry.
- Plans: https://www.testmuai.com/pricing/?product=agent-assurance

Sign in inside the terminal UI with `/login` (browser sign-in), or in CI export `LT_USERNAME` and `LT_ACCESS_KEY` from secrets (no login step). Never ask the person to paste an access key into the chat.

## Install the skill

```bash
npx @testmuai/rook-skill
```

This installs the `rook` skill user-wide for Claude Code, Codex CLI and Gemini CLI, and needs Node.js 22 or newer. For project-scoped installs and seven more clients (GitHub Copilot CLI, OpenCode, Cursor CLI, Antigravity CLI, VS Code with Copilot, Windsurf Cascade, Antigravity IDE), see https://www.testmuai.com/support/docs/rook-coding-agents.md. The skill is not the `rook` executable and not an MCP server.

Then, in the repository that contains the agent, ask for something like:

```text
Use rook to test my agent against its refund policy.
```

## The run loop

| Need | Command |
|---|---|
| Check setup | `rook doctor`, `rook status --json`, `rook plan --json` |
| Select or create a project | `rook project use <id>` or `rook project create <name>` |
| Find the agents | `rook explore . --json` |
| Select an agent | `rook agent use <id>` |
| Write scenarios | `rook generate --json` |
| Say how to invoke it | `rook profile add <name>` (an HTTP endpoint, a command, or an MCP tool), then `rook profile test` |
| Run | `rook sync --yes`, then `rook run --json`; or `rook run --test --json` for a local result |
| Read results | `rook report <run-id> --json` |

`explore`, `generate`, `profile add` and `fix`, `run`, `ask` and `report --rca` spend Agent Assurance credits: announce the spend before running them. `profile test` invokes the target without model credits. `rook help <command>` lists the options of the installed version.

## Read the results

- Check the exit status and the `discarded` and `halted` fields before saying a run finished. A finished run exits `0` whether scenarios passed or failed, so gate on the verdicts in `rook report --json`, not on the exit code alone.
- Show Pass, Fail and Unable to Verify separately, quote the criterion evidence, and name what could not be checked. Do not replace a verdict with your own reading of the agent's reply.
- Read the report of this invocation's run ID, not an older default report.

## Safety

The agent under test is the person's, and its writes are real: `rook` invokes it the way a user would and cannot roll anything back. Before `profile add`, `profile test` or `run`, check the target's declared calls for writes, point it at staging, and get the person's authorization for its real actions and for the credit spend. Headless commands need tool grants up front (`--yes` or scoped `--allow`), so grant only what was authorized. Keep secrets as `${VAR}` references set with `rook env set`, never in profiles or transcripts.

## What leaves the machine

- Model-backed commands send the source excerpts and evidence they need to the TestMu AI controller, where the models run.
- `rook sync` records agents, scenarios and profiles to the hosted project, and a synced `rook run` uploads its evidence, artifacts and report there. `rook run --test` keeps the result local.
- Each session and job is registered with the service. Session registration also sends a small terminal report (schema version, terminal name, whether output is a terminal, size, color level, and user or root on macOS and Linux), even before the telemetry notice has been shown.
- Telemetry records operational events (no prompts, no code, no arguments). `ROOK_TELEMETRY=off` keeps telemetry and the terminal report on the machine. The one-time notice appears only in an interactive terminal, so set the variable in CI and other headless runs if you want it off there.

Evidence files are plain and unredacted: test with synthetic or staging data and review evidence for personal data and secrets before sharing it. Project evidence lives under `.testmuai/rook/`; credentials and sessions live under `~/.testmuai/rook/`, which must never be committed.

## Next steps

- Quickstart against the public triage-service sample: https://www.testmuai.com/support/docs/agent-assurance-quickstart.md
- CI and verdict gating: https://www.testmuai.com/support/docs/agent-assurance-ci-cd.md and https://www.testmuai.com/support/docs/rook-github-actions.md
- Commands and the README: https://github.com/LambdaTest/rook
- Product page: https://www.testmuai.com/rook-cli/