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.11+
• curl or wget only for the one-line shell bootstrap command
• Docker & Docker Compose for kaleido setup (local node) and the 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.

kaleido-cli is not on PyPI yet. Once it is published, pip install kaleido-cli or uv tool install kaleido-cli will also work.

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.11+. install.sh uses the first python3, python3.1x or python on your PATH that meets it; set KALEIDO_PYTHON=/path/to/python to choose one explicitly. 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

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 upgrade <name>         # move to the node image this CLI targets (data kept)
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

wallet — BTC wallet

asset — RGB assets

channel — Lightning channels

peer — Peer connections

payment — Lightning payments

market — Kaleidoswap market data

# 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

config — CLI configuration

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