Substreams CLI reference
StreamingFast Substreams command line interface (CLI)
The
substreams
command line interface (CLI) is the primary user interface and the main tool for sending requests and receiving data.The
substreams
CLI exposes many commands to developers enabling a range of features.Note: When a package is specified, it is optional. If you do use it, you can use:
- Local
substreams.yaml
configuration files - Local
.spkg
package files - Remote
.spkg
package URLs - Local directory containing a
substreams.yaml
file
If you choose to not use it, make sure that you are in a directory that contains a substreams.yaml file. Otherwise, you will get a usage error back.
The
run
command connects to a Substreams endpoint and begins processing data.run command
substreams run -e mainnet.eth.streamingfast.io:443 \
-t +1 \
./substreams.yaml \
module_name
The details of the run command are:
-e mainnet.eth.streamingfast.io:443
is the endpoint of the provider running your Substreams.-t +1
or--stop-block
only requests a single block; the stop block is the manifest'sinitialBlock
+ 1.substreams.yaml
is the path where you have defined your Substreams manifest. You can use a.spkg
orsubstreams.yaml
configuration file.module_name
is the module we want torun
, referring to the module name defined in the Substreams manifest.
Tip: Passing a different
-s
or --start-block
runs prior modules at a higher speed. Output is provided at the requested start block, keeping snapshots along the way if you want to process it again.substreams run
$ substreams run -e mainnet.eth.streamingfast.io:443 \
https://github.com/Jannis/gravity-substream/releases/download/v0.0.1/gravity-v0.1.0.spkg \
gravatar_updates -o json
The output of the
gravatar_updates
module starting at block 6200807
will print a message resembling:run output
{
"updates": [
{
"id": "39",
"owner": "0xaadcc13071fdf9c73cfbb8d97639ea68aa6fd1d2",
"displayName": "alex | OpenSea",
"imageUrl": "https://ucarecdn.com/13a67247-cb89-417a-92d2-50a7d7aa481c/-/crop/382x382/0,0/-/preview/"
}
]
}
...
Note: The
-o
or --output
flag alters the output format.The available output display options are:
ui
, a nicely formatted, UI-driven interface, displaying progress information and execution logs.json
, an indented stream of data, not displaying progress information or logs, only data output for blocks proceeding the start block.jsonl
, same asjson
showing every individual output on a single line.
The
gui
command pops up a terminal-based graphical user interface.Its parameters are very similar to those of
run
, but provides a UI to navigate the results instead of a stream of data.When you run a
gui
session, a file called replay.log
gets written with the contents of the streamed data that persists after closing the GUI.You can reload the data without hitting the server again using
--replay
. The data is immediately reloaded in the GUI, ready for more inspection.The
pack
command builds a shippable, importable package from a substreams.yaml
manifest file.pack command
$ substreams pack ./substreams.yaml
The output of the
pack
command will print a message resembling:pack output
...
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
configuration files.info command
$ substreams info ./substreams.yaml
The output of the
info
command will print a message resembling:info output
Package name: solana_spl_transfers
Version: v0.5.2
Doc: Solana SPL Token Transfers stream
Stream SPL token transfers to the nearest human being.
Modules:
----
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
Update Policy: UPDATE_POLICY_SET
Hash: 11fd70768029bebce3741b051c15191d099d2436
graph command
$ substreams graph ./substreams.yaml
[±master ●●]
Mermaid graph:
```mermaid
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
graph
command will result in a graphic resembling:Mermaid generated graph diagram
The
inspect
command reaches deep into the file structure of a yaml
configuration file or spkg
package and is used mostly for debugging, or if you're curious_._inspect command
$ substreams inspect ./substreams.yaml | less
The output of the
inspect
command will print a message resembling:inspect output
proto_files
...
modules {
modules {
name: "my_module_name"
...
To view a list of available commands and brief explanations in the
substreams
CLI, run the substreams
command in a terminal passing the -h
flag. You can use this help reference at any time.help option
substreams -h
The output of the
help
command will print a message resembling:help output
Usage:
substreams [command]
Available Commands:
completion Generate the autocompletion script for the specified shell
decode
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
Flags:
-h, --help help for substreams
-v, --version version for substreams
Use "substreams [command] --help" for more information about a command.