Skip to main content

​
Overview​

The Hyperlane CLI is the official command-line tool for deploying Hyperlane contracts to new chains. It also includes utilities for interacting with deployed contracts and registries. The published version is available on NPM. The source is available on GitHub in the monorepo.

​
Setup​

Node 18 or newer is required
To install the CLI globally, use the npm install -g command. This will the hyperlane command available anywhere in your terminal. 
# Install with NPM
npm install -g @hyperlane-xyz/cli

# Or uninstall old versions
npm uninstall -g @hyperlane-xyz/cli
Alternatively, for running individual commands, you can use npx or dlx: 
# Run via NPM's npx command
npx @hyperlane-xyz/cli

# Or via Yarn's dlx command
yarn dlx @hyperlane-xyz/cli

​
Usage​

To view a list of the available commands and their arguments, run hyperlane --help. A few common command options include:
  • --version: Display your current installed version of the CLI
  • --registry: Set the registry URI to use for chain metadata and contract addresses
  • --overrides: Set an additional path for overrides to the canonical registry data
  • log: Set the log format for the CLI (defaults to pretty)
  • verbosity: Set the log level for the CLI (defaults to info)
  • key: Set the key to use for signing transactions (defaults to the HYP_KEY env var)

​
Registries​

By default, the CLI will pull chain metadata and contract addresses from the canonical Hyperlane Registry but will write new configs and deployments to your local filesystem. For more information see the Registries page.

​
Warp Send​

hyperlane warp send supports transfers between any combination of supported VMs:
ProtocolExamples
Ethereum (EVM)Ethereum, Arbitrum, Base, Optimism
TronTron mainnet
Sealevel (SVM)Solana, Eclipse
Cosmos / CosmosNativeNeutron, Injective, Stride
StarknetStarknet mainnet
RadixRadix mainnet

​
Basic usage

# EVM to EVM
hyperlane warp send -w ETH/ethereum-arbitrum

# EVM to Cosmos (recipient required for non-EVM destinations)
hyperlane warp send -w USDC/ethereum-neutron --recipient neutron1abc...

# Cosmos to EVM
export HYP_KEY_COSMOSNATIVE=<cosmos_hex_private_key>
hyperlane warp send -w ATOM/neutron-ethereum --amount 1000000

​
Non-EVM destination requirements

When the destination chain is non-EVM, the following rules apply:
  • --recipient is required — there is no signer-based fallback for non-EVM destinations. Omitting it will error before any transaction is sent.
  • --relay is skipped — self-relay only works when both origin and destination are EVM. For non-EVM destinations, run an external relayer or wait for the Hyperlane relayer network to deliver.
  • --round-trip requires all-EVM chains — since non-EVM chains cannot be intermediate hop origins, round-trip mode is restricted to EVM-only routes.
  • Delivery confirmation — for non-EVM destinations, the CLI polls the Hyperlane Explorer for delivery status instead of checking on-chain. The CLI prints the message ID after a successful send — track delivery at https://explorer.hyperlane.xyz/message/<messageId>.

​
Non-EVM origin requirements

When sending from a non-EVM origin chain, set the protocol-specific private key: 
# Cosmos / CosmosNative
export HYP_KEY_COSMOSNATIVE=<hex_private_key>

# Sealevel (SVM) — path to Solana keypair file
export HYP_KEY_SEALEVEL=<path_to_keypair.json>

# Starknet
export HYP_KEY_STARKNET=<hex_private_key>

# Tron
export HYP_KEY_TRON=<hex_private_key>

# Radix
export HYP_KEY_RADIX=<hex_private_key>

​
Multi-hop transfers

In multi-hop transfers, non-EVM chains can only appear as the final destination, not as intermediate hops. When no --origin/--destination is specified, the CLI automatically orders EVM chains first so non-EVM chains become the final destination.

​
Warp Route ID

Many CLI commands accept a --warp-route-id flag to specify which warp route to use. Aliases: -w, --id Accepts:
  • SYMBOL/id - full route ID, where id is the route’s unique identifier (e.g., ETH/ethereum-arbitrum, ETH/viction)
  • SYMBOL - auto-resolves if unique, prompts if multiple (errors in CI)
Resolution logic:
  1. If input contains / → exact match
  2. If SYMBOL only → find all routes with that symbol
    • Single match → use it
    • Multiple matches + interactive → prompt selection
    • Multiple matches + CI → error with list of options
  3. Commands with --origin/--destination (e.g., warp send) use those to filter route resolution (matching routes that contain both chains) and control transfer direction
Examples: 
# Full route ID
hyperlane warp check -w ETH/viction

# Symbol only - auto-selects if unique
hyperlane warp apply --id USDC

# Symbol + chain filter (warp send)
hyperlane warp send -w ETH --origin ethereum --destination arbitrum