Upload and download files with the Dosya CLI
Transfer a test file with explicit workspace and paths, understand resume, concurrency and overwrite behavior, then verify the downloaded bytes safely.
Last reviewed
Start with one non-confidential file, an explicit workspace, and separate local source and download paths. A successful upload creates stored content in Dosya; a download with --force can replace a local file. Verify the round trip before putting either command into automation.
Steps
Choose a workspace and, optionally, a destination folder ID:
DOSYA_WORKSPACE_ID='ws_REPLACE_ME'
DOSYA_FOLDER_ID='fld_REPLACE_ME'
printf 'Dosya CLI transfer check\n' > cli-transfer-check.txt
dosya upload ./cli-transfer-check.txt \
--workspace "$DOSYA_WORKSPACE_ID" \
--folder "$DOSYA_FOLDER_ID"
Omit --folder to upload to the workspace root. If neither --workspace nor a saved default is available, the command stops with Workspace ID required. Use -w <id> or set default: dosya workspace use <id>. A missing local path produces File not found: …; a directory without --recursive is refused instead of being flattened unexpectedly.
The CLI reads current workspace upload rules before transferring when that endpoint is available. Blocked extensions and files over the configured maximum are rejected locally with the server’s rule. A total larger than remaining storage produces a warning, while the server remains the final quota authority. The role and key must both permit uploads.
Files above 50 MiB use multipart upload. Individual parts are retried, and a <filename>.dosya-upload sidecar records the resumable session. Re-run the same command after interruption; the sidecar is used only when the file size and modification time still match, and it is removed after success. Smaller files use one streamed request with retry delays of 1, 3, and 8 seconds for retryable failures.

Capture the uploaded file ID
For scripts, use JSON rather than parsing progress text:
dosya upload ./cli-transfer-check.txt \
--workspace "$DOSYA_WORKSPACE_ID" \
--folder "$DOSYA_FOLDER_ID" \
--json > upload-result.json
DOSYA_FILE_ID=$(python3 -c 'import json; print(json.load(open("upload-result.json"))["file"]["id"])')
printf '%s\n' "$DOSYA_FILE_ID"
The single-file response contains file.id and file.name. Preserve upload-result.json only if its metadata is needed; it does not contain the API key. To upload a deliberate replacement as a new version, use --version-of with an existing file ID or path:
dosya upload ./report-v2.pdf --workspace "$DOSYA_WORKSPACE_ID" --version-of reports/report.pdf
Version upload changes the stored file’s current version; keep the local source until the new version appears in Dosya. Do not use --version-of when creating a separate file.
Download to a new local path
Address the file by returned ID or by a workspace-relative path:
mkdir -p ./dosya-transfer-check
dosya download "$DOSYA_FILE_ID" --output ./dosya-transfer-check/received.txt
cmp ./cli-transfer-check.txt ./dosya-transfer-check/received.txt
When --output names a directory, the server’s filename is used inside it. With no output flag, the current directory is used. An existing destination prompts before overwrite on an interactive terminal; JSON or non-interactive execution stops with already exists. Use --force to overwrite. --force replaces that local path without another confirmation.
Downloads use one connection for small files and up to 8 parallel connections by default for larger objects; --connections accepts 1–16. Interrupted segmented downloads persist <output>.dosya-download; rerun the same command with the same file and path to continue completed ranges. Expired temporary URLs are refreshed up to three times.
After transfer, the CLI checks the saved content against a recognized origin ETag: a normal MD5 or Dosya’s multipart composite form. Unknown ETag formats are skipped rather than guessed. --no-verify disables this integrity check and should be reserved for a diagnosed compatibility problem. Size alone does not detect every corruption.

Transfer folders and multiple files
Upload a directory with --recursive; by default Dosya creates a top-level folder named after the local directory. Add --contents to place only its contents into the selected destination:
dosya upload ./project --recursive --workspace "$DOSYA_WORKSPACE_ID" --parallel 3
dosya upload ./project --recursive --contents --workspace "$DOSYA_WORKSPACE_ID"
Upload concurrency defaults to 3 and is capped at 16, then reduced further when the workspace has a smaller concurrent-upload limit. For a remote folder download, use the dedicated recursive workflow. For several specific files in one archive, use dosya download --zip FILE... -o bundle.zip.
Expected result
The upload reports a concrete file ID in the intended workspace and folder. Downloading that ID to a new local path completes without overwrite ambiguity, and cmp or the CLI integrity check confirms the received bytes match the source.
Related guides
Was this helpful?
Loading helpfulness results…
Voting saves a necessary ballot cookie for up to 180 days so you can change your answer.
Questions and replies
Ask about the steps in this guide. Questions are reviewed before publication.
Keep account details, credentials and private files out of public questions. Use private support for those.
Loading questions…
Sign in to your Dosya account to ask a question.