CLI Reference

The bridge repository provides a Rust CLI named bridge-cli that exposes user, authority, and governance actions.

Global flags

Every command accepts these top-level flags:

Flag	Type	Purpose
--keypair	Path	Path to the payer/signer keypair file
--url	URL	RPC endpoint for the chain the command targets

bridge-cli --keypair ./authority.json --url http://localhost:8899 <command> [flags]

Configuration commands

These commands manage bridge setup and governance. They require authority-level access.

add-chain

Initialize a new bridge to another chain. Creates the Bridge account and its associated trackers.

Flag	Type	Required	Purpose
--chain-id	u16	Yes	Numeric identifier for the other chain
--authorities	PUBKEY...	Yes	Initial authority public keys
--threshold	u64	Yes	Voting threshold (raw U0F64 bits)
--flat-fee	u64	Yes	Flat fee in native sub-tokens
--fee-target	Pubkey	Yes	Account that receives collected fees
--other-chain-name	String	Yes	Human-readable name for the paired chain

edit-auth-proposal

Create or extend an authority proposal. A proposal collects one or more configuration changes that are applied atomically when voted through.

Flag	Type	Required	Purpose
--chain-id	u16	Yes	Target bridge's chain ID
--proposal-keypair	Path	No	Keypair for the proposal account; omit to create a new one
--complete	flag	No	Mark the proposal as ready for voting

Subcommand: add-token-pair

Adds a new bridgeable token pair to the proposal.

Flag	Type	Default	Purpose
--mint	Pubkey	—	This-chain token mint
--other-chain-mint	Pubkey	—	Other-chain token mint
--bridge-mode	String	vault	vault or mint-burn
--import-limit	u64	—	Maximum inbound tokens per period
--import-period	u64	—	Import limit period in seconds
--export-limit	u64	—	Maximum outbound tokens per period
--export-period	u64	—	Export limit period in seconds
--limit-authority	Pubkey	None	Key that can adjust limits without a proposal
--freeze-authority	Pubkey	None	Key that can freeze/unfreeze the pair
--frozen	bool	false	Whether the pair starts frozen

Bridge-specific

Both mints in an AddTokenPair item must be unique within the bridge's existing token pairs. Use ModifyTokenPair (via the program directly, if not yet exposed in CLI) to change operational parameters on an existing pair.

vote-auth-proposal

Cast a weighted vote on an existing proposal.

Flag	Type	Default	Purpose
--chain-id	u16	—	Target bridge's chain ID
--proposal	Pubkey	—	Proposal account address
--vote	String	for	Vote direction: for or against
--mint	Pubkey	None	Optional: scope vote to a specific token pair item

User commands

These commands are available to any user with a funded keypair.

deposit

Create a source-side deposit, escrowing tokens and creating a DepositEntry.

Flag	Type	Required	Purpose
--chain-id	u16	Yes	Target bridge's chain ID
--mint	Pubkey	Yes	Token mint being deposited
--amount	u64	Yes	Amount to deposit (in sub-tokens)
--min-amount	u64	Yes	Minimum acceptable amount at destination
--destination	Pubkey	Yes	Destination address on the other chain
--refund-to	Pubkey	No	Override refund address (defaults to depositor)

Bridge-specific

The min-amount flag sets a floor for the destination-side result. If authorities determine the deliverable amount is below this threshold, the deposit may be rejected and the user will receive a refund at cleanup instead of a transfer. Set this thoughtfully — too high and the deposit risks rejection; too low and fees may consume more than expected.

withdraw

Execute a finalized withdrawal on the destination chain.

Flag	Type	Required	Purpose
--chain-id	u16	Yes	Bridge chain ID
--entry-id	u64	Yes	Withdraw entry index to execute

This instruction is permissionless. It succeeds only if the WithdrawEntry at the given index is Finalized with DepositResult::Confirmed.

cleanup-deposit

Run cleanup on a finalized source-side deposit. Refunds fees and, for rejected deposits, returns escrowed tokens.

Flag	Type	Required	Purpose
--chain-id	u16	Yes	Bridge chain ID
--entry-id	u64	Yes	Deposit entry index to clean up
--mint	Pubkey	Yes	Token mint of the deposit
--refund-to	Pubkey	Yes	Address to receive refunds

This instruction is permissionless. It succeeds only if the DepositEntry is Finalized and cleanup_completed is false.

Authority commands

These commands require the signer to be a registered bridge authority. They are typically executed by the crank loop, but can be run manually for recovery or debugging.

ack-deposit

Acknowledge source-chain deposits and create/update destination-side withdraw entries.

Flag	Type	Required	Purpose
--source-chain-id	u16	Yes	Chain ID of the source (where deposits exist)
--target-chain-id	u16	Yes	Chain ID of the destination (where this command submits)
--source-url	URL	Yes	RPC endpoint for the source chain

The command reads the source DepositTracker, compares it against the destination WithdrawTracker, and submits votes for any unacknowledged entries. The --url global flag should point to the destination chain's RPC.

ack-withdraw

Acknowledge destination-chain withdrawal results back on the source chain.

Flag	Type	Required	Purpose
--source-chain-id	u16	Yes	Chain ID of the source (where this command submits)
--target-chain-id	u16	Yes	Chain ID of the destination (where results exist)
--target-url	URL	Yes	RPC endpoint for the destination chain

The command reads the destination WithdrawTracker, identifies finalized entries, and votes the observed results back onto the source DepositTracker. The --url global flag should point to the source chain's RPC.

Reading the CLI correctly

Bridge-specific

This CLI is not just a "bridge user tool." It exposes three distinct categories of action — user, authority, and governance — each with different trust requirements and operational contexts. Automation should treat them separately: user commands can be triggered by end-user wallets, authority commands should only run from secured operator infrastructure, and governance commands require multi-party coordination.

Related pages

• User Flow
• Authority / Operator Flow
• Server and Crank
• Bridge Config Reference