The Sim IDX CLI is your primary tool for interacting with the Sim IDX framework. You can use the CLI to initialize new projects, manage contract ABIs, and test your listeners.

This page provides an overview of all available commands, their functions, and potential error messages you might encounter.

​
Install or Upgrade the CLI

Installing the CLI or Upgrading to the latest version is as simple as rerunning the installer script. The installer will download the most recent release and replace your existing sim binary.

curl -L https://simcli.dune.com | bash

​
Available Commands

​
sim init

Initializes a new Sim IDX application in the current directory. This command creates the standard project structure. It includes a sim.toml configuration file, a sample listener, and a boilerplate API. The command initializes a new Git repository, and makes the first commit containing all generated files.

sim init

If the current directory is not empty, the command will fail to prevent overwriting existing files. Make sure you run mkdir new-project and create a new directory before running the init command.

You can optionally scaffold a project from one of the official templates using the --template flag. For example, to start from the contract-decoder template:

sim init --template=contract-decoder

If you omit --template, the command uses the default sample template.

​
sim build

Builds your Foundry project by running forge build under the hood. This compiles every Solidity contract in your project—including the listener contracts inside listeners/—along with any imported libraries.

sim build

If there are compilation errors in your Solidity code, the build will fail. The output will provide details from the Solidity compiler to help you debug.

​
sim test

Runs the Solidity tests for your listener contracts. The tests are located in listeners/test/. This command first compiles your contracts and then executes the tests using Foundry.

sim test

If any of the tests fail, the command will exit with an error. The output will show which tests failed and provide assertion details.

​
sim authenticate

Saves your Sim IDX API key locally, allowing the CLI to authenticate with the platform. You can find and create API keys in the Sim dashboard.

sim authenticate

You will be asked to paste your API key and press Enter.

For detailed, step-by-step instructions on obtaining your API key, see the Quickstart guide.

​
sim help

Displays help information and available commands for the Sim IDX CLI. This command shows usage instructions, available commands, and options.

sim help

You can also use sim --help or sim -h for the same functionality.

​
sim abi

Provides a set of commands for managing contract ABIs and generating corresponding Solidity interfaces for use in your listener.

​
sim abi add <file_path>

Registers a contract ABI with your project and generates all the Solidity interfaces, structs, and helper functions your listener needs.

sim abi add abis/YourContract.json

Follow these steps before running the command:

  1. Obtain the contract’s ABI JSON from Etherscan or another blockchain explorer.
  2. Inside your project, create a new file in abis/ (for example, abis/YourContract.json).
  3. Paste the ABI JSON into that file and save it.
  4. Run sim abi add abis/YourContract.json pointing to the file you just created.

The command fails if the file path you provide does not exist.

​
sim abi codegen

Manually regenerates the Solidity interfaces from all ABI files currently in the abis/ directory. This is useful if the generated files need to be refreshed.

sim abi codegen

In most cases, you don’t need to run this command manually because it runs automatically after you execute sim abi add. Use it only when you want to force-regenerate the interfaces.

​
sim listeners

A namespace for commands that interact with listener contracts during local development. Similar to sim abi, you must append a sub-command after listeners.

sim listeners <COMMAND>

​
sim listeners evaluate

Runs your listener locally against historical main-chain data so you can verify that triggers fire and events are emitted before you deploy the app.

sim listeners evaluate \
  --start-block <START_BLOCK> \
  --chain-id <CHAIN_ID> \
  --end-block <END_BLOCK>

evaluate does not persist any data. It is purely a local dry-run to ensure your handler logic behaves as expected.

FlagRequiredDescription
--start-blockYesFirst block to process.
--chain-idConditional*Chain ID to test against. If omitted, Sim tries to infer it from your addTrigger definitions. Required when your listener has triggers on multiple chains.
--end-blockNoLast block to process. Provide this if you want to replay more than one block and observe state changes over a range.

The command compiles your listener, executes the triggers across the block range, and prints a summary such as:

INFO deploy: {
  "events": [
    {
      "name": "PoolCreated",
      "fields": {
        "pool": "70307790d81aba6a65de99c18865416e1eefc13e",
        "caller": "1f98431c8ad98523631ae4a59f267346ea31f984",
        "fee": "10000",
        "token1": "c02aaa39b223fe8d0a0e5c4f27ead9083c756cc2",
        "chainId": "1",
        "token0": "593e989f08e8d3ebea0ca5a17c7990d634812bc5"
      },
      "metadata": {
        "block_number": 22757345,
        "chain_id": 1
      }
    }
  ],
  "errors": []
}