Uploading & Managing Files

This page documents all file‑management operations in Züs dStorage with the zbox CLI.

Note – ./zbox vs zbox:

Use ./zbox when running the binary from the build folder.
Use zbox when the binary is in your $PATH (recommended).
Both forms execute the same CLI.

1. Create Directory

Use createdir to create a directory in the specified allocation. The user must be the owner of the allocation.

Parameters

Parameter

Required

Description

Default

Valid values

allocation

yes

allocation id, sender must be allocation owner

string

dirname

yes

path to directory

string

Sample request

./zbox createdir --allocation {ALLOC_ID} --dirname /abcd/

Sample response

/abcd/ directory created

2. Upload

Use upload to upload file(s).

upload a local file
download segment files from remote live feed, and upload them
start live streaming from local devices, encode it into segment files with ffmpeg, and upload them.

The user must be the owner of the allocation. You can request the file be encrypted before upload, and can send thumbnails with the file.

Parameters

Parameter

Required

Description

Default

Valid values

allocation

yes

allocation id, sender must be allocation owner

string

encrypt

encrypt file before upload

false

boolean

web-streaming

transcode file before upload to fragmented mp4

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

local path of thumbnail

file path

chunknumber

how many chunks should be uploaded in a http request

int

attr-who-pays-for-reads

Who pays for reads: owner or 3rd_party

owner

owner / 3rd_party

multiuploadjson

A JSON file containing multiupload options

file path

Examples

Upload file with no encryption:

./zbox upload --localpath /absolute-path-to-local-file/hello.txt \
              --remotepath /myfiles/hello.txt \
              --allocation d0939e912851959637257573b08c748474f0dd0ebbc8e191e4f6ad69e4fdc7ac

Response

12390 / 12390 [================================================================================] 100.00% 3s
Status completed callback. Type = application/octet-stream. Name = hello.txt

Upload file with encryption:

./zbox upload --encrypt \
              --localpath <absolute path to file>/sensitivedata.txt \
              --remotepath /myfiles/sensitivedata.txt \
              --allocation d0939e912851959637257573b08c748474f0dd0ebbc8e191e4f6ad69e4fdc7ac

Response

12390 / 12390 [================================================================================] 100.00% 3s
Status completed callback. Type = application/octet-stream. Name = sensitivedata.txt

Upload file with web‑streaming:

./zbox upload --web-streaming \
              --localpath <absolute path to file>/samplevideo.mov \
              --remotepath /myfile/ \
              --allocation d0939e912851959637257573b08c748474f0dd0ebbc8e191e4f6ad69e4fdc7ac

Response

15691733 / 15691733 [=====================================================================================] 100.00% 32s
Status completed callback. Type = video/fmp4. Name = raw.samplevideo.mp4

3. Feed

Use feed to automatically download segment files from a remote live feed with --downloader-args "-q -f best", encode them into new segment files with --delay and --ffmpeg-args, and upload.

Please use:

youtube-dl -F https://www.youtube.com/watch?v=pC5mGB5enkw

to list formats of video (see below). The user must be the owner of the allocation. You can request the file be encrypted before upload, and can send thumbnails with the file.

Parameters

Parameter

Required

Description

Default

Valid values

allocation

yes

allocation id, sender must be allocation owner

string

encrypt

encrypt file before upload

false

boolean

localpath

yes

local path of segment files to download, generate and upload

file path

remotepath

yes

remote path to upload file to, use to access file later

string

thumbnailpath

local path of thumbnail

file path

chunknumber

how many chunks should be uploaded in a http request

int

delay

set segment duration to seconds.

int

feed

set remote live feed to url.

false

url

downloader-args

pass args to youtube-dl to download video. default is -q -f best.

-q -f best

youtube-dl

ffmpeg-args

pass args to ffmpeg to build segments.

-loglevel warning

ffmpeg

attr-who-pays-for-reads

Who pays for reads: owner or 3rd_party

owner

owner / 3rd_party

enum

Available formats sample (from youtube-dl)

[youtube] pC5mGB5enkw: Downloading webpage
[info] Available formats for pC5mGB5enkw:
format code  extension  resolution note
249          webm       audio only tiny   44k , webm_dash container, opus @ 44k (48000Hz), 95.21MiB
250          webm       audio only tiny   59k , webm_dash container, opus @ 59k (48000Hz), 127.05MiB
251          webm       audio only tiny  123k , webm_dash container, opus @123k (48000Hz), 264.98MiB
140          m4a        audio only tiny  129k , m4a_dash container, mp4a.40.2@129k (44100Hz), 277.82MiB
278          webm       256x136    144p   87k , webm_dash container, vp9@  87k, 30fps, video only, 188.78MiB
160          mp4        256x136    144p  118k , mp4_dash container, avc1.4d400c@ 118k, 30fps, video only, 253.62MiB
242          webm       426x224    240p  190k , webm_dash container, vp9@ 190k, 30fps, video only, 409.20MiB
133          mp4        426x224    240p  252k , mp4_dash container, avc1.4d400d@ 252k, 30fps, video only, 541.15MiB
243          webm       640x338    360p  326k , webm_dash container, vp9@ 326k, 30fps, video only, 701.53MiB
134          mp4        640x338    360p  576k , mp4_dash container, avc1.4d401e@ 576k, 30fps, video only, 1.21GiB
244          webm       854x450    480p  649k , webm_dash container, vp9@ 649k, 30fps, video only, 1.36GiB
135          mp4        854x450    480p 1028k , mp4_dash container, avc1.4d401f@1028k, 30fps, video only, 2.16GiB
247          webm       1280x676   720p 1320k , webm_dash container, vp9@1320k, 30fps, video only, 2.77GiB
136          mp4        1280x676   720p 1988k , mp4_dash container, avc1.64001f@1988k, 30fps, video only, 4.17GiB
248          webm       1920x1012  1080p 2527k , webm_dash container, vp9@2527k, 30fps, video only, 5.30GiB
137          mp4        1920x1012  1080p 4125k , mp4_dash container, avc1.640028@4125k, 30fps, video only, 8.64GiB
271          webm       2560x1350  1440p 7083k , webm_dash container, vp9@7083k, 30fps, video only, 14.84GiB
313          webm       3840x2026  2160p 13670k , webm_dash container, vp9@13670k, 30fps, video only, 28.65GiB
18           mp4        640x338    360p  738k , avc1.42001E, 30fps, mp4a.40.2 (44100Hz), 1.55GiB
22           mp4        1280x676   720p 2117k , avc1.64001F, 30fps, mp4a.40.2 (44100Hz) (best)

Tip: --downloader-args "-f 22" downloads the 22 format shown above.

Example

./zbox feed --localpath <absolute path to file>/tvshow.m3u8 \
            --remotepath /videos/tvsho \
            --allocation d0939e912851959637257573b08c748474f0dd0ebbc8e191e4f6ad69e4fdc7ac \
            --delay 10 \
            --downloader-args "-f 22" \
            --feed https://www.youtube.com/watch?v=pC5mGB5enkw

4. Download

Use download to download your own or a shared file.

owner: The owner of the allocation can always download files; owner pays.
collaborator: A collaborator can download files; owner pays. (Add collaborators with add-collab.)
authticket: To download using authticket, get a token via share. Use rx_pay to indicate who pays (true = you pay; false = owner pays). Use startblock and endblock to download part of the file.

Parameters

Parameter

Required

Description

Default

Valid values

allocation

yes

allocation id

string

authticket

auth ticked if not owner of the allocation, use share to get one

string

blockspermarker

download multiple blocks per marker

int

endblock

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

startblock

start download from specified block

int

thumbail

only download the thumbnail

false

boolean

live

start m3u8 downloader, and automatically generate media playlist on --localpath

false

boolean

delay

pass segment duration to generate media playlist (works with --live)

int

lookuphash

The remote lookuphash of the object retrieved from the list

string

multidownloadjson

A JSON file containing multi download options

string

verifydownload

pass this option to verify downloaded blocks

false

boolean

Examples

Download (owner):

./zbox download --allocation 3c0d32560ea18d9d0d76808216a9c634f661979d29ba59cc8dafccb3e5b95341 \
                --remotepath /myfiles/horse.jpeg \
                --localpath ../horse.jpeg

Download (non‑owner) with authticket:

./zbox download --allocation 3c0d32560ea18d9d0d76808216a9c634f661979d29ba59cc8dafccb3e5b95341 \
                --authticket eyJjbGllbnRfaWQiOiIiLCJvd25lcl9pZCI6IiIsImFsbG9jYXRpb24iOiIzYzBkMzI1NjBlYTE4ZDlkMGQ3NjgwODIxNmE5YzYzNGY2NjE5NzlkMjliYTU5Y2M4ZGFjYmMzZTViOTUzNDEiLCJyZW1vdGVwYXRoIjoiL215ZmlsZXMvaG9yc2UuanBlZyIsImV4cG9ydCI6IjIwMjEtMDctMjFUMDk6MjA6MjAuMDAwWiJ9 \
                --localpath ../horse.jpeg

If the authticket is for a directory, provide the lookuphash of the file you want (get it from list).

Response

4 / 4 [=======================================================================] 100.00% 3s
Status completed callback. Type = application/octet-stream. Name = horse.jpeg

Note: You can download by using only 1 of the combinations below:

--remotepath + --allocation
--authticket

Downloaded file will be in the location specified by the --localpath argument.

5. Update

Use update to update content of an existing file in the remote path. Like upload. Only the owner of the allocation or a collaborator can update a file (add collaborators with add-collab).

Parameters

Parameter

Required

Description

Default

Valid values

allocation

yes

allocation id

string

encrypt

encrypt file before upload

false

boolean

localpath

yes

local file to upload

file path

remotepath

yes

remote file to upload

string

thumbnailpath

local fumbnail file to upload

file path

chunknumber

how many chunks per HTTP request

int

Sample command

./zbox update --allocation {ALLOC_ID} --localpath ./zbox_commands.txt --remotepath /abcd/ --encrypt

Sample response

Status completed callback. Type = application/octet-stream. Name = zbox_commands.txt

6. Delete

Use delete to delete your file on the allocation. Only the owner of the application can delete a file.

Parameters

Parameter

Required

Description

Default

Valid values

allocation

yes

allocation id

string

remotepath

yes

remote path of file to delete

string

Example

./zbox delete --allocation 3c0d32560ea18d9d0d76808216a9c634flist661979d29ba59cc8dafccb3e5b95341 \
              --remotepath /myfiles/horse.jpeg

Response

/myfiles/horse.jpeg deleted

File successfully deleted (can be verified using list).

Use share to generate an authtoken that provides authorization to the holder to the specified file on the remotepath.

The auth ticket can be used with download, and list, meta and get_download_cost, but only for files in the pre-defined remote path.

Parameters

Parameter

Required

Description

Valid values

allocation

yes

allocation id

string

clientid

id of user to share file with (or revoke share from), leave blank for public share (or revoke)

string

encryptionpublickey

public key of the client to share file with, required if clientid

string

expiration-seconds

seconds before auth ticket expires

int

remotepath

yes

remote path of file to share

string

revoke

revoke share for remote path

flag

available-after

timelock making the file available for download at time (+1h30m, +30, 1647858200, 2022-03-21 10:21:38)

string

Public share

./zbox share --allocation 3c0d32560ea18d9d0d76808216a9c634f661979d29ba59cc8dafccb3e5b95341 \
             --remotepath /myfiles/hello.txt

Response (encoded token)

Auth token eyJjbGllbnRfaWQiOiIiLCJvd25lcl9pZCI6IjE3ZTExOTQwNmQ4ODg3ZDAyOGIxNDE0YWNmZTQ3ZTg4MDhmNWIzZjk4Njk2OTk4Nzg3YTIwNTVhN2VkYjk3YWYiLCJhbGxvY2F0aW9uX2lkIjoiODlkYjBjZDI5NjE4NWRkOTg2YmEzY2I0ZDBlODE0OTE3NmUxNmIyZGIyMWEwZTVjMDZlMTBmZjBiM2YxNGE3NyIsImZpbGVfcGF0aF9oYXNoIjoiM2NhNzIyNTQwZTY1M2Y3NTQ1NjI5ZjBkYzE5ZGY2ODk5ZTI0MDRjNDI4ZDRiMWZlMmM0NjI3ZGQ3MWY3ZmQ2NCIsImFjdHVhbF9maWxlX2hhc2giOiIyYmM5NWE5Zjg0NDlkZDEyNjFmNmJkNTg3ZjY3ZTA2OWUxMWFhMGJiIiwiZmlsZV9uYW1lIjoidGVzdC5wZGYiLCJyZWZlcmVuY2VfdHlwZSI6ImYiLCJleHBpcmF0aW9uIjoxNjM1ODQ5MzczLCJ0aW1lc3RhbXAiOjE2MjgwNzMzNzMsInJlX2VuY3J5cHRpb25fa2V5IjoiIiwiZW5jcnlwdGVkIjpmYWxzZSwic2lnbmF0dXJlIjoiZDRiOTM4ZTE0MDk0ZmZkOGFiMDcwOWFmN2QyMDAyZTdlMGFmNmU3MWJlNGFmMmRjNmUxMGYxZWJmZTUwOTMxOSJ9

Auth token (decoded)

{"client_id":"","owner_id":"17e119406d8887d028b1414acfe47e8808f5b3f98696998787a2055a7edb97af","allocation_id":"89db0cd296185dd986ba3cb4d0e8149176e16b2db21a0e5c06e10ff0b3f14a77","file_path_hash":"3ca722540e653f7545629f0dc19df6899e2404c428d4b1fe2c4627dd71f7fd64","actual_file_hash":"2bc95a9f8449dd1261f6bd587f67e069e11aa0bb","file_name":"test.pdf","reference_type":"f","expiration":1635849373,"timestamp":1628073373,"re_encryption_key":"","encrypted":false,"signature":"d4b938e14094ffd8ab0709af7d2002e7e0af6e71be4af2dc6e10f1ebfe509319"}

Encrypted share (private)

Upload file with --encrypt.
Get encryptionpublickey from the recipient:

./zbox getwallet

Response

PUBLIC KEY | CLIENTID | ENCRYPTION PUBLIC KEY
-----------------------------------------------------------------------------------------------------------------------------------+------------------------------------------------------------------+-----------------------------------------------
  19cd2396df9b8b77358a1110492ff65cbb5b55cae06b8bd204e0969b2454851ca620ae74aebe9ed641166be3bca056a1855610f6154f4f4435a29565a2111282 | b734ef935e2a02892b2fa31e3488b360ef300d3b0b32c03834cea3a83e2453f0 | 1JuT4AbQnmIaOMTuWn07t98xQRsSqXAxZYfwCI1yQLM=

Share privately:

./zbox share --allocation 3c0d32560ea18d9d0d76808216a9c634f661979d29ba59cc8dafccb3e5b95341 \
             --remotepath /myfiles/hello.txt \
             --clientid b6de562b57a0b593d0480624f79a55ed46dba544404595bee0273144e01034ae \
             --encryptionpublickey 1JuT4AbQnmIaOMTuWn07t98xQRsSqXAxZYfwCI1yQLM=

Response (encoded token)

Auth token eyJjbGllbnRfaWQiOiIwMGZmODhkY2IxNjQ2Y2RlZjA2OWE4MGE0MGQwMWNlOTYyMmQ3ZmUzYmQ0ZWNjMzIzYTcwZTdkNmVkMWE2YjY3Iiwib3duZXJfaWQiOiIxN2UxMTk0MDZkODg4N2QwMjhiMTQxNGFjZmU0N2U4ODA4ZjViM2Y5ODY5Njk5ODc4N2EyMDU1YTdlZGI5N2FmIiwiYWxsb2NhdGlvbl9pZCI6Ijg5ZGIwY2QyOTYxODVkZDk4NmJhM2NiNGQwZTgxNDkxNzZlMTZiMmRiMjFhMGU1YzA2ZTEwZmYwYjNmMTRhNzciLCJmaWxlX3BhdGhfaGFzaCI6IjM2Mjk0MGMwMTZlOWZlZTQ4ZmI5MTA0OGI4MzJjOGFlNWQ2MGUyYzUzMmQ1OGNlYzdmNGM0YjBmZTRkZjM2MzYiLCJhY3R1YWxfZmlsZV9oYXNoIjoiMmJjOTVhOWY4NDQ5ZGQxMjYxZjZiZDU4N2Y2N2UwNjllMTFhYTBiYiIsImZpbGVfbmFtZSI6InRlc3QyLnBkZiIsInJlZmVyZW5jZV90eXBlIjoiZiIsImV4cGlyYXRpb24iOjE2MzU4NDk4NDMsInRpbWVzdGFtcCI6MTYyODA3Mzg0MywicmVfZW5jcnlwdGlvbl9rZXkiOiIiLCJlbmNyeXB0ZWQiOnRydWUsInNpZ25hdHVyZSI6IjNlNGMwOTAwMzAwN2M5NzUzZjFiNGIwODExMWM4OGRlY2JmZjU2MDRmNTIwZDZjMmYyMTdhMzUyZTFkMmE0MTEifQ==

Auth token (decoded)

{"client_id":"00ff88dcb1646cdef069a80a40d01ce9622d7fe3bd4ecc323a70e7d6ed1a6b67","owner_id":"17e119406d8887d028b1414acfe47e8808f5b3f98696998787a2055a7edb97af","allocation_id":"89db0cd296185dd986ba3cb4d0e8149176e16b2db21a0e5c06e10ff0b3f14a77","file_path_hash":"362940c016e9fee48fb91048b832c8ae5d60e2c532d58cec7f4c4b0fe4df3636","actual_file_hash":"2bc95a9f8449dd1261f6bd587f67e069e11aa0bb","file_name":"test2.pdf","reference_type":"f","expiration":1635849843,"timestamp":1628073843,"re_encryption_key":"","encrypted":true,"signature":"3e4c09003007c9753f1b4b08111c88decbff5604f520d6c2f217a352e1d2a411"}

Directory share

Upload multiple files to a directory with zbox upload /folder1/file1.z ...
Share the directory (use encryptionpublickey as above):

./zbox share --allocation 3c0d32560ea18d9d0d76808216a9c634f661979d29ba59cc8dafccb3e5b95341 \
             --remotepath /folder1 \
             --clientid b6de562b57a0b593d0480624f79a55ed46dba544404595bee0273144e01034ae \
             --encryptionpublickey 1JuT4AbQnmIaOMTuWn07t98xQRsSqXAxZYfwCI1yQLM=

Encoded

eyJjbGllbnRfaWQiOiJiNzM0ZWY5MzVlMmEwMjg5MmIyZmEzMWUzNDg4YjM2MGVmMzAwZDNiMGIzMmMwMzgzNGNlYTNhODNlMjQ1M2YwIiwib3duZXJfaWQiOiI2MzlmMjcxZmU1MTFjZDE4ODBjMmE0ZDhlYTRhNGYyNDBmYWYzMzY1YzYxYjY1YjQyNWZhYjVlMDIzMTcxM2MzIiwiYWxsb2NhdGlvbl9pZCI6IjkzN2FkNjlmYjIwZGMxMTFiY2ZkMDFkZTQyYzc5MmEwYzJiNDQxZGUzZDNjZjRjZGIzZjI1YzIxYzFhYjRiN2IiLCJmaWxlX3BhdGhfaGFzaCI6ImFkMThmMzg1Y2I2MWM4MTNjMzE0NDU2OTM0NWYxYzQ2ODE1ODljNzM0N2JkNzI4NjkyZTg1ZjFiNzM4NmI2OWQiLCJhY3R1YWxfZmlsZV9oYXNoIjoiIiwiZmlsZV9uYW1lIjoiZm9sZGVyMSIsInJlZmVyZW5jZV90eXBlIjoiZCIsImV4cGlyYXRpb24iOjE2MzYyODgwNDMsInRpbWVzdGFtcCI6MTYyODUxMjA0MywicmVfZW5jcnlwdGlvbl9rZXkiOiIiLCJlbmNyeXB0ZWQiOnRydWUsInNpZ25hdHVyZSI6ImNiYTZlMjA2OTBjOGZjZTk5YmFjZTMzYjFjMGY3ODQ5ZDE4YmJlMTdhODkyNjczODg1MjI2MDc3MGQzNzgzMGQifQ==

Decoded

{"client_id":"b734ef935e2a02892b2fa31e3488b360ef300d3b0b32c03834cea3a83e2453f0","owner_id":"639f271fe511cd1880c2a4d8ea4a4f240faf3365c61b65b425fab5e0231713c3","allocation_id":"937ad69fb20dc111bcfd01de42c792a0c2b441de3d3cf4cdb3f25c21c1ab4b7b","file_path_hash":"ad18f385cb61c813c3144569345f1c4681589c7347bd728692e85f1b7386b69d","actual_file_hash":"","file_name":"folder1","reference_type":"d","expiration":1636288043,"timestamp":1628512043,"re_encryption_key":"","encrypted":true,"signature":"cba6e20690c8fce99bace33b1c0f7849d18bbe17a8926738852260770d37830d"}

Make sure "reference_type":"d" is d (directory).

Now you can download files inside this directory with the same authticket. Just point to the exact file in --remotepath:

zbox download --allocation 76ad9fa86f9b6685880553588a250586806ba5d7d20fc229d6905998be55d64a \
              --localpath ~/file1.z \
              --authticket $auth \
              --remotepath /folder1/file1.z

This works for both encrypted and non‑encrypted files.

share-encrypted revoke

Cancel the share for a particular buyer performed using zbox share (works only for files with --encrypted).

Use clientid of the user that was shared the remotepath. Required parameters are allocation, remotepath, and clientid.

Command

./zbox share --revoke \
             --allocation 3c0d32560ea18d9d0d76808216a9c634f661979d29ba59cc8dafccb3e5b95341 \
             --remotepath /myfiles/hello.txt \
             --clientid d52d82133177ec18505145e784bc87a0fb811d7ac82aa84ae6b013f96b93cfaa

Response Returns status message showing whether the operation was successful or not.

8. List

Use list to list files in a given remote path of dStorage. Provide an authticket when not sent by the allocation owner. Using an authticket requires a lookuphash to indicate the path for which to list contents.

Parameters

Parameter

Required

Description

Default

Valid values

allocation

yes

allocation id

string

authticket

auth ticket if not owner of the allocation

string

json

output the response in json format

false

boolean

lookuphash

hash of object to list, use with auth ticket

string

remotepath

remote path of objects to list, for auth ticket use lookuphash

string

Example (owner)

./zbox list --allocation 8695b9e7f986d4a447b64de020ba86f53b3b5e2c

PreviousCreating & Managing Allocations NextConfiguration

Last updated 25 days ago

1. Create Directory

2. Upload

3. Feed

4. Download

5. Update

6. Delete

7. Share

8. List