Uploader CLI

Install the web uploader, authenticate, and understand its commands and exit codes.

Install the pinned uploader#

The web uploader is a standalone JavaScript file. It requires Node.js 24. The project's Setup page gives you the supported version and checksum. This example pins uploader 0.3.6.

curl -fsSL -o framecheck.mjs \
  https://framecheck.dev/cli/framecheck-cli-0.3.6-19f6f88a4996.mjs
printf '%s  %s\n' \
  '19f6f88a4996a37677864050632a1c2a1bd200043c8f00fe12ee4b94d9677dc1' \
  framecheck.mjs | shasum -a 256 -c -
node framecheck.mjs --version

On Linux you can use sha256sum -c - instead of shasum -a 256 -c -. Stop if verification fails. Do not execute a file whose hash does not match.

Environment variables#

Variable	Purpose
`FRAMECHECK_API_URL`	Required API base URL: `https://api.framecheck.dev`.
`FRAMECHECK_TOKEN`	Project upload token, stored as a CI secret. Takes precedence over OIDC if set.
`FRAMECHECK_PROJECT_ID`	Project ID from Setup; particularly important when selecting a project explicitly.
`GITHUB_OUTPUT`	In GitHub Actions, precheck writes `run` and `decision` outputs here.

Older GitHub Actions setups can authenticate with GitHub OIDC using id-token: write. New guided setups use a project token. A wrongly set token is not ignored in favour of OIDC. Keep the authentication method generated for your project unless you deliberately migrate it.

Upload command#

node framecheck.mjs upload --storybook-dir storybook-static

GitHub Actions metadata is detected automatically. Elsewhere, supply the flags in other CI systems.

Flag	Meaning
`--storybook-dir DIR`	Required directory containing the static build.
`--repository owner/name`	GitHub repository.
`--commit SHA`	Full commit SHA of the code built.
`--branch NAME`	Source branch name.
`--trigger TYPE`	`pull_request`, `branch`, or `manual`.
`--pr NUMBER`	Pull-request number for a PR run.
`--pr-base-branch NAME`	Target branch of the pull request.
`--merge-base SHA`	PR merge-base commit.
`--ancestry SHA,SHA`	Explicit ancestor commits when automatic history discovery is unsuitable.

Precheck command#

node framecheck.mjs precheck

Run it before the expensive build step. It supports the repository, commit, branch, trigger, PR number, and PR base-branch flags, plus --pr-author, --pr-labels (comma-separated), and --draft. The upload command also checks whether the run should be skipped.

In GitHub Actions, only run later build/upload steps when steps.precheck.outputs.run != 'false'. Outside Actions, precheck prints its decision; it does not communicate a skip through a special exit code. Use the CI-specific Setup snippet rather than treating exit 0 as “run”.

Exit codes#

Code	Meaning
`0`	Upload queued successfully, or deliberately skipped/no work needed. Precheck also exits 0 for an ordinary decision.
`1`	Upload/API failure, including refused authentication.
`2`	Usage or configuration error, including a malformed token.

A temporary precheck outage permits the build to proceed; the upload step remains responsible for reporting upload failure. A 401 or 403 refusal stops the precheck. A queued run's visual outcome is reported separately in Framecheck and GitHub.