search

Supported chain families:

EVMSolanaAptosTONCanton

Search CCIP messages via the API with filters for sender, receiver, source/destination chains, and manual execution eligibility.

Synopsis

Bash

ccip-cli search messages [sender] [options]

Aliases: msgs

Description

The search command queries the CCIP API to find cross-chain messages matching the provided filters. Results are paginated automatically — the CLI fetches pages until the --limit is reached or all matching messages are returned.

In interactive terminals (TTY), after displaying results the CLI presents a menu to select and inspect individual messages in detail.

This command requires API access. It fails if --no-api is set.

Arguments

Argument	Type	Required	Description
[sender]	string	No	Filter by sender address. Same as --sender.

Options

Option	Alias	Type	Default	Description
--sender		string	-	Filter by sender address
--receiver		string	-	Filter by receiver address
--source	-s	string	-	Source chain (name, chainId, or selector)
--dest	-d	string	-	Destination chain (name, chainId, or selector)
--source-token		string	-	Filter by source token address
--manual-exec-only		boolean	false	Only return messages ready for manual execution
-q		string	-	Free-text match on addresses, hashes, messageId
--cursor		string	-	Resume from a cursor printed by an earlier run
--limit		number	20	Max results to return. 0 = unlimited.

See Configuration for global options (--format, --api, etc.).

Examples

Search by sender address

Bash

ccip-cli search messages 0x9d087fC03ae39b088326b67fA3C788236645b717

Or equivalently:

Bash

ccip-cli search messages --sender 0x9d087fC03ae39b088326b67fA3C788236645b717

Filter by source and destination chain

Bash

ccip-cli search messages --source ethereum-mainnet --dest arbitrum-mainnet

Chain identifiers accept names (ethereum-mainnet), chain IDs (1), or chain selectors (5009297550715157269).

Find messages ready for manual execution

Bash

ccip-cli search messages --manual-exec-only

Combine with other filters to narrow the results:

Bash

ccip-cli search messages --sender 0x9d08... --manual-exec-only --limit 5

Search by free text

Bash

ccip-cli search messages -q 0x20B79D39Bd44dEee4F89B1e9d0e3b945fde06491

-q matches source and destination token address, source pool address, transaction hashes, messageId, sender, and receiver. Because it spans fields, a hit may match in a role you did not intend; check the field you care about on each result.

Comma-separate terms to require all of them:

Bash

ccip-cli search messages -q 0x80ac24aA929eaF5013f6436cdA2a7ba190f5Cc0b,0x20B79D39Bd44dEee4F89B1e9d0e3b945fde06491

Named filters are AND-ed with -q:

Bash

ccip-cli search messages -q 0x20B79D39... --source ethereum-mainnet --limit 50

Resume a search across runs

When results are capped by --limit and more are available, the CLI prints a cursor to stderr:

Bash

ccip-cli search messages --source ethereum-mainnet --limit 100 --format json > page1.json
# stderr: More results available. Resume with --cursor 46zwbZnajt8FKiqha7om...

Pass it back to continue from where the previous run stopped:

Bash

ccip-cli search messages --source ethereum-mainnet --limit 100 --cursor "$CURSOR" --format json > page2.json

The cursor encodes the filters it was issued for. Filters may be repeated or omitted, but must not contradict the cursor.

Retrieve all matching messages

Bash

ccip-cli search messages --sender 0x9d08... --limit 0

Setting --limit 0 removes the cap and fetches all pages. For large result sets (1,000+), the CLI prints a progress warning.

Output as JSON for scripting

Bash

ccip-cli search messages --sender 0x9d08... --format json

JSON output skips the interactive menu and writes directly to stdout, making it suitable for piping:

Bash

ccip-cli search messages --sender 0x9d08... --format json | jq '.[].messageId'

Use a custom API endpoint

Bash

ccip-cli search messages --sender 0x9d08... --api https://staging-api.example.com

Output

Table format (default)

Each result is displayed as a table row with:

Field	Description
messageId	The CCIP message ID
status	Message status (e.g., SUCCESS, FAILED)
source	Source network name and chain ID
dest	Destination network name and chain ID
sender	Sender address
receiver	Receiver address
txHash	Source transaction hash
timestamp	Send timestamp

After displaying results, an interactive selection menu appears (TTY only) allowing you to pick a message and view its full details — equivalent to running ccip-cli show on that message.

JSON format

With --format json, results are written as a JSON array to stdout. No interactive menu is shown.

Log format

With --format log, each result is printed as a raw JavaScript object. The interactive menu is still available in TTY mode.

Behavior

1. Validates that API access is enabled (fails with an error if --no-api is set)
2. Resolves --source and --dest to chain selectors via networkInfo()
3. Paginates through the API a page at a time, starting from --cursor if given, requesting only as many results as --limit still needs, until the limit is reached or the results are exhausted
4. Displays results in the requested format, printing a resume cursor to stderr if more remain
5. In TTY mode (except JSON format), presents an interactive menu to inspect individual messages via getMessageById

See Also

• show — Display full details of a CCIP message
• manual-exec — Execute a pending or failed message
• Configuration — API, RPC, and output format options

Exit Codes

Code	Meaning
0	Success — results returned (or no matches found with warning)
1	Error (API unavailable, network failure, invalid arguments)