Skip to main content

​
Frequently Asked Questions

Only for the commands that talk to a node.You can browse pairs and request quotes with nothing installed but the CLI itself:
Docker is needed only for the Docker-backed environments that node manages. If you already run an RGB Lightning Node elsewhere, point the CLI at it with --node-url and skip Docker entirely.
setup is the first-run path, node create is the wizard for additional environments.
  • kaleido setup saves your API and node defaults to ~/.kaleido/config.json and, in local mode, creates and starts one environment with default ports. Bare kaleido setup runs non-interactively, so Docker must already be running.
  • kaleido node create [name] prompts for base directory, name, node count, network, and base ports. Use it when you want a second environment or non-default ports.
See Getting Started and Node Environments.
Because two different unit conventions are in play, depending on the command.So --from-amount 0.001 is right for a quote, while kaleido asset send rgb:abc... 100 rgb:invoice... sends 100 raw units, not 100 display units. Check an asset’s precision with kaleido asset metadata <asset-id> before sending.
They are two different scopes over the same protocol.For a normal trade, kaleido swap atomic run <pair> wraps init, whitelist, and execute in one command. See Market And Swaps.
The accepted set depends on the command:
  • market quote — BTC_LN, RGB_LN, BTC_ONCHAIN
  • swap atomic init and swap atomic run — BTC_L1, BTC_LN, RGB_L1, RGB_LN
Both --from-layer and --to-layer are optional: when omitted, the layers are derived from the requested pair direction. Pass them explicitly when you need a specific route, such as sending over Lightning and receiving over RGB on Lightning:
No. The CLI is a terminal client over two HTTP APIs. The mnemonic is generated inside the RGB Lightning Node when you run kaleido node init, and every signature happens there. Nothing in the CLI can move funds the node has not authorised.Wallet passwords passed with --password land in your shell history — prefer the interactive prompt for anything you care about, and keep backups from kaleido wallet backup somewhere safe.
The node keeps its keys encrypted at rest, so it starts locked. kaleido node init runs once per node; kaleido node unlock runs after every restart.Unlock also tells the node which Bitcoin services to use. Interactively the CLI offers three profiles — signet defaults, regtest defaults, or custom — and asks how the node should follow the chain:
  • --chain-sync block (default) reads blocks from a bitcoind over RPC
  • --chain-sync transaction follows the chain from the indexer only, with no bitcoind at all
With --chain-sync transaction, the --bitcoind-* options are ignored. See Node Environments.
In this order, highest first:
  1. Command-line flags: --node-url, --api-url
  2. Environment variables: KALEIDO_NODE_URL, KALEIDO_API_URL
  3. Stored config in ~/.kaleido/config.json
Inspect the stored layer with kaleido config show and its path with kaleido config path. Note that kaleido node use <name> writes to the stored config, so it has no effect on a command that also passes --node-url.
Yes. Each environment is a separate Docker Compose project with its own compose file, volumes, and ports, and one environment can hold several nodes.
Node 1 gets daemon port 3001 and peer port 9735, node 2 gets 3002 and 9736, and so on. When exactly one environment exists, commands like up, stop, logs, and clean auto-detect it; with several, you must name one.
How much they destroy:clean is irreversible: it takes the environment down and then deletes the data volumes, wallet included. Take a kaleido wallet backup first if the node holds anything you need.
RGB assignments live on specific Bitcoin outputs, so the node needs spare “colored” UTXOs to allocate before it can issue, receive, or send an asset. A funded on-chain balance sitting in one large UTXO is not enough.
Create them ahead of heavy RGB activity rather than one at a time. --up-to changes --num from “create this many” to “top up to this many in total”.
Three flags cover it:
  • --json returns raw JSON instead of tables, for piping into jq
  • --agent disables every interactive prompt, so a missing value fails instead of blocking
  • --yes accepts quotes, payments, and destructive confirmations that would otherwise prompt
In non-interactive mode the CLI refuses rather than guessing, with messages like --yes is required in non-interactive mode to accept the quoted price. See Troubleshooting.
Yes — it wraps the Python SDK (kaleido-sdk), which is why command output maps so closely onto the API models. Practical consequences:
  • Requests use a 30-second timeout and up to 3 retries
  • Errors surface as Error: <message> from the underlying SDK exception, so the SDK error reference explains what a failure means
  • market quote display amounts are converted with the same precision helpers the SDK exposes
If you are building an application rather than running commands, use the KaleidoSDK directly.
They all drive the same two APIs, so a node created with the CLI can be used from the SDK, and the other way round.
The CLI is installed from source — it is not published on PyPI, so pip install kaleido-cli will not find it. Use the bootstrap installer or uv:
Update by re-running the same command; uv installs replace the existing tool. There is no kaleido --version flag, so report your version as the output of uv tool list or the commit you installed from. Full options in Installation.

​
Get Help

Check the Troubleshooting for errors rather than questions, and Additional Resources for upstream documentation and links. For anything else, report a problem through your preferred channel from the options below, including:
  1. How you installed the CLI, and the output of uv tool list (there is no --version flag)
  2. Python version (python --version) and your operating system
  3. The exact command you ran, plus its output with --json added
  4. Whether the node is a local Docker environment or a remote one, and the network
  5. kaleido config show and kaleido node ps output, with passwords removed

Telegram Community

Ask the community.

GitHub Issues

Report a bug on the relevant repository.

Email Support

Direct support for urgent issues.