@interfere/cli

Command-line tool for Interfere release workflows. Uploads source maps and registers releases so the collector accepts spans from your deployments.

Install

npm install -D @interfere/cli
# or
bun add -d @interfere/cli
# or
pnpm add -D @interfere/cli

Usage

Run after your build step to upload source maps and preflight the release:

interfere sourcemaps upload ./dist

Typically added as a postbuild script in package.json:

{
  "scripts": {
    "build": "tsc",
    "postbuild": "interfere sourcemaps upload ./dist"
  }
}

What it does

1. Auto-detects the CI runner and extracts commit SHA, branch, run ID, and run URL
2. Derives a release slug from the commit SHA (same algorithm the SDK uses at runtime)
3. Registers the release with the collector (POST /v1/releases/)
4. Discovers .js.map files in the target directory
5. Uploads source maps via presigned URLs
6. Marks the release as preflight-confirmed so the collector accepts spans for it

Options

interfere sourcemaps upload --source-maps <dir> [options]

Options:
  --source-maps <dir>  Directory containing .js.map files (required)
  --release <slug>     Override the release slug (default: derived from commit SHA)
  --url <api-url>      Interfere collector URL (default: $INTERFERE_API_URL)
  --api-key <key>      Interfere API key (default: $INTERFERE_API_KEY)
  --commit-sha <sha>   Commit SHA (default: auto-detected from CI or git)
  --commit-ref <ref>   Branch or tag ref (default: auto-detected from CI or git)
  --build-id <id>      Build identifier (default: same as --commit-sha)
  --runner <name>      CI runner name override (default: auto-detected)
  --run-id <id>        CI run ID override (default: auto-detected)
  --run-url <url>      CI run URL override (default: auto-detected)
  --skip-preflight     Don't mark the release preflight-confirmed after upload
  --dry-run            Print what would be sent without making API calls
  --json               Output results as JSON
  -h, --help           Show help
  --version            Show version

CI Auto-Detection

The CLI automatically detects the CI runner and extracts metadata from environment variables. No flags are needed when running in a supported CI environment.

| Runner | Detection | Commit SHA | Branch | Run ID | Run URL | |---|---|---|---|---|---| | GitHub Actions | GITHUB_ACTIONS | GITHUB_SHA | GITHUB_HEAD_REF / GITHUB_REF_NAME | GITHUB_RUN_ID | Constructed from GITHUB_SERVER_URL + GITHUB_REPOSITORY | | CircleCI | CIRCLECI | CIRCLE_SHA1 | CIRCLE_BRANCH | CIRCLE_BUILD_NUM | CIRCLE_BUILD_URL | | GitLab CI | GITLAB_CI | CI_COMMIT_SHA | CI_COMMIT_REF_NAME | CI_PIPELINE_ID | CI_PIPELINE_URL | | Buildkite | BUILDKITE | BUILDKITE_COMMIT | BUILDKITE_BRANCH | BUILDKITE_BUILD_NUMBER | BUILDKITE_BUILD_URL | | Manual | (none) | git rev-parse HEAD | - | - | - |

When no CI is detected, the CLI falls back to git rev-parse HEAD for the commit SHA. Pass --commit-sha explicitly if running outside a git repository.

Note (GitHub Actions): on pull_request events, GITHUB_SHA is the ephemeral merge commit, not the head commit of your branch. Releases registered from PR builds will carry a SHA that exists on no branch. Run the upload on push/deploy workflows, or pass --commit-sha ${{ github.event.pull_request.head.sha }} explicitly.

Environment Variables

| Variable | Required | Purpose | |---|---|---| | INTERFERE_API_KEY | Yes | Authenticates with the collector. Format: interfere_secret_us_* or interfere_secret_eu_* | | INTERFERE_SOURCE_ID | No | Override the commit SHA used to derive the release slug. Falls back to CI-detected SHA or git rev-parse HEAD. | | INTERFERE_API_URL | No | Override the default collector URL |

How release identity works

The CLI and the SDK independently derive the same release slug from the commit SHA using a shared deriveReleaseSlug() function. For this to work, both must see the same SHA:

• At build time (CLI): reads from INTERFERE_SOURCE_ID, CI env vars, or git rev-parse HEAD
• At runtime (SDK): reads from the same env vars or git

In Docker deployments where .git isn't in the image, set INTERFERE_SOURCE_ID in the runtime environment to the same commit SHA used during the build.

Examples

GitHub Actions

- name: Build
  run: npm run build

- name: Upload source maps
  run: npx interfere sourcemaps upload ./dist
  env:
    INTERFERE_API_KEY: ${{ secrets.INTERFERE_API_KEY }}
    # Runner, commit SHA, branch, run ID, and run URL are auto-detected

CircleCI

- run:
    name: Upload source maps
    command: npx interfere sourcemaps upload ./dist
    # CIRCLECI, CIRCLE_SHA1, etc. are auto-detected

Dry Run

Preview the release payload and the source maps that would be uploaded, without making API calls:

interfere sourcemaps upload ./dist --dry-run --json

Docker

ARG GIT_SHA
ENV INTERFERE_SOURCE_ID=$GIT_SHA

COPY dist/ ./dist/
CMD ["node", "dist/main.js"]

docker build --build-arg GIT_SHA=$(git rev-parse HEAD) .