Getting started
First upload
Upload a folder of screenshots with the CLI and see the build appear.
You need three things: a folder of PNG screenshots (any test tool will do; Playwright's page.screenshot({ path: 'screenshots/home.png' }) is enough), your CirCI address and the project's CI token.
-
Set your address and token. The project's Settings › CI token page shows this snippet with your address filled in.
Terminal window export CIRCI_API_URL=http://localhost:3000export CIRCI_TOKEN=circi_… -
Upload the folder and wait for the result.
npx circi upload ./screenshots --wait -
Open the project in the dashboard. The build is there, with its screenshots counted by state.
What the CLI does
Section titled “What the CLI does”- Every
*.pngunder the folder is a screenshot, named by its path:settings/profile.pngbecomessettings/profile. Hidden folders andnode_modulesare skipped; symbolic links are followed. - An optional
<file>.png.jsonnext to a screenshot adds metadata (browser, viewport, test name). - A screenshot can be at most 25 MB.
- On a CI it recognizes, it reads the commit, branch and pull request itself. Locally it uses git. Override with
CIRCI_COMMIT,CIRCI_BRANCH,CIRCI_PR_NUMBERandCIRCI_BASE_BRANCH. - It retries network errors and server errors (5xx) with growing waits, and prints how many screenshots it found.
With --wait it then waits for the result and exits 0 (passed), 1 (changes need review) or 2 (error). Every flag is in the CLI reference.
What you see
Section titled “What you see”The first build of a project has nothing to compare with, so every screenshot is Added and the build waits for review. With no git host linked, --wait exits 1 until you approve.
Next: First review.