Upload Command

Use vizzly upload when your screenshots already exist on disk.

vizzly upload ./screenshots

This is the simplest path for custom tooling, archived screenshot folders, or test runners that already write image files.

What it does

scans the path you pass in
uploads screenshots to Vizzly
attaches git metadata when it can
can wait for comparisons with --wait

You need a project token for upload mode: pass --token, set VIZZLY_TOKEN, or link the checkout with vizzly project link. A user login alone is not enough for uploads.

Screenshot names and image limits

The cloud screenshot requirements apply to images from disk too. Filenames also need to follow your operating system’s rules.

Fix an upload error

An oversized screenshot gets an error like this:

Image dimensions 1280×60001 exceed the 60,000-pixel limit per dimension

Capture a smaller region or split the page into named sections. If the error says the format isn’t supported, export a PNG, JPEG, or WebP. If the image is incomplete or can’t be decoded, capture it again and check that you can open the file before retrying.

Saving the same image with a different encoder changes its file hash (SHA), even when it looks identical. That means Vizzly needs to upload the new file instead of reusing the stored copy. It won’t help with a dimension error unless you also resize the image.

API error codes

If you’re calling the SDK API directly, read error for the explanation and details.code to handle the failure in your code:

Code	What went wrong
`IMAGE_DIMENSIONS_EXCEEDED`	The image is wider or taller than 60,000 pixels.
`IMAGE_TOO_LARGE`	The image exceeds 50 MiB.
`INVALID_IMAGE_BASE64`	`image_data` isn’t valid base64.
`EMPTY_IMAGE`	No image bytes were supplied.
`UNSUPPORTED_IMAGE_FORMAT`	The file isn’t a PNG, JPEG, or WebP.
`INVALID_IMAGE_CONTAINER`	The image file is incomplete or malformed.
`MULTIPAGE_IMAGE`	The file contains animation or multiple pages.
`IMAGE_DECODE_FAILED`	The server couldn’t decode the image.

Common examples

vizzly upload ./screenshots --wait
vizzly upload ./screenshots --build-name "Release candidate"
vizzly upload ./screenshots --parallel-id "$CI_RUN_ID"

Options people use most

--wait
--build-name
--environment
--branch
--commit
--message
--threshold
--parallel-id
--upload-all
--batch-size
--upload-timeout
--metadata

--upload-timeout controls how long --wait polls for build processing. It does not change the screenshot upload HTTP timeout.

If you need the full option list, run:

vizzly upload --help

A note on `--wait`

--wait keeps the command open until comparisons finish and prints the result summary.

If you want Vizzly to wrap your test command directly instead of uploading a folder afterward, use vizzly run.