CLI scripting and API access
Full CLI reference for v0.40.0, published . Cloud features may behave differently today.
Request JSON
Add --json when your script needs JSON. Check the exit code first. Command
results are under data; API results are under data.response.
In JSON mode, run and tdd run send wrapped test output to stderr so stdout stays parseable.
Read local TDD results
npx vizzly tdd screenshots list --status failed --jsonnpx vizzly tdd screenshots show <comparison-id> --image all --jsonThese read the latest saved report without a server or cloud login. Use comparison IDs when names have several variants, and check each image's exists flag before opening it. If hasNext is true, use the next page with the same page size and filters.
If the saved report might be old, rerun your visual tests.
See TDD mode for captures and local review.
Read cloud evidence
Start by finding the request you need:
npx vizzly api schema --jsonnpx vizzly api schema sdk.listBuilds --jsonnpx vizzly api schema sdk.listBuildScreenshots --jsonnpx vizzly api schema sdk.getComparisonImage --jsonUse the method, path, headers, and inputs from the schema. Add the API version header yourself. Look up sdk.getBuildStatus for progress, sdk.listBuildScreenshots for captures, or visualReview.show for review state.
A capture may have a null comparison ID while processing or after a failure. Use its own image request until you have a comparison ID.
Save images and full analysis with --output <new-file>. It won't overwrite a file. Follow the operation's page fields with the same filters. See API schema and requests.
Check before writing
Check the request’s method, login requirements, and body before sending a review or comment. Do this only when the task asks for it. Project tokens can’t perform review writes.
Send JSON with --data @request.json or stdin using --data @-. If the action supports commandId, use a new UUID per action and keep it with the same body for retries. Read back the state if you're unsure what happened. The CLI doesn't replay writes automatically.
Use --auth user for your saved login. Review and comment requests disclose recognized agents automatically, including calls through vizzly api. Use --via-agent <slug> to choose the agent.