Skip to content

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 the latest release, or update the one you have, with:

Terminal window
curl -fsSL https://raw.githubusercontent.com/cgs-earth/sal/main/install.sh | sh

The 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:

Terminal window
export PATH="$HOME/.local/bin:$PATH"

Check the installation:

Terminal window
sal --version

To choose another installation directory, pass SAL_INSTALL_DIR to the installer’s shell:

Terminal window
curl -fsSL https://raw.githubusercontent.com/cgs-earth/sal/main/install.sh | SAL_INSTALL_DIR="$HOME/bin" sh

Add that directory to your PATH if needed. To install a specific release, pass SAL_VERSION with its tag instead:

Terminal window
curl -fsSL https://raw.githubusercontent.com/cgs-earth/sal/main/install.sh | SAL_VERSION=v0.1.2 sh

Choose a tag from the releases page. You can set both options together. Run the default install command again to update to the latest release.

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:

Terminal window
CGO_ENABLED=1 go install github.com/cgs-earth/sal@latest

Go 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):

Terminal window
git clone https://github.com/cgs-earth/sal.git
cd sal
make ui
make install

This installs SAL with the web UI into ~/.local/bin.

SAL also requires Git for project metadata and Docker to build and run SAL modules.

Run sal init from the root of a Git repository that already has a remote:

Terminal window
sal init

It 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.

SAL finds RDF files in the paths you pass to sal validate or sal build. Use Turtle or JSON-LD for source data.

Terminal window
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.

After source changes are committed, build the local Iceberg table, saying what the build changes the way a Git commit message does:

Terminal window
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.

Open the built table in the SQL shell:

Terminal window
sal query

SAL creates a triples view in the shell. From there, run SQL such as:

SELECT subject, predicate, object
FROM triples
LIMIT 10;

Next, publish the generated table using Publishing Data.

Developed byCenter for Geospatial SolutionsCenter for Geospatial Solutions