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.

Dosya CLI file round trip with an explicit workspace, upload result, separate download path, and size or integrity comparison.
Keep the original file, upload once, download to a new name, and compare the result before scaling the command. Open full-size screenshot.

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.

Dosya Zapier setup page, separate from the terminal commands and API key used by the Dosya CLI.
The CLI uses its own REST-enabled API key; the Zapier invitation and setup controls do not configure terminal transfers. Open full-size screenshot.

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.

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.

    Check the outcome before you retry

    Use these shared checks when a task needs a second look.