# 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.

```sh
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
```sh
node framecheck.mjs upload --storybook-dir storybook-static
```

GitHub Actions metadata is detected automatically. Elsewhere, supply the flags in [other CI systems](/other-ci/).

| 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
```sh
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.