XChain Node: CLI Manual

The complete reference for the xchain-node command line: every command, its arguments, and its options. This is the same information as xchain-node --help and xchain-node <command> --help, expanded with context.

If you are setting up a node for the first time, start with the Node Operator Quickstart. For keeping a node current, see Upgrading: the short version is xchain-node update all.

Prerequisites

• Node.js >= 22
• Docker installed and running (docker --version and docker ps must both succeed)
• npm for dependency installation

Running xchain-node

xchain-node is a CLI tool, not a long-running service. Install it globally via npm link and invoke commands as needed:

npm link
xchain-node <command> [service] [chain] [network] [options]

Arguments are order-independent: xchain-node start bitcoin mainnet xchain-encoder and xchain-node start xchain-encoder mainnet bitcoin are equivalent.

Commands

Service Management

Logging & Monitoring

Container Operations

Advanced Operations

Global Options

Parameters

When all is used, the command expands to every valid combination. Regtest-only services (xchain-regtest-miner, xchain-e2e-test) are automatically excluded from mainnet and testnet expansions.

Installation Workflow

When xchain-node install master all bitcoin regtest is executed:

1. Pre-flight checks: Docker verification, directory creation, MariaDB connection open, version fetch
2. Docker network creation: creates xchain-node-bitcoin-regtest network
3. Database provisioning: pulls MariaDB image, creates shared database container
4. Module installation (for each service in dependency order):
   • Clone the service repository from GitHub at the specified branch
   • Build a Docker image tagged with the naming convention
   • Create and start a container with generated environment variables
   • Store the container ID in the module state table
5. Database setup: create databases and users for decoder and indexer
6. Hub/Explorer configuration: update hub and explorer with service endpoint information

flowchart TD
    S1["1. Pre-flight checks:<br>Docker verification, directory creation,<br>MariaDB connection open, version fetch"]
    S2["2. Docker network creation"]
    S3["3. Database provisioning:<br>pull MariaDB image, create shared database container"]
    S5["5. Database setup:<br>create databases and users for decoder and indexer"]
    S6["6. Hub/Explorer configuration:<br>update hub and explorer with service endpoint information"]

    subgraph S4["4. Module installation, for each service in dependency order"]
        direction TD
        C1["Clone the service repository from GitHub at the specified branch"]
        C2["Build a Docker image tagged with the naming convention"]
        C3["Create and start a container with generated environment variables"]
        C4["Store the container ID in the module state table"]
        C1 --> C2 --> C3 --> C4
    end

    S1 --> S2 --> S3 --> S4
    S4 --> S5 --> S6

Docker

xchain-node manages Docker directly via execFile calls; it does not use Docker Compose. All Docker commands use array-based arguments (no shell interpolation).

Key Docker operations:

• Network creation: docker network create xchain-node-{coin}-{network}
• Image building: docker build -t {image-name} {module-dir}
• Container creation: docker run -d --hostname {image-name} --network {network} -e KEY=VALUE ... {image-name}
• Container lifecycle: docker start/stop/restart/kill/rm {container-id}
• Command execution: docker exec -i {container-id} {command...}
• Log streaming: docker logs -f --tail 10 {container-id} via spawn

Stopping

Use xchain-node stop to stop containers. Module state entries are preserved, and containers can be restarted later with xchain-node start.

Use xchain-node uninstall to fully remove containers, images, and module state entries.

Multi-Pane Monitoring

The monitor command opens a full-terminal Blessed TUI:

• Displays live log output from up to 6 containers simultaneously
• Each container gets its own scrollable pane
• Press Q, Esc, or Ctrl+C to exit

Bootstrap Operations

Creating a Bootstrap

xchain-node bootstrap create xchain-utxo-tracker bitcoin mainnet

Creates a gzipped tar archive of the service’s data volume plus a SHA-256 hash file.

Restoring a Bootstrap

xchain-node bootstrap restore xchain-utxo-tracker bitcoin mainnet

Verifies the SHA-256 hash before extraction. Aborts cleanly on hash mismatch.

Validator Setup

The validator command has two subcommands for onboarding a node into the XChain federation. Both are offline operations: they write only to the local config directory and never contact Docker or MariaDB. This means they can be run before any stack is installed, and the Docker precheck is intentionally skipped for them.

validator init

xchain-node validator init [options]

Generates an Ed25519 signing key and writes the validator configuration files (validator.json, signing_key.hex, capabilities.json) under the config/validator/ directory. These files are injected as environment variables into the hub container the next time it is installed or started, causing the hub to run in full validator mode (P2P + PBFT + oracle).

Options:

Running validator init more than once without --force is a no-op: it prints the existing pubkey and exits. Use --force only if you need to rotate to a new key.

validator status

xchain-node validator status

Reads the persisted validator configuration and prints the public key, configured peers, and capabilities. If no validator has been initialized it prints a hint to run validator init.

Telemetry

xchain-node collects anonymous usage telemetry by default to help track adoption and surface issues. Only the following are collected: an anonymous install ID, version numbers, which services are running, and basic OS/Docker info. The IP address is never stored: the hub derives at most a coarse region from the connection and discards it.

Opt-out options (highest precedence first)

1. Pass --no-telemetry on any command invocation.
2. Set XCHAIN_NODE_NO_TELEMETRY=1 in the environment before invoking xchain-node.
3. Once opted out via either of the above, the preference is persisted to ~/.xchain-node/telemetry.json so subsequent runs also stay opted out without requiring the flag or env var.

To self-host the collector, override XCHAIN_NODE_TELEMETRY_URL with your collector’s endpoint.

Troubleshooting

Docker not found

Error: docker --version failed

Install Docker and ensure it is running. Verify with docker --version and docker ps.

Port already in use

A container fails to start because the host port is already bound. Check for conflicting containers or processes:

docker ps -a | grep {port}
lsof -i :{port}

Update the port in the config file (config/{coin}-{network}) and reinstall the affected service.

MariaDB connection failure

Error: Couldn't open the xchain_node MariaDB database

The shared MariaDB container is not running or the per-user credentials are stale. Start the database container and retry:

xchain-node start database

If the container is running but the credentials are wrong, remove ~/.xchain-node/credentials.json to trigger a re-provisioning on the next command.

Container not found in module state

Error: container not found

The service was never installed, or its row in the xchain_node.modules table was removed. Use xchain-node sync to reconcile the table against running Docker containers, or re-install the service:

xchain-node sync
xchain-node install master xchain-encoder bitcoin mainnet

Branch not found

Error: Invalid branch name: ...

Branch names are validated against /^[a-zA-Z0-9._\-\/]+$/. Shell metacharacters, spaces, and special characters are rejected. Use a valid branch name.

Git clone failure

If git clone fails (network error, branch not found), xchain-node falls back to the master branch. If master also fails, the installation aborts with an error.

Database container not running

If the MariaDB container is not running when installing a service that needs a database, xchain-node will fail during the database setup step. Start the database first:

xchain-node start database

Hub unreachable after installation

The hub configuration update retries up to 10 times with 3-second delays. If the hub container is slow to start, this is normal. If it persists, check the hub container logs:

xchain-node logs xchain-hub

Copyright © 2025–2026 Dankest, LLC

Based on XChain Platform by Dankest, LLC – https://dankest.llc

Licensed under the GNU Affero General Public License v3.0 (AGPL-3.0-or-later) with a commercial license available for proprietary use.

You may use, modify, and distribute this material under the terms of the License. See LICENSE and NOTICE for full terms. See the licensing overview.