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
Have not set up a Züs account on Blimp or any other Züs app (e.g., Bolt or Vult)
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
Go to Blimp.software and "Sign Up For Free" (Figure 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.
Record and verify your mnemonic.
Warning: If you lose this mnemonic, you will not be able to recover your account or data.
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.
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
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.
Once created, go to your Manage Allocation page. You can find your allocation ID here.

Step 2 -Install the CLIs
In this section, we will be setting up and using two CLIs:
- 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:
Starting with zboxcli installation, clone the
zboxcli
repo and installgit clone https://github.com/0chain/zboxcli.git cd zboxcli make install
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
Run
zbox
command to display the list of supported command. This will verify your installation was successful../zbox
Once successful, move back to the parent directory
cd ..
To install
zwalletcli
, clone the repo and installgit clone https://github.com/0chain/zwalletcli.git cd zwalletcli make install
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.
Recover your wallet:
cd zwalletcli ./zwallet recoverwallet --wallet zus_wallet.json --mnemonic "your twenty four word mnemonic"
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.

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

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
Last updated