Installation

System Requirements🔗

Spade runs on Linux and macOS. You need:

• A terminal with a POSIX-compatible shell (bash, zsh)
• Git (for building block collections from source with spade install; not needed for registry-fetch installs like spade install gdal@latest)

For block development, you also need the toolchain for your chosen language — see the library documentation for specifics.

Install the Spade CLI🔗

The Spade CLI is a single Go binary. Install it with:

go install github.com/spade-dev/spade/cli@latest

This places the spade binary in your $GOPATH/bin directory. Make sure that directory is in your PATH.

Set up the sandbox (Linux)🔗

On Linux, spade run executes every block inside the isolate sandbox, which confines the block to its working directory and enforces the memory limit from its manifest. The repository ships a script that builds isolate, installs it setuid, creates the sandbox user and uid ranges, and enables the isolate.service daemon that hands the sandbox its control group:

./install_isolate.sh

It needs sudo and a systemd host. The script ends by running a block-shaped smoke test through the sandbox, so if it finishes cleanly spade run will work.

If spade run later fails with "the isolate cgroup keeper is not running", the service was not started; sudo systemctl enable --now isolate.service fixes it.

Initialize Spade🔗

After installing, run the setup command to create the local Spade directory:

spade setup

This creates ~/.spade/ with the following structure:

~/.spade/
  auth/        # Session credentials from `spade login`
  blocks/      # Installed block collections
  cache/       # Execution cache for block outputs
  pipelines/   # Working directories for pipeline runs
  registry.db  # SQLite registry of installed blocks

Verify the installation🔗

Check that everything is working:

spade --help

You should see output listing all available commands:

Spade - A data processing system for massive data

Usage:
  spade [command]

Available Commands:
  run         Run a pipeline locally
  check       Validate blocks or pipelines
  install     Install a block collection from the cloud registry, a git repository, or a local directory
  publish     Submit a block collection to the cloud registry for screening, build, and distribution
  init        Create a new block collection
  add         Add a new block to the current collection
  setup       Set up the Spade environment
  login       Authenticate to the cloud registry
  secret      Manage local and cloud secrets for pipeline runs

Custom install location🔗

By default, Spade stores everything in ~/.spade/. To use a different location, set the SPADE_DIR environment variable:

export SPADE_DIR=/path/to/custom/spade
spade setup

Language toolchains🔗

To develop blocks, you need the appropriate language toolchain installed:

Next steps🔗

Now that Spade is installed, continue to Your First Pipeline to run a simple workflow.