Getting Started
SAL projects are ordinary Git repositories with a .sal workspace for generated data.
The source files stay in your repository; the Iceberg table generated by SAL lives under .sal/data.
Install SAL
Section titled “Install SAL”Install the latest release, or update the one you have, with:
curl -fsSL https://raw.githubusercontent.com/cgs-earth/sal/main/install.sh | shThe installer supports Linux amd64 and macOS Apple Silicon. It downloads the binary from the latest release, verifies its SHA-256 checksum, and installs it as ~/.local/bin/sal, replacing any existing binary there. Release binaries include the web UI and do not require Go or Node.js.
If ~/.local/bin is not on your PATH, add this line to your shell configuration (~/.zshrc or ~/.bashrc) and open a new terminal:
export PATH="$HOME/.local/bin:$PATH"Check the installation:
sal --versionInstall options
Section titled “Install options”To choose another installation directory, pass SAL_INSTALL_DIR to the installer’s shell:
curl -fsSL https://raw.githubusercontent.com/cgs-earth/sal/main/install.sh | SAL_INSTALL_DIR="$HOME/bin" shAdd that directory to your PATH if needed. To install a specific release, pass SAL_VERSION with its tag instead:
curl -fsSL https://raw.githubusercontent.com/cgs-earth/sal/main/install.sh | SAL_VERSION=v0.1.2 shChoose a tag from the releases page. You can set both options together. Run the default install command again to update to the latest release.
Build from source
Section titled “Build from source”To build from source, install Go 1.26 or newer and a C/C++ toolchain (build-essential on Debian or Ubuntu, or the Xcode command line tools on macOS), then run:
CGO_ENABLED=1 go install github.com/cgs-earth/sal@latestGo installs the binary into GOBIN, or $(go env GOPATH)/bin when GOBIN is unset; add that directory to your PATH.
DuckDB is linked into SAL, so no separate DuckDB installation is needed.
A binary installed with go install has no web UI for sal serve --with-ui, because the UI is built separately from the Go binary. To include it in a source build, clone the repository and build the UI before installing SAL (also requires Make and Node.js 22 with npm):
git clone https://github.com/cgs-earth/sal.gitcd salmake uimake installThis installs SAL with the web UI into ~/.local/bin.
SAL also requires Git for project metadata and Docker to build and run SAL modules.
Initialize a repository
Section titled “Initialize a repository”Run sal init from the root of a Git repository that already has a remote:
sal initIt asks for a sentence or two describing the project, which --description can give instead, and records it in .sal/config.jsonld; a directory that already has that file is already a project and sal init fails.
It also creates the local SAL data directory and adds .sal/data to .gitignore.
Generated data is not meant to be committed to source control.
Read more about the generated files in Data Layout.
Add RDF files
Section titled “Add RDF files”SAL finds RDF files in the paths you pass to sal validate or sal build.
Use Turtle or JSON-LD for source data.
sal validate data/Validation checks that RDF parses correctly and that prefixed terms resolve against their vocabularies.
If you need to remap vocabulary prefixes while validating, pass one or more --prefix-maps values.
Build the data product
Section titled “Build the data product”After source changes are committed, build the local Iceberg table, saying what the build changes the way a Git commit message does:
sal build --message "Add the station data" data/The message is required, and is recorded in the snapshot the build commits.
By default, SAL writes an Iceberg table.
For validation-only workflows or debugging, see sal validate and the --format option in sal build.
Query the result
Section titled “Query the result”Open the built table in the SQL shell:
sal querySAL creates a triples view in the shell.
From there, run SQL such as:
SELECT subject, predicate, objectFROM triplesLIMIT 10;Next, publish the generated table using Publishing Data.

