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	no	encrypt file before upload	false	boolean
web-streaming	no	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	no	local path of thumbnail		file path
chunknumber	no	how many chunks should be uploaded in a http request	1	int
attr-who-pays-for-reads	no	Who pays for reads: owner or 3rd_party	owner	owner / 3rd_party
multiuploadjson	no	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	no	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	no	local path of thumbnail		file path
chunknumber	no	how many chunks should be uploaded in a http request	1	int
delay	no	set segment duration to seconds.	5	int
feed	no	set remote live feed to url.	false	url
downloader-args	no	pass args to youtube-dl to download video. default is -q -f best.	-q -f best	youtube-dl
ffmpeg-args	no	pass args to ffmpeg to build segments.	-loglevel warning	ffmpeg
attr-who-pays-for-reads	no	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	no	auth ticked if not owner of the allocation, use share to get one		string
blockspermarker	no	download multiple blocks per marker	10	int
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
startblock	no	start download from specified block		int
thumbail	no	only download the thumbnail	false	boolean
live	no	start m3u8 downloader, and automatically generate media playlist on --localpath	false	boolean
delay	no	pass segment duration to generate media playlist (works with --live)	5	int
lookuphash	no	The remote lookuphash of the object retrieved from the list		string
multidownloadjson	no	A JSON file containing multi download options		string
verifydownload	no	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	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
chunknumber	no	how many chunks per HTTP request	1	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).

7. Share

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	no	id of user to share file with (or revoke share from), leave blank for public share (or revoke)	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
available-after	no	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)

1. Upload file with --encrypt.

2. Get encryptionpublickey from the recipient:

./zbox getwallet

Response

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

1. 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	no	auth ticket if not owner of the allocation		string
json	no	output the response in json format	false	boolean
lookuphash	no	hash of object to list, use with auth ticket		string
remotepath	no	remote path of objects to list, for auth ticket use lookuphash		string

Example (owner)

./zbox list --allocation 8695b9e7f986d4a447b64de020ba86f53b3b5e2c