@no-witness-labs/hydra-sdk-cli

CLI for managing Hydra head lifecycle, built on @no-witness-labs/hydra-sdk and @effect/cli.

Installation

# From the monorepo root — build and link globally
pnpm --filter @no-witness-labs/hydra-sdk-cli build
cd packages/hydra-sdk-cli && pnpm link --global

# Verify
hydra --help

# Unlink later
pnpm unlink --global @no-witness-labs/hydra-sdk-cli

Configuration

The CLI uses a three-tier fallback for options: CLI flag > environment variable > config file.

Config file location: ~/.config/hydra-sdk/config.yaml

Config commands

hydra config set --key url --value ws://localhost:4001
hydra config set --key blockfrostKey --value preprodXXXXXX
hydra config set --key mnemonic --value "word1 word2 ... word24"
hydra config set --key network --value preprod

hydra config get --key url
hydra config list
hydra config path
hydra config remove --key url

Environment variables

| Variable | Description | |---|---| | HYDRA_NODE_URL | Hydra node WebSocket URL | | HYDRA_MNEMONIC | BIP39 seed phrase | | HYDRA_BLOCKFROST_KEY | Blockfrost project ID |

Usage

Every command that connects to a Hydra node accepts --url and --json flags. When configured via hydra config set or environment variables, --url can be omitted.

hydra status --url ws://localhost:4001
hydra status --json

Commands

Connection

# Test connection
hydra connect --url ws://localhost:4001

# Check head status
hydra status --url ws://localhost:4001

# Watch status continuously (1s interval)
hydra status --watch

Head lifecycle

hydra init                          # Initialize a new head
hydra abort                         # Abort initialization
hydra close                         # Close the head
hydra contest                       # Contest closure with newer snapshot
hydra fanout                        # Fan out from closed head to L1

Commits

# Empty commit
hydra commit

# Commit specific UTxOs (requires wallet credentials)
hydra commit \
  --utxo "txhash1#0,txhash2#1" \
  --mnemonic "word1 word2 ... word24" \
  --blockfrost-key preprodXXXXXX

Incremental commits & decommits

# Recover a failed deposit
hydra recover --tx-id <deposit-tx-id>

# Decommit UTxOs back to L1
hydra decommit --tx-cbor <cbor-hex> --tx-id <tx-id>

UTxO queries

# List L1 wallet UTxOs
hydra l1-utxo --mnemonic "..." --blockfrost-key preprodXXXXXX

# List L2 UTxOs in the head snapshot
hydra l2-utxo --url ws://localhost:4001

TUI

Interactive terminal UI for real-time head monitoring. Press q to quit.

hydra tui --url ws://localhost:4001

Full lifecycle example

export HYDRA_NODE_URL=ws://localhost:4001

hydra connect            # verify connection
hydra init               # initialize head
hydra commit             # commit (empty or with UTxOs)
# ... wait for all participants to commit ...
hydra status --watch     # monitor until Open
hydra close              # close head
hydra status --watch     # monitor contestation period
hydra fanout             # fan out to L1