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
npx vizzly init --agent-guidanceThis 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:
npx vizzly tdd run "npm test" --no-open --jsonnpx vizzly tdd screenshots list --status failed --jsonnpx vizzly tdd screenshots list --status new --jsonnpx vizzly tdd screenshots show <comparison-id> --image all --jsonThese 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:
npx vizzly tdd screenshots accept <comparison-id> --jsonThis 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:
npx vizzly api schema --jsonnpx vizzly api schema sdk.listBuilds --jsonnpx vizzly api schema sdk.listBuildScreenshots --jsonUse 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.