DocumentationLedger LiveAccountsBeginner's guidesBuild the CLI for development

Building the CLI for development

In this tutorial, you’ll learn how to set up and use the Ledger Live CLI (Command Line Interface) for development. The CLI provides a faster alternative to running the full Ledger Live application when testing your blockchain integration.

What you’ll learn

By the end of this tutorial, you’ll be able to:

  • Set up the development environment for the Ledger Live CLI
  • Build and configure the CLI for your development needs
  • Execute basic CLI commands to interact with devices and accounts
  • Use environment variables to customize CLI behavior
  • Understand the CLI’s capabilities and limitations

What you’ll build

You’ll have a working Ledger Live CLI that can:

  • Connect to and interact with your Ledger device
  • Sync accounts and retrieve balances
  • Generate addresses and send transactions
  • Support experimental currencies during development

Prerequisites

Before starting this tutorial, make sure your setup meets the requirements.

Step 1: Clone and navigate to the repository

If you haven’t already, clone the Ledger Live repository and navigate to it:

git clone https://github.com/LedgerHQ/ledger-live.git
cd ledger-live

Step 2: Install dependencies

Install all project dependencies using pnpm:

pnpm i

This command will:

  • Install all required packages and dependencies
  • Set up the monorepo structure
  • Prepare the CLI for building

Expected result: You should see pnpm downloading and installing packages. This may take several minutes.

Step 3: Build the CLI

Build the CLI for development use:

pnpm build:cli

This command:

  • Compiles the CLI source code
  • Generates the necessary build artifacts
  • Prepares the CLI for execution

Expected result: The build process should complete without errors, and you’ll see build output indicating successful compilation.

Step 4: Verify your CLI installation

Test that your CLI is working correctly by running these verification commands:

4.1 Check the CLI version

pnpm run:cli version

Expected result: This should print the live-common version number, confirming the CLI is properly built and accessible.

4.2 Test device connection (optional)

If you have a Ledger device connected and unlocked:

pnpm run:cli deviceInfo

Expected result: This should display information about your connected device, including model and firmware version.

âś…

Success checkpoint: If both commands work, your CLI is ready for development!

Step 5: Explore basic CLI operations

Now let’s explore the core functionality of the CLI with practical examples:

5.1 Account synchronization

Sync a Bitcoin account using your device:

pnpm run:cli sync -c bitcoin -i 0 -s native_segwit

Or using an extended public key (xpub):

pnpm run:cli sync -c bitcoin --xpub 'xpub...'

What this does: Retrieves account balance, transaction history, and current state.

5.2 Address generation

Generate a Bitcoin address:

pnpm run:cli getAddress -c bitcoin --path "84'/0'/0'/0/0" --derivationMode ''

What this does: Derives a new address using the specified derivation path.

5.3 View available commands

List all available CLI commands:

pnpm run:cli --help

What this does: Shows all available commands and their basic usage.

Step 6: Configure environment variables

The CLI supports extensive customization through environment variables.

6.1 List all available environment variables

pnpm run:cli envs

What this does: Displays all environment variables that can be used to configure the CLI.

6.2 Enable experimental currencies

For development of new blockchain integrations, use:

EXPERIMENTAL_CURRENCIES=mycoin pnpm run:cli sync -c mycoin -i 0

What this does: Allows the CLI to work with currencies that aren’t officially supported yet.

6.3 Use environment variables with Ledger Live Desktop

You can also use environment variables when running Ledger Live Desktop:

EXPERIMENTAL_CURRENCIES=mycoin pnpm dev:lld

Understanding CLI limitations

ℹ️

Important: The CLI has some limitations compared to Ledger Live Desktop:

  • Every sync operation will synchronize the entire account history
  • Some advanced features may not be available
  • UI-specific functionality is not accessible

Next steps

Now that you have a working CLI, you can:

  1. Explore more commands - Check the complete command reference
  2. Test your integration - Use the CLI to test your blockchain integration more efficiently
  3. Set up automated testing - Integrate CLI commands into your development workflow
  4. Configure custom environment variables - Add your own variables in src/env.ts for your specific needs

Troubleshooting

Common issues and solutions

CLI command not found:

  • Ensure you’re in the correct directory (ledger-live root)
  • Verify that pnpm build:cli completed successfully

Device connection issues:

  • Make sure your device is connected and unlocked
  • Check that the relevant app is installed and opened on the device
  • Try reconnecting the device

Build failures:

  • Verify all prerequisites are installed
  • Clear node modules and reinstall: rm -rf node_modules && pnpm i

Demo

  • 00:00 Ledger Live Installation
  • 00:38 CLI Build
  • 01:20 CLI Usage
Ledger
Copyright © Ledger SAS. All rights reserved. Ledger, Ledger Stax, Ledger Nano S, Ledger Vault, Bolos are trademarks owned by Ledger SAS