CLI Installation and Usage

Install the HDP CLI and run your first HDP pipeline

Use this page to install the HDP CLI and run a complete local pipeline.

Prerequisites

HDP requires:

• Rust
• Scarb (Cairo toolchain)
• uv (Python package manager)
• Access to chain RPC endpoints

Install Rust:

curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh

Install uv:

curl -LsSf https://astral.sh/uv/install.sh | sh

Optional:

• Docker
• Nightly Rust (if you plan to generate STWO prover input locally)

Install HDP CLI

Install latest:

curl -fsSL https://raw.githubusercontent.com/HerodotusDev/hdp-cairo/main/install-cli.sh | bash

Install a specific version:

VERSION=vX.X.X curl -fsSL https://raw.githubusercontent.com/HerodotusDev/hdp-cairo/main/install-cli.sh | bash

Build from source (optional)

git clone https://github.com/HerodotusDev/hdp-cairo.git
cd hdp-cairo
git submodule update --init
uv sync
source .venv/bin/activate

Optional Make targets:

make setup
make build
make test

Optional Docker path:

docker build -t hdp-cairo .
docker run --rm -it hdp-cairo --help

Configure environment

Check required variables:

hdp env-info

Check only the variables needed for your run:

hdp env-check --inputs dry_run_output.json

For all environment variables, see Configuration reference.

If you are working from a local hdp-cairo checkout, copy:

cp example.env .env

Then set your RPC endpoints and environment values.

First usage flow (CLI)

After you compile your module (for example with scarb build), run:

1. Dry run:

hdp dry-run -m module_contract_class.json --print_output

2. Fetch proofs:

hdp fetch-proofs

3. Sound run:

hdp sound-run -m module_contract_class.json --print_output

At the end of the flow, HDP prints output data used for downstream proving and settlement workflows.

First full run example (starkgate)

cd examples/starkgate
scarb build
hdp dry-run -m target/dev/example_starkgate_module.compiled_contract_class.json --print_output
hdp fetch-proofs
hdp sound-run -m target/dev/example_starkgate_module.compiled_contract_class.json --print_output

Expected artifacts:

• Stage 1: dry_run_output.json
• Stage 2: proofs.json
• Stage 3 output includes task_hash, output_root, and mmr_metas

See output details in Output model.

Full command example (eth_call)

From the official example:

scarb build -p example_eth_call && \
hdp dry-run -m target/dev/example_eth_call_module.compiled_contract_class.json --print_output && \
hdp fetch-proofs --mmr-deployment-config examples/eth_call/mmr_deployment_config.json && \
hdp sound-run -m target/dev/example_eth_call_module.compiled_contract_class.json --print_output --cairo_pie ./pie.zip

Reference files:

• Module: examples/eth_call/src/lib.cairo
• Run script: examples/eth_call/run.sh

On-chain finality reminder

Even with successful local execution, on-chain settlement requires that accessed blocks are included in Herodotus Satellite MMRs.