@riffcc/lens-node

@riffcc/lens-node

@riffcc/lens-node is a command-line interface (CLI) for setting up and running your Lens node. It utilizes Peerbit for peer-to-peer networking and the @riffcc/lens-sdk to interact with the Lens ecosystem.

Table of Contents

• @riffcc/lens-node
  • Table of Contents
  • Prerequisites
  • Installation
  • Getting Started
  • Usage
    • Global Options
    • Commands
      • setup
      • import
      • export
      • run
  • Configuration
  • Development

Prerequisites

• A recent version of Node.js (v18.x or later recommended).
• pnpm is recommended for development (as per package.json), but npm or yarn can be used for global installation.

Installation

To install the lens-node CLI globally, run:

pnpm add -g @riffcc/lens-node

Or, using npm:

npm install -g @riffcc/lens-node

Or, using yarn:

yarn global add @riffcc/lens-node

After installation, the lens-node command will be available in your terminal.

Getting Started

• Setup your Lens Node: The first step is to initialize your node. This will create a data directory, generate necessary cryptographic identities, and create a configuration file.

  lens-node setup
  

  This command will:

  • Create a directory at ~/.lens-node (or a custom path if specified with --dir).
  • If the directory already exists, it will prompt you to confirm reconfiguration.
  • Initialize a Peerbit client and a Lens Site.
  • Save the configuration, including the Lens Site address, to config.json within the data directory.
  • Print important details like your Peer ID, Public Key, and Site Address.

• Import an existing site: Alternatively, you can import an existing site ID to become a lens for that site:

  lens-node import
  

  This command will:

  • Create a directory at ~/.lens-node (or a custom path if specified with --dir).
  • If the directory already exists, it will prompt you to confirm reconfiguration.
  • Prompt you to enter the site address to import.
  • Initialize a Peerbit client.
  • Save the configuration with the imported site address to config.json.
  • Print important details like your Peer ID, Public Key, and the imported Site Address.

• Run your Lens Node: Once setup or import is complete, you can start your node:

  lens-node run
  

  This will start the node daemon, connect to the Peerbit network, and open your Lens Site. An interactive menu will be available for further actions.

Usage

The basic syntax for the CLI is:

lens-node <command> [options]

You can get help at any time:

lens-node --help
lens-node <command> --help

Global Options

These options are available for most commands:

• --dir <path>, -d <path>: Specifies the directory for storing node data.
  • Default: ~/.lens-node (e.g., /home/user/.lens-node on Linux or /Users/user/.lens-node on macOS).
• --help, -h: Show help.
• --version, -v: Show version number.

Commands

setup

Initializes and configures a new Lens node.

lens-node setup [options]

Description: Sets up the Lens node by creating a data directory, generating a Peerbit identity, creating a new Lens Site, and saving its address to a configuration file.

Options:

• --dir <path>, -d <path>
  • Directory to store node data.
  • Default: ~/.lens-node

Example:

# Setup with default directory
lens-node setup

# Setup with a custom directory
lens-node setup --dir /path/to/my/lens-node-data

import

Imports an existing site ID to become a lens for that site.

lens-node import [options]

Description: Imports an existing site ID by creating a data directory, generating a Peerbit identity, and saving the imported site address to a configuration file.

Options:

• --dir <path>, -d <path>
  • Directory to store node data.
  • Default: ~/.lens-node

Example:

# Import with default directory
lens-node import

# Import with a custom directory
lens-node import --dir /path/to/my/lens-node-data

export

Exports the current node configuration to a specified format (JSON or Vite .env).

lens-node export [options]

Description: Reads the config.json from the node data directory and outputs it. This is useful for backing up your configuration or integrating with other tools.

Options:

• --dir <path>, -d <path>
  • Specifies the directory where node data (including config.json) is stored.
  • Default: ~/.lens-node
• --format <json|vite>, -f <json|vite> (Required)
  • The format for the exported configuration.
    • json: Outputs the full config.json content.
    • vite: Outputs a .env style file with VITE_ADDRESS=<site_address>.
• --output <filepath>, -o <filepath>
  • Optional. The file path to save the exported configuration.
  • If not provided, the configuration will be printed to standard output (your terminal).
  • If a directory path is provided, a default filename (e.g., config_export.json or config_export.env) will be used within that directory.

Examples:

# Export configuration as JSON to the terminal
lens-node export --format json

# Export configuration as a Vite .env file and save it to .env in the current directory
lens-node export --format vite --output .env

# Export configuration as JSON from a custom data directory and save to a backup file
lens-node export --format json --dir /path/to/my-data --output /backups/lens_config_backup.json

run

Starts the Lens node daemon.

lens-node run [options]

Description: Starts the Lens node, connects to the Peerbit network, and opens the configured Lens Site. It provides an interactive menu for actions like authorizing accounts.

Options:

• --dir <path>, -d <path>
  • Directory where node data (including config.json) is stored.
  • Default: ~/.lens-node
• --relay
  • Type: boolean
  • Default: false
  • Enable relay mode for the node.
• --domain <domain1>
  • Type: string
  • Domain to announce for libp2p configuration (e.g., for external reachability).
  • Example: --domain my-node.example.com
• --listenPort <port>
  • Type: number
  • Default: 8001
  • Port to listen on for libp2p configuration.
• --onlyReplicate
  • Type: boolean
  • Default: false
  • Run the node in replicator mode. This uses replication settings to run this node as dedicated replicator and disables the interactive menu.

Example:

# Run the node using default configuration
lens-node run

# Run the node in relay mode
lens-node run --relay

# Run the node and announce specific domains
lens-node run --domains /dns4/node1.example.com/tcp/4002/p2p/QmRelayPeerId /ip4/123.45.67.89/tcp/9000

Interactive Menu Actions:

• Authorise an account: Prompts for a string public key and account type (Member or Admin) to authorize on the Lens Site.
• Shutdown Node: Gracefully shuts down the node.

The node can also be stopped by pressing Ctrl+C.

Configuration

The lens-node stores its configuration in a config.json file located within the node's data directory (default: ~/.lens-node/config.json).

The primary piece of configuration stored is the Lens Site address:

{
  "address": "zd...siteAddress..."
}

This file is automatically generated by the lens-node setup or lens-node import command and read by the lens-node run command. The configuration is validated against a schema on load.

Development

If you want to contribute to or modify lens-node:

Clone the repository:

git clone https://github.com/riffcc/lens-node.git

cd lens-node

Install dependencies (using pnpm): The project is set up to use pnpm.

pnpm install

Build the project: This compiles the TypeScript code to JavaScript in the dist directory.

pnpm run build