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:

Response

Upload file with encryption:

Response

Upload file with web‑streaming:

Response

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:

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)

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

Example

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):

Download (non‑owner) with authticket:

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

Response

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

Sample response

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

Response

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

Response (encoded token)

Auth token (decoded)

Encrypted share (private)

  1. Upload file with --encrypt.

  2. Get encryptionpublickey from the recipient:

Response

  1. Share privately:

Response (encoded token)

Auth token (decoded)

Directory share

  • Upload multiple files to a directory with zbox upload /folder1/file1.z ...

  • Share the directory (use encryptionpublickey as above):

Encoded

Decoded

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:

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

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)

PreviousCreating & Managing AllocationsNextConfiguration

Last updated