Skip to content

Upload from CI

CLI reference

Every flag, environment variable and exit code of the circi upload command.

The circi CLI (package @circi/cli) uploads screenshots and sites from CI. It's a different program from the circi server command inside the Docker image (see the admin CLI).

CIRCI_TOKEN=circi_… CIRCI_API_URL=https://ci.acme.io npx circi upload ./screenshots --wait

Uploads a directory of PNG screenshots as a build.

Flag Meaning
<dir> Directory with .png screenshots, searched recursively.
--name <name> Build name, for several kinds of builds per commit (default default). Letters, digits, ., _, -; at most 64. Each name has its own baselines.
--wait Wait for the result and exit non-zero when it should block the merge.
--shard <n/total> This job uploads shard n of total of one parallel build (for example 2/4). The build is processed once all shards arrive.
--nonce <id> Ties the shards of one parallel build together. Default: the CI job's run ID.
--gate <mode> Who blocks the merge: status (the git host's check; exit 0 on unreviewed changes) or exit-code (this job). Default: decided by the server from the project's settings.
--author <login> Who made the change (their login on the git host). Default: the CI actor (for example GITHUB_ACTOR).
--timeout <seconds> How long --wait waits (default 600).
--api-url <url> CirCI address. Default: CIRCI_API_URL.
--no-fetch Don't run git fetch to complete a shallow history.
--json Print the result as JSON (progress goes to stderr).

Global: --debug prints the stack trace of an unexpected error (or set DEBUG=1). --version and --help work as usual.

  • Every *.png under the folder is a screenshot, named by its path without the extension, using / on every OS (settings/profile.png is settings/profile).
  • Hidden folders and node_modules are skipped. Symbolic links to files and folders are followed; a link back up the tree is skipped.
  • At most 25 MB per screenshot and 10,000 screenshots per build.
  • An optional <file>.png.json file next to a screenshot adds metadata (browser, viewport, test name): a JSON object.
  • PNG only.
Variable Meaning
CIRCI_TOKEN The project's CI token. Required.
CIRCI_API_URL Your CirCI address, for example https://ci.acme.io. Required unless --api-url.
CIRCI_COMMIT, CIRCI_BRANCH, CIRCI_PR_NUMBER, CIRCI_BASE_BRANCH Override what is detected.
CIRCI_AUTHOR Same as --author.
CIRCI_PARALLEL_NONCE Ties shards together when the CI isn't recognized.
DEBUG=1 Stack traces.

CI detection covers GitHub Actions (for pull requests the head SHA from the event payload, not the merge commit), Gitea and Forgejo Actions, GitLab CI (merge request pipelines too), Bitbucket Pipelines, CircleCI, Buildkite, Jenkins and Azure Pipelines. For Jenkins, pass the pull request yourself unless you use the multibranch plugin (CHANGE_ID, BRANCH_NAME, CHANGE_TARGET are read).

The CLI collects the commit history CirCI needs to pick the baseline, from the head commit, never from HEAD (CI checkouts often sit on a synthetic merge commit).

  • Shallow checkouts are fine: it fetches the base branch and just enough history (and deepens up to 2,000 commits if needed). A full fetch is faster for large repositories.
  • In a full clone it never changes the repository's history; only an already shallow checkout is deepened.
  • --no-fetch turns this off. If it still can't find a merge base, the build page shows a warning and CirCI falls back to the default branch's newest eligible build.

--shard 2/4 uploads shard 2 of 4. Every job uploads its own screenshots; CirCI joins them into one build (they share the run's ID) and processes it when the fourth arrives. A shard that never arrives fails the build after UPLOAD_TIMEOUT_MINUTES (default 60), naming the missing shards. A re-run of the whole workflow is a new attempt and starts a new build. Vitest's --shard is picked up automatically by the Vitest plugin.

Code Meaning
0 Uploaded. With --wait: the build passed, or the git host's check is the merge gate.
1 With --wait: visual changes need review and this job is the gate. Approve them in the dashboard, then re-run the job.
2 An error: bad flags or setup, the server couldn't be reached, the build failed to process (the server's reason is printed), screenshots couldn't be read (see below), or --wait timed out.

--wait names each screenshot the server couldn't read and why. Whether that exits 2 or 0 is explained in How a build flows.

Errors print one line (error: No such directory: ./screenshotz); every message and what to do about it is in Errors and exit codes. API calls are retried with backoff on network errors and 5xx answers, and time out after 30 seconds each.

Who blocks the merge, the git host's check or this job, is explained in How a build flows. Override it with --gate.

circi site upload <dir> and circi storybook upload <dir>

Section titled “circi site upload <dir> and circi storybook upload <dir>”

Upload a built static site next to the screenshots (the project must have Host static sites on and the server a STATIC_SITES_HOST; see Hosted sites).

Flag Meaning
<dir> The built site, a folder with its index.html.
--name <name> Which of the project's sites this is (default site; storybook for the shortcut).
--kind <kind> storybook, vitest-report, playwright-report, coverage, docs, generic or auto (default). Not on storybook upload.
--spa Serve unknown paths with the entry page (single-page apps).
--api-url <url> CirCI address.
Terminal window
circi storybook upload ./storybook-static
circi site upload ./playwright-report --name playwright
circi site upload ./coverage --kind coverage

Prints the two lines that point the Argos SDKs at this server (from CIRCI_API_URL and CIRCI_TOKEN): ARGOS_API_BASE_URL=<url>/v2 and ARGOS_TOKEN=<token>. See the Argos-compatible API.