Bridge CLI Reference

Configuration values prefixed YOUR_ are placeholders for your own deployment. For the public testnet use the contract reference; never mix networks or environments.

The bridge-cli is the command-line tool for operating and managing AstralBeam.

Installation

cd cli
npm install
npm run build
npm link  # Makes 'bridge-cli' available globally

Global Options

Option	Description
`-V, --version`	Show version number
`--config`	Show current configuration (use with a command, e.g. `bridge-cli --config status`)
`-h, --help`	Show help for command

Command Categories

Worker Commands

Start, stop, and monitor bridge workers.

Command	Description
`start`	Start relay services
`stop`	Stop relay services
`status`	Check relay service status
`watch`	Full-screen TUI dashboard

Admin Commands

Administrative operations for the bridge.

Command	Description
`admin register-token`	Register an ERC-20 token on MultiSigLocker
`admin update-token-mapping`	Update token mapping for registered token
`admin deploy-wrapped-token`	Deploy wrapped ERC-20 for Casper-native token
`admin lock-tokens`	Lock ERC-20 tokens (EVM → Casper)
`admin burn-tokens`	Burn CEP-18 tokens (Casper → EVM)
`admin lock-native`	Lock CEP-18 native tokens (Casper → EVM wrapped)
`admin burn-wrapped`	Burn wrapped ERC-20 (EVM → Casper native)
`admin inbound-status`	Destination state of an inbound transfer (exposure-control lockers)
`admin complete-queued-release`	Complete a domain's queue head (permissionless)
`admin retry-held`	Retry a held inbound transfer (permissionless)
`admin update-relayer-set`	Update relayers on EVM contract
`admin get-relayer-set`	Query current relayer configuration
`admin casper-*`	Casper contract admin operations

Casper Commands

Query Casper contract state.

Command	Description
`casper EthClient <method>`	Query EthClient contract
`casper TokenFactory <method>`	Query TokenFactory contract
`casper BridgedToken <method>`	Query CEP-18 bridged tokens

Note: Contract names are case-sensitive (EthClient, not eth_client).

EVM Commands

Query EVM contract state.

Command	Description
`evm networks`	List available EVM networks
`evm MultiSigLocker <method>`	Query MultiSigLocker contract

Service Commands

Manage bridge as a systemd service.

Command	Description
`service install`	Install systemd service
`service uninstall`	Remove systemd service
`service start`	Start service
`service stop`	Stop service
`service logs`	View service logs

Quick Examples

Start the Relayer

# Start all workers
bridge-cli start

# Start only EVM→Casper direction
bridge-cli start --direction evm2casper

Check Status

bridge-cli status

Launch TUI Dashboard

bridge-cli watch

Lock Tokens (EVM → Casper)

bridge-cli admin lock-tokens \
  --erc20 0x1c7D4B196Cb0C7B01d743Fbc6116a902379C7238 \
  --route <lock-mint route id> \
  --amount 100000000 \
  --recipient account-hash-abc123... \
  --network sepolia

Query Casper Contract

# List method categories
bridge-cli casper EthClient

# Call specific method
bridge-cli casper EthClient get_threshold
bridge-cli casper TokenFactory is_paused

Query EVM Contract

# List available networks
bridge-cli evm networks

# Query on specific network
bridge-cli evm --network sepolia MultiSigLocker getRelayerSet

Environment Variables

The CLI reads configuration from environment variables:

# Required EVM Chain Config
SEPOLIA_RPC_URL=https://sepolia.infura.io/v3/KEY
SEPOLIA_LOCKER=YOUR_SEPOLIA_LOCKER

# Required Casper Config
CASPER_NODE_URL=https://node.testnet.casper.network

# Optional
LOG_LEVEL=debug
METRICS_ENABLED=true

See Configuration for complete list.

Error Handling

Exit Codes

Code	Meaning
0	Success
1	General error

Common Errors

# Missing private key
Error: ETH_PRIVATE_KEY not configured in .env

# Token not registered
Error: Token is not registered on MultiSigLocker

# Not admin
Error: Caller 0x... is not admin (0x...)

Getting Help

# General help
bridge-cli --help

# Command-specific help
bridge-cli admin --help
bridge-cli casper --help
bridge-cli evm --help

CLI Overview