Skip to main content

Library commands

The Library commands provide a CLI interface for discovering and installing libraries from the Chromia library registry. These commands allow developers to browse available Rell libraries and integrate them into their projects.

info

The Library Chain is a complete dApp deployed on the Chromia blockchain that hosts the library registry. You can explore it on the Chromia Explorer

library list​

List all available libraries in the registry.

Usage:

chr library list [options]

Options:

  • --limit <number>, -l <number>: Maximum number of libraries to display (default: 10)
  • --offset <number>, -o <number>: Number of libraries to skip (default: 0)
  • --sort-by <order>: Sort order (asc or desc, default: desc)

Example:

chr library list

library view​

View detailed information about a specific library.

Usage:

chr library view <library_id> [options]

Arguments:

  • library_id: ID of the library to view

Example:

chr library view com.chromia.ft4

library versions​

List all versions of a specific library.

Usage:

chr library versions <library_id> [options]

Arguments:

  • library_id: ID of the library to list versions for

Options:

  • --limit <number>, -l <number>: Maximum number of versions to display (default: 10)
  • --offset <number>, -o <number>: Number of versions to skip (default: 0)

Example:

chr library versions com.chromia.ft4

library install​

Install libraries from the registry to your local project.

The library install command reads your chromia.yml file and installs all libraries defined in the libs section. It supports both library-chain libraries (published to Chromia's library registry) and external Git libraries.

Usage:

chr library install <library_id> [options]

Arguments:

  • library_id (optional): Specific library ID to install. If not provided, all configured libraries in chromia.yml will be installed.

Options:

  • --force, -f: Force installation even if RID verification fails (use with caution)
warning

When using the --force flag, the RID verification is skipped. This is not recommended as it can lead to security vulnerabilities.

Configuration​

Libraries are configured in your chromia.yml file using the libs section:

Library-chain libraries​

Published to Chromia's library registry:

libs:
  com.chromia.ft4: # Library from Chromia's library-chain registry
    version: 0.0.1

Configuration options:

  • version: Version of the library to install

External Git libraries​

Hosted in Git repositories:

libs:
  ft4: # External library from Git
    registry: https://bitbucket.org/chromawallet/ft3-lib
    path: rell/src/lib/ft4
    tagOrBranch: v1.0.0r
    rid: x"FA487D75E63B6B58381F8D71E0700E69BEDEAD3A57D1E6C1A9ABB149FAC9E65F"
    insecure: false

Configuration options:

  • registry: Git repository URL
  • path: Path within the repository to the library
  • tagOrBranch: Git tag or branch to use
  • rid: Expected RID for verification
  • insecure: Skip RID verification (not recommended)

Installation examples​

Install all configured libraries:

chr library install

Install a specific library:

chr library install com.chromia.ft4
note

It installs the latest version of the library. It will print message like this:

add this into chromia.yaml file under libs :
com.chromia.ft4
        version: 1.0.0
  • you have to add this into chromia.yaml file under libs

Install a specific version:

chr library install com.chromia.ft4@1.0.0

Install latest version:

chr library install com.chromia.ft4

Force installation:

chr library install com.chromia.ft4 --force
warning

Use the --force flag with caution, as it bypasses RID verification which is an important security measure.

Using installed libraries​

Once installed, you can import and use libraries in your Rell code. Libraries are imported using their simple name:

import ft4;

// Use library functions
val result = ft4.some_function();
note

When importing libraries in Rell code, use the library's simple name (e.g., ft4) rather than the full library ID (e.g., com.chromia.ft4).

Common options​

All library commands inherit common options for connecting to the library-chain:

Connection options:

  • --url <url>: URL to the target node. Only required if library-chain is deployed on a custom network (e.g., https://custom-network). Defaults to Chromia's mainnet if not provided.
  • --brid <hex>: Blockchain RID of the library-chain. Only required if library-chain is deployed on a custom network.

Examples of common usage patterns:

chr library <command> [options]