CesiumCloud — Python CLI and SDK

Release 0.2.41 · Python 3.10+ · Windows, macOS and Linux

The Python package provides a CesiumCloud command-line client and Python APIs for authorized storage operations. It is independent of the Node.js CLI and does not require Node.js.

Web app: https://cloud.cesiummc.space/app/ · PyPI: https://pypi.org/project/cesiumcloud/

Installation

Use a virtual environment when possible:

python -m venv .venv

Activate the environment with .venv\Scripts\activate in Windows CMD, .venv\Scripts\Activate.ps1 in PowerShell (if local policy permits), or source .venv/bin/activate in Linux/macOS. Alternatively call the environment's Python executable directly.

python -m pip install --upgrade cesiumcloud==0.2.41
python -m cesiumcloud --version
python -m cesiumcloud authenticate
python -m cesiumcloud whoami

You can run cesiumcloud instead of python -m cesiumcloud when its executable is on PATH. Device authorization opens a browser flow; a manually created API key is not necessary for interactive use. cesiumcloud upgrade and update install the current release from official PyPI.

Ubuntu/Debian: if your OS restricts global pip, use python3 -m venv and install into that environment. Python 3.10+ is required; cryptography>=42 is the package's declared dependency for encryption.

File and directory commands

cesiumcloud upload "./backup.zip"
cesiumcloud upload "./Projects"
cesiumcloud upload "./backup.zip" --replace
cesiumcloud upload "./a.zip" [and] "./b.zip" -simultaneous 2
cesiumcloud list -a
cesiumcloud list -n 20 -sort name
cesiumcloud search ext:png
cesiumcloud dir /
cesiumcloud dir "photos"
cesiumcloud download "backup.zip"
cesiumcloud download "photos" --location "./Restored"
cesiumcloud download --all "./RestoreAll"
cesiumcloud rename "old.txt" "new.txt"
cesiumcloud move "a.txt" [to] "archive"
cesiumcloud delete "archive/a.txt"

Command reference: authenticate, whoami, logout, upgrade, update, stats, upload, download, upload cancel, download cancel, uploads, cancel-upload, discard-upload, resume-upload (legacy), list, search, dir, rename, move, delete, e2ee and help. Use cesiumcloud help COMMAND or cesiumcloud COMMAND --help for detailed syntax.

Literal [and] separates multiple inputs; [to] (or to) separates sources from a move destination. Quote local filenames with spaces or parentheses. Relative cloud paths resolve from the saved cloud directory selected with dir; the root/ prefix refers to the cloud root rather than a local filesystem directory.

Downloads and folder restoration

A named download saves to the OS Downloads directory unless --location DIRECTORY is specified. Existing local files are preserved by choosing a numbered filename. Folder downloads preserve nested paths and empty folders beneath the selected destination. download --all LOCALDIR restores the full account hierarchy. -simultaneous N / --simultaneous N permits 1–64 active downloads (default 1). Uploading folders or multiple files supports up to 40 active uploads by default for folders.

Browsing

list shows 15 files by default; -a lists recursively; -n N, N and -N specify count; -next N advances the list cursor; -sort size|name|datecreated|lastmodified|reset controls order; -long adds metadata. search finds case-insensitive matches in cloud paths; ext:png matches a file extension. dir .. moves up, dir / returns to root, and dir with no argument displays the current cloud directory. rename preserves a file extension unless -ne is used.

Upload behavior, cancellations and options

Python single-file uploads default to 99,876,864-byte chunks (aligned under 100 MB), matching Node.js. Uploads of directories or multiple files use the batched transfer path with separate file progress and admission controls.

The Python CLI supports the following upload chunk variables:

Near-100 MB is the Python default. Every chunk is capped at 100 MB, including SDK overrides. Node-specific read-ahead and stream-block settings do not apply.

For Bash:

CESIUMCLOUD_UPLOAD_CHUNK_MB=100 cesiumcloud upload "./backup.zip"

For PowerShell:

$env:CESIUMCLOUD_UPLOAD_CHUNK_MB = "100"
cesiumcloud upload "E:\Backup\backup.zip"
Remove-Item Env:\CESIUMCLOUD_UPLOAD_CHUNK_MB

Cancellation: Ctrl+C interrupts the Python CLI when the terminal forwards it. Alternatively, run cesiumcloud upload cancel or cesiumcloud download cancel from a second terminal on the same computer and configuration. A cancelled/failed upload is discarded, not paused for future resumption. Upload transport may retry an unacknowledged chunk during a continuing session; that is not a persistent resume feature. Use cesiumcloud uploads to inspect any pending cleanup. Completed cloud files survive cancellation; successful local downloads survive cancelled batches.

The Windows-specific raw console Ctrl+C fallback introduced in the Node.js CLI 0.2.29 does not automatically apply to the Python CLI. Use the second-terminal cancellation command if your Python terminal does not deliver the interrupt.

Python SDK

Prefer IsolatedTransferClient for individually managed cloud files. It requires an authorized device token, obtainable through the normal login process for your account; use an environment variable rather than embedding tokens in code.

import os
from pathlib import Path
from cesiumcloud import IsolatedTransferClient

storage = IsolatedTransferClient(os.environ["CESIUMCLOUD_API_KEY"])
storage.upload_file(Path("notes.txt"), "docs/notes.txt")
files = storage.all_files()
match = next((item for item in files if item["path"] == "docs/notes.txt"), None)
if match is not None:
    storage.download_file(match["id"], Path("notes-restored.txt"))

Additional supported operations include upload_path, download_path, list_files, find_path, directory_exists, mkdir, rmdir, rename_file, move_folder, delete_file, pending_uploads, cancel_upload, discard_upload and status.

The package also exposes CesiumCloudClient for device authorization and compatible high-level methods:

from cesiumcloud import CesiumCloudClient

client = CesiumCloudClient()
profile = client.authenticate()
print(profile.get("email", "CesiumCloud account"))

SDK downloads do not automatically rename files that already exist; the overwrite option must be considered explicitly when restoring to an existing local path. See the complete SDK reference.

Local end-to-end content encryption (optional)

cesiumcloud e2ee keygen
cesiumcloud e2ee encrypt "./notes.txt" --location "./Encrypted"
cesiumcloud e2ee decrypt "./Encrypted/notes.txt.ccenc" --location "./Restored"
cesiumcloud e2ee upload "./notes.txt"
cesiumcloud e2ee download "notes.txt.ccenc" --location "./Restored"
cesiumcloud e2ee migrate "old.txt"

The recovery key is stored locally in the CesiumCloud configuration directory. Back it up securely offline; if it is lost, CesiumCloud cannot recover encrypted contents. Plain upload remains unencrypted. Encrypted file contents are protected, but filenames, sizes, paths and usage metadata are not. Migrating plaintext to an encrypted copy preserves the original unless both --purge-original and --i-backed-up-key are specified.

Troubleshooting

Important: CLI delete moves completed files to Trash for 48 hours. Keep independent backups of important files and your encryption key. logout removes local authorization but does not revoke the device on the service.

For the current command matrix and complete guides, see https://cloud.cesiummc.space/api-docs.html and the documentation bundled with the client source.

Windows version and package upgrades

Use where cesiumcloud to check which executable Windows starts. Python's Scripts executable may precede the npm CLI on PATH. Use cesiumcloud.cmd version for the npm global client or python -m cesiumcloud version for Python. The upgrade and update commands update both package types when both are installed. For npm global installation use npm install -g cesiumcloud; without -g npm installs into the current project.

Uploads are admitted through a queue before bytes are transferred. The service enforces admission to prevent skipping the queue by making direct requests. Upload chunk sizes are capped at 100 MB.

Folder deletion in 0.2.41

Use the delete command with a quoted cloud folder path. It moves that directory and all its contents into the 48-hour recoverable Trash, including empty folders; it never calls permanent deletion. A trailing Windows backslash is supported.