CesiumCloud — Python CLI and SDK

Release 0.2.31 · 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.31
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 64 MiB chunks; this differs from the Node.js CLI's newer ~100 MB default. 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:

The near-100 MB setting is opt-in for Python; a 512 MiB request may fall back to near-100 MB after HTTP 413, depending on the operation. Larger chunks use more RAM. Node-specific variables for HTTP stream blocks, prefetch, and experimental parallel lanes are not Python upload tuning controls.

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: delete is permanent. 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.