> ## Documentation Index > Fetch the complete documentation index at: /docs/llms.txt > Use this file to discover all available pages before exploring further. # CLI commands > IBC CLI command reference The IBC CLI contains commands for configuring, deploying, running, and monitoring IBC deployments, relayers, and attestors. Commands are grouped here the way the binary groups them, so any of them prints its own flags with `--help`. The sections run in the order a reader meets them: `config` and `keys`, then `deploy`, then `relayer` and `attestor`, then `tx` and `query`, then `migrate`. ## Global flags | Flag | Default | Description | | - | - | - | | `--config ` | `ibc.yml` | Config file relative to home. | | `--db ` | | Database URL override. | | `--home ` | `~/.ibc` | IBC home directory. | | `--log-json` | | Enable JSON logging. | | `--log-level ` | `info` | Log level (debug, info, warn, error). | | `-q, --quiet` | | Quiet mode. | `--home` is where the config file, the keystore, the manifests, and the relayer's database live. A command that reads the config changes into that directory first, so a config naming `keys/alice.json` finds `~/.ibc/keys/alice.json`. ## `config` The config is a YAML file describing every chain, connection, attestor, and signer the other commands use. ### `ibc config add-chain` Add a chain entry to the config. | Flag | Default | Description | | - | - | - | | `--chain-id ` | required | Chain ID. | | `--deployer ` | | Signer alias used by ibc deploy for this chain. | | `--router ` | left blank, fill in via render-config | Ics26Router address. | | `--rpc ` | required | Chain RPC URL. | | `--ws ` | | Chain websocket URL, required for chains sourcing auto-relayed routes. | ```bash theme={null} ibc config add-chain --chain-id 41001 --rpc http://localhost:8545 ``` Leave `--router` out until the chain has a router to point at. `ibc deploy render-config` prints the finished chain entries, with the router and multicall addresses filled in from the manifests. ### `ibc config new` Create new config file. | Flag | Default | Description | | - | - | - | | `--out` | | Output the config to stdout. | The command refuses to overwrite an existing file, so it is safe to run twice. ### `ibc config validate` Validate config structure and cross-references. | Flag | Default | Description | | - | - | - | | `--live` | | Extra validation checks. | `--live` adds checks that need live chain RPC endpoints. Pass `relayer` or `attestor` to also verify the file is sufficient to run that process. This command rejects unknown fields and unresolved cross-references. ```bash theme={null} ibc config validate ``` ```json theme={null} { "path": "/home/you/.ibc/ibc.yml", "status": "valid" } ``` With a target, the response also includes `"relayer": "valid"` or `"attestor": "valid"`. ## `keys` Keys live in `/keys/`, one file each. These can be named by signers in the config file. ### `ibc keys import` Import a private key into `/keys/`. | Flag | Default | Description | | - | - | - | | `--private-key ` | required | Hex-encoded private key. | | `-p, --populate-config` | | Write key reference to the config. | ```bash theme={null} ibc keys import ecdsa deployer --private-key "$DEPLOYER_KEY" --populate-config ``` ### `ibc keys list` Lists every key from `/keys/`. ### `ibc keys new` Saves key into `/keys/` or prints to stdout if name is not provided. | Flag | Default | Description | | - | - | - | | `-p, --populate-config` | | Write key reference to the config. | ```bash theme={null} ibc keys new ecdsa relayer --populate-config ``` ### `ibc keys show` Show key details from `/keys/`; optionally print the private key. | Flag | Default | Description | | - | - | - | | `--private` | | Show private key. | ```bash theme={null} ibc keys show relayer ``` > **Warning:** Do not run `keys show --private` on a shared or recorded terminal. The private key it prints controls every asset its address holds. ## `deploy` Deploying a working connection between two chains takes `deploy core` on both, then a `deploy client` subcommand on both, each client tracking the other chain. The [tutorial](/docs/ibc/05-ibc-cli/02-tutorial/01-deploy-ibc-and-send-a-token.md) walks that through end to end. `--chain` is declared once for the whole `deploy` group, and the commands that provision something reject an empty value themselves: `deploy core`, `deploy client attestation`, `deploy client besu`, `deploy gmp`, and `deploy ift`. `--dry-run` prints the steps a provisioning command would take and submits nothing. It has no effect on `deploy show`, `deploy status`, or `deploy render-config`; `render-config --populate-config` still writes the configuration. Manifests are machine-generated. A command that provisions something reads the manifest, decides from it what is already done, and writes it back. > **Warning:** Do not edit a manifest by hand. A deploy command decides what to skip from it, and an edit that disagrees with the chain either is overwritten or makes the next run fail. ### `ibc deploy client attestation` Deploy and register an attestation light client. | Flag | Default | Description | | - | - | - | | `--attestors ` | configured attestations for the tracked chain | Attestors for the new client as addresses, attestation names, or signer aliases. | | `--client-id ` | `cli--`, chain ids sorted | Client id. | | `--counterparty-chain ` | required | Counterparty chain id the client tracks. | | `--counterparty-client-id ` | `cli--`, chain ids sorted | Counterparty's client id. | | `--height ` | counterparty head | Initial trusted height. | | `--threshold ` | `1` | Signature threshold. | | `--timestamp ` | counterparty head | Initial trusted timestamp seconds. | | `--chain ` | required | Chain ID for the chain being deployed to. | | `--deployer ` | | Signer alias override for deployment transactions. | | `--dry-run` | | Print the step plan without submitting transactions. | | `--manifest-dir ` | `deployments` | Manifest directory relative to home. | | `--yes` | | Skip confirmation prompts. | ```bash theme={null} ibc deploy client attestation --chain 41001 --counterparty-chain 41002 --threshold 1 --yes ``` The client lives on `--chain` and watches `--counterparty-chain`. `--attestors` names the attestors watching the counterparty, since those are the signatures this client verifies. For `remote` attestors, pass the address instead of names. Left out entirely, the command fails when the config lists no attestors for the counterparty chain. Rerunning with the same `--client-id` continues that client. Rerunning with different attestors or a different threshold under the same id fails and lists the differences, because those values are fixed when the client is constructed. ### `ibc deploy client besu` Deploy and register a Besu light client that trusts a recent counterparty header. | Flag | Default | Description | | - | - | - | | `--client-id ` | `cli--`, chain ids sorted | Client id. | | `--counterparty-chain ` | required | Counterparty chain id the client tracks. | | `--counterparty-client-id ` | `cli--`, chain ids sorted | Counterparty's client id. | | `--trust-level ` | `2/3` | Fraction n/d of the trusted validators that must seal an update, from 1/3 to 2/3. | | `--trusting-period ` | required | Positive trusted state lifetime, at most 720h. | | `--chain ` | | Chain ID for the chain being deployed to. | | `--deployer ` | | Signer alias override for deployment transactions. | | `--dry-run` | | Print the step plan without submitting transactions. | | `--manifest-dir ` | `deployments` | Manifest directory relative to home. | | `--yes` | | Skip confirmation prompts. | `--chain` is required. ```bash theme={null} ibc deploy client besu --chain 41002 --counterparty-chain 41001 --trusting-period 336h --yes ``` The client starts trusting the counterparty's current head, or an earlier header when the head is more than the 12-second maximum clock drift ahead of this chain's latest block. One light client contract verifies QBFT and IBFT 2.0; the relayer submits each header in the form its seals sign. Configure the counterparty chain's `evm.ics26Router` with its deployed router address first; no local counterparty manifest is required. Rerunning under the same id with a different router, trusting period or trust level fails and lists the differences. See [Besu light clients](/docs/ibc/04-light-clients/03-besu-light-client.md#deploying) for choosing the trusting period. ### `ibc deploy core` Deploy the core IBC routing stack on one chain. | Flag | Default | Description | | - | - | - | | `-p, --populate-config` | | Write the deployed router and multicall addresses to the config. | | `--chain ` | required | Chain ID for the chain being deployed to. | | `--deployer ` | | Signer alias override for deployment transactions. | | `--dry-run` | | Print the step plan without submitting transactions. | | `--manifest-dir ` | `deployments` | Manifest directory relative to home. | | `--yes` | | Skip confirmation prompts. | Deploys the access manager, router, and multicall. The manifest records the proxies as `core.router` and `core.multicall`. Rerunning resumes unfinished deployment steps and skips contracts already deployed. Pass `--populate-config` to write the router and multicall addresses into the chain's config entry. With `--dry-run`, the config stays unchanged. ### `ibc deploy gmp` Deploy the ICS27-GMP app on one chain. | Flag | Default | Description | | - | - | - | | `--chain ` | required | Chain ID for the chain being deployed to. | | `--deployer ` | | Signer alias override for deployment transactions. | | `--dry-run` | | Print the step plan without submitting transactions. | | `--manifest-dir ` | `deployments` | Manifest directory relative to home. | | `--yes` | | Skip confirmation prompts. | ### `ibc deploy ift` Deploy an IFT token on one chain and set its rate limit, which IFT requires before any transfer. Rerunning with a different rate limit updates it. With an `--owner` other than the deployer no limit is set and the rate-limit flags are rejected: the owner must call setIFTRateLimit before any transfer. | Flag | Default | Description | | - | - | - | | `--name ` | required | ERC20 token name. | | `--owner ` | `deployer` | Token owner address. | | `--rate-limit-capacity ` | required | Most base units each direction lets through when full; not allowed with an `--owner` other than the deployer. | | `--rate-limit-window ` | `24h0m0s` | Time for an empty rate-limit bucket to refill completely. | | `--symbol ` | required | ERC20 token symbol (need not be unique). | | `--chain ` | required | Chain ID for the chain being deployed to. | | `--deployer ` | | Signer alias override for deployment transactions. | | `--dry-run` | | Print the step plan without submitting transactions. | | `--manifest-dir ` | `deployments` | Manifest directory relative to home. | | `--yes` | | Skip confirmation prompts. | ```bash theme={null} ibc deploy ift --chain 41001 --name "Demo Token" --symbol DEMO --rate-limit-capacity 1000000000000000000000 --yes ``` ### `ibc deploy ift-bridge` Register both sides of an IFT bridge between two chains' tokens. | Flag | Default | Description | | - | - | - | | `--chain-a ` | required | First chain id. | | `--chain-b ` | required | Second chain id. | | `--client-id ` | `cli--` | Client id the bridge relays over. | | `--ift-a ` | required | IFT token address on chain A. | | `--ift-b ` | required | IFT token address on chain B. | | `--send-call-constructor-a ` | deploy or reuse the EVM constructor | Send call constructor address on chain A. | | `--send-call-constructor-b ` | deploy or reuse the EVM constructor | Send call constructor address on chain B. | | `--chain ` | | Chain ID for the chain being deployed to. | | `--deployer ` | | Signer alias override for deployment transactions. | | `--dry-run` | | Print the step plan without submitting transactions. | | `--manifest-dir ` | `deployments` | Manifest directory relative to home. | | `--yes` | | Skip confirmation prompts. | ```bash theme={null} ibc deploy ift-bridge --chain-a 41001 --ift-a 0xTokenOnA --chain-b 41002 --ift-b 0xTokenOnB --yes ``` ### `ibc deploy render-config` Print the existing config plus the settings to relay between two chains. | Flag | Default | Description | | - | - | - | | `--signer-a ` | | Override the relay signer on chainA; omitted preserves existing settings. | | `--signer-b ` | | Override the relay signer on chainB; omitted preserves existing settings. | | `-p, --populate-config` | | Write the printed config to the config file. | | `--chain ` | | Chain ID for the chain being deployed to. | | `--deployer ` | | Signer alias override for deployment transactions. | | `--dry-run` | | Print the step plan without submitting transactions. | | `--manifest-dir ` | `deployments` | Manifest directory relative to home. | | `--yes` | | Skip confirmation prompts. | ```bash theme={null} ibc deploy render-config 41001 41002 ``` ### `ibc deploy show` Print the recorded deployment manifest for a chain. | Flag | Default | Description | | - | - | - | | `--chain ` | | Chain ID for the chain being deployed to. | | `--deployer ` | | Signer alias override for deployment transactions. | | `--dry-run` | | Print the step plan without submitting transactions. | | `--manifest-dir ` | `deployments` | Manifest directory relative to home. | | `--yes` | | Skip confirmation prompts. | ```bash theme={null} ibc deploy show 41001 ``` ### `ibc deploy status` Verify recorded deployments against live chain state. | Flag | Default | Description | | - | - | - | | `--chain ` | | Chain ID for the chain being deployed to. | | `--deployer ` | | Signer alias override for deployment transactions. | | `--dry-run` | | Print the step plan without submitting transactions. | | `--manifest-dir ` | `deployments` | Manifest directory relative to home. | | `--yes` | | Skip confirmation prompts. | ## `relayer` The relayer runs in the foreground and serves gRPC on `server.listenAddr`. ### `ibc relayer relay` Trigger relaying of the packets emitted by a source transaction. | Flag | Default | Description | | - | - | - | | `--chain-id ` | required | Source chain id. | | `--host ` | | Dial this address instead of resolving from config. | | `--tx-hash ` | required | Source transaction hash. | ```bash theme={null} ibc relayer relay --chain-id 41001 --tx-hash 0xSendTxHash ``` The command asks for every packet in that transaction. The relayer takes the ones it has a configured client and route for. ### `ibc relayer run` Run the relayer. | Flag | Default | Description | | - | - | - | | `--clear-on-start` | `true` | Clear outstanding packets at startup. | | `--no-migrate` | | Skip database migrations. | One process can be both. `relayer run` serves the relayer API and also runs every attestor the config marks `local`. It applies pending database migrations at startup, and `--no-migrate` skips that. ### `ibc relayer packets` List the packets the relayer is aware of, most recent first. | Flag | Default | Description | | - | - | - | | `--all` | | Follow every page and print the combined result. | | `--chain-id ` | | Source chain id. | | `--cursor ` | | Next\_cursor from a previous response, to resume paging. | | `--destination-chain-id ` | | Destination chain id. | | `--destination-client-id ` | | Destination client id. | | `--host ` | | Dial this address instead of resolving from config. | | `--limit ` | 100, max 1000 | Maximum packets to return. | | `--sequence ` | | Packet sequence number. | | `--source-client-id ` | | Source client id. | | `--state ` | | Relay state (not-selected, pending, rejected, relay-failed, succeeded, timed-out). | | `--tx-hash ` | | Source transaction hash. | ```bash theme={null} ibc relayer packets --chain-id 41001 --tx-hash 0xSendTxHash ``` Every filter flag is optional, and they combine. Results are paged: `--all` follows the pages and prints the combined result, and `--cursor` resumes from a previous one. Use the short names in the flag table for `--state`. For example, `--state succeeded` selects `PACKET_STATE_SUCCEEDED` results. See [API](/docs/ibc/05-ibc-cli/04-reference/03-api.md#packetstate) for the returned states. ## `attestor` The attestor also runs in the foreground and serves gRPC on `server.listenAddr`. The query commands take an attestor's name as an argument rather than a flag, and `--host` dials an address directly instead of resolving that name through the config. ### `ibc attestor info` Query a local attestor's identity. | Flag | Default | Description | | - | - | - | | `--host ` | | Dial this address instead of resolving from config. | ### `ibc attestor latest-height` Query a local attestor's latest attestable height. | Flag | Default | Description | | - | - | - | | `--host ` | | Dial this address instead of resolving from config. | ### `ibc attestor run` Run the attestor. ### `ibc attestor state-attestation` Query a local attestor for a state attestation at `--height`. | Flag | Default | Description | | - | - | - | | `--height ` | | Height to attest. | | `--host ` | | Dial this address instead of resolving from config. | Pass a positive `--height`. Zero and omission are rejected. Use `ibc attestor latest-height ` to get the highest attestable height. ## `tx` These commands submit transactions to a chain. ### `ibc tx ift mint` Mint `--amount` of the IFT token at `--ift` to `--to`. The `--from` signer must be the token's owner. | Flag | Default | Description | | - | - | - | | `--amount ` | required | Amount to mint, in the token's base unit. | | `--to ` | required | Recipient address, or a configured signer alias. | | `--chain ` | required | Chain ID the IFT token is deployed on. | | `--from ` | required | Signer alias to submit the transaction with. | | `--ift ` | required | IFT token address. | ### `ibc tx ift send` Initiate a cross-chain transfer of `--amount` of the IFT token at `--ift`, over the bridge registered for `--client-id`, to `--to` on the counterparty chain. | Flag | Default | Description | | - | - | - | | `--amount ` | required | Amount to send, in the token's base unit. | | `--client-id ` | required | Client id the bridge is registered for. | | `--timeout ` | `15m0s` | Relative send timeout. | | `--to ` | required | Receiver address on the counterparty chain, or a configured signer alias. | | `--chain ` | required | Chain ID the IFT token is deployed on. | | `--from ` | required | Signer alias to submit the transaction with. | | `--ift ` | required | IFT token address. | ```bash theme={null} ibc tx ift send --chain 41001 --ift 0xTokenOnA --client-id cli-41001-41002 \ --to 0xReceiver --amount 500000000000000000 --from deployer ``` The send commits a packet and emits it. Relaying can then be called with `relayer relay`. ## `query` These commands read chain state and submit nothing. ### `ibc query ift balance` Query an address's IFT token balance. | Flag | Default | Description | | - | - | - | | `--address ` | required | Account address, or a configured signer alias. | | `--chain ` | required | Chain ID the IFT token is deployed on. | | `--ift ` | required | IFT token address. | ## `migrate` These commands move the schema of the relayer's database up and down. ### `ibc migrate down` Migrate DB down. `migrate down` reverses one migration, the most recent. ### `ibc migrate status` Print migration status. ### `ibc migrate up` Migrate DB up. Migrations run against the `db` block, so `--db` picks a different database for one invocation. ## Next steps * [Configuration](/docs/ibc/05-ibc-cli/04-reference/01-configuration.md) for the file these commands read. * [API](/docs/ibc/05-ibc-cli/04-reference/03-api.md) for the gRPC calls behind `relayer relay`, `relayer packets`, and the attestor queries. This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.