spade install

The spade install command installs a block collection so its blocks can be used in pipelines. It supports two distinct modes depending on what <source> looks like:

• Registry-fetch mode — <source> is a registry reference like gdal@1.0.0 or gdal@latest. Spade downloads a prebuilt, signed artifact from the cloud registry. No local build, no language toolchain required.
• Build-from-source mode — <source> is a git URL or a local path. Spade acquires the source and builds it locally using the appropriate language toolchain.

Both modes end the same way: blocks are unpacked into ~/.spade/blocks/<collection>/<version>/ and registered in the local block index (~/.spade/registry.db). What differs is where the artifact comes from and whether it's signed.

Usage🔗

# Registry-fetch mode: a registry reference
spade install gdal@1.0.0
spade install gdal@latest

# Build-from-source mode: a git URL
spade install https://github.com/spade-dev/gdal-blocks.git
spade install git@github.com:spade-dev/gdal-blocks.git

# Build-from-source mode: a local path
spade install .
spade install ./my-collection
spade install /home/user/projects/my-collection

<source> is interpreted as follows:

A local path does not need to be a git repository — the directory is used as-is.

Registry-fetch mode🔗

For a registry reference, no source is cloned and nothing is compiled. Spade downloads an artifact the registry already built, screened, and signed.

1. Resolve the version🔗

gdal@1.0.0 resolves directly; gdal@latest asks the registry for the newest available version.

Resolved gdal@latest -> 1.3.0

2. Determine platform and architecture🔗

Spade detects the local machine's platform and architecture (for example, linux/amd64) to select the matching artifact.

3. Download the artifact and signature🔗

The CLI downloads the tarball and its detached signature for <collection>/<version>/<platform>/<arch>:

<collection>/<version>/<platform>/<arch>.tar.gz
<collection>/<version>/<platform>/<arch>.tar.gz.sig

4. Verify the signature🔗

The signature is checked against the registry's list of trusted public keys. If verification fails, the artifact is rejected and nothing is installed.

5. Verify the content hash🔗

The downloaded tarball's content hash is compared against the value recorded in the registry's metadata for that artifact.

6. Unpack🔗

The verified artifact is unpacked into ~/.spade/blocks/<collection>/<version>/.

7. Update the local block index🔗

Each block manifest from the artifact is registered in ~/.spade/registry.db, marked as a registry-fetched, signed install.

Resolved gdal@latest -> 1.3.0
Downloading gdal/1.3.0/linux/amd64.tar.gz...
Signature verified.
Content hash verified.
Installed 6 block(s) to /home/user/.spade/blocks/gdal/1.3.0

The CLI uses your spade login session if one is available, falling back to the registry's public read endpoints for unauthenticated fetches of public collections. Workers use a service token instead of a developer session — see the registry's authentication model in the Block Collections overview.

Only collection versions in the available state can be fetched this way. Versions that have been yanked or recalled are refused; see Block Collections for what those states mean.

Build-from-source mode🔗

For a git URL or a local path, Spade builds the collection itself using the appropriate language toolchain. This is the developer-facing path — the one you use while iterating on a collection, before (or between) publishing it.

1. Acquire the source🔗

• Git URL: shallow-cloned (--depth=1) into a temporary directory.
• Local path: used in place. Not required to be a git repository.

Cloning https://github.com/spade-dev/gdal-blocks.git...

2. Detect the language🔗

Spade examines the source root for language marker files, checked in this order:

Detected language: rust

3. Discover blocks🔗

All blocks/*.yaml files are loaded and parsed as block manifests. If none are found, the install fails.

4. Read collection metadata🔗

The collection name and version are read from the language-specific manifest:

Multiple versions of the same collection can be installed side by side.

5. Build🔗

A language-specific build command is run against the source:

Local-path installs build in place, so native toolchains (Cargo, Go, etc.) can reuse their incremental build caches across repeated spade install . runs.

6. Install🔗

The built artifacts and block manifests are installed to ~/.spade/blocks/<collection>/<version>/.

Detected language: rust
Collection: gdal-blocks v1.2.0
Building...
Installed 6 block(s) to /home/user/.spade/blocks/gdal-blocks/1.2.0

7. Update the local block index🔗

Each block manifest is registered in ~/.spade/registry.db, marked as locally built rather than registry-fetched.

Signed vs. locally built🔗

This distinction is tracked, not cosmetic:

Locally-built collections are not signed, and the local block index records them as such. This is intentional: signing only happens after the registry's screening step, so a locally built artifact has no screening signal behind it. Production workers always fetch signed artifacts from the registry; build-from-source is for local development and testing before you publish.

Verifying the installation🔗

After installing, you can verify that blocks are registered by referencing them in a pipeline and running spade check:

spade check my-pipeline.yaml

If the pipeline references a block type that was just installed and spade check reports it as valid, the installation succeeded.

You can also run spade setup --rebuild-index to verify that the filesystem and registry are consistent.

Examples🔗

Registry-fetch:

spade install gdal@1.0.0

Resolved gdal@1.0.0
Downloading gdal/1.0.0/linux/amd64.tar.gz...
Signature verified.
Content hash verified.
Installed 6 block(s) to /home/user/.spade/blocks/gdal/1.0.0

Build-from-source, from a git URL:

spade install https://github.com/spade-dev/gdal-blocks.git

Cloning https://github.com/spade-dev/gdal-blocks.git...
Detected language: rust
Collection: gdal-blocks v1.2.0
Building...
Installed 6 block(s) to /home/user/.spade/blocks/gdal-blocks/1.2.0

Build-from-source, from the current directory (typical during development):

spade install .

Detected language: python
Collection: my-collection v0.1.0
Building...
Installed 3 block(s) to /home/user/.spade/blocks/my-collection/0.1.0

See also🔗

• spade publish for submitting a collection to the registry so others can spade install the signed artifact
• spade login for authenticating registry-fetch requests
• spade setup for initializing the local environment before installing
• spade check for verifying the installed blocks work in a pipeline
• spade init for creating a new collection to develop locally