☁️
Zus Docs
  • About Züs
  • System
    • Providers and Services
      • Miner
      • Sharder
      • Blobber
      • Validator
      • Authorizer
      • Node Locator (0DNS)
    • Storage
      • Architecture and Data Management
      • Protocol
        • Allocations
        • Reference Objects
        • Challenges
        • Write Markers
          • Chain Hashing
          • Two Commit
        • Blobber Repair Protocol
      • ZS3 Server
        • Backup, Recovery and Replication
        • Encryption and Compression
        • S3FS Setup and Usage
        • Backup & Recovery with Restic on Blimp + ZS3 Server
        • Backup & Recovery with Veeam on Blimp + ZS3 Server
      • File Operations
        • Upload
        • Download
        • File Sharing
        • Partial Error Recovery
        • Streaming
        • Rent a Blobber
    • Smart Contracts
      • Storage S.C.
      • Miner S.C.
      • ZCN S.C.
      • ERC-20 S.C.s
      • Bridge Protocol
    • Blockchain & Consensus
      • Entities
    • User Authentication and Wallet Management System
      • OKTA Integration
      • Key Management System (KMS)
  • APIs
    • 0DNS API
    • JS API
    • Mobile API
  • CLIs
    • Storage CLI
      • Quickstart
      • Configuring the tool
    • Wallet CLI
      • Wallet Configuration
      • Quickstart
      • Configuring the tool
  • SDKs
    • Go SDK
      • GO SDK Microservices
    • JS SDK
  • Tokenomics
    • Staking
    • Reward & Penalty
  • ✨Züs Apps
    • 🗝️Vult
      • Getting Started
        • Web
        • Mobile
      • Vult AI
        • Batch Processing
        • Memory Retention
        • Technical Implementation
        • Architecture Overview
      • Login / Register
      • File Management Pages
      • File Sharing
      • Storage Management Dashboard
      • Storage Maintenance and Troubleshooting
      • Züs Subscription
      • Wallet Management
      • Refer a friend
      • Settings
    • 🏗️Blimp
      • Getting Started
      • Login / Register
      • Configure Storage
        • Create Standard Storage Allocation
        • Create Enterprise Allocation
        • Create S3 Server Allocation
        • Create Cloud Migration Allocation
        • Allocation Maintenance and Troubleshooting
      • File Management Pages
      • File Sharing
      • Manage Allocations
      • Upgrade Storage
      • Blimp Vault
      • Refer a friend
      • Settings
      • Launching ZS3 Server
      • Using CLI to backup files into Blimp + ZS3 Server
    • 🏠Chimney
      • Getting Started
      • Login / Register
      • Create New Deployment
      • Manage Your Deployments
      • Homepage
      • Staking Dashboard
      • Rank Dashboard
      • Monitor Dashboard
      • Stats Dashboard
      • Logs Dashboard
      • Wallet Dashboard
      • Operations on your Deployments
      • Restricted Blobbers
      • Settings
        • Manage Profile
        • Wallet Settings
        • Update Blobber Settings
        • Update Blobber Version
        • Refer a friend
        • Help
    • 🌐Atlus
      • Getting Started
      • Home page
      • Service Providers Page
      • Charts Page
        • Market Charts
        • Network Charts
        • Storage Charts
      • Blockchain Page
      • Server Map Page
      • Storage Explainer Page
      • Details Pages
        • Block Details Page
        • Transaction Details Page
        • Wallet Details Page
        • Miner Details Page
        • Sharder Details Page
        • Blobber Details Page
        • Validator Details Page
        • Authorizer Details Page
        • Allocation Details Page
      • Appendix: Common Components
    • ⚡Bolt
      • Getting Started
        • Web
        • Mobile
      • Login / Register
      • Sign In with external wallet
      • Staking Dashboard
      • Staking/Unstaking a provider
      • Claiming Rewards
      • Send/Receive ZCN tokens
      • Buy ZCN
      • Deposit/Withdraw ZCN tokens
      • Activity Dashboard
      • Refer a friend
      • Settings
  • Releases
    • Hardfork
Powered by GitBook
On this page
  • Prerequisites
  • Step 1 - Get a wallet and a standard Blimp allocation
  • Step 2 -Install the CLIs
  • Step 3 - Extract your wallet information
  • Step 4 - Interact with your Blimp allocation

CLIs

Interact with Blimp using CLI

PreviousMobile APINextStorage CLI

Last updated 16 days ago

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 .

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 to create an allocation on Blimp. For more details on different allocation types, refer to .

Step 1 - Get a wallet and a standard Blimp allocation

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

  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.

Step 2 -Install the CLIs

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

Prerequisites:

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.

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)

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.

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

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
...

- for your wallet interactions (Github: )

zboxcli - for storage allocation interactions (Github: )

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

To learn more about the command check here :

To learn more about the command check here :

To learn more about the command check here :

To learn more about the command check here :

https://github.com/0chain/zwalletcli
https://github.com/0chain/zboxcli
here
https://github.com/0chain/zboxcli?tab=readme-ov-file#upload
https://github.com/0chain/zboxcli?tab=readme-ov-file#download
https://github.com/0chain/zboxcli?tab=readme-ov-file#update
https://github.com/0chain/zboxcli?tab=readme-ov-file#upload
docs
here
this guide
Fig1. Homepage for blimp.software
Fig2: Manage Allocations tab in Blimp web app
Fig3: Root Path in Blimp allocation
Fig4: File Details for uploaded file