Nexus CLI

A high-performance command-line interface for contributing proofs to the Nexus network.

Nexus Network

The Nexus network unifies compute from nodes around the world into one verifiable system state. Learn more.

There have been several testnets so far:

Quick Start

Installation

Precompiled Binary (Recommended)

For the simplest and most reliable installation:

curl https://cli.nexus.xyz/ | sh

This downloads the latest binary, prompts for Terms of Use acceptance, and starts interactive mode.

Non-Interactive Installation

For automated installations (e.g., in CI):

curl -sSf https://cli.nexus.xyz/ -o install.sh
chmod +x install.sh
NONINTERACTIVE=1 ./install.sh

Proving

Proving with the CLI is documented here.

To start with an existing node ID, run:

nexus-cli start --node-id <your-node-id>

Alternatively, you can register your wallet address and create a node ID with the CLI, or at app.nexus.xyz.

nexus-cli register-user --wallet-address <your-wallet-address>
nexus-cli register-node --node-id <your-cli-node-id>
nexus-cli start

To run the CLI noninteractively, you can also opt to start it in headless mode.

nexus-cli start --headless

Quick Reference

The register-user and register-node commands will save your credentials to ~/.nexus/config.json. To clear credentials, run:

nexus-cli logout

For troubleshooting or to see available command-line options, run:

nexus-cli --help

Adaptive Task Difficulty

The Nexus CLI features an adaptive difficulty system that automatically adjusts task difficulty based on your node's performance. This ensures optimal resource utilization while preventing system overload.

How It Works

Starts at: small difficulty
Auto-promotes: If tasks complete in < 7 minutes

When to Override Difficulty

Lower Difficulty (e.g. Small or SmallMedium):

Resource-constrained systems
Background processing alongside other apps
Testing/development environments
Battery-powered devices

Higher Difficulty (e.g. Large, ExtraLarge, or ExtraLarge2):

High-performance hardware (8+ cores, 16+ GB RAM)
Dedicated proving machines
Maximum reward optimization

Using Difficulty Override

# Lower difficulty for resource-constrained systems
nexus-cli start --max-difficulty small
nexus-cli start --max-difficulty small_medium

# Higher difficulty for powerful hardware
nexus-cli start --max-difficulty medium
nexus-cli start --max-difficulty large
nexus-cli start --max-difficulty extra_large
nexus-cli start --max-difficulty extra_large_2
nexus-cli start --max-difficulty extra_large_3
nexus-cli start --max-difficulty extra_large_4

# Equivalent to extra_large_4 if no extra_large_5 tasks available
nexus-cli start --max-difficulty extra_large_5

# Case-insensitive (all equivalent)
nexus-cli start --max-difficulty MEDIUM
nexus-cli start --max-difficulty medium
nexus-cli start --max-difficulty Medium

Difficulty Guidelines

Difficulty	Use Case
`small`	Default, starting task
`small_medium`	Building reputation
`medium` and `large`	Standard desktop/laptop
`extra_large` and above	High-performance systems, more points

Tip: Use nexus-cli start --help to see the full auto-promotion details in the CLI help text.

Troubleshooting Difficulty Issues

Tasks taking too long:

Try a lower difficulty.

nexus-cli start --max-difficulty small_medium

Want more challenging tasks:

Request a harder difficulty. It will still take time to build up reputation to get the requested difficulty.

nexus-cli start --max-difficulty extra_large_2

Unsure about system capabilities:

Use the default adaptive system (no --max-difficulty needed)
The system will automatically find the optimal difficulty for your hardware
Only override if you're fine-tuning performance

Docker Installation

For containerized deployments:

Install Docker and Docker Compose
Update the node ID in docker-compose.yaml
Build and run:

docker compose build --no-cache
docker compose up -d
docker compose logs  # Check logs
docker compose down  # Shutdown

Terms of Use

Use of the CLI is subject to the Terms of Use. First-time users running interactively will be prompted to accept these terms.

Node ID

During the CLI's startup, you'll be asked for your node ID. To skip prompts in a non-interactive environment, manually create a ~/.nexus/config.json in the following format:

{
   "node_id": "<YOUR NODE ID>"
}

Get Help

Network FAQ
Discord Community
Technical issues? Open an issue
To submit programs to the network for proving, contact growth@nexus.xyz.

Contributing

Interested in contributing to the Nexus Network CLI? Check out our Contributor Guide for:

Development setup instructions
How to report issues and submit pull requests
Our code of conduct and community guidelines
Tips for working with the codebase

For most users, we recommend using the precompiled binaries as described above. The contributor guide is intended for those who want to modify or improve the CLI itself.

🛠 Developer Guide

The following steps may be required in order to set up a development environment for contributing to the project:

Linux

sudo apt update
sudo apt upgrade
sudo apt install build-essential pkg-config libssl-dev git-all
sudo apt install protobuf-compiler

macOS

# Install using Homebrew
brew install protobuf

# Verify installation
protoc --version

Windows

Install WSL, then see Linux instructions above.

# Install using Chocolatey
choco install protobuf

License

Nexus CLI is distributed under the terms of both the MIT License and the Apache License (Version 2.0).