Skip to content
Vizzly Docs

CLI Scripting and API Access

The CLI gives scripts structured output for common commands. When you need cloud data that does not have a dedicated command, use the API schema to find a supported request.

Discover an API request

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

The operation details include the HTTP method, API version header, query parameters, request body, and response shape. Follow those details when you call the endpoint: Pass the version header with --header; the CLI does not add it automatically.

Terminal window
vizzly api /api/sdk/builds \
  --header 'Vizzly-API-Version: 2026-09-12' --json

Schema discovery does not need authentication. API requests use your Vizzly login or a project token in VIZZLY_TOKEN, depending on the operation.

The API command accepts query parameters, headers, and a JSON body:

Terminal window
vizzly api /api/sdk/builds --query limit=5 \
  --header 'Vizzly-API-Version: 2026-09-12' --json

Use the request method and body shown in the schema for operations that need them. Some operations change review state or add comments, so check the method before calling one.

Build context returns comparison IDs. Use getComparisonContext for review details, then sdk.getComparisonImage to save the current screenshot, baseline, or diff. Pass the image kind as the last path segment. Replace cmp456 with the comparison ID from the build response:

Terminal window
vizzly api /api/sdk/context/comparisons/cmp456/images/diff \
  --header 'Vizzly-API-Version: 2026-09-12' \
  --output diff.png

To download the full OpenAPI document:

Terminal window
vizzly api schema --full --output openapi.json

Parse JSON output

Successful JSON output goes to stdout; progress goes to stderr. Other command results are under data. API calls include the endpoint and method, with the response under data.response. Most commands accept comma-separated fields after --json:

Terminal window
vizzly builds --limit 1 --json id,status,branch
vizzly api /api/sdk/builds \
  --header 'Vizzly-API-Version: 2026-09-12' --json | jq '.data.response'

Check the exit code and error detail before using a result.

Read local TDD results

Local TDD context is available without cloud authentication:

Terminal window
vizzly context build current --source local --json

Use --json on other CLI commands when a script needs structured output. For example:

Terminal window
vizzly builds --limit 1 --json id,status,branch

About the old compact output

The --agent options for context build and context comparison are deprecated in v0.37.x and will be removed in v0.38.0. Use API schema discovery for cloud requests. Use vizzly context ... --json for local TDD results.

Next steps