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 --version

Displays the current version of the Sim IDX CLI. 
sim v0.0.86 (eaddf2 2025-06-22T18:01:14.000000000Z)
When a CLI command displays an error log, the current CLI version appears at the bottom of the output.

​
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(s) 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> \
  --listeners <LISTENER_CONTRACT>
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. Note that data availability for historical blocks can vary by chain. See the Supported Chains page for details.
--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.
--listenersNoSpecific listener contract to evaluate. Accepts any listener contract within any of the Solidity files in /listener/src. If omitted, the command will run all listener contracts in all files. The command will fail if you specify an unknown listener.
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": []
}
Handling Failed Transaction Events
When you run sim listeners evaluate, the output in your terminal may include events where the value of the name property is prefixed with fail_, such as fail_PoolCreated. A fail_ prefix indicates that the event data was generated from a transaction that failed or was reverted onchain.
This output appears exclusively in the terminal during a local evaluate run to give you a complete picture of how your listener reacts to all transactions within a block, including failed ones.Data from these failed transactions is not written to your app’s database.It is for informational purposes only.
Here’s an example of a failed trace in the terminal:
Failed Transaction Example
INFO deploy: {
  "events": [
    {
      "name": "fail_TracesBase",
      "fields": {
        "block_number": 34190545,
        "block_timestamp": 1755170437,
        "call_depth": 2,
        "call_type": 3,
        "callee": "0x7458bfdc30034eb860b265e6068121d18fa5aa72",
        "caller": "0xcbb7c0000ab88b473b1f5afd9ef808440eed33bf",
        "func_sig": "0x70a08231",
        "parent_func_sig": "0x70a08231",
        "success": false,
        "trace_address": "1,4,0",
        "tx_from": "0x17288b66bcadf1a3d083eb33e6c9ce772ff4e74f",
        "tx_to": "0x0000000000000000000000000000000000000000",
        "txn_hash": "0x9e00c37c073b300294398b2e028dfe58e1daf6ee0df53ef593de891714010fed",
        "user_op_from": "0x0000000000000000000000000000000000000000"
      },
      "metadata": {
        "blockNumber": 34190545,
        "chainId": 8453
      }
    }
  ],
  "errors": []
}