Overview

Mental model

• rgbldkd is the node daemon (HTTP API + Lightning + optional RGB runtime).
• rgbldk is the CLI client (you run it locally, it calls the daemon over HTTP).

Most CLI commands are stateless requests to the daemon. Your local machine mainly provides:

• a place to store rgbldk contexts (ctx ...)
• a local keystore directory for keystore ... and node unlock/lock defaults (--data-dir)

Pick your target daemon

You can target a daemon in three equivalent ways:

1. --connect per command
2. ctx add + ctx use (recommended)
3. environment defaults (advanced)

The docs use contexts because it keeps commands readable.

Output modes (important)

The CLI supports:

• --output text (human-friendly tables/messages)
• --output json (machine-friendly; use --pretty for readable JSON)
• --output auto (text on TTY, json otherwise)

When scripting, prefer JSON:

rgbldk --output json --pretty node status

Common global flags

These flags apply to most commands:

rgbldk --connect http://127.0.0.1:8501 \
  --output text|json|auto \
  --color auto|always|never \
  --pretty \
  --yes \
  --no-truncate \
  <command...>

Notes:

• Use --yes only when you’re okay with destructive operations (e.g. force-close).
• Use --no-truncate when you need to copy full IDs from tables.
• On failed requests, the CLI now prints structured server fields when available (message, detail, hint, checks) instead of only the top-level error code.

Authentication (if enabled)

If your daemon is configured with an HTTP token, pass it to the CLI:

rgbldk --connect http://<host>:8501 --token "$RGBLDK_HTTP_TOKEN" node status

Or read it from stdin / a file (useful for CI and secret managers):

printf '%s\n' "$RGBLDK_HTTP_TOKEN" | rgbldk --token-stdin node status
rgbldk --token-file /path/to/token.txt node status

Lock/unlock (local control socket vs hosted control HTTP)

Two different mechanisms exist:

• node unlock/lock: talks to a local Unix control socket (typically on the same machine as the daemon)
• node unlock-hosted: talks to a separate authenticated control HTTP server

If you are running rgbldkd locally, node unlock is usually what you want.

Next steps

• Transfers: ./transfers
• Command index: ./commands