CLIs

Interact with Blimp using CLI

Blimp is an AI-ready, distributed on-prem storage solution powered by Züs, the world’s fastest blockchain, offering 400 ms optimistic and 2-second full finality. As the first S3-compatible storage platform that is both ACID-compliant and runs on a zero-knowledge network, Blimp is designed for enterprise-scale storage and AI-driven applications.

In this tutorial, you'll learn how to install and set up essential CLI tools like zwalletcli and zboxcli. You'll also discover how to use the CLI to upload, download, and update files in your Blimp allocation. An allocation is a contract specifying how your data will be stored, including details like storage size, read/write prices, and data/parity shards.

For more information on Blimp, check out our docs.

Prerequisites

1. Have not set up a Züs account on Blimp or any other Züs app (e.g., Bolt or Vult)

2. Linux (Ubuntu Preferred) Version: 20.04+ or Mac(Apple Silicon or Intel) Version: Big Sur (v11.0.1+)

Note: If you already have a wallet or allocation with another Züs app, you can follow the instructions here to create an allocation on Blimp. For more details on different allocation types, refer to this guide.

Step 1 - Get a wallet and a standard Blimp allocation

1. Go to Blimp.software and "Sign Up For Free" (Figure 1).

Fig1. Homepage for blimp.software

1. Next complete the sign up process by picking a Google/Apple/Okta SSO or enter a username + email. Then, complete the one-time password (OTP) check.

2. Record and verify your mnemonic.

Warning: If you lose this mnemonic, you will not be able to recover your account or data.

1. Blobbers are independent servers that store your data. During setup, you must choose the blobber 'brand' you want to host your allocation data. Select the option that best fits your needs—in this tutorial, we will choose Züs‑Only.

Option	Description
Züs‑Only	Only Züs‑operated blobbers (max performance & support)
All‑Blobbers	Every available blobber, both company‑owned and independent (decentralization focus)
Unbranded	Only third‑party blobbers
All Brands	A mix of Züs‑operated and third‑party blobbers

1. Once the wallet has been generated, you will be directed to your Blimp web app. If you encounter an error, just click Create an allocation—it will still generate the 2 GB allocation.

2. Once created, go to your Manage Allocation page. You can find your allocation ID here.

Fig2: Manage Allocations tab in Blimp web app

Step 2 -Install the CLIs

In this section, we will be setting up and using two CLIs:

• zwalletcli- for your wallet interactions (Github: https://github.com/0chain/zwalletcli)

• zboxcli - for storage allocation interactions (Github: https://github.com/0chain/zboxcli)

Prerequisites:

• Go: Installation instructions for Mac, Linux and Windows can be found here.

Procedures:

1. Starting with zboxcli installation, clone the zboxcli repo and install

   git clone https://github.com/0chain/zboxcli.git
   cd zboxcli
   make install

2. Add config yaml at ~/.zcn/config.yaml

   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

3. Run zbox command to display the list of supported command. This will verify your installation was successful.

   ./zbox

4. Once successful, move back to the parent directory

   cd ..

5. To install zwalletcli, clone the repo and install

   git clone https://github.com/0chain/zwalletcli.git
   cd zwalletcli
   make install

6. Run zwallet command to display the list of supported command. This will verify your installation was successful.

   ./zwallet

Step 3 - Extract your wallet information

When the CLIs are both properly installed, have your mnemonic available.

With your mnemonic, you will recover your wallet and store the information into a JSON file.

1. Recover your wallet:

   cd zwalletcli
   ./zwallet recoverwallet --wallet zus_wallet.json --mnemonic "your twenty four word mnemonic"

For the wallet flag, you can specify any name for your JSON file. In this case, we have named the JSON file 'zus_wallet'.

1. If successful, it will return "Wallet recovered!!" and the wallet should be saved in your ~/.zcn folder. To verify run the following:

   cat ~/.zcn/zus_wallet.json

The output of the json should look like this:

{"client_id":"xxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
"client_key":"xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
"keys":[{"public_key":"xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
"private_key":"xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"}],
"mnemonics":"xxxx xxxx xxxx xxxxx",
"version":"1.0","date_created":"2023-05-03T12:44:46+05:30","nonce":0,"is_split":false}

Step 4 - Interact with your Blimp allocation

Once everything has been setup, have your blimp allocation ID and the wallet.json ready . As long as you have the allocation ID, these following zbox commands apply to any type of allocation you may have.

To start, make sure you are in the zboxcli directory.

cd ..
cd zboxcli

In this example, these will be the main inputs:

• wallet : zus_wallet.json

• allocation ID: 9e6fad9af55c41f4af0b71b6a4af8e6ec18e24acc3d4d37b22997c297b79a333

Uploading a File

We will be using the upload command. In this example, we will highlight some common flags:

• --localpath : Local path of file to upload

• --remotepath: Path on Blimp allocation you will upload to

• --allocation: Allocation ID

• --wallet: Local path to wallet JSON

If you want to upload to a folder in your Blimp web app, first add a folder in the app. Then, click the ellipsis on the folder icon and select 'Folder Details.' In the modal, locate the 'Path' field, which you can use for the remotepath flag.

This command will upload a single local file into your root path in the Blimp allocation.

./zbox upload --localpath /My/local/path/cat-headphones.png --remotepath / --allocation 9e6fad9af55c41f4af0b71b6a4af8e6ec18e24acc3d4d37b22997c297b79a333 --wallet zus_wallet.json

To check for success, you can read the console output.

Output
...
Status completed callback. Type = image/png. Name = cat-headphones.png
...

You can also check your blimp allocation (Figure 3). After the page refreshes, you should be able to see your newly uploaded file.

Fig3: Root Path in Blimp allocation

To learn more about the command check here : https://github.com/0chain/zboxcli?tab=readme-ov-file#upload

Downloading a File

We will be using the download command. In this example, we will highlight some common flags:

• --localpath : Local path to store your downloaded file

• --remotepath: Path of file on Blimp you would like to download

• --allocation: Allocation ID

• --wallet: Local path to wallet JSON

This will download my file from my Blimp root path and store it in my local Downloads folder.

./zbox download  --remotepath /cat-headphones.png --localpath  /Local/path/to/Downloads --allocation 9e6fad9af55c41f4af0b71b6a4af8e6ec18e24acc3d4d37b22997c297b79a333 --wallet zus_wallet.json

If you do not know your file's remotepath, you can click the file icon's ellipsis . Click "File Details" and check the path (see Figure 4)

Fig4: File Details for uploaded file

To check for success, you can read the console output.

Output
...
Status completed callback. Type = image/png. Name = cat-headphones.png

You can also check your local path to see if the file is present in the specified directory.

To learn more about the command check here :https://github.com/0chain/zboxcli?tab=readme-ov-file#download

Updating a File

We will be using the update command. In this example, we will highlight some common flags:

• --localpath : Local path of the file you would like to update

• --remotepath: Path of file on Blimp you would like to update

• --allocation: Allocation ID

• --wallet: Local path to wallet JSON

This updates the existing .txt file in my Blimp root path with the file of the same name from my local directory.

./zbox update --localpath /My/local/path/example-data.txt --remotepath /example-data.txt --allocation 9e6fad9af55c41f4af0b71b6a4af8e6ec18e24acc3d4d37b22997c297b79a333 --wallet zus_wallet.json

To check for success, you can read the console output.

Output
...
Status completed callback. Type = text/plain. Name = example-data.txt

To learn more about the command check here : https://github.com/0chain/zboxcli?tab=readme-ov-file#update

Uploading Multiple Files

We will be using the upload command. In this example, we will highlight some common flags:

• --multiuploadjson : Local path of multiple upload paths in a JSON

• --remotepath: Path on Blimp allocation you will upload to

• --allocation: Allocation ID

• --wallet: Local path to wallet JSON

Example of the JSON used for multiuploadjson:

[
    {
      "remotePath": "/",
      "filePath": "/My/local/path/cat-headphones.png",
      "thumbnailPath": "",
      "fileName": "cat-headphones.png",
      "encrypt": false
    },
    {
      "remotePath": "/",
      "filePath": "/My/local/path/pikachu wallpaper.webp",
      "thumbnailPath": "",
      "fileName": "pikachu wallpaper.webp",
      "encrypt": false
    },
    {
      "remotePath": "/",
      "filePath": "/My/local/path/deku wallpaper3.png",
      "thumbnailPath": "",
      "fileName": "deku wallpaper3.png",
      "encrypt": false
    }
]

A maximum of 50 files can be uploaded per command execution

This reads the paths in the multi-upload.json file and uploads each file to the root path of the Blimp allocation.

./zbox upload --multiuploadjson /My/local/path/multi-upload.json --remotepath / --allocation 9e6fad9af55c41f4af0b71b6a4af8e6ec18e24acc3d4d37b22997c297b79a333 --wallet zus_wallet.json

To check for success, you can see if the files have been uploaded to your Blimp allocation or check output in the console.

Output
...
Status completed callback. Type = image/png. Name = cat-headphones.png
Status completed callback. Type = image/webp. Name = pikachu wallpaper.webp
Status completed callback. Type = image/png. Name = deku wallpaper3.png
...

To learn more about the command check here : https://github.com/0chain/zboxcli?tab=readme-ov-file#upload