> For the complete documentation index, see [llms.txt](https://docs.zus.network/zus-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.zus.network/zus-docs/clis/zboxcli/installation.md).

# Installation

The **zbox CLI** can be built and installed on Linux, macOS, and other supported platforms.\
This guide covers prerequisites, system requirements, installation steps, and how to run your first `zbox` command.

### Prerequisites

* **Go**\
  Install Go for [Mac, Linux, or Windows](https://golang.org/doc/install). Then, Verify installation:

  ```bash
  go version
  ```
* **Git**\
  Required to clone the repository (not needed on macOS by default).

  ```bash
  sudo apt install git
  ```
* **Build Tools**

  * Linux/macOS: `make`, `gcc`, or `clang`
  * Recommended: `gcc 11` for compatibility (Ubuntu 22 ships with gcc-11 by default; Ubuntu 20 requires upgrade).

  Upgrade gcc on Ubuntu 20:

  ```bash
  sudo add-apt-repository ppa:ubuntu-toolchain-r/test
  sudo apt update
  sudo apt install build-essential
  sudo apt install gcc-11 g++-11
  ```

### System Requirements

Minimum recommended machine specifications for building and running `zbox`:

* **Linux (Ubuntu preferred):** Version 20.04+
* **macOS:** Big Sur+ (Intel or Apple Silicon)
* **CPU:** 4 vCPU
* **Memory:** 4 GB RAM
* **Storage:** 2 GB free space (build + storage allocation)

### Installation

#### 1. Clone the Repository

```bash
git clone https://github.com/0chain/zboxcli.git
cd zboxcli
```

#### 2. Build and Install

```bash
make install
```

This compiles the binary and installs it into your `$GOPATH/bin` or system path.

### Configuration

zbox requires a config file located at:

```
$HOME/.zcn/config.yaml
```

Create it using the following script:

```bash
mkdir -p ~/.zcn
cat > ~/.zcn/config.yaml << EOF
block_worker: https://mainnet.zus.network/dns
signature_scheme: bls0chain
min_submit: 50 # in percentage
min_confirmation: 50 # in percentage
confirmation_chain_length: 3
EOF
```

This sets the **Züs mainnet** as your default network.

### Running zbox

Navigate to the `zboxcli` directory and run:

```bash
./zbox
```

Running without arguments displays the full list of supported commands and global flags.

Example usage output:

```
Usage:
  zbox [command]

Available Commands:
  add                Adds free storage assigner
  alloc-cancel       Cancel an allocation
  alloc-fini         Finalize an expired allocation
  bl-info            Get blobber info
  bl-update          Update blobber settings by its delegate_wallet owner
  collect-reward     Collect accrued rewards for a stake pool.
  completion         Generate the autocompletion script for the specified shell
  copy               Copy an object(file/folder) to another folder on blobbers
  ...
  wp-unlock          Unlock some expired tokens in a write pool.
```

### Alternative Builds

For non-standard platforms (e.g., **ARM64 Linux, Raspberry Pi 3B+**):

1. Download the build script:

   ```bash
   wget https://raw.githubusercontent.com/0chain/zboxcli/master/pibuild.sh
   ```
2. Run the script:

   ```bash
   bash pibuild.sh
   ```

This builds the MCL/BLS libraries with the required `MCL_USE_GMP=0` flag and installs `zbox`.