> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cosmos.network/llms.txt
> Use this file to discover all available pages before exploring further.

# Command Line Interface (CLI)

> The CLI tool ('evmd') provides a full-feature interface for interacting with the blockchain. This includes commands for node operations, key management, querying blockchain state, submitting transactions, and more.

export const footnote = ({children}) => {
  return <span style={{
    fontSize: '0.8em',
    opacity: 0.75,
    display: 'block',
    marginTop: '0.5em'
  }}>
      {children}
    </span>;
};

<Info>
  **Node Requirements**

  To use the `query` and `tx` commands, your `evmd` node must either:

  * Be fully synced with the network you're interacting with, OR
  * Be configured to use an external RPC endpoint in `~/.evmd/config/client.toml`

  Example client.toml configuration:

  ```toml theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}}
  # The network chain ID
  chain-id = "myapp-1"
  # The keyring's backend
  keyring-backend = "os"
  # CLI output format
  output = "text"
  # <host>:<port> to CometBFT RPC interface for this chain
  node = "tcp://localhost:26657"
  # Transaction broadcasting mode (sync|async)
  broadcast-mode = "sync"
  ```

  To use an external RPC, update the `node` field to point to a public or private RPC endpoint.
</Info>

## Global Flags

These flags are available for all commands:

| Flag                   | Description                                                                  | Default                 |
| ---------------------- | ---------------------------------------------------------------------------- | ----------------------- |
| `-b, --broadcast-mode` | Transaction broadcasting mode (sync\|async)                                  | `sync`                  |
| `--chain-id`           | Specify Chain ID for sending Tx                                              |                         |
| `--fees`               | Fees to pay along with transaction (e.g., 10atest)                           |                         |
| `--from`               | Name or address of private key with which to sign                            |                         |
| `--gas-adjustment`     | Adjustment factor to multiply against the estimate returned by tx simulation | `1`                     |
| `--gas-prices`         | Gas prices to determine the transaction fee (e.g., 10atest)                  |                         |
| `--home`               | Directory for config and data                                                | `~/.evmd`               |
| `--keyring-backend`    | Select keyring's backend                                                     | `os`                    |
| `--log_format`         | The logging format (json\|plain)                                             | `plain`                 |
| `--log_level`          | The logging level                                                            | `info`                  |
| `--log_no_color`       | Disable colored logs                                                         |                         |
| `--node`               | \<host>:\<port> to CometBFT RPC interface                                    | `tcp://localhost:26657` |
| `--trace`              | Print out full stack trace on errors                                         |                         |

## Core Commands

### Node Operations

#### `start`

Run the full node.

```bash theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}}
evmd start [flags]
```

Key flags:

* `--json-rpc.enable`: Enable the JSON-RPC server
* `--json-rpc.address`: JSON-RPC server address (default: `127.0.0.1:8545`)
* `--json-rpc.ws-address`: JSON-RPC WebSocket server address (default: `127.0.0.1:8546`)
* `--json-rpc.api`: API namespaces to enable (default: `eth,net,web3`)
* `--json-rpc.enable-indexer`: Enable the custom tx indexer for json-rpc
* `--json-rpc.enable-profiling`: Enable profiling in the debug namespace
* `--json-rpc.filter-cap`: Sets the global cap for total number of filters (default: `200`)
* `--json-rpc.gas-cap`: Sets a cap on gas that can be used in eth\_call/estimateGas (default: `25000000`)
* `--json-rpc.txfee-cap`: Sets a cap on transaction fee that can be sent via RPC APIs (default: `1`)
* `--json-rpc.batch-request-limit`: Maximum number of requests in a batch (default: `1000`)
* `--json-rpc.evm-timeout`: Sets a timeout used for eth\_call (default: `5s`)
* `--json-rpc.logs-cap`: Sets the max number of results from eth\_getLogs query (default: `10000`)
* `--json-rpc.block-range-cap`: Sets the max block range allowed for eth\_getLogs query (default: `10000`)

<Warning>
  You should only expose the debug endpoint in non production settings as it could impact network performance and uptime under certain conditions.
</Warning>

### Additional Information

For more detailed information about specific commands, simply use the `--help` or `-h` flag:

```bash theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}}
evmd [command] --help
evmd [command] [subcommand] --help
```

#### Initializing the client / Running a node

Creates validator consensus key, p2p address book file, genesis (replace with the relevant one for your chain), and CometBFT + application configuration files.

# Initialize node

```bash theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}}
evmd init mynode --chain-id my-chain-1
```

# Start node with JSON-RPC enabled

```bash theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}}
evmd start --json-rpc.enable --json-rpc.api eth,web3,net,txpool,debug
```

# Get node status

You must be either running the client as part of a netork (or alone, for testing) or have an external RPC configured in `client.toml` first.

```bash theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}}
evmd status
```

Returns:

```json theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}}
{
  "node_info": {
    "protocol_version": {
      "p2p": "8",
      "block": "11",
      "app": "0"
    },
    "id": "f9bc9603524303b8843911c4ce7a4f12764af8dc",
    "listen_addr": "tcp://0.0.0.0:26656",
    "network": "4321",
    "version": "0.38.17",
    "channels": "40202122233038606100",
    "moniker": "devnet-1-node-0",
    "other": {
      "tx_index": "on",
      "rpc_address": "tcp://0.0.0.0:26657"
    }
  },
  "sync_info": {
    "latest_block_hash": "A6E4FDB7255B09788C5A6CB25C05060D3EA2180B4DA387CB93086691B6BEDF5E",
    "latest_app_hash": "43377D0A56BFA70643781115C388472B7DDF788398D61AE19AC1EC133862FBBF",
    "latest_block_height": "1752468",
    "latest_block_time": "2025-07-30T18:24:16.220775791Z",
    "earliest_block_hash": "65BDD3E49B82D762F7D75C1333EBF795186F604CF945A711A82353BA840070E0",
    "earliest_app_hash": "E3B0C44298FC1C149AFBF4C8996FB92427AE41E4649B934CA495991B7852B855",
    "earliest_block_height": "1",
    "earliest_block_time": "2025-06-14T01:11:39.072887517Z",
    "catching_up": false
  },
  "validator_info": {
    "address": "E7C00E112C764B0726EBFB96905BB282FCFCA36C",
    "pub_key": {
      "type": "tendermint/PubKeyEd25519",
      "value": "IN0vx0HE22RHnnCHlfsY5nE7IDW2016TrIi1eAQsZRo="
    },
    "voting_power": "0"
  }
}
```

<Tip>The same information can be seen by calling the `/status` method on any accessible Comet RPC</Tip>

#### `index-eth-tx`

Index historical Ethereum transactions.

```bash theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}}
evmd index-eth-tx [backward|forward] [flags]
```

* `backward`: Index from first indexed block to earliest block
* `forward`: Index from latest indexed block to latest block

### Key Management

The `keys` command provides keyring management functionality for accounts.

#### `keys add`

Add a new key or recover from mnemonic.

```bash theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}}
evmd keys add [name] [flags]
```

Flags:

* `--recover`: Recover key from mnemonic
* `--algo`: Key algorithm (eth\_secp256k1)
* `--coin-type`: Coin type (60 for Ethereum)

#### `keys list`

List all keys in the keyring.

```bash theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}}
evmd keys list [flags]
```

#### `keys list-key-types`

List all supported key types.

```bash theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}}
evmd keys list-key-types [flags]
```

#### `keys show`

Display key information.

```bash theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}}
evmd keys show [name|address] [flags]
```

#### `keys export`

Export a private key.

```bash theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}}
evmd keys export [name] [flags]
```

#### `keys import`

Import a private key.

```bash theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}}
evmd keys import [name] [keyfile] [flags]
```

#### EVM-specific Key Commands

##### `keys unsafe-export-eth-key`

Export an Ethereum private key (**UNSAFE**).

```bash theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}}
evmd keys unsafe-export-eth-key [name] [flags]
```

##### `keys unsafe-import-eth-key`

Import Ethereum private keys into the local keybase (**UNSAFE**).

```bash theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}}
evmd keys unsafe-import-eth-key [name] [pk] [flags]
```

### Query Commands

The `query` (or `q`) command provides read-only access to blockchain data.

#### EVM Module Queries

##### `query evm account`

Get account information for an address.

```bash theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}}
evmd query evm account [address] [flags]
```

##### `query evm balance-bank`

Get bank balance for a 0x address.

```bash theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}}
evmd query evm balance-bank [0x-address] [denom] [flags]
```

##### `query evm balance-erc20`

Get ERC20 token balance.

```bash theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}}
evmd query evm balance-erc20 [0x-address] [erc20-address] [flags]
```

##### `query evm code`

Get smart contract code.

```bash theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}}
evmd query evm code [address] [flags]
```

##### `query evm storage`

Get storage value at a specific key.

```bash theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}}
evmd query evm storage [address] [key] [flags]
```

##### `query evm config`

Get EVM configuration values.

```bash theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}}
evmd query evm config [flags]
```

##### `query evm params`

Get EVM module parameters.

```bash theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}}
evmd query evm params [flags]
```

##### Address Conversion

Convert between Ethereum (0x) and Cosmos (bech32) addresses:

```bash theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}}
# 0x to bech32
evmd query evm 0x-to-bech32 [0x-address] [flags]

# bech32 to 0x
evmd query evm bech32-to-0x [bech32-address] [flags]
```

#### ERC20 Module Queries

##### `query erc20 token-pairs`

Get all registered token pairs.

```bash theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}}
evmd query erc20 token-pairs [flags]
```

##### `query erc20 token-pair`

Get a specific token pair.

```bash theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}}
evmd query erc20 token-pair [token-address-or-denom] [flags]
```

##### `query erc20 params`

Get ERC20 module parameters.

```bash theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}}
evmd query erc20 params [flags]
```

#### Feemarket Module Queries

##### `query feemarket base-fee`

Get the base fee at a given height.

```bash theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}}
evmd query feemarket base-fee [flags]
```

##### `query feemarket block-gas`

Get the block gas used at a given height.

```bash theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}}
evmd query feemarket block-gas [flags]
```

##### `query feemarket params`

Get fee market parameters.

```bash theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}}
evmd query feemarket params [flags]
```

#### Precisebank Module Queries

##### `query precisebank remainder`

Get the remainder amount in the precise bank module.

```bash theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}}
evmd query precisebank remainder [flags]
```

##### `query precisebank fractional-balance`

Get the fractional balance of an account.

```bash theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}}
evmd query precisebank fractional-balance [address] [flags]
```

#### Standard Cosmos Queries

##### Bank Module

```bash theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}}
# Get account balances
evmd query bank balances [address] [flags]

# Get specific denom balance
evmd query bank balance [address] [denom] [flags]

# Get total supply
evmd query bank total [flags]
```

##### Staking Module

```bash theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}}
# Get all validators
evmd query staking validators [flags]

# Get delegations for an address
evmd query staking delegations [delegator-address] [flags]

# Get unbonding delegations
evmd query staking unbonding-delegations [delegator-address] [flags]
```

##### Distribution Module

```bash theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}}
# Get rewards
evmd query distribution rewards [delegator-address] [validator-address] [flags]

# Get commission
evmd query distribution commission [validator-address] [flags]
```

##### Governance Module

```bash theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}}
# List all proposals
evmd query gov proposals [flags]

# Get specific proposal
evmd query gov proposal [proposal-id] [flags]

# Get votes on a proposal
evmd query gov votes [proposal-id] [flags]
```

### Transaction Commands

The `tx` command is used to create and broadcast transactions.

#### EVM Transactions

##### `tx evm send`

Send funds between accounts.

```bash theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}}
evmd tx evm send [from] [to] [amount] [flags]
```

##### `tx evm raw`

Build a Cosmos transaction from a raw Ethereum transaction.

```bash theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}}
evmd tx evm raw [hex-encoded-tx] [flags]
```

#### ERC20 Transactions

##### `tx erc20 convert-coin`

Convert native Cosmos coins to ERC20 tokens.

```bash theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}}
evmd tx erc20 convert-coin [amount] [receiver] [flags]
```

##### `tx erc20 convert-erc20`

Convert ERC20 tokens to native Cosmos coins.

```bash theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}}
evmd tx erc20 convert-erc20 [contract-address] [amount] [receiver] [flags]
```

##### `tx erc20 register-erc20`

Register native ERC20 tokens (governance only).

```bash theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}}
evmd tx erc20 register-erc20 [contract-address...] [flags]
```

##### `tx erc20 toggle-conversion`

Enable or disable token pair conversion (governance only).

```bash theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}}
evmd tx erc20 toggle-conversion [token] [flags]
```

#### Standard Cosmos Transactions

##### Bank Transactions

```bash theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}}
# Send coins
evmd tx bank send [from] [to] [amount] [flags]

# Multi-send
evmd tx bank multi-send [from] [to1] [amount1] [to2] [amount2] ... [flags]
```

##### Staking Transactions

```bash theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}}
# Create validator
evmd tx staking create-validator [flags]

# Delegate
evmd tx staking delegate [validator-address] [amount] [flags]

# Unbond
evmd tx staking unbond [validator-address] [amount] [flags]

# Redelegate
evmd tx staking redelegate [src-validator] [dst-validator] [amount] [flags]
```

##### Governance Transactions

```bash theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}}
# Submit proposal
evmd tx gov submit-proposal [proposal-type] [flags]

# Vote on proposal
evmd tx gov vote [proposal-id] [option] [flags]

# Deposit on proposal
evmd tx gov deposit [proposal-id] [amount] [flags]
```

### Advanced Commands

#### `genesis`

Genesis file manipulation commands.

```bash theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}}
# Add genesis account
evmd genesis add-genesis-account [address] [coins] [flags]

# Collect genesis transactions
evmd genesis collect-gentxs [flags]

# Generate genesis transaction
evmd genesis gentx [key-name] [amount] [flags]
```

#### `comet`

CometBFT-specific commands.

```bash theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}}
# Show node ID
evmd comet show-node-id [flags]

# Show validator info
evmd comet show-validator [flags]

# Reset blockchain state
evmd comet unsafe-reset-all [flags]
```

#### `debug`

Debugging utilities.

```bash theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}}
# Get raw bytes for address
evmd debug addr [address] [flags]

# Decode raw hex bytes
evmd debug raw-bytes [hex] [flags]

# Convert public key
evmd debug pubkey [pubkey] [flags]
```

## Examples

### Setting up a new account

```bash theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}}
# Create a new account
evmd keys add myaccount

# Import an Ethereum private key
evmd keys unsafe-import-eth-key myethaccount 0x...

# List all accounts
evmd keys list

# Show account details
evmd keys show myaccount
```

### Querying blockchain state

```bash theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}}
# Get account balance
evmd query bank balances cosmos1...

# Get EVM account info
evmd query evm account 0x...

# Get ERC20 balance
evmd query evm balance-erc20 0xUserAddress 0xTokenAddress

# Get base fee
evmd query feemarket base-fee
```

### Sending transactions

```bash theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}}
# Send native tokens
evmd tx bank send myaccount cosmos1... 100atest --gas-prices 10atest

# Send native tokens using EVM message
evmd tx evm send myaccount 0x... 100atest --gas-prices 10atest

# Convert coins to ERC20
evmd tx erc20 convert-coin 100atest 0x... --from myaccount
```

## Configuration

* Configuration directory: `~/.evmd/`
* Key storage: Managed by the keyring backend (os, file, test)
* Node configuration: `~/.evmd/config/config.toml`
* App configuration: `~/.evmd/config/app.toml`

<Info>If you use the `--home` flag upon initializing the light client, the root/config directory will be generated there</Info>