Install the SDK and create a project

New to Sprig? Start with the bilingual beginner tutorial and build a local Task Tracker, then return here for installation, project and release details.

Sprig is an experimental JVM language for CLI tools, automation and reliable application code. Install JDK 17+; both java and javac must be on PATH. The SDK contains the compiler/runtime libraries and launcher, not a JDK.

Install and upgrade

On Linux/macOS the managed installer downloads the official SDK ZIP and its SHA-256 file, verifies them, installs into a version directory and puts sprig in ~/.local/bin:

curl -fsSL https://raw.githubusercontent.com/ColinHouse/Sprig/main/scripts/install-sprig.sh | sh
export PATH="$HOME/.local/bin:$PATH"
sprig upgrade --check
sprig upgrade

The full install/upgrade contract is in Install and upgrade.

Manual download and verify

The published experimental Beta SDK is v0.5.0-beta.1. Download the ZIP and its .sha256 from that release. On Linux/macOS:

curl -LO https://github.com/ColinHouse/Sprig/releases/download/v0.5.0-beta.1/sprig-v0.5.0-beta.1-jdk.zip
curl -LO https://github.com/ColinHouse/Sprig/releases/download/v0.5.0-beta.1/sprig-v0.5.0-beta.1-jdk.zip.sha256
shasum -a 256 -c sprig-v0.5.0-beta.1-jdk.zip.sha256
unzip sprig-v0.5.0-beta.1-jdk.zip
cd sprig-v0.5.0-beta.1-jdk

On Linux, sha256sum -c is also available. Stop if the checksum differs. Use the release assets and capability output to check which features your SDK actually includes. The Beta adds project testing, wrapper generation, schema-4 dependency locks, selected explicit Java interop and first-party CLI, HTTP, JSON, SQLite and Web packages. It keeps language version 0.8-dev; see the release notes for the scope and limits.

Initialize, resolve, run

Inside the extracted SDK, save an absolute launcher path so changing directory keeps it available:

./bin/sprig version
SPRIG="$(pwd)/bin/sprig"
"$SPRIG" init my-tool
cd my-tool
"$SPRIG" resolve
"$SPRIG" run

Expected program output:

Hello, Sprig!

init creates sprig.toml and src/main.spr without overwriting existing files. resolve creates sprig.lock. run checks types, generates Java, invokes javac, and executes on the JVM. Source edits do not require a new lock; manifest/dependency changes require resolve again.

Windows and source builds

Windows is an experimental preview, not a supported release platform. The portable source build is available for testing. Requires Git, JDK 17+ and Python 3.12+; Maven CLI and Bash are not required. PowerShell:

git clone https://github.com/ColinHouse/Sprig.git
Set-Location Sprig
py -3 scripts/build.py
$Sprig = (Resolve-Path .\bin\sprig.cmd).Path
& $Sprig version
& $Sprig init my-tool
Set-Location my-tool
& $Sprig resolve
& $Sprig run

On Linux/macOS, clone the same repository and use python3 scripts/build.py, then the bin/sprig sequence above. The first build downloads pinned ANTLR and Maven Resolver libraries. Node.js 20+/npm is needed only for documentation and the full contributor gate. Release status states which OS/JDK combinations have actually passed.

Ask the compiler, then edit

From your project (replace sprig with the absolute launcher if it is not on PATH):

sprig capabilities --json
sprig help generics --json
sprig api java.time.LocalDate --json
sprig check --json
sprig test --json          # runs project tests/**/*.spr
sprig explain SPR-TYPE-NULLABLE --json
sprig run

JSON diagnostics carry stable codes and source positions. Do not guess from another language: Java reference results are nullable, integer division is explicit and generics use explicit type arguments. Tooling and JSON explains the envelopes.

The Beta SDK includes test, wrap and run --stacktrace; check capabilities --json for the full implemented feature set. To integrate a third-party JVM library or framework build, read JVM interoperability and Fabric / JVM framework integration.

Make it useful

Try the showcase projects: repository auditing with JSON output, a real Maven-library application and source analysis. Each README specifies the entry, fixture and offline boundary. Learn individual constructs in the executable tutorial and example pages or the language tour; application projects live in the examples gallery.

When a host build system (Gradle/Loom/Maven) owns the classpath and must compile Sprig-generated Java back into its artifact, the reusable wiring and clean-build/package checklist are in Fabric / JVM framework integration.

Want to contribute with your coding agent? Read Contributing and AGENTS.md, choose a scoped issue, run scripts/verify.sh (py -3 scripts/verify.py on Windows), review and open a PR.

First-run problems

• JDK unavailable: install a JDK and check both java -version and javac -version.
• Missing or stale lock: run resolve in the project after manifest edits.
• Offline cache miss: populate the cache with an online resolve first; a lock alone is insufficient.
• SPR-LEX-TAB: use spaces for indentation.
• Nullable Java result: narrow with != null before use.
• Checksum mismatch: retain the evidence and redownload the affected artifact; never disable checksum verification.