Using the CLI

StreamingFast Substreams command line interface (CLI)
The Substreams command line interface (CLI) is the user interface and central access point for working with Substreams.
The Substreams CLI exposes many commands to developers enabling a range of functionality. Each command is explained in further detail.
Substreams command-line interface screenshot
Note: any time a package is specified any of the following can be used, local substreams.yaml file, local .spkg or a remote .spkg URL.


The run command connects to a Substreams endpoint and begins processing data.
substreams run -e \
-t +1 \
./substreams.yaml \

Run Command Breakdown

  • -e is the endpoint of the provider running our Substreams
  • -t +1 (or --stop-block) only requests a single block (stop block will be manifest's initialBlock + 1)
  • substreams.yaml is the path where we have defined our Substreams Manifest. This can be an .spkg or a substreams.yaml file.
  • module_name is the module we want to run, referring to the name defined in the manifest.
Passing a different -s (or --start-block) will run any prior modules at high speed, in order to provide you with output at the requested start block as fast as possible, while keeping snapshots along the way, in case you want to process it again.
Example output of gravatar_updates starting at block 6200807.
$ substreams run -e \ \
gravatar_updates -o json
"updates": [
"id": "39",
"owner": "0xaadcc13071fdf9c73cfbb8d97639ea68aa6fd1d2",
"displayName": "alex | OpenSea",
"imageUrl": ",0/-/preview/"
Notice the -o (or --output), that can alter the output format. The options are:
  • ui, a nicely formatted, UI-driven interface, with progress information, and execution logs.
  • json, an indented stream of data, with no progress information nor logs, but just data output for blocks following the start block.
  • jsonl, same as json but with each output on a single line.


The pack command builds a shippable, importable package from a substreams.yaml manifest file.
$ substreams pack ./substreams.yaml
Successfully wrote "your-package-v0.1.0.spkg".


The info command prints out the contents of a package for inspection. It works on both local and remote yaml or spkg files.
$ substreams info ./substreams.yaml
Package name: solana_spl_transfers
Version: v0.5.2
Doc: Solana SPL Token Transfers stream
This streams out SPL token transfers to the nearest human being.
Name: spl_transfers
Initial block: 130000000
Kind: map
Output Type: proto:solana.spl.v1.TokenTransfers
Hash: 2b59e4e840f814f4154a688c2935da9c3b61dc61
Name: transfer_store
Initial block: 130000000
Kind: store
Value Type: proto:solana.spl.v1.TokenTransfers
Hash: 11fd70768029bebce3741b051c15191d099d2436


The graph command prints out a visual graph of the package in the mermaid-js format.
Note: see for a live mermaid-js editor.
$ substreams graph ./substreams.yaml [±master ●●]
Mermaid graph:
graph TD;
spl_transfers[map: spl_transfers]
sf.solana.type.v1.Block[source: sf.solana.type.v1.Block] --> spl_transfers
transfer_store[store: transfer_store]
spl_transfers --> transfer_store
The code will a graphic similar to
Open the link and change ".ink/svg/" to ".live/edit#" in the URL, to go back to edit mode.


This command goes deep into the file structure of a package (yaml or spkg). The inspect command is used mostly for debugging, or for the curious ;)
$ substreams inspect ./substreams.yaml | less
proto_files {
modules {
modules {
name: "my_module_name"


The commands and a brief explanation are also provided in the Substreams CLI application. To access the help at any time simply execute the substreams command, in a terminal, and pass a flag of -h.
Output similar to the following will appear in the terminal.
substreams [command]
Available Commands:
completion Generate the autocompletion script for the specified shell
graph Generate mermaid-js graph document
help Help about any command
info Display package modules and docs
inspect Display low-level package structure
pack Build an .spkg out of a .yaml manifest
protogen Generate Rust bindings from a package
run Stream modules from a given package on a remote endpoint
tools Developer tools related to substreams
-h, --help help for substreams
-v, --version version for substreams
Use "substreams [command] --help" for more information about a command.