Check a program before deployment

Use this task when you already have a compiled SBF program and want to catch a wrong artifact or unsupported header before considering deployment. The result is a local header verdict. It requires no wallet, funds, RPC endpoint or GPU.

Prerequisites: a readable program file and the public @0xsingularity/cli. The commands were checked with CLI 0.3.0, Node 22.22.2 and npm 9.2.0 on Linux on 8 September 2026. Follow CLI installation if needed; the CLI reference separates this release from checkout 0.4.0 and the Rust operator utility.

Inspect the artifact you intend to use

If you used the directory-local installation in the CLI guide, select that executable. Set PROGRAM to your project's actual compiled file; the path below is the conventional example location, not a file supplied by the CLI.

CLI=./singularity-tools/node_modules/.bin/singularity
PROGRAM=./target/deploy/my_program.so
"$CLI" version
"$CLI" check-program "$PROGRAM"

An accepted header exits with code 0 and prints OK, the path and its flags. A fresh header-only test fixture produced:

OK    header-only.so
      e_flags is 0x0 (SBPF v1). The loader accepts this program.

The wording is the CLI's output. Interpret it as this guard accepted the header. The fixture contained no executable program body, yet passed; that directly demonstrates why this command cannot certify bytecode verification or runtime behavior.

The guard reads the ELF magic, class, byte order, machine and flags. It accepts BPF machine markers 247 and 263 (0x107) and flags 0x0 or 0x20. It does not execute the program, resolve imports, check its full loader lifecycle or test CPI behavior. Header parser, guard decisions.

Resolve a rejection

A failed check exits with code 1 and prints FAIL plus the reason to standard error.

For unsupported flags, the CLI suggests cargo build-sbf --arch v0. That suggestion depends on your program toolchain and is not a build executed by this task. Follow SVM compatibility before choosing compiler settings. The source's native loader and engine are the authoritative execution boundary.

Fresh checks rejected a text file, a missing file and a synthetic BPF header with flags 0x3. The positive header fixture and these rejection cases tested the installed CLI; no program build or deployment occurred.

Record the result and choose the next boundary

Keep the CLI version, exact artifact identity and verdict with your build evidence. A passed check completes this task. Before a deployment, separately establish the node's release and health, loader compatibility, available execution engine and a meaningful positive/negative program test. The availability reference and SVM execution explanation describe those boundaries.

deploy invokes the guard before toolchain setup and network submission, but it is a separate operation with wallet, toolchain and endpoint requirements. Use the deployment command reference when those prerequisites are satisfied. Deployment ordering.