CesiumCloud for Python

CesiumCloud cloud storage client for Python 3.10+.

Installation

Install the latest version from PyPI:

python -m pip install cesiumcloud

Or install the official wheel directly:

python3 -m pip install https://cloud.cesiummc.space/clients/cesiumcloud-0.1.5-py3-none-any.whl

Command-line use

python -m cesiumcloud authenticate
python -m cesiumcloud upload "/home/user/Documents"
python -m cesiumcloud upload "/home/user/dogimages.zip"
python -m cesiumcloud download "/home/user/Restored"
python -m cesiumcloud whoami

The cesiumcloud command is equivalent to python3 -m cesiumcloud.

Ubuntu 22.04, 24.04, 26.04 LTS and 26.10

Use Python 3.10 or newer. This Python client uses only the standard library and does not require Node.js.

On Ubuntu, use a virtual environment instead of changing the system Python:

sudo apt-get update
sudo apt-get install -y python3 python3-venv
python3 -m venv "$HOME/.local/share/cesiumcloud/venv"
"$HOME/.local/share/cesiumcloud/venv/bin/python" -m pip install --upgrade https://cloud.cesiummc.space/clients/cesiumcloud-0.1.5-py3-none-any.whl
"$HOME/.local/share/cesiumcloud/venv/bin/cesiumcloud" authenticate
"$HOME/.local/share/cesiumcloud/venv/bin/cesiumcloud" upload "$HOME/Videos/My video.mp4"

The CLI accepts a single path containing spaces even when it is unquoted, but quoting paths is still recommended. Authentication keeps the existing ~/.cesiumcloud/credentials.json.

Large uploads display transport-send progress in 256 KiB increments. 99% means data has been handed to the transport but may await server response; 100% appears only after the storage server commits the upload. The Python client does not yet maintain resumable checkpoints across separate processes.

Python SDK

from cesiumcloud import CesiumCloudClient

client = CesiumCloudClient()
client.authenticate()
client.upload("/home/user/dogimages.zip")
files = client.list_files()
print([file["name"] for file in files])
client.download("/home/user/Restored")

Authentication uses your CesiumCloud account without copying an API key. The Python implementation requires no Node.js runtime or third-party Python dependencies.

Current limitations

Data is streamed directly from local files. The Python client does not yet maintain restart-safe checkpoints across processes. Existing destination files are not silently overwritten. Keep an independent backup of important data.

Access management

Revoke credentials from the CesiumCloud dashboard. The logout command removes local credentials only.

Existing accounts

CesiumCloud connects to the existing API and stores credentials in ~/.cesiumcloud/credentials.json. Existing CesiumCloud package installations are not modified.

PowerShell filenames with parentheses

PowerShell treats unquoted parentheses as shell syntax and may remove them before a program receives command arguments. Quote the entire path:

cesiumcloud upload "E:\\Downloads\\Roblox 2026-10-18 13-37-47 (1).mp4"

The CLI joins unquoted fragments containing ordinary spaces, but cannot reconstruct text that the shell has discarded. Version 0.1.5 displays matching filenames and complete quoted examples when the supplied path does not exist; it never guesses and uploads the wrong file.

Reliable Python restore (0.1.5)

The Python CLI restores all committed files into a chosen directory. Data is downloaded in bounded chunks, using authenticated HTTP byte-range requests to resume incomplete or prematurely terminated file segments. A successful restore checks every restored file's expected size.

If a previous restore stopped, use a NEW directory when retrying; partial files in the old destination are left for inspection and are never deleted silently. A restore is not a selective single-file fetch; it reconstructs the account's committed backup set.

Only retry/download traffic changes; uploading still uses two Worker writes per new pack, plus account and other metadata requests as applicable.

Browse, search, rename, and permanently delete (0.1.6)

Python and npm CLIs share an account-backed file catalog.

cesiumcloud list                   # root, 15 items, size descending
cesiumcloud list -10               # 10 items
cesiumcloud list -a                # all files, recursively
cesiumcloud list -100 images/dogs  # directory entries
cesiumcloud list -next 15 images/dogs
cesiumcloud list -sort name        # persistent for future lists
cesiumcloud list -sort lastmodified
cesiumcloud list -sort datecreated
cesiumcloud list -sort reset       # size sorting
cesiumcloud list -10 "images/dogs|images/cats"
cesiumcloud search puppy
cesiumcloud search .png            # extension
cesiumcloud search ext:jpg
cesiumcloud dir images/dogs        # enter directory
cesiumcloud dir ..                 # parent
cesiumcloud dir -                  # previous visited directory
cesiumcloud dir /                  # root
cesiumcloud rename images/dogs/a.png b      # keeps original .png
cesiumcloud rename images/dogs/a.png b -ne  # drops extension
cesiumcloud delete images/dogs/a.png
cesiumcloud delete -resume

List shows file extensions, file sizes, last modified and upload timestamps in local time. Creation timestamps are captured for new uploads when the source filesystem provides them; older packs fall back to upload time.

Permanent delete is not hide-only. Files may share immutable backup packs, so the CLI stages replacements for surviving files, cuts over to verified replacements, and deletes the old backing storage objects. The service checks that removed backing storage objects are absent before reclaiming their storage accounting. Use delete -resume after an interrupted purge. Deletion is irreversible and needs temporary free quota for replacement packs. Folders are not deleted recursively by default.

For multiple directories, quote the complete expression with the pipe character, since an unquoted pipe is shell syntax. The program accepts separately quoted directory arguments too. ZIP archives are not expanded by list: extract and upload a folder to browse inside it.

Fast file listing in 0.1.7

Versions 0.1.6 and earlier reread two storage metadata ranges from every backup pack, sequentially, on every list/search/dir command. This could appear to hang on an account containing many packs.

Version 0.1.7 uses an authenticated, account-isolated index stored in the edge service service database: GET /v1/catalog/index?cursor=N. Immutable pack metadata is cached after validation, including when new packs are committed. A first catalog read on an older account may build this index; subsequent reads use service database. Cloud directories and filenames remain identical to previous versions.

Navigation to /, .., and - is local; it does not need API access. Other directory lookups use the indexed catalog. No user file contents are stored in the metadata index (only paths, sizes, timestamps and pack segment locations).

SQL-indexed file browsing (0.1.8)

All listing, searching, sorting, pagination and remote-directory existence checks are now server-side indexed queries against CesiumCloud metadata index. A list -10 request returns only ten entries plus their directory count. It does not loop through packs, download remote metadata, load the whole catalog into the CLI, or read any user file contents.

A persistent file_catalog_segments index is written at the same time a new immutable backup pack's metadata is committed. Existing packs are backfilled from the already-cached metadata, once, without downloading the original packs. Physical backing storage deletion and pack replacement remain unchanged; visibility switches and pack deletion are reflected by the indexed queries.

A file's stored byte size (including 64 GB or larger) does not change the cost of browsing. Directory navigation to root, parent and history is handled locally. The API uses /v1/catalog/browse with mode, dir, sort, limit, offset and search as optional parameters.

Readable terminal listings (0.1.9)

By default, list and search output an aligned, responsive terminal table with filename, extension or directory marker, human-readable file size, and short local timestamps, e.g. 2026-10-27 10:17. Repeated labels have been removed from each file row.

The renderer adapts to 40- to 160-column terminals. On narrow consoles it shows fewer columns rather than wrapping each entry; long names are clipped in the middle while preserving their endings. To show the COMPLETE names and metadata in multiple lines, run:

cesiumcloud list -long
cesiumcloud list -long 20 images
cesiumcloud search .png -long

All of these commands list 20 items:

cesiumcloud list 20
cesiumcloud list -20
cesiumcloud list -n 20
cesiumcloud list --limit 20

Previously 'list 20' was mistakenly interpreted as the directory '/20' and printed zero items. It is now accepted as a numeric limit.

The API-backed SQL listing, file contents, download behavior, physical Drive deletion and authentication are unchanged. This is a CLI-only release.

Download an individual cloud file to a local folder (0.1.10)

Select just one cloud file with --location:

cesiumcloud download dog.png --location "C:/Users/matth/Desktop"
cesiumcloud download "images/dogs/dog.png" --location "E:/Downloads"
cesiumcloud download "photos/picture (1).jpg" --location "./restored"

A relative cloud file name is resolved within the virtual directory selected with cesiumcloud dir. An explicit cloud path can include nested directories. The file is saved directly into the requested local folder under its original basename (the CLI does not recreate parent folders for this selected download). If no extension was included, the server resolves it only when there is a single unambiguous match; otherwise include the extension.

This is a real single-file download, not a full backup restore: the CLI requests only the file's segment metadata from CesiumCloud metadata index and streams its segments from backing storage. In the normal case it makes one Worker metadata request plus one Worker download request per nonempty segment (retries may add requests). An empty file is created without a segment-download request.

Downloads write to a temporary file and are made visible at the destination only after the complete expected size is received. Existing files are NEVER overwritten. Partial files are cleaned up after a failed transfer.

Backward compatibility: cesiumcloud download "E:/restore-all" without --location still restores the entire cloud backup collection to that directory, as it did previously.

CESIUMCLOUD CLI REFERENCE — Python and npm (0.1.11)

Usage: cesiumcloud COMMAND [arguments]. Use cesiumcloud help for this reference. Linux/macOS examples use / paths; Windows examples use quotes around local paths.

ACCOUNT cesiumcloud authenticate Approve device code at CesiumCloud website cesiumcloud whoami Show signed-in account cesiumcloud logout Remove local CLI credential; does not revoke key remotely

UPLOAD / DOWNLOAD cesiumcloud upload "E:\Downloads\dog.png" Upload local file cesiumcloud upload "./My Documents" Upload local folder (recursively) cesiumcloud download "E:\restore" Full-account restore into local folder cesiumcloud download dog.png --location "E:\Downloads" cesiumcloud download "images/dog.png" --location "E:\Downloads" Download ONLY one named cloud file into the local folder. The folder is created if needed. Existing local files are never overwritten. Relative filenames use the current cloud directory set by cesiumcloud dir. Quote local Windows paths and names containing spaces/parentheses.

BROWSING cesiumcloud list List 15 items of current cloud directory cesiumcloud list -10 List 10 items cesiumcloud list 20 List 20 items (also -n 20) cesiumcloud list -a List all files (paginated) cesiumcloud list -long Show full names and metadata cesiumcloud list -next 15 Next 15 results after list cesiumcloud list -10 "images/dogs|images/cats" cesiumcloud list -sort size Default sorting (largest first) cesiumcloud list -sort name Persist sort by name cesiumcloud list -sort lastmodified Persist newest-modified-first sorting cesiumcloud list -sort datecreated Persist newest-created-first sorting cesiumcloud list -sort reset Reset sort to size cesiumcloud search dog.png Search filename cesiumcloud search .png Search extension cesiumcloud search ext:png Search extension (alternate) cesiumcloud dir Go to cloud root and show it cesiumcloud dir images/dogs Change virtual directory cesiumcloud dir .. Up to parent directory cesiumcloud dir - Back in navigation history cesiumcloud dir / Go to root directory

RENAME (changes virtual filename; same stored bytes) cesiumcloud rename dog.png cat.png cesiumcloud rename root/images/dog.png cat.png cesiumcloud rename root/images/dog.png cat -ne Without -ne, omitted NEW extension inherits the original one. With -ne, remove the original extension if new name has none. A plain new name stays in the original file's cloud directory. Rename refuses existing target paths. Folder rename not supported; use move for entire directories.

MOVE (changes virtual paths, without transferring or rewriting file bytes) cesiumcloud move root/images/dog.png to root/things cesiumcloud move "root/passwords.txt|root/securitypasswords.txt" to root/important/secure/critical cesiumcloud move "root/images|root/notes" to root/archived cesiumcloud move "images/dog.png|images/cat.png" [to] root/things cesiumcloud move root/things/dog.png to root Accepts file and whole-directory sources (1-20 sources per invocation, max 1000 affected files). Directory moves preserve their folder name and subfolders. File moves preserve original basenames/extensions. Destination directories are virtual and created automatically as needed. Move rejects target collisions, duplicate sources, and recursive moves. The server applies each batch of path changes in one service database transaction. These are logical CesiumCloud paths, NOT local filesystem paths.

DELETE (PERMANENT, not recoverable through the CLI) cesiumcloud delete dog.png cesiumcloud delete "root/images/dog.png|root/notes/old.txt" cesiumcloud delete root/images/dog.png root/notes/old.txt cesiumcloud delete -resume Finish a pending physical removal Files are permanently removed from backing storage, not just hidden. Other files that share storage packs are preserved and verified. Each selected file is processed in sequence; batch delete is not atomic. Directory deletion is deliberately unavailable.

PATHS & SHELL RULES root/ is the top of YOUR authenticated cloud namespace (for rename, move, delete). Bare filenames use the current virtual directory. For browsing, use '/' as root, e.g. 'cesiumcloud list -10 /'. On PowerShell, CMD, Bash, and Zsh, a bare | is a shell pipe: you MUST quote the WHOLE pipe-separated source argument, such as "a.txt|b.txt", or pass filenames as separate arguments where supported. Do NOT type 'cesiumcloud delete a.txt | b.txt' without quotes. Use 'to' or the literal '[to]' as the move destination separator. Put quotes around paths containing spaces or special shell characters. An extensionless filename matches only when unambiguous; otherwise include its extension. '/' is the cloud separator, not Windows ''.

MORE HELP cesiumcloud help cesiumcloud --help cesiumcloud move --help cesiumcloud rename --help cesiumcloud delete --help cesiumcloud list --help

FILE MANAGEMENT GUARANTEES Browsing uses indexed metadata rather than streaming file payloads. Move/rename do not rewrite payload bytes. Single-file download streams only the requested segments. Delete is destructive and can require repacking unaffected files; resume cleanup if interrupted.