Comment on page
Uploading and Managing Files
./zbox upload
command is used to upload a file on dStorage. Parameters for uploading a file to dStorage can be viewed by using the ./zbox upload --help command.
Here are the Parameters :
Parameter | Required | Description | Default | Valid values |
---|---|---|---|---|
allocation | yes | allocation id, sender must be allocation owner | | string |
commit | no | save metadata to blockchain | false | boolean |
encrypt | no | encrypt file before upload | false | boolean |
localpath | yes | local path of the file to upload | | file path |
remotepath | yes | remote path to upload file to, use to access file later | | string |
thumbnailpath | no | local path of thumbnail | | file path |
Example :
Let's upload an info.txt file to allocation, the local path for the file is mapped to a
local
variable and the remote directory is mapped to a remote
variable which is myfiles/info.txt.
Sample Command:
./zbox upload --localpath $local --remotepath $remote --allocation $ALLOC
Response:

Verify whether the uploaded file is available on dStorage using list command required parameters are allocation ID and remote path
./zbox list --remotepath $remote --allocation $ALLOC
Response:
TYPE | NAME | PATH | SIZE | NUM BLOCKS |LOOKUP HASH |
IS ENCRYPTED | DOWNLOADS PAYER
+------+----------+-------------------+------+------------+-----------------------------------------------
f | info.txt | /myfiles/info.txt | 24 | 4 | f15383a1130bd2fae1e52a7a15c4322
69eeb7def555f1f8b9b9a28bd9611362c | NO | owner
The response yields a lookuphash which works as a unique identifier for the uploaded file. Since you uploaded the file, the download payer section will show it as
owner
.Copy and mark your lookup hash to a variable as it will be used for performing other file operations
export LOOKUPHASH=f15383a1130bd2fae1e52a7a15c432269eeb7def555f1f8b9b9a28bd9611362c
Parameters for encrypting and uploading a file to dStorage are almost the same as uploading a file on dStorage and only requires an additional
--encrypt
flag with the command.For instance if we want to encrypt and upload a sample
info.txt
file the command would be:Command:
./zbox upload --encrypt --localpath $local --remotepath $remote --allocation $ALLOC
Response:
24 / 24 [================================================================] 100.00% 0s
Status completed callback. Type = application/octet-stream. Name = info.txt
To verify whether the file is encrypted and uploaded to dstorage use the list command :
./zbox list --allocation $ALLOC --remotepath $remote
Response:
TYPE | NAME | PATH | SIZE | NUM BLOCKS |LOOKUP HASH
| IS ENCRYPTED | DOWNLOADS PAYER
+------+----------+-------------------+------+------------+-----------------------------------------------
f | info.txt | /myfiles/info.txt | 24 | 4 | f15383a1130bd2fae1e52a7a15c432269
eeb7def555f1f8b9b9a28bd9611362c | YES | owner
Scroll right in the response and check the
IS ENCRYPTED
section, it will say YES
if the file is encrypted.Use
./zbox update
command to update the content of an existing file in the remote path. Like upload command. Only the owner of the allocation or a collaborator can update a file. To add collaborators to an allocation, check File Collaboration.Parameters for updating the contents of the file on dStorage can be seen by typing
./zbox update --help
Here are the parameters:
Parameter | Required | Description | Default | Valid values |
---|---|---|---|---|
allocation | yes | allocation id | | string |
encrypt | no | encrypt file before upload | false | boolean |
localpath | yes | local file to upload | | file path |
remotepath | yes | remote file to upload | | string |
thumbnailpath | no | local fumbnail file to upload | | file path |
commit | no | save meta data to blockchain | false | boolean |
Sample Command:
./zbox update --localpath $local --remotepath $remote --allocation $ALLOC
Verify the contents of updated file on dStorage using the list command.
./zbox list --remotepath $remote --allocation $ALLOC
Sample Response:
TYPE | NAME | PATH | SIZE | NUM BLOCKS | LOOKUP HASH
| IS ENCRYPTED | DOWNLOADS PAYER
f | info.txt | /myfiles/info.txt | 76 | 4 | f15383a1130bd2fae1e52a7a15c432
269eeb7def555f1f8b9b9a28bd9611362c | NO | owner
./zbox createdir
command is used to create directory on allocation for storing files.Parameter | Description | Valid Values |
---|---|---|
--allocation | Provide Allocation ID | string |
--dirname | Provide Directory Name and absolute path . | string |
--h,--help | help for createdir | int |
Sample Command:
./zbox createdir --allocation $ALLOCATION_ID --dirname /photos
Sample Response:
/photos directory created
Zbox supports sharing of files using auth tokens. Sharing can be encrypted or not encrypted for this section we will describe the non-encrypted share functionality. For encrypted shared functionality have a look at Private Sharing .
./zbox share
command is used to generate an authtoken that provides authorization to the holder to the specified file on the remotepath. Parameters for sharing the file can be viewed using the ./zbox share --help
The parameters are:
Parameter | Required | Description | Valid values |
---|---|---|---|
allocation | yes | allocation id | string |
clientid | no | id of user to share file with, leave blank for public share | string |
encryptionpublickey | no | public key of the client to share file with, required if clientId | string |
expiration-seconds | no | seconds before auth ticket expires | int |
remotepath | yes | remote path of file to share | string |
revoke | no | revoke share for remote path | flag |
Command:
./zbox share --remotepath $remote --allocation $ALLOC
The response will yield an Auth token which can be shared publicly to users for downloading the file.
Sample Response:

Note: Use an export command and mark your Auth token to a variable to use with more commands
export AUTH= eyJjbGllbnRfaWQiOiIiLCJvd25lcl9pZCI6IjE3NTNkMjlkODE5ODkyNmZhYzJlZDQzYWNj
MzcwNDhhNzFmZmYzNDg2YTQ4N2ZjNmVlZDU0ZWFkNDY5YWQxNTkiLCJhbGxvY2F0aW9uX2lkIjoiNTJmYjl
iNTkyNmMwNmU0M2E5MjkwZTlkN2FkMzIxN2E0YWVlNTFjOTQ2ODRiYWYwZmMxNzRhYTQxYWJlNjA1OSIsIm
ZpbGVfcGF0aF9oYXNoIjoiZjE1MzgzYTExMzBiZDJmYWUxZTUyYTdhMTVjNDMyMjY5ZWViN2RlZjU1NWYxZ
jhiOWI5YTI4YmQ5NjExMzYyYyIsImZpbGVfbmFtZSI6ImluZm8udHh0IiwicmVmZXJlbmNlX3R5cGUiOiJmIi
wiZXhwaXJhdGlvbiI6MTYyNjIwNDM5NSwidGltZXN0YW1wIjoxNjE4NDI4Mzk1LCJyZV9lbmNyeXB0aW9uX2tle
SI6IiIsInNpZ25hdHVyZSI6ImM1ZDViYzY3M2Q1NTNmZmM3M2FhNTg2MDkwNDgwODVlMjZhN2UyZmUzNTQ2MjA5O
TlhNTk3NDdhNDFlNmNiMWQifQ==
The
./zbox download
can be used to download the file in two ways from dStorage. Using the Allocation ID or Authticket.Parameters for downloading the contents of file from dStorage can be viewed using the
./zbox download --help
Here are the parameters:
Parameter | Required | Description | Default | Valid values |
---|---|---|---|---|
allocation | yes | allocation id | | string |
authticket | no | auth ticked if not owner of the allocation, use share to get auth ticket | | string |
blockspermarker | no | download multiple blocks per marker | 10 | int |
commit | no | save metadata to blockchain | false | boolean |
endblock | no | download until specified block number | | int |
localpath | yes | local path to which to download the file to | | file path |
remotepath | yes | remote path to which the file was uploaded | | string |
rx_pay | no | authticket must be valid, true = sender pays, false = allocation owner pays | false | boolean |
startblock | no | start download from specified block | | int |
thumbail | no | only download the thumbnail | false | boolean |
Command:
./zbox download --localpath $local --remotepath $remote --allocation $ALLOC
Sample Response:

If you are not able to download files and getting Error in file operation: File content didn't match with uploaded file response check Error 2 in Tips and Troubleshooting Section.
The necessary flags for downloading the file using the Authticket is auth ticket and local path. Get the AuthToken for the file on dstorage from another user and mark it to a variable. We will use auth token created and marked to
AUTH
variable for the file we shared in sharing a file on dStorage section .Command:
./zbox download --authticket $AUTH --localpath $local
Response:
28 / 28 [==========================================================] 100.00% 0s
Status completed callback. Type = application/octet-stream. Name = info.txt
As you can see Zbox has identified the file(info.txt) based on the auth token and didn't require any remote path and allocation id.
Deleting the file on dStorage can be done using the
./zbox delete
command. Parameters for deleting the contents of the file on dStorage can be seen by typing ./zbox delete --help
Here are the parameters:
Parameter | Required | Description | Default | Valid values |
---|---|---|---|---|
allocation | yes | allocation id | | string |
remotepath | yes | remote path of file to delete | | string |
commit | no | save meta data to blockchain | false | boolean |
Command:
./zbox delete --remotepath $remote --allocation $ALLOC
Sample Response:

Verify whether the updated txt file is available on dstorage using the list command
./zbox list --remotepath $remote --allocation $ALLOC
Response:
TYPE | NAME | PATH | SIZE | NUM BLOCKS | LOOKUP HASH | IS ENCRYPTED | DOWNLOADS PAYER
+------+------+------+------+------------+-------------+--------------+-----------------+
As you can see the file is not showing in remote directory which means the file has been successfully deleted.
Use
./zbox copy
command to copy file to another folder path in dStorage. Only the owner of the allocation can copy an object.By using
./zbox copy --help
.You can have a look at the parameters:Parameter | Required | Description | default | Valid values |
---|---|---|---|---|
allocation | yes | allocation id | | string |
commit | no | save metadata to blockchain | false | boolean |
remotepath | yes | remote path of object to copy | | string |
destpath | yes | destination, an existing directory to copy object | | string |
Required Flags for copying the file to another folder are Allocation ID, the remote path to the existing file on dstorage, and the new destination path/folder path to copy a file to.
Steps :
- 1.Verify whether the sync.txt file is available in the remote path using list command.
./zbox list --remotepath / --allocation $ALLOC
Response:
TYPE | NAME | PATH | SIZE | NUM BLOCKS | LOOKUP HASH | IS ENCRYPTED | DOWNLOADS PAYER
+------+----------+-----------+------+------------+------------------------------------------------------------------+--------------+-----------------+
d | myfiles | /myfiles | | 4 | 0343cabc0c987686344be0b30055df76994888ce9159f97a9c76de035225fc9a | | owner
f | sync.txt | /sync.txt | 68 | 4 | 1fe7228abacc12a28277ff2fb5f97c7b7288942b8bbd7c5a96f80a1a65a0367e | NO | owner
2. Use the
./zbox copy
command to copy files../zbox copy --remotepath /sync.txt --destpath /myfiles --allocation $ALLOC
Successful Response:
/sync.txt copied
3. Verify whether the file has copied using:
./zbox list --remotepath /myfiles --allocation $ALLOC
Response:
TYPE | NAME | PATH | SIZE | NUM BLOCKS | LOOKUP HASH | IS ENCRYPTED | DOWNLOADS PAYER
+------+----------+-------------------+------+------------+------------------------------------------------------------------+--------------+-----------------+
f | info.txt | /myfiles/info.txt | 76 | 4 | f15383a1130bd2fae1e52a7a15c432269eeb7def555f1f8b9b9a28bd9611362c | NO | owner
f | sync.txt | /myfiles/sync.txt | 68 | 4 | 4a5669bef007b8f3b8a93e34fb9c43ab1f868701379777c2580b8196029e9923 | NO | owner
The
./zbox move
command can be used to move files between folder paths in dStorage. The parameters required for the move command can be viewed using ./zbox move --help
Parameter | Required | Description | default | Valid values |
---|---|---|---|---|
allocation | yes | allocation id | | string |
commit | no | save metadata to blockchain | false | boolean |
remotepath | yes | remote path of object to copy | | string |
destpath | yes | destination, an existing directory to copy object | | string |
The required parameters are Allocation ID , dest path and remote path of the moving file .
Steps:
- 1.Verify whether the directories are available in the remote path using the list command.
./zbox list --remotepath / --allocation $ALLOC
Response:
TYPE | NAME | PATH | SIZE | NUM BLOCKS | LOOKUP HASH | IS ENCRYPTED | DOWNLOADS PAYER
+------+----------+-----------+------+------------+------------------------------------------------------------------+--------------+-----------------+
d | myfiles | /myfiles | | 8 | 0343cabc0c987686344be0b30055df76994888ce9159f97a9c76de035225fc9a | | owner
f | sync.txt | /sync.txt | 68 | 4 | 1fe7228abacc12a28277ff2fb5f97c7b7288942b8bbd7c5a96f80a1a65a0367e | NO | owner
d | myfiles1 | /myfiles1 | | 4 | d541b2190c7527967ae10a8f991f34ebf9d474c10ba02832d224093110f1fcfc | | owner
As you can see there are two directory paths available
/myfiles
and myfiles1
.We will move the info.txt file available remotepath /myfiles
to the destpath
/myfiles1
.2. Use the
./zbox move
command./zbox move --remotepath /myfiles/info.txt --destpath /myfiles1 --allocation $ALLOC
Successful Response:
/myfiles/info.txt moved
3. Verify whether the file has moved by listing the directory path using:
./zbox list --remotepath /myfiles1 --allocation $ALLOC
Response:
TYPE | NAME | PATH | SIZE | NUM BLOCKS | LOOKUP HASH | IS ENCRYPTED | DOWNLOADS PAYER
+------+-----------+---------------------+------+------------+------------------------------------------------------------------+--------------+-----------------+
f | info1.txt | /myfiles1/info1.txt | 112 | 4 | 675fab6ebfd03539848e224c2f758af33f5c8f34fb1471c9ede1fa387e389d52 | NO | owner
f | info.txt | /myfiles1/info.txt | 76 | 4 | c369ce1609ca141142ab3146b7c436d945bfa4f1dd6dda1f19820dbd71c3dfe1 | NO | owner
./zbox rename
command can be used to rename files already existing in dStorage.Only the allocation's owner can rename a file. Parameters for the command can be viewed using ./zbox rename --help
Parameter | Required | Description | default | Valid values |
---|---|---|---|---|
allocation | yes | allocation id | | string |
commit | no | save metadata to blockchain | false | boolean |
destname | yes | new neame of the object | | string |
remotepath | yes | remote path of object, do not use with authticket | | string |
Command:
./zbox rename --remotepath /sync.txt --destname $DEST_PATH --allocation $ALLOC
Response:
/sync.txt renamed
Verify by listing the remote path using
./zbox list --remotepath / --allocation $ALLOC
Response:
TYPE | NAME | PATH | SIZE | NUM BLOCKS | LOOKUP HASH | IS ENCRYPTED | DOWNLOADS PAYER
+------+-------------------+-------------------+------+------------+------------------------------------------------------------------+--------------+-----------------+
d | myfiles | /myfiles | | 4 | 0343cabc0c987686344be0b30055df76994888ce9159f97a9c76de035225fc9a | | owner
d | myfiles1 | /myfiles1 | | 8 | d541b2190c7527967ae10a8f991f34ebf9d474c10ba02832d224093110f1fcfc | | owner
f | /myfiles/info.txt | /myfiles/info.txt | 68 | 4 | f15383a1130bd2fae1e52a7a15c432269eeb7def555f1f8b9b9a28bd9611362c | NO | owner
./zbox list
command is used to list all the files from a specified directory on dStorage. Use ./zbox list --help
to know the possible parameters.Parameter | Required | Description | Valid Values |
---|---|---|---|
allocation | yes | allocation id | string |
lookuphash | | adjust storage expiration time | string |
remotepath | yes | Remote Path of directory on dStorage | string |
Command :
./zbox list --remotepath $remote --allocation $ALLOC
Sample Response :

./zbox stats
command can be used to get upload, download and challenge information for a file. Parameters for the command can be viewed using ./zbox stats --help
Parameter | Required | Description | default | Valid values |
---|---|---|---|---|
allocation | yes | allocation id | | string |
json | no | print result in json format | false | boolean |
remotepath | yes | file of which to get stats | | string |
Steps:
- 1.Verify whether the file exists at the remote path using
./zbox list --remotepath $remote --allocation $ALLOC
Response:
TYPE | NAME | PATH | SIZE | NUM BLOCKS | LOOKUP HASH | IS ENCRYPTED | DOWNLOADS PAYER
+------+-----------+---------------------+------+------------+------------------------------------------------------------------+--------------+-----------------+
f | info1.txt | /myfiles1/info1.txt | 112 | 4 | 675fab6ebfd03539848e224c2f758af33f5c8f34fb1471c9ede1fa387e389d52 | NO | owner
f | info.txt | /myfiles1/info.txt | 76 | 4 | c369ce1609ca141142ab3146b7c436d945bfa4f1dd6dda1f19820dbd71c3dfe1 | NO | owner
2. Run the stats command using
./zbox stats --remotepath $remote --allocation $ALLOC
Sample Response:

./zbox meta
command is used to get meta data for the given file in dStorage . Use ./zbox meta --help
to know more about possible flags.Parameter | Required | Description | default | Valid values |
---|---|---|---|---|
allocation | yes | allocation id | | string |
authticket | no | auth ticked if not owner of the allocation | | string |
json | no | print result in json format | false | boolean |
lookuphash | no | hash of object, use with auth ticket | | string |
remotepath | no | remote path of object, do not use with authticket | | string |
Command:
./zbox meta --remotepath $remote --allocation $ALLOC
Sample Response:

./zbox get-download-cost
determines the cost for downloading the remote file from dStorage. The client must either be the owner, a collaborator or be using an auth ticket.Parameter | Required | Description | default | Valid values |
---|---|---|---|---|
allocation | yes | allocation id | | string |
authticket | no | auth ticket to use if not the owner | | string |
lookuphash | no | hash of remote file, use with auth ticket | | string |
remotepath | yes | file of which to get stats, use if owner | | string |
Command:
./zbox get-download-cost --allocation $ALLOC --remotepath $remote
Sample Response:

./zbox get-upload-cost
determines the cost for uploading a local file on dStorage. --duration
Ignored if --end
true, in which case the cost of upload calculated until the allocation expires.Parameter | Required | Description | default | Valid values |
---|---|---|---|---|
allocation | yes | allocation id | | string |
duration | no | duration for which to upload file | | duration |
end | no | upload file until allocation expires | false | boolean |
localpath | yes | local of path to calculate upload | | file path |
Command:
./zbox get-upload-cost --allocation $ALLOC --localpath $local
Response:

./zbox get-diff
command returns the differences between the local files specified by localpath
and the files stored on the root remotepath of the allocation.localcache
flag can also be specified to use the local cache of remote snapshot created during Sync for file comparison.Parameter | Required | Description | default | Valid values |
---|---|---|---|---|
allocation | yes | allocation id | | string |
excludepath | no | remote folder paths to exclude during syncing | | string array |
localcache | no | local cache of remote snapshot | | string |
localpath |