Nexus CLI Documentation

To prevent rate limiting and ensure reliability, the Nexus CLI fetches version.json using a tiered fallback strategy. If one source fails, it attempts to reach the next in the following order:

1. Primary: https://cli.nexus.xyz/version.json (via Firebase Hosting)
2. Cache: https://us-central1-nexus-cli.cloudfunctions.net/version (via Cloud Function)
3. Fallback: https://raw.githubusercontent.com/nexus-xyz/nexus-cli/refs/heads/main/public/version.json (via GitHub)

To automate the process of building the guest program for the RISC-V target and placing the resulting ELF file into the Nexus CLI assets directory, use the provided shell script. This script copies the ELF file to ../../clients/cli/assets/fib_input_initial (without a file extension).

./build_and_copy.sh

The fib_input_initial program is a guest program used for anonymous proving in the Nexus CLI. It computes the nth Fibonacci number in a generalized sequence with custom initial values. To build the program manually, you must have the riscv32im-unknown-none-elf Rust target installed.

# 1. Add the RISC-V target
rustup target add riscv32im-unknown-none-elf

# 2. Build the program
cargo build --release --target riscv32im-unknown-none-elf

The build_guest.sh script automates the creation and compilation of guest programs. It uses cargo nexus host to generate or rebuild the program, compiles it for the RISC-V target (riscv32i-unknown-none-elf), and copies the resulting ELF file to the assets/[guest_name] directory.

Requirements:

• cargo nexus must be installed and available in your PATH.
• An assets/ directory must exist in the CLI repository root.

Workflow for modifying programs:

1. Edit the source code at programs/[guest_name]/src/guest/src/main.rs.
2. Run the build script: ./scripts/build_guest.sh [guest_name].
3. The updated ELF is automatically moved to assets/[guest_name].

# Build with default name (fib_input_initial)
./scripts/build_guest.sh

# Build with a custom name
./scripts/build_guest.sh my_custom_program

The peak_memory.sh script monitors the peak memory consumption of nexus-compute-cli during operation. It starts nexus-compute-cli start --headless in the background and tracks memory usage every second for a specified duration.

Requirements:

• nexus-compute-cli must be built and available in your PATH or the current directory.
• A valid Nexus configuration (Node ID) must be present for the CLI to operate.

Usage: Run the script with a duration in seconds to capture statistics.

# Monitor for 20 seconds
./scripts/peak_memory.sh 20

# Monitor for 5 minutes
./scripts/peak_memory.sh 300

The Nexus CLI (command name nexus-compute-cli) can be installed via a precompiled binary or a non-interactive script for automation.

Recommended Installation

Run the following command to download the latest binary, accept the Terms of Use, and enter interactive mode:

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

Non-Interactive Installation

For CI/CD or automated environments, use the NONINTERACTIVE environment variable:

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

Note: While nexus-cli remains available as an alias for a transition period, all new setups should use nexus-compute-cli.

You can start contributing proofs to the Nexus network using several methods.

Using an existing Node ID

If you already have a node ID, start the CLI directly:

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

Registering a new user and node

If you do not have credentials, you can register your wallet and create a node ID via the CLI:

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

Headless Mode

To run the CLI without interactive prompts:

nexus-compute-cli start --headless

Managing Credentials

Credentials (wallet and node ID) are saved to ~/.nexus/config.json. To clear them, use:

nexus-compute-cli logout

To build this guest program, you must target the riscv32i-unknown-none-elf architecture. The resulting ELF file will be located at target/riscv32i-unknown-none-elf/release/guest.

# Build for RISC-V target
cargo build --target riscv32i-unknown-none-elf --release

Nexus VM example programs are built against nexus-rt, a minimal RISC-V runtime. You can execute these programs using the nexus-run tool. In this repository, nexus-run is configured as the default runner for cargo.

To run the default 'hello world' program, use the following command:

cargo run -r --bin example

To work with the Firebase Functions in this repository, follow these steps in the functions directory:

Install dependencies:

cd functions
npm install

Run locally:

npm run serve

Build the functions:

npm run build

Deploy to Firebase:

npm run deploy