Enum ApiCommands 

pub enum ApiCommands {
    Serve {
        snapshot_files: Vec<PathBuf>,
        chain: Option<NetworkChain>,
        port: u16,
        auto_download_snapshot: bool,
        height: i64,
        index_backfill_epochs: usize,
        genesis: Option<PathBuf>,
        save_token: Option<PathBuf>,
    },
    Compare {
        forest: UrlFromMultiAddr,
        lotus: UrlFromMultiAddr,
        filter: String,
        filter_file: Option<PathBuf>,
        fail_fast: bool,
        run_ignored: RunIgnored,
        max_concurrent_requests: usize,
        create_tests_args: CreateTestsArgs,
        dump_dir: Option<PathBuf>,
        test_criteria_overrides: Vec<TestCriteriaOverride>,
        report_dir: Option<PathBuf>,
        report_mode: ReportMode,
    },
    GenerateTestSnapshot {
        test_dump_files: Vec<PathBuf>,
        db: Option<PathBuf>,
        chain: NetworkChain,
        out_dir: PathBuf,
        use_response_from: Option<NodeType>,
        allow_failure: bool,
    },
    DumpTests {
        create_tests_args: CreateTestsArgs,
        path: ApiPaths,
        include_ignored: bool,
    },
    Test {
        files: Vec<PathBuf>,
    },
    TestStateful {
        to: Address,
        from: Address,
        payload: String,
        topic: EthHash,
        filter: String,
    },
}

Variants

Serve

Starts an offline RPC server using provided snapshot files.

This command launches a local RPC server for development and testing purposes. Additionally, it can be used to serve data from archival snapshots.

Fields

snapshot_files: Vec<PathBuf>

Snapshot input paths. Supports .car, .car.zst, and .forest.car.zst.

chain: Option<NetworkChain>

Filecoin network chain

port: u16

auto_download_snapshot: bool

height: i64

Validate snapshot at given EPOCH, use a negative value -N to validate the last N EPOCH(s) starting at HEAD.

index_backfill_epochs: usize

Backfill index for the given EPOCH(s)

genesis: Option<PathBuf>

Genesis file path, only applicable for devnet

save_token: Option<PathBuf>

If provided, indicates the file to which to save the admin token.

Compare

Compare two RPC providers.

The providers are labeled forest and lotus, but other nodes may be used (such as venus).

The lotus node is assumed to be correct and the forest node will be marked as incorrect if it deviates.

If snapshot files are provided, these files will be used to generate additional tests.

Example output:

| RPC Method                        | Forest              | Lotus         |
|-----------------------------------|---------------------|---------------|
| Filecoin.ChainGetBlock            | Valid               | Valid         |
| Filecoin.ChainGetGenesis          | Valid               | Valid         |
| Filecoin.ChainGetMessage (67)     | InternalServerError | Valid         |

The number after a method name indicates how many times an RPC call was tested.

Fields

forest: UrlFromMultiAddr

Forest address

lotus: UrlFromMultiAddr

Lotus address

filter: String

Filter which tests to run according to method name. Case sensitive.

filter_file: Option<PathBuf>

Filter file which tests to run according to method name. Case sensitive. The file should contain one entry per line. Lines starting with ! are considered as rejected methods, while the others are allowed. Empty lines and lines starting with # are ignored.

fail_fast: bool

Cancel test run on the first failure

run_ignored: RunIgnored

Behavior for tests marked as ignored.

max_concurrent_requests: usize

Maximum number of concurrent requests

create_tests_args: CreateTestsArgs

dump_dir: Option<PathBuf>

Specify a directory to which the RPC tests are dumped

test_criteria_overrides: Vec<TestCriteriaOverride>

Additional overrides to modify success criteria for tests

report_dir: Option<PathBuf>

Specify a directory to dump the test report

report_mode: ReportMode

Report detail level: full (default), failure-only, or summary

GenerateTestSnapshot

Generates RPC test snapshots from test dump files and a Forest database.

This command processes test dump files and creates RPC snapshots for use in automated testing. You can specify the database folder, network chain, and output directory. Optionally, you can allow generating snapshots even if Lotus and Forest responses differ, which is useful for non-deterministic tests.

See additional documentation in the https://docs.forest.chainsafe.io/developers/guides/rpc_test_snapshot/.

Fields

test_dump_files: Vec<PathBuf>

Path to test dumps that are generated by forest-tool api dump-tests command

db: Option<PathBuf>

Path to the database folder that powers a Forest node

chain: NetworkChain

Filecoin network chain

out_dir: PathBuf

Folder into which test snapshots are dumped

use_response_from: Option<NodeType>

Allow generating snapshot even if Lotus generated a different response. This is useful when the response is not deterministic or a failing test is expected. If generating a failing test, use Lotus as the argument to ensure the test passes only when the response from Forest is fixed and matches the response from Lotus.

allow_failure: bool

Allow generating snapshot even if the test fails.

DumpTests

Dumps RPC test cases for a specified API path.

This command generates and outputs RPC test cases for a given API path, optionally including ignored tests. Useful for inspecting or exporting test cases for further analysis or manual review.

See additional documentation in the https://docs.forest.chainsafe.io/developers/guides/rpc_test_snapshot/.

Fields

create_tests_args: CreateTestsArgs

path: ApiPaths

Which API path to dump.

include_ignored: bool

Test

Runs RPC tests using provided test snapshot files.

This command executes RPC tests based on previously generated test snapshots, reporting success or failure for each test. Useful for validating node behavior against expected responses.

See additional documentation in the https://docs.forest.chainsafe.io/developers/guides/rpc_test_snapshot/.

Fields

files: Vec<PathBuf>

Path to test snapshots that are generated by forest-tool api generate-test-snapshot command

TestStateful

Run multiple stateful JSON-RPC API tests against a Filecoin node.

Connection: uses FULLNODE_API_INFO from the environment.

Some tests require sending a transaction to trigger events; the provided from, to, payload, and topic inputs are used for those cases.

Useful for verifying methods like eth_newFilter, eth_getFilterLogs, and others that rely on internal state.

Inputs:

• --to, --from: delegated Filecoin (f4) addresses
• --payload: calldata in hex (accepts optional 0x prefix)
• --topic: 32‑byte event topic in hex
• --filter: run only tests that interact with a specific RPC method

Example output:

running 7 tests
test eth_newFilter install/uninstall ... ok
test eth_newFilter under limit ... ok
test eth_newFilter just under limit ... ok
test eth_newFilter over limit ... ok
test eth_newBlockFilter works ... ok
test eth_newPendingTransactionFilter works ... ok
test eth_getFilterLogs works ... ok
test result: ok. 7 passed; 0 failed; 0 ignored; 0 filtered out

Fields

to: Address

Test Transaction to address (delegated f4)

from: Address

Test Transaction from address (delegated f4)

payload: String

Test Transaction hex payload

topic: EthHash

Log topic to search for

filter: String

Filter which tests to run according to method name. Case sensitive.

Implementations

impl ApiCommands

pub async fn run(self) -> Result<()>

Trait Implementations

impl Debug for ApiCommands

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl FromArgMatches for ApiCommands

fn from_arg_matches(__clap_arg_matches: &ArgMatches) -> Result<Self, Error>

Instantiate Self from ArgMatches, parsing the arguments as needed.

fn from_arg_matches_mut( __clap_arg_matches: &mut ArgMatches, ) -> Result<Self, Error>

Instantiate Self from ArgMatches, parsing the arguments as needed.

fn update_from_arg_matches( &mut self, __clap_arg_matches: &ArgMatches, ) -> Result<(), Error>

Assign values from ArgMatches to self.

fn update_from_arg_matches_mut<'b>( &mut self, __clap_arg_matches: &mut ArgMatches, ) -> Result<(), Error>

Assign values from ArgMatches to self.

impl Subcommand for ApiCommands

fn augment_subcommands<'b>(__clap_app: Command) -> Command

Append to Command so it can instantiate Self via FromArgMatches::from_arg_matches_mut

fn augment_subcommands_for_update<'b>(__clap_app: Command) -> Command

Append to Command so it can instantiate self via FromArgMatches::update_from_arg_matches_mut

fn has_subcommand(__clap_name: &str) -> bool

Test whether Self can parse a specific subcommand