Robert DeLuca February 5, 2026 Updated September 27, 2026 2 min read

A CLI Can Work for People and Agents

Structured CLI output and API schema discovery make Vizzly useful in scripts and coding tools.

We built an MCP server so coding tools could read Vizzly results. I never loved maintaining a separate integration for information the CLI already had.

The GitHub CLI showed me a better fit. Run a command, ask for JSON, and use the result in a script or give it to an agent. Vizzly’s CLI now also lets agents discover the supported API requests.

Discover what the API can do

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

The first command lists supported operations. The second shows the method, request fields, and response shape for one operation. Use those details when you make a request:

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

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

Use JSON in scripts

Common commands already return structured output:

vizzly orgs --json
vizzly projects --org acme --json
vizzly builds --branch main --limit 1 --json

Successful output goes to stdout. Progress output goes to stderr. The API response is under data.response:

vizzly api /api/sdk/builds \
  --header 'Vizzly-API-Version: 2026-09-12' --json | jq '.data.response'

Inspect a visual change

Use the schema to find requests for build, screenshot, and comparison data. When a request returns an image, save it to a file with --output so an agent can open it.

Local TDD results are available without cloud authentication:

vizzly context build current --source local --json

The context build --agent and context comparison --agent options are deprecated in CLI 0.37.x and will be removed in 0.38.0. Use the API schema for cloud requests.

Take review actions deliberately

The CLI has commands for approvals, rejections, and comments:

vizzly approve <comparison-id>
vizzly reject <comparison-id> --reason "Unexpected layout shift"
vizzly comment <build-id> "The mobile spacing needs another look"

These actions update review state. Keep them in the workflow when someone asks for the review decision. Agents can inspect evidence and explain what they find.

CLI scripting and API guide