Install

Surface is a single static binary. The quickest way to get it locally is npm (below). In CI, most repos never install it directly - they consume the GitHub Action or the pre-commit hook, which fetch the binary for you. There’s also a curl | sh installer and a from-source build.

npm

npm install --save-dev @gradient-tools/surface
npx @gradient-tools/surface check

A thin shim package pulls in the prebuilt binary for your platform via optionalDependencies (macOS Apple Silicon and Linux x86_64) - there is no postinstall download step. On an unsupported platform the shim errors and points you at the from-source build.

GitHub Action

.github/workflows/surface.yml:

name: Surface
on: pull_request
jobs:
  surface:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4   # plain checkout - do NOT set fetch-depth: 0
      - uses: Connorrmcd6/surface@v0.8.0

See CI integration for the checkout-depth rule and scoping flags.

pre-commit

.pre-commit-config.yaml:

- repo: https://github.com/Connorrmcd6/surface
  rev: v0.6.1
  hooks:
    - id: surf-check

Install script

curl --proto '=https' --tlsv1.2 -fsSL https://raw.githubusercontent.com/Connorrmcd6/surface/main/install.sh | sh

Prebuilt binaries are published for macOS (Apple Silicon) and Linux (x86_64). On Intel macOS or other Unix architectures, build from source.

Each release publishes a <asset>.sha256 alongside every binary, and the install script verifies it before installing - a missing checksum or a mismatch aborts the install rather than running an unverified binary.

Platform support

Platform	Status
macOS (Apple Silicon)	prebuilt binary
Linux (x86_64)	prebuilt binary
Intel macOS, other Unix arches	build from source
Windows	not supported

Windows is unsupported: anchor at: paths are forward-slash only, and the install script rejects non-Unix systems. Use WSL if you need Surface on a Windows machine.

From source

Requires Rust:

git clone https://github.com/Connorrmcd6/surface
cd surface
cargo install --path surf-cli      # puts `surf` on your PATH (~/.cargo/bin)
# or: cargo build --release        # binary at target/release/surf