Skip to content
Latest

Use the CLI with agents

Your agent can run visual tests, open screenshots, and read reviews from your checkout. Use vizzly tdd screenshots for saved local results and vizzly api for cloud builds.

Set up your agent

Terminal window
npx vizzly init --agent-guidance

This installs the Vizzly skill and adds a note to AGENTS.md. Run it again after updating the CLI to refresh the instructions. Your config and other notes stay put.

Check a local change

Run your project’s screenshot tests, then look at the results:

Terminal window
npx vizzly tdd run "npm test" --no-open --json
npx vizzly tdd screenshots list --status failed --json
npx vizzly tdd screenshots list --status new --json
npx vizzly tdd screenshots show <comparison-id> --image all --json

These commands read .vizzly/, so they work after the server stops and need no cloud login. Use an ID from list when a name has several browser or viewport variants. If hasNext is true, continue with the next --page and the same filters and --page-size.

show gives you image paths and saved comparison details. Check each image’s exists flag, then open the files. A new capture may have no baseline or diff. Use latest [name] when you just need the newest current image’s path.

Local failed means the image changed; error means the comparison couldn’t run. The saved report doesn’t tell you which Git commit produced it. If it might be old, rerun the tests.

When you’ve reviewed the change and want to keep it:

Terminal window
npx vizzly tdd screenshots accept <comparison-id> --json

This updates one local baseline. Ask your agent to accept it only when that’s part of the task. See TDD mode for the live dashboard.

Read a cloud build

Start with the API schema. You can browse it without signing in:

Terminal window
npx vizzly api schema --json
npx vizzly api schema sdk.listBuilds --json
npx vizzly api schema sdk.listBuildScreenshots --json

Use the method, path, headers, and inputs it returns with vizzly api. Add the API version header yourself. For data requests, use the login or project token the operation requires; --auth user selects your saved CLI login.

Find the build, then list its screenshots. A capture’s comparison_id can be null while processing or after a failure. Use sdk.getScreenshotImage for that capture, or sdk.getComparisonImage for a comparison’s current, baseline, and diff images. Save images with --output <new-file> and open them before explaining what changed.

The schema also lists requests for review state, regions, analysis, and comments. See API requests for those operations and pagination. In scripts, check the exit code first. API results are under data.response; local TDD results are under data.

Leave a review

Ask your agent to comment, approve, or reject when you’re ready. These actions need a user login with the right scope; project tokens can’t do them.

Look up the write operation before sending it. For actions that support commandId, use a new UUID per action and keep it with the same body for retries. If you’re unsure whether a write worked, read the current state first.

Vizzly discloses recognized agents on review and comment requests, including calls through vizzly api. Use --via-agent <slug> to name another agent or choose one when several are detected. You stay the author. See API requests for body options.