Kaleido CLI

Manage RGB Lightning Nodes and trade on Kaleidoswap — all from your terminal.

Beta Software — Use at Your Own Risk

This CLI is under active development and currently intended for testnet/signet use only. It is not considered safe for mainnet or production environments. The authors assume no responsibility for any loss of funds or damages arising from the use of this software.

Overview

kaleido covers two main areas:

• RGB Lightning Node (RLN) — spin up Docker-based node environments, manage your BTC wallet, RGB assets, Lightning channels, peers, and payments.
• Kaleidoswap API — query market data, create maker swap orders, run maker atomic swaps, and coordinate low-level local swap steps.

---

Requirements

• Python 3.10+
• curl or wget only for the one-line shell bootstrap command
• Docker & Docker Compose only for Docker-based node commands

---

Installation

One command for macOS, Linux, and WSL

With Python only:

python3 -c "import urllib.request; exec(urllib.request.urlopen('https://raw.githubusercontent.com/kaleidoswap/kaleido-cli/master/install.py').read())"

Or with the shell bootstrap:

curl -fsSL https://raw.githubusercontent.com/kaleidoswap/kaleido-cli/master/install.sh | sh

Or with wget:

wget -qO- https://raw.githubusercontent.com/kaleidoswap/kaleido-cli/master/install.sh | sh

The bootstrap script downloads the latest master branch, prefers uv tool install when available, and otherwise installs into an isolated Kaleido virtual environment using Python's standard library. It does not install packages into the system Python environment.

Then run:

kaleido setup

kaleido setup creates and starts one mutinynet node with defaults. You can also run:

kaleido setup signetcustom

Use kaleido setup --mode market --defaults for a market-only setup that works without Docker.

Alternative installers

Install directly from a local checkout for development:

git clone https://github.com/kaleidoswap/kaleido-cli
cd kaleido-cli
./install.sh

Install without the shell bootstrap:

uv tool install git+https://github.com/kaleidoswap/kaleido-cli.git

For Windows or a cross-platform Python-based installer:

python install.py

The Python installer has the same minimal requirement: Python 3.10+. When uv is unavailable, it creates a dedicated app virtual environment and writes a kaleido launcher into your user script directory.

For a local editable install with the existing Makefile helper:

make install

Makefile targets

Command	Description
make install	Install the current checkout via uv tool
make uninstall	Remove the global installation
make reinstall	Uninstall then reinstall

---

Initial Configuration

Configuration is stored in ~/.kaleido/config.json.

For first-time use, prefer:

kaleido setup

If you want to configure manually, use:

kaleido config show                              # view current config
kaleido config set api-url https://api.signet.kaleidoswap.com/
kaleido config set network mutinynet
kaleido config reset                             # reset to defaults

Override per-command with flags or environment variables:

kaleido --node-url http://localhost:3001 wallet balance
kaleido --api-url https://api.signet.kaleidoswap.com/ market pairs

export KALEIDO_NODE_URL=http://localhost:3001
export KALEIDO_API_URL=https://api.signet.kaleidoswap.com/

Valid config keys: api-url, node-url, network, spawn-dir

---

Node Environments

The CLI uses a named environment model. Each environment is an isolated Docker Compose setup with its own compose file and data volumes stored under ~/.kaleido/ by default.

~/.kaleido/
├── config.json
├── mainenv/
│   ├── docker-compose.yml
│   └── volumes/
│       └── dataldk0/
└── testenv/
    ├── docker-compose.yml
    └── volumes/
        ├── dataldk0/
        └── dataldk1/

Creating an environment

kaleido setup                       # create/start one mutinynet node with defaults
kaleido setup signetcustom          # create/start one node on an explicit network
kaleido node create
# or give it a name directly:
kaleido node create testenv

mutinynet, signetcustom, and customsignet are accepted as aliases for the Kaleidoswap custom signet RLN network.

The wizard prompts for:

1. Base directory — where all environments are stored (default: ~/.kaleido, saved to config as spawn-dir)
2. Environment name — becomes a subdirectory under the base dir
3. Node count — number of RGB Lightning Nodes to spin up
4. Network — mutinynet (default), signetcustom/customsignet, signet, regtest, or mainnet
5. Node ports — base daemon API port (3001+) and LDK peer port (9735+)
6. Start now — whether to bring containers up immediately

Managing environments

kaleido node list                   # list all environments with their node URLs
kaleido node up     <name>          # start containers (docker compose up -d)
kaleido node stop   <name>          # stop containers (data preserved)
kaleido node down   <name>          # stop and remove containers
kaleido node ps     <name>          # show container status
kaleido node logs   <name>          # stream all logs
kaleido node logs   <name> --service bitcoind   # filter by service
kaleido node clean  <name>          # delete all data volumes (irreversible)

<name> can be omitted when only one environment exists — it is auto-detected.

Switching between nodes

Use kaleido node use to point the active node-url at any node in any environment:

kaleido node use testenv            # use node 1 of 'testenv' (port 3001)
kaleido node use testenv --node 2   # use node 2 of 'testenv' (port 3002)

kaleido node list marks the currently active node with ●:

Environments in ~/.kaleido:

  testenv  →  ~/.kaleido/testenv
    ● node 1: http://localhost:3001
    ○ node 2: http://localhost:3002

First-time node setup

After creating and starting an environment:

kaleido node use testenv            # set the active node URL
kaleido node init                   # initialise the wallet (once per node)
kaleido node unlock                 # unlock the wallet (after every restart)
kaleido node info                   # confirm the node is reachable

---

Command Reference

All commands accept --json for machine-readable output:

kaleido --json market pairs

node — Node lifecycle

Command	Description
kaleido setup [network]	Create/start one node, mutinynet by default
kaleido node create [name]	Wizard: configure and generate a named environment
kaleido node list	List all environments with node URLs
kaleido node use <name> [--node N]	Set node-url to node N in an environment
kaleido node up <name>	Start containers (docker compose up -d)
kaleido node stop <name>	Stop containers (data preserved)
kaleido node down <name>	Stop and remove containers + networks
kaleido node ps <name>	Show container status
kaleido node logs <name> [--service S]	Stream logs (optionally filtered by service)
kaleido node clean <name>	Delete all data volumes (irreversible)
kaleido node init	Initialise node wallet (once after first start)
kaleido node unlock	Unlock wallet (after every restart)
kaleido node lock	Lock the wallet
kaleido node info	Show node info from /nodeinfo
kaleido node network	Show network info from /networkinfo

wallet — BTC wallet

Command	Description
kaleido wallet address	Get a new on-chain deposit address
kaleido wallet balance	Show BTC balance
kaleido wallet send <amount> <address>	Send on-chain BTC (sats)

asset — RGB assets

Command	Description
kaleido asset list	List all RGB assets held by the node
kaleido asset balance <asset-id>	Show balance for a specific RGB asset
kaleido asset metadata <asset-id>	Show metadata for a specific RGB asset

channel — Lightning channels

Command	Description
kaleido channel list	List all Lightning channels
kaleido channel open <peer>	Open a new channel
kaleido channel close <channel-id>	Close a channel

peer — Peer connections

Command	Description
kaleido peer list	List connected peers
kaleido peer connect <peer>	Connect to a peer
kaleido peer disconnect <pubkey>	Disconnect from a peer

payment — Lightning payments

Command	Description
kaleido payment invoice	Create a BOLT11 invoice (BTC or RGB+LN)
kaleido payment send <invoice>	Pay a BOLT11 invoice
kaleido payment list	List payment history

market — Kaleidoswap market data

Command	Description
kaleido market assets	List all tradeable assets
kaleido market pairs	List all available trading pairs
kaleido market quote <pair>	Get a swap quote for a trading pair

# Send BTC via Lightning, receive USDT via RGB Lightning
kaleido market quote BTC/USDT --from-amount 100000 --from-layer BTC_LN --to-layer RGB_LN

swap — Grouped swap flows

swap is split by scope:

• kaleido swap order ... for maker swap-order flows on the Kaleidoswap server
• kaleido swap atomic ... for atomic swaps against the Kaleidoswap maker server
• kaleido node swap ... for low-level local RLN node swap flows

Command	Description
kaleido market quote <pair>	Get a maker quote for a trading pair
kaleido swap order create <pair>	Create a maker swap order from a live quote
kaleido swap order status <id>	Check the status of a maker swap order
kaleido swap order history	List maker swap-order history
kaleido swap atomic run <pair>	Run atomic init -> whitelist -> execute in one command
kaleido swap atomic init <pair>	Initialize an atomic swap against the maker server
kaleido swap atomic execute	Execute an atomic swap against the maker server
kaleido swap atomic status <hash>	Check atomic swap status against the maker server
kaleido node swap pubkey	Show the local node's taker public key
kaleido node swap init	Initialize a low-level local node swap
kaleido node swap whitelist	Whitelist a swap on the local taker node
kaleido node swap execute	Execute a low-level local node swap
kaleido node swap status <hash>	Check local node swap status by payment hash
kaleido node swap list	List swaps known to the local RLN node

config — CLI configuration

Command	Description
kaleido config show	Display current configuration
kaleido config set <key> <value>	Set a configuration value
kaleido config reset	Reset configuration to defaults
kaleido config path	Print the config file path

---

Quick Start

# 1. Install
curl -fsSL https://raw.githubusercontent.com/kaleidoswap/kaleido-cli/master/install.sh | sh

# 2. Create/start one mutinynet node
kaleido setup

# 3. Initialise and unlock the wallet
kaleido node init
kaleido node unlock

# 4. Confirm the node is healthy
kaleido node info

# 5. Get a funding address
kaleido wallet address

# 6. Browse available trading pairs
kaleido market pairs

# 7. Get a swap quote
kaleido market quote BTC/USDT --from-amount 100000

For a non-interactive local setup with mutinynet defaults:

kaleido setup

Working with multiple nodes

# Create a second environment on different ports
kaleido node create stagingenv

# See all environments and which node is active
kaleido node list

# Switch to node 2 in the staging environment
kaleido node use stagingenv --node 2
kaleido node unlock
kaleido wallet balance