Metadata-Version: 2.5
Name: kaleido-cli
Version: 0.1.2
Summary: CLI for managing RGB Lightning Nodes and interacting with Kaleidoswap
Project-URL: Homepage, https://kaleidoswap.com
Project-URL: Repository, https://github.com/kaleidoswap/kaleido-cli
Author-email: Kaleidoswap <dev@kaleidoswap.com>
License-Expression: MIT
License-File: LICENSE
Keywords: bitcoin,cli,kaleidoswap,lightning,rgb
Requires-Python: >=3.11
Requires-Dist: kaleido-sdk<0.2,>=0.1.23
Requires-Dist: pyyaml>=6.0.0
Requires-Dist: rich>=13.0.0
Requires-Dist: shellingham>=1.5
Requires-Dist: typer>=0.12.0
Provides-Extra: dev
Requires-Dist: pytest-asyncio>=0.23.0; extra == 'dev'
Requires-Dist: pytest-mock>=3.15.1; extra == 'dev'
Requires-Dist: pytest>=8.0.0; extra == 'dev'
Description-Content-Type: text/markdown

# Kaleido CLI

[![CI](https://github.com/kaleidoswap/kaleido-cli/actions/workflows/ci.yml/badge.svg)](https://github.com/kaleidoswap/kaleido-cli/actions/workflows/ci.yml)
[![Python 3.11+](https://img.shields.io/badge/python-3.11%2B-blue)](https://www.python.org/)
[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](./LICENSE)

Manage RGB Lightning Nodes and trade on [Kaleidoswap](https://kaleidoswap.com) — 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:

```bash
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:

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

Or with `wget`:

```bash
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:

```bash
kaleido setup
```

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

```bash
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:

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

Install without the shell bootstrap:

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

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

```bash
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:

```bash
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:

```bash
kaleido setup
```

If you want to configure manually, use:

```bash
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:

```bash
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

```bash
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

```bash
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:

```bash
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:

```bash
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:

```bash
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 upgrade <name>`             | Move to the node image this CLI targets             |
| `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 |
| `kaleido asset transfers [asset-id]` | List transfers (`--no-asset`, `--txid`) |

### `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, `--description`) |
| `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   |

```bash
# 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

```bash
# 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:

```bash
kaleido setup
```

### Working with multiple nodes

```bash
# 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
```
