CLI

All commands and flags.

Commands

terminal
sieve [OPTIONS]                Run the indexer
sieve init                     Scaffold a new project (sieve.toml, .env, abis/)
sieve init --docker            Same + docker-compose.yml with PostgreSQL
sieve schema                   Print generated SQL DDL
sieve reset                    Drop and recreate all tables
sieve inspect                  Dry-run: show tables, columns, and filters
sieve add-contract <ADDRESS>   Fetch ABI from Etherscan and add to config
sieve peers [--chain <NAME>]   Test P2P connectivity (no DB or config needed)
sieve archive-plan [OPTIONS]   Plan a Base archive import offline (JSON output)

Flags

--config <PATH>

Path to TOML config. Default: sieve.toml

--start-block <NUM>

Override start block for all contracts.

--end-block <NUM>

Stop at this block. Omit for follow mode. With a Base [archive] section it must equal the archive end, or exceed it with handoff = true. See Base Archive.

--database-url <URL>

PostgreSQL URL. Overrides DATABASE_URL from .env.

--api-port <PORT>

Override GraphQL API port. Also configurable via [api] port in TOML.

--p2p-port <PORT>

Override P2P listen port. Default: 30303.

--workers <NUM>

Block-processing workers. Default: CPU count. Also configurable via [sync] workers in TOML. Cap it when running several instances on one host.

--fresh

Drop and recreate all tables before indexing.

--assume-factory-coverage

Adopt factories that have no coverage record, for databases created before coverage tracking. See Factory Contracts.

-v, --verbose

Use tracing logs instead of the pretty UI.

-V, --version

Print version.

Environment variables

All sensitive values live in .env (auto-loaded at startup via dotenvy). Never in TOML.

VariablePurpose
DATABASE_URLPostgreSQL connection URL
WEBHOOK_URLWebhook endpoint URL
RABBITMQ_URLRabbitMQ connection URL
ETHERSCAN_API_KEYEtherscan API key

sieve add-contract

Fetches a verified ABI from Etherscan for the chain in your root config, saves it to abis/, and appends a [[contracts]] block to your config. Auto-detects proxy contracts. Automatically sets start_block to the contract's deploy block. It reads and writes the root config only, never a fragment.

terminal
sieve add-contract 0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48
sieve add-contract 0xA0b8... --name USDC
sieve add-contract 0xA0b8... --start-block 21000000

sieve inspect

Validates your config without a database connection. Shows what tables, columns, context fields, and filters would be created, merging any *.sieve.toml fragments next to it.

terminal
sieve inspect --config sieve.toml

sieve peers

Tests P2P connectivity without a database or config. Reports peer count and chain head every 5 seconds. Useful for diagnosing Docker/NAT issues. Pass --chain to test any supported chain.

terminal
sieve peers
# peers=5 best_head=22525078
# peers=8 best_head=22525090

sieve peers --chain base

sieve archive-plan

Reads a local Base V2 snapshot manifest and prints a JSON import plan to stdout: selected archive groups, decode dependencies, download and staging estimates, and the trust inputs still needed. No config, database, peers, or network. See Base Archive Bootstrap.

terminal
sieve archive-plan --manifest base-manifest.json \
  --manifest-sha256 <64-hex-digit-digest> \
  --start-block 500123 --end-block 1000010
--manifest <PATH> · required

Local manifest JSON, up to 16 MiB.

--manifest-sha256 <HEX> · required

SHA-256 of the exact manifest bytes, 64 hex digits without 0x.

--start-block <NUM> --end-block <NUM> · required

Inclusive block range to index. Must be covered by the manifest.

--checkpoint-hash <HASH>

Trusted hash at the end block. Recorded in the plan, not verified.

--max-staging-bytes <NUM>

Staging budget to check the plan against. A budget that is too small is reported in the JSON, not as an error.

--working-space-bytes <NUM>

Working allowance added to file sizes. Default: 1073741824 (1 GiB).

--min-free-bytes <NUM>

Free-space reserve added on top. Default: 5368709120 (5 GiB).